↓Skip to main content
IT Blog IT Blog
  1. All Posts/

Fresque

Tools PHP

#Fresque

Fresque is a command line tool to manage your php-resque workers.

##Prerequisites
If you don’t know what is resque or redis, take a look at their official website :

  • Redis : http://redis.io/
  • Resque : https://github.com/resque/resque/
  • Php-Resque : https://github.com/chrisboulton/php-resque/

This tool is intended to facilitate your life by making interfacing with php-resque more easier and more friendly.
You should already have some knowledge about php-resque, and have php-resque installed and running.
I’ll assume in this tutorial that you have sufficient knowledge to start a worker normally with php-resque.
##Requirements

  • Redis
  • sudo package installed on your system

php-resque will be installed automatically as a composer dependency.
##What is Fresque
Fresque is a command line tool to manage your php-resque workers

# Start a worker without fresque
$ QUEUE=file_serve php resque.php

# Starting a worker with fresque
$ fresque start -q file_serve

It’s more friendly, and provides more options, like restart, stop, etc …
Php-resque, and resque, by default doesn’t provide an out-of-the-box way to stop your workers. You have to directly kill the worker process. With Fresque, you’ll enjoy stopping and restarting your workers at gogo. No more system process handling!
##Installation

By cloning the git repo 

$ git clone git://github.com/kamisama/Fresque.git

cd to the Fresque folder you just cloned

$ cd Fresque

Then download Composer

$ curl -s https://getcomposer.org/installer | php

Finally, install dependencies

$ php composer.phar install

Using Composer

If your application is already using Composer, just add Fresque in your composer dependencies

"require": {
    "fresque/fresque": "~1.2.0"
}

and update the dependencies with composer update
##Configuration
A fresque.ini file is provided to set the workers default parameters, and other options used by fresque, such as redis connection options.
It’s well documented, and you shouldn’t have difficulties editing it.
##Usage
For convenience, you should add the fresque executable to your system path.
You can just then call fresque with

$ fresque <command>

Or if you didn’t add it,

$ cd /path/to/fresque
$ ./fresque <command>

If installed as a composer dependency, it’s also available in composer bin folder

$ vendor/bin/fresque <command>

There’s a bunch of interesting commands available :
Examples are available at the end of this section.

  • start

To start a new resque worker. By default, it will use the default configuration defined in you fresque.ini for the queue name, the pooling frequency, and other options. You can override all of them with an option flag. Available options :

-u or --user : User running the php process. Should be the user running your php application, usually www-data for apache. Using a different user could lead to permissions problems.
-q or --queue : A list of queues name polled by the worker, separated with a comma.

-i or --interval : Polling frequency. Number of seconds between each polling.

-n or --workers : Number of workers working on the same queues.

-l or --log : Absolute or relative path to the log file. You can set a different log for each worker.
The --user must have permission to read and write to that file (and the parent folder, since the file will be created if non-existent).
Relative path is relative to the fresque folder.

  • startScheduler

To start the scheduler worker.

-i or --interval : Polling frequency. Number of seconds between each polling.

Scheduler worker is disabled by default, enable it in the configuration file, in the [Scheduler] section. When enabled, it’ll be automatically started when using load().
Only one scheduler worker can run at the same time

  • stop

To stop workers. Will wait for all jobs to finish, then stop the worker. If more than one worker is running, a list of workers will be displayed, to choose the worker to stop.

-f or --force : Stop worker immediately, without waiting for the current job to finish processing. This will fail the current job.
-w or --all : Stop all workers at once, skipping the worker menu.

  • pause

To pause workers. Similary to stop, you’ll be prompted with a worker list if more than one worker is available.

-w or --all : Stop all workers, skipping the worker menu.

  • resume

To resume paused workers. Again, you’ll be prompted with a worker list if there is more than one paused worker.

-w or --all : Stop all workers, skipping the worker menu.

  • restart

To restart all the workers, keeping their settings.

  • load

To start a batch of pre-defined workers (set in your configuration file). See fresque.ini for more informations.

  • stats

Display total number of failed/processed jobs, as well as various stats for each workers and queues.

  • tail

Tail a worker’s log. If you have more than one log file, you’ll be prompted with list of log.

  • enqueue

Add a job to a queue. Takes 3 arguments :

queuename : Name of the queue you will enqueue this job to
jobclass : Name of the class that will perform the job, and that your application autoloader will have to load.
arguments : comma separated list of arguments, passed to the job.

Will print the Job ID if the job is successfully enqueued.
Successfully enqueuing a job does not mean it will perform it successfully

  • test

Test your configuration. If no options are provided, it will test your fresque.ini. It accepts all type of options.
Finally, there’s some global options, that can be used for all commands. Default value in your config file will be used unless you use these.

-s or --host : Redis hostname

-p or --port : Redis port

-b or --lib : Absolute path to the php-resque library. Used when you already have your own, and don’t want to use the one shipped with fresque.

-c or --config : Absolute path to your config file. You can use different config for different workers. Default one is fresque.ini, in the same directory as the executable.

-a or --autoloader : Absolute path to your application entry point. Usually, it should be the file that will autoload all your job classes.

##Examples
Let’s start a worker with the default settings defined in the config file (fresque.ini):

$ fresque start

Let’s start another worker, polling the activity queue, with a polling frequency of 1 second. Also, we’ll want to have two workers working on this queue:

$ fresque start -q activity -i 1 -n 2

If we want another worker, working on the queues default and activity at the same time:

$ fresque start -q default,activity

Oh wait, we have another resque on another redis server. we’ll want to log its activities in another log file: remote.log

$ fresque start -s 192.168.1.26 -p 6390 -q myspecialqueue -l /path/to/remote.log
  • -s 192.168.1.26 is the address of the redis server
  • -p 6390 is the redis server port
  • -q is the queuename
  • -l is the path to the log file

If you have your config file elsewhere, and your php-resque lib elsewhere also

$ fresque start -c /path/to/my-config.ini -b /path/to/my/custom/php-resque

To view stats of your workers (to know how many you have, processed/failed jobs count, uptime, etc …)

$ fresque stats

It should output something like that

-----------------
Resque statistics
-----------------

Jobs Stats
   Processed Jobs : 18,617
   Failed Jobs    :    319

Queues Stats
   Queues count : 3
        - default           : 0 pending jobs
        - myspecialqueue    : 0 pending jobs
        - activity          : 0 pending jobs

Workers Stats
   Active Workers : 6
	Worker : KAMISAMA-MAC.local:33197:default
	 - Started on     : Wed May 16 00:33:04 EDT 2012
	 - Uptime         : less than a minute
	 - Processed Jobs : 0
	 - Failed Jobs    : 0
	Worker : KAMISAMA-MAC.local:33207:default
	 - Started on     : Wed May 16 00:33:08 EDT 2012
	 - Uptime         : less than a minute
	 - Processed Jobs : 0
	 - Failed Jobs    : 0
	Worker : KAMISAMA-MAC.local:33215:myspecialqueue
	 - Started on     : Wed May 16 00:33:10 EDT 2012
	 - Uptime         : less than a...


↑