Introduction

Prerequisites

This tutorial assumes RabbitMQ is installed and running

on localhost on standard port (5672). In case you use

a different host, port or credentials, connections settings would require adjusting.

Where to get help

If you're having trouble going through this tutorial you can

through the mailing list.

RabbitMQ is a message broker: it accepts and forwards messages.

You can think about it as a post office: when you put the mail that you want posting in a post box,

you can be sure that Mr. or Ms. Mailperson will eventually deliver the mail to your recipient.

In this analogy, RabbitMQ is a post box, a post office and a postman.

The major difference between RabbitMQ and the post office is that it doesn't deal with paper,

instead it accepts, stores and forwards binary blobs of data messages.

RabbitMQ, and messaging in general, uses some jargon.

Producing means nothing more than sending.

A program that sends messages is a producer :

digraph {

bgcolor=transparent;

truecolor=true;

rankdir=LR;

node [style="filled"];

//

P1 [label="P", fillcolor="#00ffff"];

}

A queue is the name for a post box which lives inside RabbitMQ.

Although messages flow through RabbitMQ and your applications, they can only be stored inside a queue.

A queue is only bound by the host's memory & disk limits, it's essentially a large message buffer.

Many producers can send messages that go to one queue, and many consumers can try to receive data from one queue.

This is how we represent a queue:

digraph {

bgcolor=transparent;

truecolor=true;

rankdir=LR;

node [style="filled"];

//

subgraph cluster_Q1 {

label="queue_name";

color=transparent;

Q1 [label="{||||}", fillcolor="red", shape="record"];

};

}

Consuming has a similar meaning to receiving.

A consumer is a program that mostly waits to receive messages:

digraph {

bgcolor=transparent;

truecolor=true;

rankdir=LR;

node [style="filled"];

//

C1 [label="C", fillcolor="#33ccff"];

}

Note that the producer, consumer, and broker do not have to reside on the same host; indeed in most applications they don't.

An application can be both a producer and consumer, too.

"Hello World"

(using the php-amqplib Client)

In this part of the tutorial we'll write two programs in PHP; a

producer that sends a single message, and a consumer that receives

messages and prints them out. We'll gloss over some of the detail in

the php-amqplib API, concentrating on this very simple thing just to get

started. It's a "Hello World" of messaging.

In the diagram below, "P" is our producer and "C" is our consumer. The

box in the middle is a queue - a message buffer that RabbitMQ keeps

on behalf of the consumer.

The php-amqplib client library

RabbitMQ speaks multiple protocols. This tutorial covers AMQP 0-9-1, which is an open,

general-purpose protocol for messaging. There are a number of clients

for RabbitMQ in many different

languages. We'll

use the php-amqplib in this tutorial, and Composer

for dependency management.

Add a composer.json file to your project:

{




    "require": {




        "php-amqplib/php-amqplib": ">=2.6.1"




    }




}

Provided you have Composer installed and functional,

you can run the following:

composer.phar install

There's also a Composer installer for Windows.

Now we have the php-amqplib library installed, we can write some

code.

Sending

We'll call our message publisher (sender) send.php and our message receiver

receive.php. The publisher will connect to RabbitMQ, send a single message,

then exit.

In

send.php,

we need to include the library and use the necessary classes:

require_once __DIR__ . '/vendor/autoload.php';




use PhpAmqpLib\Connection\AMQPStreamConnection;




use PhpAmqpLib\Message\AMQPMessage;

then we can create a connection to the server:

$connection = new AMQPStreamConnection('localhost', 5672, 'guest', 'guest');




$channel = $connection->channel();

The connection abstracts the socket connection, and takes care of

protocol version negotiation and authentication and so on for us. Here

we connect to a broker on the local machine - hence the

localhost. If we wanted to connect to a broker on a different

machine we'd simply specify its name or IP address here.

Next we create a channel, which is where most of the API for getting

things done resides.

To send, we must declare a queue for us to send to; then we can publish a message

to the queue:

$channel->queue_declare('hello', false, false, false, false);









$msg = new AMQPMessage('Hello World!');




$channel->basic_publish($msg, '', 'hello');









echo " [x] Sent 'Hello World!'\n";

Declaring a queue is idempotent - it will only be created if it doesn't

exist already. The message content is a byte array, so you can encode

whatever you like there.

Lastly, we close the channel and the connection;

$channel->close();




$connection->close();

Here's the whole send.php

class.

Sending doesn't work!

If this is your first time using RabbitMQ and you don't see the "Sent"

message then you may be left scratching your head wondering what could

be wrong. Maybe the broker was started without enough free disk space

(by default it needs at least 200 MB free) and is therefore refusing to

accept messages. Check the broker logfile to confirm and reduce the

limit if necessary. The configuration

file documentation will show you how to set disk_free_limit.

Receiving

That's it for our publisher. Our receiver is pushed messages from

RabbitMQ, so unlike the publisher which publishes a single message, we'll

keep it running to listen for messages and print them out.

The code (in receive.php) has almost the same

include and uses as send:

require_once __DIR__ . '/vendor/autoload.php';




use PhpAmqpLib\Connection\AMQPStreamConnection;

Setting up is the same as the publisher; we open a connection and a

channel, and declare the queue from which we're going to consume.

Note this matches up with the queue that send publishes to.

$connection = new AMQPStreamConnection('localhost', 5672, 'guest', 'guest');




$channel = $connection->channel();









$channel->queue_declare('hello', false, false, false, false);









echo " [*] Waiting for messages. To exit press CTRL+C\n";

Note that we declare the queue here, as well. Because we might start

the consumer before the publisher, we want to make sure the queue exists

before we try to consume messages from it.

We're about to tell the server to deliver us the messages from the

queue. We will define a PHP callable

that will receive the messages sent by the server. Keep in mind

that messages are sent asynchronously from the server to the clients.

$callback = function ($msg) {




  echo ' [x] Received ', $msg->body, "\n";




};









$channel->basic_consume('hello', '', false, true, false, false, $callback);









while (count($channel->callbacks)) {




    $channel->wait();




}

Our code will block while our $channel has callbacks. Whenever we receive a

message our $callback function will be passed the received message.

Here's the whole receive.php class

Putting it all together

Now we can run both scripts. In a terminal, run the consumer (receiver):

php receive.php

then, run the publisher (sender):

php send.php

The consumer will print the message it gets from the sender via

RabbitMQ. The receiver will keep running, waiting for messages (Use

Ctrl-C to stop it), so try running the sender from another terminal.

Listing queues

You may wish to see what queues RabbitMQ has and how many

messages are in them. You can do it (as a privileged user) using the rabbitmqctl tool:

sudo rabbitmqctl list_queues

On Windows, omit the sudo:

rabbitmqctl.bat list_queues

Time to move on to part 2 and build a simple work queue.

Production [Non-]Suitability Disclaimer

Please keep in mind that this and other tutorials are, well, tutorials.

They demonstrate one new concept at a time and may intentionally oversimplify some things and leave out others. For example topics such as

connection management, error handling, connection recovery, concurrency and metric collection are largely omitted

for the sake of brevity. Such simplified code should not be considered production ready.

Please take a look at the rest of the documentation before going live with your app.

We particularly recommend the following guides: Publisher Confirms and Consumer Acknowledgements,

Production Checklist and Monitoring.

Getting Help and Providing Feedback

If you have questions about the contents of this tutorial or

any other topic related to RabbitMQ, don't hesitate to ask them

on the .

Help Us Improve the Docs <3

If you'd like to contribute an improvement to the site,

its source is available on GitHub.

Simply fork the repository and submit a pull request. Thank you!