Luiz Schons – Microservices

Design for Failure: wait, my system fails?

Thu, 15 Oct 2026 00:00:00 -0300

Every system fails. The question is not whether a service will go down, it is what happens to everything else when it does. That is the subject of my talk Design for Failure, which I gave at SoftWeek and PHPeste in 2025, and this article is its written version, with a bit more room for the details that do not fit in 40 minutes on stage.

The idea of the talk is simple: give names to the patterns we already use, sometimes without knowing it. Retry, fallback, circuit breaker and saga are not recent inventions, and understanding where each one comes from helps you know when to use it, and above all when not to.

A warning before we start: all the code here is for teaching. It exists to show the idea, not to go straight to production. For that there are well-tested libraries, which I mention along the way.

From one server to many points of failure

Every online store starts the same way: one server, one application and one database. While the server runs at 20% of its capacity, all is well. Then the store grows, usage goes to 80%, and it is time to scale. There are two ways to do it:

Vertical: you upgrade the hardware you already have. More CPU, more memory, a bigger server. It is simple, but it has a ceiling and gets expensive fast.
Horizontal: you add more machines. More servers, containers, a Kubernetes cluster orchestrating it all. There is no clear ceiling, but now the system is distributed.

And it is in a distributed system that you start to notice how many points of failure there are. A call between two services can take too long, the other side may be down, a lock may be holding a resource. Every arrow on an architecture diagram is a network call, and every network call can fail.

For the rest of the article, we will use a store split into services. A purchase goes through the e-commerce service, which talks to stock, shipping and payment. If everyone answers, the customer gets a 200 OK. But what if the shipping service is down?

Retry: trying again, the right way

The most natural answer is to try again. Many network failures are temporary: a lost packet, a timeout at a busy moment, a container restarting. A second attempt, a moment later, often works.

This idea dates back to the 70s and 80s, when the first shared networks had to deal with collisions: Ethernet, for example, picks a random time to wait before transmitting again, from a range that doubles with each collision. That is where the two ingredients of a good retry come from:

Exponential backoff: the wait grows with each attempt (1 s, 2 s, 4 s, 8 s…). That way you do not keep hammering a service that is already struggling.
Jitter: a bit of randomness in that wait (for example, 4 s ± 20%). It looks like a detail, but it is what keeps every client from retrying at the same instant.

In PHP, with Guzzle, it looks like this:

use GuzzleHttp\Exception\ConnectException;
use GuzzleHttp\Exception\ServerException;

public function callShipping(array $data): array
{
 $maxAttempts = 3;

 for ($attempt = 1; ; $attempt++) {
 try {
 $response = $this->httpClient->post('http://shipping/api/quote', [
 'json' => $data,
 'timeout' => 2,
 ]);

 return json_decode((string) $response->getBody(), true);
 } catch (ConnectException | ServerException $e) {
 if ($attempt === $maxAttempts) {
 throw $e;
 }

 $backoffMs = 1000 * 2 ** ($attempt - 1); // 1 s, 2 s, 4 s...
 $jitter = random_int(-20, 20) / 100; // ±20%
 usleep((int) ($backoffMs * (1 + $jitter) * 1000));
 }
 }
}

Notice what is not retried. The catch only takes connection failures and 5xx errors, the cases where trying again may work. A 4xx, like a 400 or a 422, means the request itself is wrong, and sending the same request three times only produces three errors.

Three precautions that apply to any retry:

Only repeat what is idempotent. Retrying a shipping quote is safe. Retrying a charge without an idempotency key can charge the customer twice, because the first attempt may have worked and only its response got lost.
Count the total time. With a 2 s timeout and waits of 1 s and 2 s, the worst case is 9 seconds. Someone is waiting on the other end.
On PHP-FPM, waiting costs a process. That usleep holds a worker doing nothing. On Swoole and Hyperf, the same call only pauses the coroutine, and the process keeps serving other requests.

