Download the PHP package aldemeery/onion without Composer
On this page you can find all versions of the php package aldemeery/onion. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Informations about the package onion
🧅 Onion: A Layering Mechanism for PHP Applications
Onion is a lightweight PHP package designed to facilitate layered processing within applications, It provides a clean and efficient way to stack layers of functionality, allowing developers to create flexible and reusable components that can be easily composed and managed. Each layer can perform a specific operation on the data being passed through, making it simple to build complex workflows while maintaining clear separation of concerns.
- Installation
- How it works
- Onion
- Layers
- Peeling the Onion
- Advanced Usage
- Adding Layers
- Adding Metadata to Layers
- Composing Onions of Other Onions
- Exception Handling
- Usecases and Examples
- PHP Pipe Operator
- PHP League's Pipeline
- Laravel's Pipeline
- PSR-15 Request Handlers
Installation
How it works
Onion
The Onion object is the core component, representing a stack of layers that process data sequentially. Each layer can transform the input data and/or perform specific operations.
To create an Aldemeery\Onion\Onion instance, you can directly instantiate it:
Or, you can use the Aldemeery\Onion\onion helper function for convenience:
Either way, you can optionally pass an initial layer or list of layers as an argument:
Layers
Layers are simple PHP Closures or classes that implement the Aldemeery\Onion\Interfaces\Invokable interface, and they are the essential building blocks of the Onion object, enabling you to define specific operations that are executed during processing.
Layers are executed sequentially in the order they were added, with the output of one layer becoming the input of the next.
[!NOTE] Layers can only accept a single value because PHP functions/methods can only return a single value.
Peeling the Onion
Once your layers are defined and added to the Onion object, you can execute the full stack of layers using the peel() method. This method takes an optional value and passes it as an argument to the first layer, from there the output of each layer is passed as the input of the next layer, with the output of the last layer being returned as the output of the Onion itself.
You can also call peel() without any arguments. Layers also don't necessarily need to return a value:
[!IMPORTANT] Since layers can only accept a single value, the
peel()method passes only the first argument to the first layer, ignoring any additional arguments. To pass multiple values, consider using an array or a DTO.
Because Onion objects themselves are callables, you could directly invoke them as functions, or pass them around as arguments:
Advanced Usage
Adding Layers
You don't need to provide all the layers when instantiating the Onion object.
You can add more layers later by calling the add() method, which accepts either a single layer or an array of layers.
Or for a more fluent approach, you could use the convenience addIf() and addUnless() methods:
Adding Metadata to Layers
Onion provides a way for you to attach metadata to layers. This metadata can be helpful for debugging purposes, allowing you to gain insights into the operations of your layers.
You can attach metadata to layers using the Aldemeery\Onion\Attributes\Layer attribute.
The metadata is stored as an associative array, enabling you to pass any relevant data along with your layers.
Composing Onions of Other Onions
Since Onion objects are Invokable, they can be treated as layers themselves.
This allows you to combine multiple Onions into a single Onion, making it easy to build complex workflows while maintaining simplicity and readability.
For instance:
By composing Onions in this way, you can modularize your layers, promoting reusability and keeping the structure clean even as complexity grows.
Exception Handling
In Onion, each layer you add is automatically wrapped with internal handling that catches exceptions and converts them into a standardized Aldemeery\Onion\Exceptions\LayerException.
This ensures consistent error handling across all layers, giving you full insight into which layer caused the exception and the context surrounding it.
The LayerException encapsulates key information such as the original exception, the passable value (data being processed), the problematic layer, and any metadata attached to that layer.
This makes it easier to trace and debug issues within your layers.
Additionally, LayerException provides several methods to help retrieve this contextual data:
| Method | Description |
|---|---|
getPassable(): mixed |
Retrieves the value that was passed into the layer. |
getLayer(): Closure\|Invokable |
Returns the specific layer that caused the exception. |
getLayerMetadata(): array |
Gets the metadata array associated with the layer. |
getLayerMetadata(string $key): mixed |
Fetches a specific metadata value by key. |
In certain scenarios, you may wish to bypass exception handling entirely.
To do this, simply invoke the withoutExceptionHandling() method on the Onion object:
If you prefer to implement a custom exception handler, you can utilize the setExceptionHandler() method on the Onion object.
An exception handler is defined as a Closure with the following signature: function (Throwable $e, Closure|Invokable $layer, mixed $passable): mixed.
Here's an example:
This approach offers you flexibility in handling exceptions, allowing for tailored behavior based on your application's requirements.
Usecases and Examples
Onion can be applied in various scenarios, making it a versatile tool for structuring data flow and functional composition.
Below are some examples that highlight how Onion simplifies and enhances certain workflows.
PHP Pipe Operator
The RFC to introduce a Pipe Operator in PHP was once proposed but ultimately declined. The operator would have allowed for more intuitive functional composition.
Onion achieves the exact same functionality, allowing you to stack operations in a clean and organized way, just like the proposed pipe operator.
Here’s an example from the RFC, demonstrating how Onion can replace the pipe operator.
Original RFC Example:
Re-written Using Onion:
Similarly, other examples from the RFC can also be adapted using Onion in the same way, showcasing its flexibility in handling sequential transformations.
PHP League's Pipeline
The PHP League offers a robust implementation of the Pipeline pattern, widely used to process data through a series of steps, or "stages", much like Onion. Both Onion and PHP League's Pipeline share a similar goal: they allow developers to sequentially process data through layers, simplifying complex workflows.
However, while both tools provide similar core functionality, Onion offers a more functional syntax with a few distinct features like converting all exceptions to LayerExceptions, conditionally adding layers, and the ability to attach metadata to layers.
Here's an example based on the PHP League's Pipeline documentation and its Onion equivalent:
Using Onion:
Laravel's Pipeline
Laravel provides its own implementation of the Pipeline pattern. However, it is slightly tailored specifically for its framework.
If you're looking for a solution that offers similar functionality without being tied to the Laravel framework, Onion is an excellent alternative.
Here's an example from the Laravel Pipeline documentation re-written using Onion:
Using Onion:
PSR-15 Request Handlers
PSR-15 defines a standardized interface for HTTP server request handlers, which are essential for any web application.
You can implement PSR-15 request handlers as Invokable layers with Onion, allowing for a clean and modular handling of requests.
Here's an example: