Luiz Schons – PHP

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.

Hexagonal Architecture and Messaging with PHP

Thu, 04 Jul 2024 00:00:00 -0300

Hexagonal Architecture (Ports and Adapters)

Project link: https://github.com/sschonss/microservices-hexagonal

There are many ways to organize a project, and one of the best known is hexagonal architecture. Hexagonal architecture organizes a project so that it is independent of frameworks, databases, UI and so on. The goal is for the project to be independent of any technology, so that each one can be easily replaced.

In this project, hexagonal architecture was implemented with the PHP programming language and the Laravel framework. The idea is for the project to be independent of Laravel, so we use Laravel only to create routes and controllers, and the rest of the project does not depend on it.

Project structure

The project was split into 3 main layers:

Laravel: All of the project's infrastructure, such as routes, controllers, etc.
Adapters: Layer that holds the project's input and output adapters.
Core: Layer that holds the project's business rules. Inside the core, we will work with Domain Driven Design (DDD).

Adapters

Adapters are responsible for adapting the project's inputs and outputs. But what does that mean?

Imagine you have a project that needs to talk to a database. Without an adapter layer, you would have to use the database directly in your project. That means using the database classes directly in your code, which makes your project dependent on the database.

An ORM (Object Relational Mapping) is an example of an adapter. The ORM is a layer that adapts communication with the database, so the project does not depend on the database itself.

In our project, we have the following adapters:

EmailAdapter: Adapter responsible for sending emails.
RabbitMQAdapter: Adapter responsible for sending messages to RabbitMQ.

They contain the classes that adapt communication with the email service and with RabbitMQ.

All of this uses plain PHP, without Laravel, so the project stays independent and each piece can be easily replaced.

Core

The core is the layer that holds the project's business rules. Inside the core, we will work with Domain Driven Design (DDD).

What is DDD?

Domain Driven Design is a way of organizing a project so that it is split into domains. Each domain is a part of the project that holds business rules. This keeps the project organized and easy to maintain.

Inside the core, we have the following domains:

Email: Domain responsible for the application's emails in general.
Connections: Domain responsible for connections to external services, such as RabbitMQ, Redis, etc.

Inside each domain, we have the layers that hold the business rules for each feature.

Most importantly, the core depends on nothing. It is independent of any framework, database, etc. That way, we can easily replace Laravel with another framework, or MySQL with another database.

The core talks to external services through the adapters. That way, the core does not depend on any external service, only on the adapter.

The project

The project is a simple example of how hexagonal architecture can be implemented. It is a user registration system, where users can sign up and receive a welcome email.

The project was split into 3 services:

Main App: The main service, where users sign up. This is where the hexagonal architecture lives.
RabbitMQ: The messaging service, to which the Main App sends a message.
Email App: The email service, which reads messages from RabbitMQ and sends an email to the user.

This way, the Main App does not depend on RabbitMQ or on the email service. It just sends a message to RabbitMQ, and RabbitMQ delivers the message to the email service.

How to run the project

To run the project, you need Composer, Docker and Docker Compose installed on your machine.

After installing Docker and Docker Compose, just run the following command:

cd main-app composer install ./vendor/bin/sail up

After running the command, the project will be running on port 80.

We can now create a user through the POST /api/user endpoint, sending the following JSON:

{ "name": "John Doe", "email": "john@doe.com", "password": "123456" }

After the user is created, an event is published to RabbitMQ, but the email service is not running yet. To run it, just run the following command:

cd email-app docker-compose up --build --force-recreate

After running the command, the email service will be running, reading messages from RabbitMQ and sending an email to the user.

Accessing RabbitMQ

To access RabbitMQ, just open the following address:

http://localhost:15672

And log in with the following credentials:

Username: guest Password: guest

Conclusion

Hexagonal architecture is a way of organizing a project so that it is independent of any technology. In this project, it was implemented with PHP and the Laravel framework. The idea is for the project to be independent of Laravel, so we use Laravel only to create routes and controllers, and the rest of the project does not depend on it.

The project is a simple example of how hexagonal architecture can be implemented. It is a user registration system, where users can sign up and receive a welcome email.

