AMQP Agent

An elegant wrapper around the famous php-amqplib for 90% use case. [![PHP Version][php-icon]][php-href] [![Latest Version on Packagist][version-icon]][version-href] [![License][license-icon]][license-href] [![Maintenance][maintenance-icon]][maintenance-href] [![Documentation][documentation-icon]][documentation-href] [![Total Downloads][downloads-icon]][downloads-href] [![Scrutinizer Build Status][scrutinizer-icon]][scrutinizer-href] [![Scrutinizer Code Coverage][scrutinizer-coverage-icon]][scrutinizer-coverage-href] [![Scrutinizer Code Quality][scrutinizer-quality-icon]][scrutinizer-quality-href] [![Travis Build Status][travis-icon]][travis-href] [![StyleCI Code Style][styleci-icon]][styleci-href]

Table of Contents

[Installation](#installation)
[About AMQP Agent](#about-amqp-agent)
[API](#api)
Documentation
[Configuration](#configuration)
[Examples](#examples)
[Links](#links)
[License](#license)
[Changelog](./CHANGELOG.md)

Key Features

1. Framework agnostic, integrates easily in any codebase
2. An intuitive and tested API with out-of-the-box support for Publishers, Consumers, and RPC Endpoints
3. Contains tons of helpers to get you up and running in no time without deep knowledge of the topic
4. Unlimited flexibility when it comes to customizing it to your exact needs
5. Actively maintained, well documented and all about syntactic sugar.

Installation

Try AMQP Agent out now:

Composer using Packagist:

Composer using GitHub Repo (unstable):

Copy this configuration in your composer.json:

Run:

Note: AMQP Agent supports now PHP 7.1 by default starting from version v1.1.1, if you used the php7.1-compatibility branch in older versions, update your composer.json!

About AMQP Agent

AMQP Agent tries to simplify the implementation of a message-broker in a PHP project. It takes away the entire overhead of building and configuring objects or creating classes that you would need in order to talk with RabbitMQ server (through php-amqplib) and exposes a tested, fully configurable, and flexible API that fits almost any project.

The php-amqplib library is awesome and works very well. The one and only problem is, it's pretty bare-bone to be used in a project, without remaking your own wrapper classes, it's almost impossible to not write spaghetti code. Plus the enormous amount of functions, methods, and configurations (parameters) that come with it make it really hard to implement a reasonable API to be used. AMQP Agent solves this problem by making as much abstraction as possible without losing control over the workers and by bringing back the terminology associated with message-brokers, a Publisher and a Consumer is all that you need to deal with if you are a newcomer.

According to this motto, AMQP Agent makes working with RabbitMQ as fun and elegant as possible by exposing some fluent interfaces that are cleverly implemented, fit modern PHP development, nice to work with and very simple to use; yet very powerful and can overwrite the smallest quirks at any point of working with the worker. With AMQP Agent you can start publishing and consuming messages with just a few lines of code!

AMQP Agent does not overwrite anything of php-amqplib nor it does change the terminology associated with its functions. It only simplifies it; takes out the noise of functions' names and extends it in some places. It also adds some nice features like workers-commands, dynamic channel-waiting, and facilitation methods.

AMQP Agent does also offer a powerful event-based RPC Client and RPC Server for your IoT projects.

Working with AMQP Agent can be as easy as:

API

AMQP Agent exposes a number of concrete classes that can be directly used and other abstract classes that can be extended. These two class-variants also have a helper sub-division.

AMQP Agent Classes

See also: AbstractWorkerSingleton, PublisherSingleton, ConsumerSingleton, AbstractWorkerInterface, PublisherInterface, ConsumerInterface, WorkerFacilitationInterface, WorkerMutationTrait, WorkerCommandTrait, AbstractEndpointInterface, ClientEndpointInterface, ServerEndpointInterface, EventTrait, ArrayProxyTrait, ClassProxyTrait, AbstractParameters.

Bibliography

• *C Concrete: This class is a concrete class and can be instantiated directly.
• *A Abstract: This class is an abstract class and cannot be instantiated directly.
• *H Helper: This class is a helper class. Third-party alternatives can be freely used instead.
• *R Recommended: This class is recommended to be used when working with AMQP Agent (best practice).
• S Singleton: This class has a singleton version available via suffixing the class name with Singleton and can be retrieved via `Singleton::getInstance(), i.e.Publisher->PublisherSingleton`.

Note: Singleton is considered an anti-pattern, try avoiding it as much as possible, though there are use-cases for it. Use singletons only if you know what you are doing.

Configuration

If you just quickly want to publish and consume messages, everything is ready and configured already, AMQP Agent is shipped with a tested configuration that follows best practices. You can simply import Publisher class and/or Consumer class in your file and overwrite the parameters you want (RabbitMQ credentials for example) later on the instance.

If you want to fine-tune and tweak AMQP Agent configuration to your exact needs, there is a bit of work to do. You have to supply a config file (see: maks-amqp-agent-config.php and pay attention to the comments). You don't have to supply everything, you can simply only write the parameters you want to overwrite, AMQP Agent is smart enough to append the deficiency. These parameters can also be overwritten later through public assignment notation or per method call.

Fact: AMQP Agent uses the same parameter names as php-amqplib in the config file and in the parameters array passed on the method call.

Here is an example of a config file

Note: Array first-level key names (suffixed with Options) are specific to AMQP Agent.

Examples

Before we start with examples, we have to clarify a few things. It's worth mentioning from the beginning that with AMQP Agent there are multiple ways to how you can retrieve a worker, there is the simple way, the recommended way, and the more advanced ways. After you retrieve a worker, it's like clay, you can form it the way you want. This modular design gracefully accommodates your needs, drives to a scalable codebase, and simply makes everyone happy.

The ways a worker can be retrieved

1. The simplest way is to instantiate a worker directly i.e. using new keyword. This way requires passing parameters via the constructor, method calls, or public property assignment.
2. The more advanced way is retrieving a singleton worker i.e PublisherSingleton::getInstance(). This way requires passing parameters via getInstance() method, method calls, or public property assignment.
3. The more advanced but recommended way is to use an instance of the Client class. This way also makes code more readable as the parameters are retrieved from the passed config.

Here are some examples of a publisher

1. Variant I: Passing parameters in worker's constructor.

2. Variant II: Overwriting parameters per method call.

Here are some examples of a consumer

1. Variant I: Passing parameters in worker's constructor.

2. Variant II: Overwriting parameters per method call.

Here are some examples of an RPC client

1. Variant I: Passing parameters in client's constructor.

2. Variant II: Overwriting parameters per method call.

Here are some examples of an RPC server

1. Variant I: Passing parameters in server's constructor.

2. Variant II: Overwriting parameters per method call.

Fact: When supplying parameters provide only the parameters you need. AMQP Agent is smart enough to append the deficiency.

Advice: You can simplify the heavy constructors written in the examples above if you use get($className) on an instance of the Client class after providing a config file with the parameters you want.

Note: Refer to AMQP Agent Docs for the full explanation of the methods. Refer to RabbitMQ Documentation and php-amqplib for the full explanation of the parameters.

Advanced Examples

In these examples, you will see how you would work with AMQP Agent in a real-world scenario.

• Publisher Example: You will see here how you would publish messages with priority to a queue. Use workers-commands to start additional consumers (sub-processes/threads) for redundancy in case a consumer fails and publish channel-closing commands to close consumers' channels after they finish.

• Consumer Example: You will see here how you would consume messages. Read workers-commands to start additional consumers (sub-processes/threads) and close consumers' channels.

• RPC Client Example: You will see here how you would send request to the RPC Server and add additional functionality to the endpoint by using the events it offers.

• RPC Server Example: You will see here how you would respond to request from the RPC Client and add additional functionality to the endpoint by using the events it offers.

Fact: You can make the code in Publisher/Consumer Advanced Examples way more easer if you make all parameters' changes in a config file and pass it to the client instead of the default.

Advice: AMQP Agent code-base is well documented, please refer to this link to have a look over all classes and methods.

Links

• Documentation: Full API
• Dependency: php-amqplib

License

AMQP Agent is an open-sourced package licensed under the php-amqplib license.
Copyright (c) 2020 Marwan Al-Soltany. All rights reserved.