Thundering herd: when retrying makes it worse

Now picture a thousand clients calling the same service the moment it goes down. They all fail together, they all wait 1 second, and they all retry together. The service, which was trying to recover, gets a thousand requests at the same instant and falls over again. This has a name: the thundering herd.

Jitter is exactly what breaks that synchrony. I simulated the thousand clients with and without it:

Without jitter, the service gets 1,000 requests within 100 ms, three times in a row. With ±20%, the peak drops to 271. It is the same number of attempts, just spread out. And the more randomness, the more they spread: drawing the whole wait between zero and the backoff, known as full jitter, lowers the peak even further.

Fallback: an alternative answer

Retry handles short failures. But what if shipping stays down for ten minutes? Trying three times and returning an error to the customer means no purchase goes through during that time, because of a single service.

This is where fallback comes in, an idea that gained ground in the 90s and 2000s together with high availability and graceful degradation: when a critical service fails, the system does not stop entirely, it returns an alternative answer. It can be a default value, a cached response or a value computed beforehand.

In the store example, if shipping does not answer, we can use the last value calculated for that zip code, or a default shipping rate:

private const DEFAULT_SHIPPING = ['price' => 29.90, 'days' => 10];

public function shippingQuote(array $data): array
{
 try {
 return $this->callShipping($data);
 } catch (ConnectException | ServerException $e) {
 $this->logger->warning('Shipping unavailable, using fallback', [
 'error' => $e->getMessage(),
 ]);

 return $this->cache->get("shipping:{$data['zip']}", self::DEFAULT_SHIPPING);
 }
}

The purchase goes on. The customer may pay a slightly different shipping rate, but they can buy.

Two important things about fallbacks:

It is a business decision, not just a technical one. A default rate may cost the store more than the real one, and someone needs to agree to that. And not everything has a fallback: there is no “default payment”.
Going through the fallback is never a good sign. It keeps the system standing, but it hides the problem. That is why the log in there is not decoration: every fallback needs a metric and an alert, or shipping can be down for a week without anyone noticing.

Circuit breaker: stop kicking a dead horse

With retry and fallback, the customer is served. But look at what is happening underneath: on every purchase, the e-commerce service tries shipping three times, waits for the timeouts, and only then falls back. Multiply that by every purchase, and the shipping service, which is down, keeps getting a flood of calls. It is kicking a dead horse: nobody gains anything, and it gets in the way of the recovery.

Ideally, the shipping service could say “stop trying, I’m still recovering”. Since it cannot, the caller has to notice on its own. That is the job of the circuit breaker, inspired by electrical breakers and popularized by Michael Nygard’s book Release It!, in 2007. When failures cross a threshold, the breaker “trips” and cuts the calls for a while.

It has three states:

CLOSED: the normal state. Calls go through, and failures are counted.
OPEN: failures reached the threshold. No call goes out; everything goes straight to the fallback, with no timeout to wait for. The service on the other side gets some breathing room.
HALF-OPEN: the cooldown has passed. One test call is let through. If it works, the circuit closes and life goes on. If it fails, it opens again and the count restarts.

A lean version in PHP:

enum CircuitState
{
 case Closed;
 case Open;
 case HalfOpen;
}

final class CircuitBreaker
{
 private CircuitState $state = CircuitState::Closed;
 private int $failures = 0;
 private ?int $openedAt = null;

 public function __construct(
 private int $threshold = 5, // failures in a row to open
 private int $cooldown = 60, // seconds until a test call
 ) {}

 public function canExecute(): bool
 {
 if ($this->state === CircuitState::Open
 && time() - $this->openedAt >= $this->cooldown) {
 $this->state = CircuitState::HalfOpen; // let one test call through
 return true;
 }

 return $this->state === CircuitState::Closed;
 }

 public function onSuccess(): void
 {
 $this->failures = 0;
 $this->state = CircuitState::Closed;
 }

 public function onFailure(): void
 {
 $this->failures++;

 if ($this->state === CircuitState::HalfOpen || $this->failures >= $this->threshold) {
 $this->state = CircuitState::Open;
 $this->openedAt = time();
 }
 }
}

And using it, together with retry and fallback:

public function shippingQuote(array $data): array
{
 if (! $this->breaker->canExecute()) {
 return $this->shippingFallback($data);
 }

 try {
 $quote = $this->callShipping($data); // retry included
 $this->breaker->onSuccess();

 return $quote;
 } catch (ConnectException | ServerException $e) {
 $this->breaker->onFailure();

 return $this->shippingFallback($data);
 }
}

With the circuit open, a purchase no longer waits nine seconds to reach the fallback: it goes straight there. The customer is served faster and shipping stops taking a beating.

A detail that catches many people in PHP: where does this state live? On PHP-FPM, every request starts from scratch, so a CircuitBreaker object in memory forgets everything at the end of each request and never opens. The state has to live somewhere shared, like Redis or APCu. On Swoole and Hyperf, the process stays alive between requests, and in-memory state works per worker. Hyperf even ships components for this, hyperf/retry and hyperf/circuit-breaker.

And, as with fallbacks, a circuit opening is an event someone needs to see. It should raise an alert and show up in your monitoring.

Saga: what about consistency?

So far, each pattern dealt with one call that fails. But a purchase is a set of steps: reserve the stock, charge the payment, schedule the delivery. What if the stock was reserved and the payment charged, but the delivery failed?

In a single database, that would be a transaction: either everything happens, or nothing does. But each service has its own database, and there is no transaction that spans them all. The answer to this is the saga, described by Hector Garcia-Molina and Kenneth Salem in 1987: a sequence of local transactions in which every action has a matching compensation. Reserved stock? The compensation is releasing the reservation. Charged? The compensation is a refund.

To the user, the operation looks atomic, but technically the consistency is eventual. The system guarantees “all or nothing” not through a real transaction, but through the ability to undo each step if the process fails.

There are two main ways to coordinate a saga:

Choreographed

Nobody coordinates: each service reacts to events and publishes its own. When something fails, whoever notices publishes an event, and each service undoes its own part. In the talk I used Hyperf’s event dispatcher to keep the example short. Between different services, that event travels through a broker such as Kafka or RabbitMQ, and the listener becomes a consumer.

Whoever notices the failure publishes the event:

} catch (ConnectException | ServerException $e) {
 $this->breaker->onFailure();

 $this->eventDispatcher->dispatch(new OrderCancelled(
 orderId: $data['order_id'],
 reason: 'Shipping failed: ' . $e->getMessage(),
 ));
}

And each service takes care of its own compensation. In stock, for example:

use Hyperf\Event\Contract\ListenerInterface;

final class ReleaseStockOnOrderCancelled implements ListenerInterface
{
 public function __construct(private StockRepository $stock) {}

 public function listen(): array
 {
 return [OrderCancelled::class];
 }

 public function process(object $event): void
 {
 // Idempotent: the same event may arrive twice.
 $this->stock->releaseReservation($event->orderId);
 }
}

The strength is decoupling: there is no central service that stops everything if it goes down. The weakness is that the flow is not written anywhere. It exists spread across listeners, and understanding “what happens when an order is cancelled” means looking at several services. I wrote more about this style in the article on Event-Driven Architecture.

Orchestrated

An orchestrator knows the whole flow: it calls each service in order and, if one fails, triggers the compensations for the steps that already happened, in reverse order:

final class PlaceOrderSaga
{
 public function run(Order $order): void
 {
 $compensations = [];

 try {
 $this->stock->reserve($order);
 $compensations[] = fn () => $this->stock->release($order);

 $this->payment->charge($order);
 $compensations[] = fn () => $this->payment->refund($order);

 $this->shipping->schedule($order);
 } catch (Throwable $e) {
 foreach (array_reverse($compensations) as $compensate) {
 $compensate();
 }

 throw new OrderFailed("Order {$order->id} failed", previous: $e);
 }
 }
}

If delivery fails, the payment is refunded and then the stock is released. The flow lives in one place, easy to read and to test. In exchange, the orchestrator becomes a central piece: if it goes down, no saga moves.

In a real system, one thing is missing from this code: storing the saga’s state. If the orchestrator dies in the middle of a compensation, it needs to know where it stopped when it comes back. And a compensation can fail too, so it needs retries and has to be idempotent. That is why, in production, sagas usually run on top of tools like Temporal or a carefully kept state table.

Kinds of saga

The book Software Architecture: The Hard Parts (Ford, Richards, Sadalage and Dehghani) organizes sagas by three choices: synchronous or asynchronous communication, atomic or eventual consistency, and orchestrated or choreographed coordination. In the talk I showed three of the combinations:

	Communication	Consistency	Coordination
Epic Saga	Synchronous (HTTP)	Atomic	Orchestrated
Parallel Saga	Asynchronous (Kafka)	Eventual	Orchestrated
Anthology Saga	Asynchronous (Kafka)	Eventual	Choreographed

The Epic Saga is the closest to the code above: the orchestrator calls each service over HTTP, waits for the answer, and no service talks to another directly. The Parallel Saga keeps the orchestrator but talks through messages, which lets steps run in parallel. The Anthology Saga is pure choreography: no orchestrator, each service keeps its own transaction and handles its own rollback. The further down the table, the less coupling and the more scale, and the harder it is to understand what is going on.

Putting it all together

In a real architecture, these patterns show up together. The call to shipping has retry with backoff and jitter, a circuit breaker around it, a fallback with the last calculated value, and a log of every attempt and failure. The whole purchase is a saga, which undoes its steps if something goes wrong along the way.

Now your systems can fail in peace.

Or maybe not.

Each of these patterns solves one problem and creates another. Retry adds load to a service that is already struggling. Fallback hides the failure and may cost money. The circuit breaker needs shared state and well-tuned thresholds, or it opens for no reason or never opens at all. The saga trades a simple transaction for eventual consistency, compensations and a lot more code. It is all a trade-off.

So do not get attached to patterns. Figure out what makes the most sense in your context: which failure is likely, how much it costs, how long someone can wait, and which wrong answer is acceptable. There is no silver bullet.

The talk’s slides are on Speaker Deck. If you have been through a cascading failure, or use any of these patterns in a different way, tell me in the comments.

Are microservices technical debt?

Fri, 06 Dec 2024 00:00:00 -0300

Building software has never been so complex and, at the same time, so simple. The complexity lies in the sheer number of technologies, frameworks, languages and patterns available to us. The simplicity lies in how easy it is to access those technologies and to build software with them.

Because building software is so easy, we often don't worry about the quality of what we are building. Software quality is a key factor in the success of a project. It is what makes software easy to maintain, easy to evolve and easy to fix.

We often focus our study and our time on learning new technologies and frameworks, but forget to study software architecture, and that is a big mistake. Software architecture is what ensures the maintainability, evolution and correctness of software.

Deciding which architecture to use in a project is a very important task and must be done with great care. A poor choice can bring many problems to the project and to the development team, and the big problem is that these side effects may not show up at the beginning of the project, but only over time.

Some of the main problems a poor software architecture can cause are high coupling between modules, low cohesion between modules, difficulty scaling, performance problems and difficulty testing, among others.

Imagine the following scenario: time goes by, and you and your team notice the software is getting more and more complex. It seems that with every new feature, the software becomes more unstable, harder to maintain, harder to evolve and harder to fix. Now what? What do you do?

Then, out of nowhere, the magic word appears: Microservices. Microservices are the solution to every software architecture problem. Microservices are the solution to every problem of coupling, cohesion, scalability, performance and testing.

