1.Introduction.md

Documentation - introduction

SlmQueue is a job queue abstraction layer. It allows you to easily use job queue systems in a Laminas application. Thereby it does not enforce you to specifically use one type of job queue. You can write your code and jobs independent of the underlying system. This enables great flexibility and decoupling of the systems.

Why a queue system?

In PHP applications, the request/response cycle is vital to have a fast response time. The earlier you can return a response, the better it is for your visitors. However, if you need to perform a lot of processing, the response time will be extended. If these processing tasks contain pieces of code which can be executed at a later moment (say, 5 minutes later) they are an excellent candidate for a job queue system.

A job queue system allows you to perform some work in the background, independent from the request/response cycle in your MVC application. If a client visits a page, the controller will tell the queue to perform a job at a later moment. Next, the controller can return a response very fast, without the waiting on this job. Some examples of a job are:

1. Send an email
2. Create a PDF file
3. Connect to a third party server over HTTP

A typical sketch of a job queue system is the following:

Request   __________       _______           ________
------>  |         |      |       |         |        |
         | Server  | ---> | Queue |  -----> | Worker |
Response |         |      |       |   ^--|  |        |
 <------ |_________|      |_______|         |________|

The server sends jobs to the queue. There is a worker which waits until a job arrives. If it got one, it executes the job and waits again until the next job arrives. The worker is in most cases a long running process, processing jobs one by one. If the workload is too much for one worker, you can let two workers process the same queue.

A queue abstraction layer

SlmQueue is called a job queue abstraction layer. This layer sits in between your application and the queue system. The benefit of such layer, is your application is indepedent from the queue system.

Currently, SlmQueue supports beanstalkd, Amazon SQS and Doctrine. A layer like this makes it possible to use Doctrine first as your application starts small. If the system grows, you might want to migrate something more mature like beanstalkd or SQS. Without an abstraction layer, you have to rewrite your complete code to support the new system. With SlmQueue in place, you simply switch a configuration parameter and all your code still works.

Another typical example are your different application environments. On your local machine, you just run SlmQueue on top of Doctrine or beanstalkd. With your application hosted at Amazon's EC2, your production environment might use the SQS adapter (although it is not required to use SQS with EC2 or vice versa). All these different adapters are irrelevant for your application, making it very flexible to switch, test and try all implementations.

The SlmQueue architecture

SlmQueue consists of three main components: a Job, a Queue and a Worker. Besides these, there is a controller, a CLI command and several factory classes.

The Job class represents a single job. An example from above is sending an email. The job describes this specific task by wrapping the code to send an email inside a Job object. You create your own class (for instance, EmailJob) which has to implement the interface SlmQueue\Job\JobInterface. Inside the execute() method, all logic is placed to send this email. If you need to perform various tasks through a job queue, you write for every job a separate class.

The Queue class is a direct representation of a queue implementation. All different queues implement the same SlmQueue\Queue\QueueInterface. For every implementation (beanstalkd, SQS or Doctrine, at this moment) there is a class implementing this interface. The object is the main point of entry to insert jobs in the queue and retrieve them back from it.

The Worker class consumes a Queue object and interacts with it to extract jobs from the queue and execute the job. The worker represents the long running process Every implementation has its own worker, accepting a queue from a certain type. This way, a worker can handle accordingly to the general flow of jobs from the specific implementation.

Navigation

Next page: Configuration

1. Introduction
2. Configuration
3. Jobs
4. QueueAware
5. Workers
6. Events
7. Worker management