Repository files navigation

This package provides an easy wayto put PHP tasks of any kindinto a work queuesuch as Beanstalkd or Redisto execute them at a later time.

This isversion 0.21.1.

$ composer require mle86/wq

It requires PHP 8.0+and has no other dependencies(apart from PHPUnit/Coveralls for developmentand the PSR-3 interfaces).

You'll also want to install at least one other packagewhich contains aWorkServerAdapter implementation,such as:

• mle86/wq-beanstalkd(Beanstalkd server adapter),
• mle86/wq-redis(Redis server adapter),
• mle86/wq-amqp(RabbitMQ server adapter).

• AJob is something which should be done exactly once.Maybe it's sending an e-mail,maybe it's an external API call like a webhook,maybe it's some slow clean-up process.In any case, we're talking about a unit of workthat could be executed right awaybut it would be better for the application's performanceto put it in aWork Queue instead, so it can be done asynchronously.

• AWork Queue is a list of jobs that should be executed at some other time.They are stored in some kind ofWork Server.One work server well-known in the PHP world isBeanstalkd.It can store any number of work queues, although it calls them “tubes”.

Different work queues, or tubes, are commonly used to separate job types.For example, the same work server might haveone “mail” queue for outgoing mails to be sent,one “cleanup” queue for all kinds of clean-up jobs,and one “webhook” queue for outgoing web-hook calls.

This package provides some helpful classesto set up a simple work queue system.

This is our Job implementation.It represents an e-mail that can be sent.

<?phpusemle86\WQ\Job\AbstractJob;class EMailextends AbstractJob{protected$recipient;protected$subject;protected$message;publicfunction__construct(string$recipient,string$subject,string$message)    {$this->recipient =$recipient;$this->subject   =$subject;$this->message   =$message;    }publicfunctionsend()    {if (mail($this->recipient,$this->subject,$this->message)) {// ok, has been sent!        }else {thrownew \RuntimeException ("mail() failed");        }    }}

We have some code using that e-mail class:

<?phpusemle86\WQ\WorkServerAdapter\BeanstalkdWorkServer;$mailJob =newEMail("test@myproject.xyz","Hello?","This is a test mail.");$workServer = BeanstalkdWorkServer::connect("localhost");$workServer->storeJob("mail",$mailJob);

And finally,we have our background worker scriptwhich regularly checks the work serverfor new e-mail jobs:

<?phpusemle86\WQ\WorkServerAdapter\BeanstalkdWorkServer;usemle86\WQ\WorkProcessor;$queue ="mail";printf("%s worker %d starting.\n",$queue,getmypid());$processor  =newWorkProcessor(BeanstalkdWorkServer::connect("localhost"));$fn_handler =function(EMail$mailJob) {$mailJob->send();// don't catch exceptions here, or the WorkProcessor won't see them.};while (true) {try {$processor->processNextJob($queue,$fn_handler);    }catch (\Throwable$e) {echo$e ."\n";// TODO: add some real logging here    }}

1. Implementing a Job class
2. Execute or Queue
3. Work the Queue
4. Error Handling
5. Usage Examples

Class reference:

• Job interface
  • AbstractJob base class
  • QueueEntry wrapper class
• WorkServerAdapter interface
  • AffixAdapter wrapper class
  • BlackHoleWorkServer dummy class
• WorkProcessor class
  • SignalSafeWorkProcessor class
  • JobResult enum class
  • JobContext dto class
• Exceptions