I agree that microservices are an excellent solution to many software architecture problems, but they are not the solution to all of them.

Have you considered refactoring your code before trying a more complex solution like microservices?

Have you considered studying software architecture before trying a solution based purely on current trends, or on solutions that worked for other companies?

Netflix, Amazon and Google have great solutions to their own software architecture problems, but do those solutions work for your project?

Is it time for you and your team to stop trying magic solutions and start studying software quality and architecture?

Don't you think that using microservices to solve software architecture problems is a form of technical debt?

I won't answer these questions, but I think you should think about them.

I don't think you should never use microservices, but I do think you should think hard before using them.

There are cases where this architecture makes complete sense, but there are many cases where it is only being used to pay off technical debt left by a wrong decision made at the beginning of the project.

Don't despise microservices, but don't use them as the solution to every problem.

Study, learn, and make decisions based on facts, not on trends.

Keeping software at a high quality is hard work that takes a lot of study and dedication, but it is work worth doing.

And you, what do you think? Are microservices technical debt?

Static and dynamic coupling in microservices

Fri, 11 Oct 2024 00:00:00 -0300

Monolithic applications are those with a single codebase, a single executable and a single process. They are often built in a single programming language and deployed to a single server.

When we start developing, monoliths are usually our first experience. They are easy to develop, test and deploy. However, as the application grows, the monolith starts to become a problem.

Scalability is one of the most important things to consider in software today. Being able to handle the growth of users and data dynamically is essential to a software product's success.

Monolithic systems are hard to scale. They are built as a single block of code, which means that to scale the application you need to replicate all of the code or scale the server vertically. That can be expensive and inefficient.

Vertical scalability is the ability to increase a server's capacity by adding more resources, such as CPU, RAM and disk. It is done to improve a server's performance.

Horizontal scalability is the ability to increase a system's capacity by adding more instances of it. It is done to improve a system's availability and reliability.

Microservices is a software architecture that solves this problem (but creates others). Instead of building a single monolithic application, you build several small, independent applications called microservices. Each microservice is responsible for a specific part of the application and communicates with the others.

Although microservices seem in theory to offer an ideal solution to scalability problems, in practice they bring challenges of their own. One of the main ones is managing the coupling between them.

In an ideal world, microservices should be independent and decoupled. That means one application should be able to work without depending on another. However, especially when migrating from monoliths to microservices, it is common for them to depend on each other, and that is what we call coupling.

There are two kinds of coupling in microservices: static coupling and dynamic coupling, and those are what we are going to talk about today.

Example of a microservices architecture

Components:

API Gateway:
- Acts as the entry point for all external requests to the system.
- Receives HTTP requests from clients and routes them to the appropriate internal services (such as ProductCatalogService, OrderService and UserService).
- Handles access control, authentication, request routing and response aggregation.
ProductCatalogService:
- Manages information about products for sale, such as descriptions, prices and availability.
- Can query a discovery service such as Consul to locate other services it needs.
OrderService:
- Creates purchase orders.
- Interacts with other services to get product information (via ProductCatalogService) and user details (via UserService).
- Handles orders in the MongoDB database and publishes order events to RabbitMQ, enabling asynchronous communication with other services.
UserService:
- Manages user information, such as profiles, preferences and purchase history.
- Lets other services query user information securely.
PaymentService:
- Responsible for processing payment transactions.
- Interacts with the MongoDB database to store information about financial transactions.
- Publishes transaction events to RabbitMQ so that other services (such as NotificationService) are notified of financial events.
RabbitMQ:
- Enables asynchronous messaging between services, making decoupled communication easier.
- Delivers order and transaction events to interested parties.
NotificationService:
- Sends notifications to users based on events received through RabbitMQ, such as order status updates or payment confirmation messages.
MongoDB:
- Stores data critical to the system, such as order, user and transaction information.
- A NoSQL database like MongoDB is well suited to systems that need schema flexibility and efficient handling of unstructured data.
Consul:
- Service used for service discovery, configuration and management.
- Lets microservices dynamically discover the location of other services, enabling a highly flexible and resilient architecture.
Nginx:
- Can act as a reverse proxy or load balancer that distributes requests across several API Gateway instances, improving capacity and availability.

