Skip to content

Latest commit

 

History

History
145 lines (110 loc) · 5.9 KB

README.md

File metadata and controls

145 lines (110 loc) · 5.9 KB
Raw

Mage Resque

Mage Resque is a lightweight Magento implementation of the PHP Resque library and job runner. PHP Resque itself is based on Ruby's Resque, a Redis backed background job processing library.

Getting started

Licence

Mage Resque is covered by the MIT opensource licence. Unless specifically stated otherwise, terms of use are as laid out in the included LICENCE file.

Requirements

  • PHP 7.2+
  • Redis 2.2+
  • ext-pcntl
  • Magento 1.9.3.9+
  • Composer

Installation

Mage Resque uses Composer and Magento Composer Installer to handle installation of the module and its dependencies. To install Mage Resque you will need a copy of composer.phar in your path. If you do not have it availble, run the following commands from your terminal.

$ curl -sS https://getcomposer.org/installer | php
$ chmod a+x composer.phar

If you are already using Magento Composer Installer and have an existing composer.json, add https://github.com/ajbonner/mage-resque to the repositories list and ajbonner/mage-resque as a required dependency for your project. That's it!

If you do not have an existing Magento Composer Installer composer.json file defined, you can use the following template.

{
    "require": {
        "ajbonner/mage-resque": "*"
    },
    "require-dev": {
        "fbrnc/Aoe_Profiler": "*",
        "MageTest/Mage-Test": "*"
    },
    "repositories": [
    {
        "type": "vcs",
        "url": "https://github.com/magento-hackathon/magento-composer-installer"
    },
    {
        "type": "vcs",
        "url": "https://github.com/ajbonner/magento-composer-autoload"
    },
    {
        "type": "vcs",
        "url": "https://github.com/ajbonner/mage-resque"
    },
    {
        "type": "vcs",
        "url": "https://github.com/MageTest/Mage-Test"
    },
    {
        "type": "vcs",
        "url": "https://github.com/fbrnc/Aoe_Profiler"
    }
    ],
    "extra":{
        "magento-root-dir": "./"
    },
    "config": {
        "bin-dir": "shell"
    },
    "minimum-stability": "dev"
}

To install Mage Resque and its dependencies just run composer.phar.

$ ./composer.phar install

Configuration

PHP Resque is a Redis backed job queue, and you will need access to a running Redis instance. To use a particular Redis server and database, add the following xml snippet to local.xml.

<!-- This is a child node of config for Magento CE -->
<default>
    <mnsresque>
        <redis>
            <backend>localhost:6379</backend>
            <database>1</database>
        </redis>
    </mnsresque>
</default>

If you use Redis for Magento caching or as a session store, e.g. you use one of Colin Mollenhour's excellent modules, then make sure you select an alternate database, or better yet, a separate Redis instance that is exclusively for Mage Resque.

If you are storing your binaries in a different directory, you can specify it in local.xml as well:

<default>
    <mnsresque>
       ...
       <env>
         <bin_dir>bin</bin_dir>
       </env>
    </mnsresque>
</default>

You can configure the number of resque workers to start by adding a <num_workers/> element to your mnsresque env configuation:

<default>
    <mnsresque>
       ...
       <env>
         ...
         <num_workers>4</num_workers>
       </env>
    </mnsresque>
</default>

All configuration options can be found in app/code/community/ajbonner/mage-resque/etc/config.xml in the defaults section.

Usage

PHP Resque has two functions, to add jobs to Redis backed job queues, and to manage workers processing jobs from those queues.

As an example, let's add a simple job to a queue that writes a message to Magento's system log. Mage Resque bundles Mns_Resque_Model_Job_Logmessage to do just this.

$resque = Mage::getSingleton('mnsresque/factory')->create();
$resque->addJob(
	'Mns_Resque_Model_Job_Logmessage',
	array('message'=>'foo'));

You can pass any classname to addJob that identifies a class implementing a process() method. You can find out more about how Job classes work in the PHP Redis README.

To process the queue and run background jobs, Mage Resque provides a job runner in the shell directory. To start it run the following command from your terminal.

$ php shell/resque.php --daemon

To stop the daemon gracefully (allow workers to finish their current job) run the following command.

$ php shell/resque.php --quit

To stop the daemon immediately (which means stopping workers potentially in the middle of a job) use the --terminate option.

$ php shell/resque.php --terminate

Running Unit Tests

Mage Resque comes bundled with a UnitTest Suite. This suite serves as a regression safety net and as rough documentation on the use of the module. To execute the tests you will need to install Mage Resque's development dependencies.

$ composer.phar install --dev

If you have ran composer.phar install, you will need to delete composer.lock and the vendor directory, then re-run install with the --dev argument.

To run the tests, in your Magento root directory, issue the following command from your terminal.

$ phpunit -c vendor/ajbonner/mage-resque/tests/phpunit.xml

Feedback and pull requests are very welcome. You can get in touch with me on twitter @ajbonner or via the issues system here on github.