We also implemented a messaging service with RabbitMQ and an email service. This way, the Main App does not depend on RabbitMQ or on the email service. It just sends a message to RabbitMQ, and RabbitMQ delivers it to the email service.

We saw how messaging helps decouple services, and how hexagonal architecture helps organize a project so that it is independent of any technology.

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

PHP — Stream Filters

Tue, 04 Jun 2024 00:00:00 -0300

If you have ever worked with files in PHP, you have probably used functions like fopen, fwrite, fread and fclose. Streams are a very powerful and flexible abstraction for working with files and other I/O resources.

Streams abstract the handling of input and output data, letting you read and write data from and to different sources, such as files, strings, network connections, etc.

For example, you can use streams to read data from a file, process it and write it to another file, without worrying about where the data comes from or where it goes.

Or you can use streams to read data from a network connection, process it and write it to a database. And so on.

Basic example

$stream = fopen('data.txt', 'r');
while (!feof($stream)) {
 $line = fgets($stream);
 echo $line;
}
fclose($stream);

In this example, we open a file called data.txt in read mode ('r'). Then we read the file line by line until the end (feof($stream)). Finally, we close the file with fclose($stream).

But what is a stream? A stream is a resource that represents a source or destination of data. In the example above, $stream is a stream that represents the file data.txt.

Let's look at a more advanced example.

Advanced example

$context = stream_context_create([
 'http' => [
 'method' => 'POST',
 'header' => 'Content-Type: application/json',
 'content' => json_encode(['key' => 'value']),
 ],
]);

$stream = fopen('http://example.com/data.csv', 'r', false, $context);
while (!feof($stream)) {
 $line = fgetcsv($stream);
 print_r($line);
}
fclose($stream);

In this example, we create a stream context with stream_context_create, an associative array of configuration options for the stream. Here we configure an HTTP stream with the POST method, the Content-Type: application/json header and a JSON request body.

Then we open a stream to the URL http://example.com/data.csv in read mode ('r') with the stream context we just created.

Next, we read the stream line by line with fgetcsv, which reads a line from the stream and turns it into an array of comma-separated values.

Finally, we close the stream with fclose.

But why use streams?

PHP was born at a time when file handling was the main way to interact with the file system and other I/O resources. That is why PHP's file functions are based on low-level operations such as opening, reading, writing and closing files: the famous fopen, fread, fwrite and fclose.

Over time, the need to interact with other kinds of I/O resources, such as network connections and databases, became more and more common. That is where streams came in.

Streams are essentially an abstraction layer over different kinds of I/O resources, letting you read and write data from and to them consistently, regardless of where the data comes from or goes to.

By I/O resources, I mean anything you can read data from or write data to, such as files, strings, console windows, network connections, sockets, pipes, etc.

And by not worrying about where the data comes from or goes to, I mean you don't need to know whether you are reading from a file, a network connection, a database, etc. You simply read the data from the stream and process it however you like. That is very powerful and flexible.

So how do I use streams?

To use streams in PHP, you need to understand a few basic concepts:

Resource
Context
Wrapper
Stream functions
Stream filters

Note: this is just a basic overview of streams in PHP. To learn more, see the official documentation.

Resource

Let's dig a little deeper into the concept of a resource in PHP.

A stream is represented by a resource in PHP. A resource is a special variable that holds an internal reference to an external resource, such as a file or a network connection. You can create a resource with fopen and close it with fclose.

A resource in PHP is an internal identifier for external resources, and the get_resource_type function can be used to get the resource's type.

$stream = fopen('data.txt', 'r');
echo get_resource_type($stream);
fclose($stream);

In the console, you will see something like stream.

The resource always refers to the open file.

Context

A stream context is an associative array of configuration options for the stream. You can create one with stream_context_create and pass it as an argument to functions that open streams, such as fopen, file_get_contents, etc.

When you open a stream with a stream context, the context's options are applied to the stream. For example, you can configure an HTTP stream with the POST method, the Content-Type: application/json header, etc.

$context = stream_context_create([
 'http' => [
 'method' => 'POST',
 'header' => 'Content-Type: application/json',
 'content' => json_encode(['key' => 'value']),
 ],
]);