Static coupling

The components in green represent static coupling.

Static coupling happens when a microservice depends on another microservice at compile time or at the system's initial configuration.

Most of the time, static coupling is easy to spot. The most common forms are:

Code dependency: a microservice calls another one directly through a function call or an API.
Database dependency: a microservice accesses another application's database directly.
Configuration dependency: a microservice depends on specific settings of another microservice.

Another form of static coupling is when a microservice depends on a specific contract of another one. For example, a microservice expects another service to return a specific JSON object. If the contract changes, the microservice that depends on it may break, so the application that depends on the contract has to be updated.

Dynamic coupling

The components in blue represent dynamic coupling.

Dynamic coupling happens when a microservice depends on another one at runtime.

Most of the time, dynamic coupling is harder to spot. The most common forms are:

Messaging dependency: a microservice sends a message to a message bus and expects another service to respond.
Service discovery dependency: a microservice queries a discovery service to locate another one.

The interesting thing about dynamic coupling is that it lets microservices be more independent and decoupled. If a microservice is unavailable, the one that depends on it can keep working, even if in a limited way.

Conclusion

When designing microservices, it is important to consider the coupling between them. Static coupling and dynamic coupling are two forms of coupling that can be used in distributed systems.

There is no hard rule about which kind of coupling is better. In fact, most microservices systems will have a combination of static and dynamic coupling.

As an architect, you need to decide which kind of coupling makes the most sense for the problem you are solving right now. In some cases, static coupling can be simpler and more efficient. In others, dynamic coupling can be more flexible and resilient.

What matters is understanding the differences between static and dynamic coupling and knowing when to use each one.

References

Software Architecture: The Hard Parts — Modern Trade-Off Analyses for Distributed Architectures

Event-driven Architecture (EDA)

Sat, 03 Aug 2024 00:00:00 -0300

Software architecture involves many trade-offs. A poor choice can lead to rework and delays, so it is important to know the available options and understand when each one makes sense.

In this article, we will talk about Event-driven Architecture (EDA), a style whose main characteristic is communication between services through events.

What is EDA?

Event-driven Architecture promotes the production, detection, consumption of and reaction to events. An event can be any fact relevant to the system: a state change, a user action, an error or a received message.

Events are asynchronous messages generated by a producer and consumed by one or more consumers. The producer does not need to know the consumers, and the consumers do not need to know the producers. This makes it possible to build systems that are more decoupled, scalable and flexible.

In this article’s example, we will simulate the following scenario:

Hands-on example

The system is made up of four services.

`ecommerce-frontend`

Frontend of an e-commerce store that lets you add products to the cart.
Uses React to build the user interface.

`stock-service`

Manages product stock.
Uses PHP to communicate with RabbitMQ.

A simplified example of publishing a stock event in PHP:

$message = new AMQPMessage(json_encode([
 'order_id' => 1,
 'status' => 'updated',
]));

$channel->basic_publish($message, '', 'stock_updated');

The code above is just a teaching example, not working or production-safe code.

`payment-service`

Processes order payments.
Uses Python to communicate with RabbitMQ.

def process_payment(order):
 print(f"Processing payment for order: {order['order_id']}")
 return True

`rabbitmq`

Message broker that enables communication between the services.
Receives published events and routes them to interested consumers.

The full code is available in the project repository.

Communication flow

The user opens the e-commerce frontend and adds a product to the cart.
The frontend sends a request to the stock service to check out.
The stock service checks availability and publishes an event to RabbitMQ.
The payment service consumes the event and processes the payment.
The payment service publishes an event with the result of the processing.

Trade-offs

This flow is a simple example of how EDA can decouple services and enable asynchronous communication without producers and consumers having to know each other. Each service is responsible for one task and can be replaced or updated with less impact on the others.

On the other hand, event-driven architecture increases operational complexity. You have to deal with ordering, delivery, idempotency, traceability and debugging of distributed problems.

So before adopting EDA, consider whether the benefits outweigh that complexity for your project.

Conclusion

Event-driven Architecture is a powerful alternative for building decoupled, flexible and resilient systems. There is no perfect architecture: the best choice depends on the project’s requirements, constraints and operational maturity.

The full code is available on GitHub.

Microservices and Messaging with PHP, NodeJS, RabbitMQ and Docker

Sat, 29 Jun 2024 00:00:00 -0300

Microservices development is an architectural approach that structures an application as a set of small, independent services, each running in its own process and communicating through lightweight protocols such as HTTP, WebSockets or AMQP.

In this article, we will build a microservices application with PHP, RabbitMQ and Docker. RabbitMQ is messaging software that implements AMQP (Advanced Message Queuing Protocol), an asynchronous messaging protocol.

What is RabbitMQ?

Imagine the following scenario: you have a system that needs to send emails to users. Instead of sending the emails directly, you can send a message to a message queue, which will be consumed by a service that sends the emails. That is what RabbitMQ does: it receives messages from producers and delivers them to consumers.

This decouples producing messages from consuming them, which lets you scale each part of the system independently. RabbitMQ also makes sure messages are delivered in the right order and are not lost.

Application architecture

Our application will have two microservices: a producer and a consumer. The producer sends messages to a message queue, and the consumer reads the messages and prints them to the terminal.

Our first step is to create the docker-compose.yml file to define our application's services:

services:
 rabbitmq:
 image: "rabbitmq:3-management"
 container_name: "rabbitmq"
 ports:
 - "15672:15672"
 - "5672:5672"

 php-app:
 build: ./php-app
 depends_on:
 - rabbitmq

 node-app:
 build: ./node-app
 depends_on:
 - rabbitmq

In this file, we define three services: rabbitmq, php-app and node-app. The rabbitmq service is based on the rabbitmq:3-management image, which includes the RabbitMQ management UI. The php-app and node-app services are based on custom images we are going to build.

Building the producer with PHP

Now let's create the php-app directory and a Dockerfile inside it:

mkdir php-app && touch php-app/Dockerfile

In the Dockerfile, we define the base image and copy the application files:

FROM php:7.4-cli

RUN apt-get update && apt-get install -y librabbitmq-dev libssl-dev git unzip wget curl

RUN docker-php-ext-install sockets pdo pdo_mysql
RUN pecl install amqp && docker-php-ext-enable amqp

COPY . /usr/src/myapp
WORKDIR /usr/src/myapp

RUN curl -sS https://getcomposer.org/installer | php -- --install-dir=/usr/local/bin --filename=composer

RUN composer clear-cache

RUN composer install

CMD ["php", "./publisher.php"]

In this file, we use the php:7.4-cli base image and install the dependencies needed for RabbitMQ and Composer. Then we copy the application files into /usr/src/myapp, install the Composer dependencies and run the publisher.php script.

Now let's create the publisher.php file at the project root:

require_once __DIR__ . '/vendor/autoload.php';
use PhpAmqpLib\Connection\AMQPStreamConnection;
use PhpAmqpLib\Message\AMQPMessage;

$maxRetries = 5;
$retryDelay = 5;

for ($attempt = 0; $attempt try {
 $connection = new AMQPStreamConnection('rabbitmq', 5672, 'guest', 'guest');
 $channel = $connection->channel();
 break;
 } catch (Exception $e) {
 echo "Failed to connect to RabbitMQ. Retrying in $retryDelay seconds...\n";
 sleep($retryDelay);
 }
}

