<commit_before>Documentation - Events
====================

SlmQueue triggers events at selected moments in the worker code flow. This enables users of SlmQueue to create hooks at
several points:

 * `WorkerEvent::EVENT_PROCESS_QUEUE_PRE`: just before queue processing starts
 * `WorkerEvent::EVENT_PROCESS_QUEUE_POST`: just after processing ends
 * `WorkerEvent::EVENT_PROCESS_JOB_PRE`: just before a job will be processed
 * `WorkerEvent::EVENT_PROCESS_JOB_POST`: just after a job has been processed

Any listener waiting for above events will be passed a `WorkerEvent` class which contains a reference to the queue. The
`EVENT_PROCESS_JOB_PRE` and `EVENT_PROCESS_JOB_POST` events also have a reference to the job class.

```php
$em->attach(WorkerEvent::EVENT_PROCESS_JOB_PRE, function(WorkerEvent $e) {
	$queue = $e->getQueue();
	$job   = $e->getJob();
});
```

In above example, `$em` refers to the event manager inside the worker object: `$em = $worker->getEventManager();`.

Using the shared event manager
------------------------------

Instead of direct access to the worker's event manager, the shared manager is available to register events too:

```php
namespace MyModule;

use SlmQueue\Worker\WorkerEvent;
use Zend\Mvc\MvcEvent;

class Module
{
	public function onBootstrap(MvcEvent $e)
	{
		$em       = $e->getApplication()->getEventManager();
		$sharedEm = $em->getSharedManager();

		$sharedEm->attach('SlmQueue\Worker\WorkerInterface', WorkerEvent::EVENT_PROCESS_QUEUE_PRE, function(){
			// log the start of the worker processing
		});
	}
}
```

Using an aggregate listener
---------------------------

If it is required to listen at multiple events, an aggregate listener is a powerful tool to hook into multiple events of
the same event manager. A good example is i18n: a job is given a locale if the job performs localized actions. This
locale is set to the translator just before processing starts. The original locale is reverted when the job has finished
processing.

In this case, all jobs which require a locale set are implementing a `LocaleAwareInterface`:

```php
namespace MyModule\Job;

interface LocaleAwareInterface
{
    /**
     * @param string $locale
     */
    public function setLocale($locale);

    /**
     * @return string
     */
    public function getLocale();
}
```

An aggregate listener will listen for two events to set and revert the locale:

```php
namespace MyModule\Listener;

use MyModule\Job\LocaleAwareInterface;
use SlmQueue\Worker\WorkerEvent;

use Zend\EventManager\AbstractListenerAggregate;
use Zend\EventManager\EventManagerInterface;
use Zend\I18n\Translator\Translator;

class JobTranslatorListener extends AbstractListenerAggregate
{

    /**
     * @var Stores original locale while processing a Job
     */
    protected $locale;

    /**
     * @var Instance of Translator
     */
    protected $translator;

    /**
     * @param Translator $translator
     */
    public function __construct(Translator $translator)
    {
        $this->translator = $translator;
    }

    /**
     * {@inheritDoc}
     */
    public function attach(EventManagerInterface $events)
    {
        $this->handlers[] = $events->attach(WorkerEvent::EVENT_PROCESS_JOB_PRE, array($this, 'onPreJobProcessing'));
        $this->handlers[] = $events->attach(WorkerEvent::EVENT_PROCESS_JOB_POST, array($this, 'onPostJobProcessing'));
    }

    protected function onPreJobProcessing(WorkerEvent $e)
    {
        $job = $e->getJob();

        if (!$job implements LocaleAwareInterface) {
            return;
        }

        $this->locale = $this->translator->getLocale();
        $this->translator->setLocale($job->getLocale());
    }

    protected function onPostJobProcessing(WorkerEvent $e)
    {
        $job = $e->getJob();

        if (!$job implements LocaleAwareInterface) {<commit_msg>Apply patches from PRs against old master<commit_after>Documentation - Events
====================

SlmQueue triggers events at selected moments in the worker code flow. This enables users of SlmQueue to create hooks at
several points:

 * `WorkerEvent::EVENT_PROCESS_QUEUE_PRE`: just before queue processing starts
 * `WorkerEvent::EVENT_PROCESS_QUEUE_POST`: just after processing ends
 * `WorkerEvent::EVENT_PROCESS_JOB_PRE`: just before a job will be processed
 * `WorkerEvent::EVENT_PROCESS_JOB_POST`: just after a job has been processed

Any listener waiting for above events will be passed a `WorkerEvent` class which contains a reference to the queue. The
`EVENT_PROCESS_JOB_PRE` and `EVENT_PROCESS_JOB_POST` events also have a reference to the job class.

```php
$em->attach(WorkerEvent::EVENT_PROCESS_JOB_PRE, function(WorkerEvent $e) {
	$queue = $e->getQueue();
	$job   = $e->getJob();
});
```

In above example, `$em` refers to the event manager inside the worker object: `$em = $worker->getEventManager();`.

Using the shared event manager
------------------------------

Instead of direct access to the worker's event manager, the shared manager is available to register events too:

```php
namespace MyModule;

use SlmQueue\Worker\WorkerEvent;
use Zend\Mvc\MvcEvent;

class Module
{
	public function onBootstrap(MvcEvent $e)
	{
		$em       = $e->getApplication()->getEventManager();
		$sharedEm = $em->getSharedManager();

		$sharedEm->attach('SlmQueue\Worker\WorkerInterface', WorkerEvent::EVENT_PROCESS_QUEUE_PRE, function(){
			// log the start of the worker processing
		});
	}
}
```

Using an aggregate listener
---------------------------

If it is required to listen at multiple events, an aggregate listener is a powerful tool to hook into multiple events of
the same event manager. A good example is i18n: a job is given a locale if the job performs localized actions. This
locale is set to the translator just before processing starts. The original locale is reverted when the job has finished
processing.

In this case, all jobs which require a locale set are implementing a `LocaleAwareInterface`:

```php
namespace MyModule\Job;

interface LocaleAwareInterface
{
    /**
     * @param string $locale
     */
    public function setLocale($locale);

    /**
     * @return string
     */
    public function getLocale();
}
```

An aggregate listener will listen for two events to set and revert the locale:

```php
namespace MyModule\Listener;

use MyModule\Job\LocaleAwareInterface;
use SlmQueue\Worker\WorkerEvent;

use Zend\EventManager\AbstractListenerAggregate;
use Zend\EventManager\EventManagerInterface;
use Zend\I18n\Translator\Translator;

class JobTranslatorListener extends AbstractListenerAggregate
{
    /**
     * @var Stores original locale while processing a Job
     */
    protected $locale;

    /**
     * @var Instance of Translator
     */
    protected $translator;

    /**
     * @param Translator $translator
     */
    public function __construct(Translator $translator)
    {
        $this->translator = $translator;
    }

    /**
     * {@inheritDoc}
     */
    public function attach(EventManagerInterface $events)
    {
        $this->listeners[] = $events->attach(WorkerEvent::EVENT_PROCESS_JOB_PRE, array($this, 'onPreJobProcessing'));
        $this->listeners[] = $events->attach(WorkerEvent::EVENT_PROCESS_JOB_POST, array($this, 'onPostJobProcessing'));
    }

    public function onPreJobProcessing(WorkerEvent $e)
    {
        $job = $e->getJob();

        if (!$job implements LocaleAwareInterface) {
            return;
        }

        $this->locale = $this->translator->getLocale();
        $this->translator->setLocale($job->getLocale());
    }

    public function onPostJobProcessing(WorkerEvent $e)
    {
        $job = $e->getJob();

        if (!$job implements LocaleAwareInterface) {
{'fraction_non_alphanumeric': 0.11677695601401324, 'fraction_numerical': 0.0010380173867912288, 'mean_word_length': 3.665859564164649, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 45, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3256464', 'n_tokens_mistral': 2211, 'n_tokens_neox': 2131, 'n_words': 702}