$stream = fopen('http://example.com/data.csv', 'r', false, $context);

Or you can use a stream context to configure an FTP stream with a username and password.

$context = stream_context_create([
 'ftp' => [
 'username' => 'user',
 'password' => 'pass',
 ],
]);

$stream = fopen('ftp://example.com/data.csv', 'r', false, $context);

Wrapper

A wrapper is a URL scheme that defines how PHP should open a stream. For example, the http wrapper is used to open HTTP streams, the ftp wrapper to open FTP streams, and so on.

When you open a stream with fopen, PHP uses the matching wrapper to open it. For example, if you open http://example.com/data.csv, PHP uses the http wrapper.

You can also use wrappers to open streams over other kinds of resources, such as strings, in-memory variables, etc.

$stream = fopen('data:text/plain;base64,SGVsbG8gV29ybGQ=', 'r');
echo stream_get_contents($stream);
fclose($stream);

In this example, we open a stream over a base64-encoded string with the data wrapper. The string's content is Hello World.

$stream = fopen('php://memory', 'r+');

In this example, we open an in-memory stream with the php wrapper. The stream is opened in read-write mode ('r+').

$stream = fopen('ogg://temp', 'r+');

OGG is a wrapper for handling audio files in the OGG format; this is an example of a custom wrapper.

You can create your own custom wrappers to open streams over other kinds of resources, such as databases, APIs, etc.

See the official documentation for more information about wrappers in PHP.

Stream functions

PHP provides several functions for working with streams, such as fopen, fclose, fread, fwrite, feof, fseek, ftell, fgetcsv, stream_get_contents, etc.

You can use these functions to open, close, read, write, seek, check for the end of a stream, and so on.

For example, you can use fopen to open a stream, fread to read from it, fwrite to write to it and fclose to close it.

$stream = fopen('data.txt', 'r');

while (!feof($stream)) {
 $line = fgets($stream);
 echo $line;
}

fwrite($stream, 'Hello World');
fclose($stream);

In this example, we open a file called data.txt in read mode ('r'). Then we read the file line by line until the end with fgets. Next, we write the string Hello World to the file with fwrite. Finally, we close the file with fclose.

You can use these functions with streams over different kinds of resources, such as curl, sockets, pipes, etc.