if (!isset($connection)) {
 echo "Not possible to connect to RabbitMQ. Exiting...\n The application will be restarted by Docker\n";
 exit(1);
}

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

$msg = new AMQPMessage('Hello, RabbitMQ! Now is ' . date('Y-m-d H:i:s'));
$channel->basic_publish($msg, '', 'hello');

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

$channel->close();
$connection->close();

In this file, we open a connection to RabbitMQ, declare a queue called hello and send a message to it. Then we close the connection. Notice that we try to connect to RabbitMQ several times, waiting 5 seconds between attempts.

This matters to make sure the application can connect to RabbitMQ even if it is not available right away. It is a common practice in distributed applications, where service availability can vary over time; look up the circuit breaker and retry pattern patterns to learn more.

To install the RabbitMQ dependencies with Composer, we need to create a composer.json file at the project root:

{ "require": { "php-amqplib/php-amqplib": "^3.1", "phpseclib/phpseclib": "^3.0" } }

Building the consumer with Node.js

Now let's create the node-app directory and a Dockerfile inside it:

mkdir node-app && touch node-app/Dockerfile

In the Dockerfile, we define the base image and copy the application files:

FROM node:14 
WORKDIR /usr/src/app 
COPY package\*.json ./ 
RUN npm install 
COPY . . 
CMD \["node", "subscriber.js"\]

In this file, we use the node:14 base image, copy the application files into /usr/src/app, install the Node.js dependencies and run the subscriber.js script.

Now let's create the subscriber.js file at the project root:

const amqp = require('amqplib');

async function connectWithRetry() {
 const maxRetries = 5;
 const retryDelay = 5000;

 for (let attempt = 1; attempt try {
 const connection = await amqp.connect('amqp://rabbitmq');
 return connection;
 } catch (err) {
 console.error(`Not possible to connect to RabbitMQ. Retrying in ${retryDelay}ms. Attempt ${attempt} of ${maxRetries}`);
 await new Promise(resolve => setTimeout(resolve, retryDelay));
 }
 }

 throw new Error(`Failed to connect to RabbitMQ after ${maxRetries} attempts`);
}

async function receiveMessages() {
 try {
 const connection = await connectWithRetry();
 const channel = await connection.createChannel();
 const queue = 'hello';

 await channel.assertQueue(queue, { durable: false });

 console.log(" [*] Waiting for messages in %s.", queue);

 channel.consume(queue, function (msg) {
 console.log(" [x] Received: %s", msg.content.toString());
 }, {
 noAck: true
 });

 } catch (err) {
 console.error(err.message);
 process.exit(1);
 }
}

receiveMessages();

In this file, we open a connection to RabbitMQ, declare a queue called hello and consume the messages from it.

Then we print the messages to the terminal. Just like in the producer, we try to connect to RabbitMQ several times, waiting 5 seconds between attempts. This makes sure the consumer can connect to RabbitMQ even if it is not available right away.

And to install the RabbitMQ dependencies, we need to create a package.json file at the project root:

{ "name": "node-app", "version": "1.0.0", "description": "", "main": "subscriber.js", "dependencies": { "amqplib": "^0.8.0" }, "author": "", "license": "ISC" }

Running the application

Now that we have the RabbitMQ, producer and consumer services, let's run the application with Docker Compose:

docker compose up --build

This will create the service containers and run the application. You will see the messages sent by the producer printed to the terminal by the consumer.

RabbitMQ will also be available on port 15672, where you can open the management UI and see the queues and messages.

With that, we have built a microservices application with PHP, RabbitMQ and Docker. This architectural approach lets you scale each part of the system independently and guarantees that messages are delivered in the right order.

I hope this article was useful and that you can apply these concepts in your projects. If you have any questions or suggestions, leave them in the comments.

Feel free to reach out with any questions.

Repository: Microservices and Messaging with PHP, RabbitMQ and Docker