$url = 'http://example.com/data/page.html';
$data = curl_init($url);
curl_setopt($data, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($data);
curl_close($data);
$stream = fopen('php://memory', 'r+');
fwrite($stream, $response);
rewind($stream);
echo stream_get_contents($stream);
fclose($stream);

In this example, we make an HTTP request with curl to http://example.com/data/page.html. Then we open an in-memory stream with the php wrapper in read-write mode ('r+'). Next, we write the response to the stream with fwrite. Finally, we print the stream's contents with stream_get_contents and close it with fclose.

Stream filters

Here we reach one of the most powerful and flexible features of streams in PHP: stream filters.

Imagine the following scenario: you are reading data from a file and need to process it before printing it. With stream filters, you can create a filter that processes the data as needed and attach it to the read stream, without changing the code that reads the data.

For example, you can use a stream filter to convert a text file's contents to uppercase before printing it.

$stream = fopen('data.txt', 'r');
stream_filter_append($stream, 'string.toupper');
echo stream_get_contents($stream);
fclose($stream);

In this example, we open a file called data.txt in read mode ('r'). Then we attach the string.toupper filter to the stream with stream_filter_append, which converts the data to uppercase. Finally, we print the stream's contents with stream_get_contents and close the file with fclose.

The conversion is done automatically by the stream filter while the data is being read, and it does not affect the original file.

You can create your own stream filters to process data however you need.

See the official documentation for more information about stream filters in PHP.

FilterPHP

I prepared an example to help you better understand how a stream filter works.

In this example, we will create a stream filter that keeps only the lines containing the word “PHP”.

<?php

class FilterPHP extends php_user_filter
{
 public $stream;
 public string $filter;

 public function onCreate(): bool {
 $this->stream = fopen('php://temp', 'w+');
 return $this->stream !== false;
 }

 public function filter($in, $out, &$consumed, $closing): int {
 $this->filter = 'PHP';
 $out_data = '';
 while ($bucket = stream_bucket_make_writeable($in)) {
 $line = explode("\n", $bucket->data);
 foreach ($line as $l) {
 if (str_contains($l, $this->filter)) {
 $out_data .= $l . "\n";
 }
 }
 }

 $bucket_out = stream_bucket_new($this->stream, $out_data);
 stream_bucket_append($out, $bucket_out);

 return PSFS_PASS_ON;
 }
}

Let's go through what the code above does, step by step.

We create a class called FilterPHP that extends php_user_filter. This class is used to create a custom stream filter.

If you have worked with classes in PHP, extending a class with such an odd name may look strange. That is because php_user_filter is an internal PHP class that predates the class naming conventions the community established over the years.

The FilterPHP class has two properties: $stream and $filter. $stream holds a temporary stream where the filtered data will be written. $filter holds the filter that will be applied to the data.
The onCreate method is called when the filter is created. In it, we open a temporary stream with fopen('php://temp', 'w+') and store the stream resource in $stream. If the stream cannot be opened, we return false.

The onCreate method acts as a constructor for the filter, and custom stream filters typically implement it to set up their resources.

But what is php://temp? php://temp is a wrapper for creating temporary streams in PHP. Temporary streams are kept in memory or in a temporary file, depending on the size of the data.

4. The filter method is called to filter the stream's data. It receives the following parameters:

$in: the input bucket brigade, from which the original data is read. It is read-only and is passed to the filter.
$out: the output bucket brigade, to which the filtered data is written. It is write-only and is passed to the filter.
&$consumed: the amount of data consumed by the filter. The filter updates this value and it is passed back to PHP.
$closing: indicates whether the stream is being closed. If it is true, the filter should release any resources it allocated.

Note: the & in front of a variable in PHP means it is passed by reference, so changes made inside the function are reflected outside it.

5. In the filter method, we read the input data with stream_bucket_make_writeable. Then we split it into lines with explode("\n", $bucket->data) and check whether each line contains the word "PHP" with str_contains($l, $this->filter).

6. If the line contains the word “PHP”, it is added to $out_data. Then we create a new output bucket with stream_bucket_new and append it to the output with stream_bucket_append.

7. Finally, we return PSFS_PASS_ON to indicate that the filter should keep passing data on to the next filter or to the output stream.

Now that we have created the stream filter, let's attach it to an input stream.

<?php
require_once './FilterPHP.php';
$json = 'https://raw.githubusercontent.com/sschonss/stream-php/main/data.json';
$fileContents = file_get_contents($json);

if ($fileContents === false) {
 die('Failed to fetch data from the endpoint.');
}

stream_filter_register('filterphp', 'FilterPHP') or die("Failed to register filter.");

$tempStream = fopen('php://temp', 'r+');
fwrite($tempStream, $fileContents);
rewind($tempStream);

$out_fp = fopen('php://stdout', 'w') or die("Failed to open output stream.");
stream_filter_append($tempStream, 'filterphp');

while ($data = fread($tempStream, 1024)) {
 $data = str_replace('"name": ', '', $data);
 $data = str_replace('"description": ', '', $data);
 echo $data;
}

fclose($tempStream);
fclose($out_fp);

In this example, we read a JSON file from a URL with file_get_contents and store its contents in a variable called $fileContents.

Then we register the FilterPHP stream filter with stream_filter_register. The first argument is the filter's name, used to attach it to the input stream. The second argument is the filter's class name.

It is important to register the stream filter before attaching it to the input stream, so PHP knows how to handle it.

Next, we open a temporary stream with fopen('php://temp', 'r+') and write the file's contents to it with fwrite. Then we rewind the stream with rewind.

Note: rewind moves the stream's internal pointer back to the beginning. This is needed because the pointer is left at the end of the stream after writing.

Note: a pointer in PHP works like a cursor that marks the current position in the stream.

Then we open an output stream with fopen('php://stdout', 'w') and attach the FilterPHP stream filter to the temporary stream with stream_filter_append.

Finally, we read the data from the temporary stream with fread and print it with echo. Before printing, we strip the name and description keys with str_replace.

At the end, we close the temporary stream and the output stream with fclose.

The output of the code above will look like this (the sample data is in Portuguese):

php-filter_1 | "PHP",
php-filter_1 | "PHP (Hypertext Preprocessor) é uma linguagem de script amplamente utilizada para desenvolvimento web e pode ser embutida em HTML."
php-filter_1 | "Composer é um gerenciador de dependências para PHP, permitindo que você declare as bibliotecas que seu projeto depende e as instale."
php-filter_1 | "Laravel é um framework web PHP, conhecido por sua sintaxe elegante e ferramentas robustas para desenvolvimento rápido de aplicativos."
php-filter_1 | "Symfony é um conjunto de componentes PHP reutilizáveis e um framework web para criar aplicações e sites."
php-filter_1 | "CodeIgniter é um framework PHP poderoso e simples de usar, construído para desenvolvedores que precisam de um toolkit elegante para criar aplicativos web completos."
php-filter_1 | "CakePHP",
php-filter_1 | "CakePHP é um framework PHP rápido de desenvolvimento que proporciona uma estrutura extensível para desenvolvedores criar aplicativos web."
php-filter_1 | "Zend Framework é uma coleção de pacotes PHP profissionais com mais de 570 milhões de instalações."

If you want to try the code above, clone the stream-php repository and run docker-compose up to start the PHP container and test it.

Conclusion

Streams are a powerful and flexible abstraction for working with files and other I/O resources in PHP. With streams, you can read and write data from and to different sources, such as files, strings and network connections, consistently and regardless of where the data comes from or goes to.

You can also use stream contexts to configure streams with specific options, wrappers to open streams over different kinds of resources, stream functions to work with streams efficiently, and stream filters to process data as needed.

I hope this guide helped you better understand how to work with streams in PHP. If you have any questions, suggestions or corrections, feel free to reach out.

See you next time!

JIT (Just in Time) — PHP

Tue, 28 May 2024 00:00:00 -0300

If you haven't upgraded to PHP 8.0 or later yet, it's time to do it. PHP 8.0 was released on November 26, 2020 and brought the JIT (Just In Time) compiler, which is what we are going to talk about today.

Opcode

When you run a PHP script, PHP compiles it into an intermediate code called opcode (PHP Opcode). The opcode is then executed by the Zend virtual machine.

Here is an example of PHP code and its opcode:

PHP:

$a = M_PI;
$b = 10 + sin($a);
echo "Result: ", $b;

Opcode:

Finding entry points
Branch analysis from position: 0
1 jumps found. (Code = 62) Position 1 = -2
filename: /in/ceTlX
function name: (null)
number of ops: 9
compiled vars: !0 = $a, !1 = $b
line #* E I O op fetch ext return operands
-------------------------------------------------------------------------------------
 2 0 E > ASSIGN !0, 3.14159
 3 1 INIT_FCALL 'sin'
 2 SEND_VAR !0
 3 DO_ICALL $3
 4 ADD ~4 10, $3
 5 ASSIGN !1, ~4
 4 6 ECHO 'Result%3A+'
 7 ECHO !1
 5 8 > RETURN 1

Basically, opcode is a sequence of instructions that the Zend virtual machine executes.

JIT

So where does the JIT come in? The JIT is a compiler that compiles opcode into native machine code. In other words, it turns opcode into machine code that the CPU can execute directly.

This way, we no longer use the Zend virtual machine to execute the opcode, but the native machine code generated by the JIT.

Enabling the JIT

The JIT is not enabled by default. To enable it, you need a few extra steps.

First, you need to install the opcache extension:

sudo apt-get install php8.0-opcache

Then, you need to enable the JIT in the PHP configuration file (php.ini):

[opcache]
opcache.enable=1
opcache.jit_buffer_size=100M
opcache.jit=tracing
opcache.jit=1205
opcache.enable_cli=1

Here we are enabling the JIT and setting the JIT buffer size to 100 MB. The JIT can run in two modes: tracing and function. The tracing mode is the default and is faster, while the function mode is more precise.

To better understand the difference between the tracing and function modes, I recommend reading the official documentation.

Finally, we enable the JIT for the command line (opcache.enable_cli=1).

Benchmark

If you run PHP on the web, the JIT may not make much difference. But if you run PHP scripts on the command line, the JIT can bring a big performance gain.

So let's run a benchmark to compare PHP 8.0 performance with and without the JIT.

In the php-jit-doc repository you will find a PHP script that calculates a lot of things to keep the processor busy.

We won't go into the details of how this script is written or its patterns, since the focus is the JIT.

Let's run the script without the JIT:

./start.sh

The result was:

Execution time: 6.2343468666077 seconds
Encrypted: 46d37684d6032ef0167c00d29f3358d5a180438d3e8604e4c11728699d78fdb0a32284bfa8234ed59f69e7febd0d23bebab983211565582a98da8cb5c8800e42

Now let's enable the JIT and run the script again:

./start-jit.sh

The result was:

Execution time: 3.292811870575 seconds
Encrypted: 46d37684d6032ef0167c00d29f3358d5a180438d3e8604e4c11728699d78fdb0a32284bfa8234ed59f69e7febd0d23bebab983211565582a98da8cb5c8800e42

With the JIT enabled, the PHP script ran 3 seconds faster. That is a very significant performance gain.

But remember, the JIT is not a silver bullet. It may not make much difference for PHP scripts that run on the web. For PHP scripts that run on the command line, however, the JIT can bring a big performance gain.

Conclusion

This was a brief overview of the JIT in PHP 8.0. If you want to learn more about it, I recommend reading the official documentation.

I only brought basic, teaching examples so you can understand what the JIT is and how to enable it. I think it was important to cover this first so we can talk about more complex and advanced topics.

If you liked this content, leave a comment and share it with your friends. See you next time!

Parallel and Asynchronous Programming with PHP

Thu, 25 Apr 2024 00:00:00 -0300

Photo by Ben Griffiths on Unsplash

Introduction

PHP is a general-purpose programming language widely used for web development. However, PHP can also be used for desktop applications, automation scripts and more. In this article, we will explore using PHP for parallel and asynchronous programming.

Parallel Programming

Parallel programming is a programming paradigm that splits a problem into smaller parts that can run at the same time. In PHP, parallel programming can be done with the parallel extension or the pthreads extension, which let you create threads in PHP.

But do you know what a thread is?

A thread is a basic unit of processing that can run independently. In a parallel program, several threads can run at the same time, which can result in a significant performance boost.

When you buy a multi-core processor, you are buying the ability to run several threads at the same time. However, to take full advantage of that, the software has to be built to use those resources efficiently.

Parallel Programming Example in PHP

<?php
use function parallel\run;

class DataProcessor
{
 public function process(array $data): array {
 $formattedData = $this->formatData($data);
 $excel_file = $this->generateExcel($formattedData);
 $this->sendEmail($excel_file, Auth::user()->email);
 }
}

$data = range(1, 1000);
$processor = new DataProcessor();

$parallelResult1 = run(function () use ($processor, $data) {
 return $processor->process($data);
});

$parallelResult2 = $processor->process($data);

In the example above, we use the parallel extension to run the process method of the DataProcessor class in parallel. This means the method runs in a separate thread, which can result in better performance.

This is not a silver bullet, and it is not always the best solution for every problem. In some cases, however, parallel programming can be an efficient way to improve an application's performance.

The example above is quite simplified, but it shows how parallel programming can be used in PHP. For more information about the parallel extension, see the official documentation.

Here is an image illustrating parallel programming:

Illustration of parallel programming, taken from the internet.

Note that parallel programming is different from asynchronous programming. In parallel programming, several threads run at the same time, while in asynchronous programming several tasks can run concurrently, but not necessarily at the same time.

Asynchronous Programming

Asynchronous programming is a programming paradigm that runs tasks concurrently, without waiting for one task to finish before starting another. In PHP, asynchronous programming can be done with the swoole extension, which lets you create asynchronous web servers in PHP.

But do you know what an asynchronous web server is?

An asynchronous web server is a server that can handle several requests at the same time without creating a new thread for each one. This makes the server more efficient and able to handle a large number of requests concurrently.

You may see the term “self-contained server” in some places, but the idea is the same: a server that can handle several requests at the same time without creating a new thread for each one.

Asynchronous Programming Example in PHP

use Swoole\Http\Server;
$server = new Server("0.0.0.0", 9501);

$server->on("start", function (Server $server) {
 echo "Server started at http://{$server->host}:{$server->port}\n";
});

$server->on("request", function ($request, $response) {
 $data = $request->rawContent();
 $response->end("Received data: $data");
});

$server->start();

In the example above, we use the swoole extension to create an asynchronous web server in PHP. The server listens on port 9501 and answers every request with a message containing the data it received.

This example is quite simplified, but it shows how asynchronous programming can be used in PHP. For more information about the swoole extension, see the official documentation.

Here is an image illustrating asynchronous programming:

Illustration of asynchronous programming, taken from the internet.

Request Lifecycle in PHP-FPM

When a request is made to a PHP web server such as PHP-FPM, the server goes through several steps to process it and return a response to the client. The lifecycle of a request in PHP-FPM can be split into these steps:

Receiving the Request: The web server (Apache, Nginx, etc.) receives the client's request and forwards it to PHP-FPM.
Process Pool: PHP-FPM keeps a pool of preloaded PHP processes to handle requests. When a request arrives, PHP-FPM picks an available process to handle it.
Autoload: PHP-FPM loads the files needed to process the request, including the classes and functions used in the PHP script. Classes and functions are loaded automatically by PHP, following the autoload rules defined in composer.json.
Parsing and Compilation: PHP parses the PHP script and compiles the code into a form the PHP interpreter can execute.
Script Execution: PHP executes the script, processing its instructions and generating the request's output.
Building the Response: PHP-FPM builds the response, including the HTTP headers and the response body.
Sending the Response: PHP-FPM sends the response to the web server, which forwards it back to the client.
Ending the Process: After sending the response, the PHP process finishes and returns to the pool of processes available for new requests.

The lifecycle of a request in PHP-FPM can vary depending on the web server and PHP-FPM configuration. However, these steps are common to most PHP web servers.

Request Lifecycle in Swoole

When a request is made to an asynchronous PHP web server such as Swoole, the server goes through several steps to process it and return a response to the client. The lifecycle of a request in Swoole can be split into these steps:

The lifecycle starts when the Swoole server boots and sets up the PHP script that will handle requests. The Swoole server listens on a specific port and waits for requests to arrive.

At this point, the server already has autoload configured, the required classes and functions are already loaded, and the PHP script is ready to handle requests.

Receiving the Request: When a request reaches the Swoole server, the server receives it and passes it to the PHP script configured to handle it.
Processing the Request: The PHP script processes the request, running the instructions needed to generate the response.
Parsing and Compilation: PHP parses the PHP script and compiles the code into a form the PHP interpreter can execute.
Script Execution: PHP executes the script, processing its instructions and generating the request's output.
Building the Response: The PHP script builds the response, including the HTTP headers and the response body.
Sending the Response: The Swoole server sends the response to the client, ending the request's lifecycle.

At that point, the Swoole server is ready for new requests, keeping a pool of PHP processes available to handle them asynchronously.

The difference between the request lifecycle in PHP-FPM and in Swoole lies in how the PHP server boots and how requests are processed. In PHP-FPM, each PHP process is set up to handle one request at a time, while in Swoole the PHP server is set up to handle many requests asynchronously.

Conclusion

In this article, we explored using PHP for parallel and asynchronous programming. Parallel and asynchronous programming are techniques that can improve an application's performance and handle a large number of requests efficiently.

There are no hard rules, and parallel or asynchronous programming is not always the best solution to a problem. Still, it is always good to know the different techniques available and when to use them well.

I hope this article was useful and that you learned something new about parallel and asynchronous programming in PHP. In the future, I hope to write a more detailed article about each of these techniques, with more complex examples.

If you have any questions, corrections or suggestions, feel free to reach out. Thanks for reading this far!

References

Author

Luiz Schons