iron-io / iron_worker
Client library for IronWorker (multi-language worker platform that runs tasks in the background, in parallel, and at scale.)
Installs: 200 920
Dependents: 5
Suggesters: 0
Security: 0
Stars: 56
Watchers: 25
Forks: 23
Open Issues: 4
Requires
- php: >=5.2.0
- iron-io/iron_core: 1.*
This package is not auto-updated.
Last update: 2024-10-26 16:28:22 UTC
README
iron_worker_php is PHP language binding for IronWorker.
IronWorker is a massively scalable background processing system. See How It Works
Getting Started
Branches
1.*
- Laravel 4.0/4.1/4.2/5.0 compatible, PHP 5.2 compatible version. No namespaces.2.*
- Laravel 5.1+ compatible, PSR-4 compatible version with namespaces.master
branch - same as2.*
Get credentials
To start using iron_worker_php, you need to sign up and get an oauth token.
- Go to http://iron.io/ and sign up.
- Get an Oauth Token at http://hud.iron.io/tokens
Install iron_worker_php
There are two ways to use iron_worker_php:
Using composer
Create composer.json
file in project directory:
{ "require": { "iron-io/iron_worker": "2.*" } }
Do composer install
(install it if needed: https://getcomposer.org/download/)
And use it:
require __DIR__ . '/vendor/autoload.php'; $worker = new \IronWorker\IronWorker();
Using classes directly (strongly not recommended)
- Copy classes from
src
to target directory - Grab IronCore classes there and copy to target directory
- Include them all.
require 'src/HttpException.php'; require 'src/JsonException.php'; require 'src/IronCore.php'; require 'src/IronWorker.php'; require 'src/IronWorkerException.php'; $worker = new \IronWorker\IronWorker();
Configure
Three ways to configure IronWorker:
- Passing array with options:
<?php $worker = new \IronWorker\IronWorker(array( 'token' => 'XXXXXXXXX', 'project_id' => 'XXXXXXXXX' ));
- Passing ini file name which stores your configuration options. Rename sample_config.ini to config.ini and include your Iron.io credentials (
token
andproject_id
):
<?php $worker = new \IronWorker\IronWorker('iron.json');
-
Automatic config search - pass zero arguments to constructor and library will try to find config file in following locations:
iron.ini
in current directoryiron.json
in current directoryIRON_WORKER_TOKEN
,IRON_WORKER_PROJECT_ID
and other environment variablesIRON_TOKEN
,IRON_PROJECT_ID
and other environment variables.iron.ini
in user's home directory.iron.json
in user's home directory
Creating a Worker
Here's an example worker:
<?php echo "Hello PHP World!\n";
Upload code to server
Using CLI tool (preferred)
- Get CLI tool
- Download or create
iron.json
config file with project_id/password - Create
HelloWorld.worker
file, example:
runtime 'php' exec 'HelloWorld.php'
- Upload!
$ iron_worker upload HelloWorld
Worker examples
You can find worker examples here: iron_worker_examples
Queueing a Worker
<?php $payload = array() $options = array('label' => 'label_name', 'cluster' => 'dedicated') $task_id = $worker->postTask('HelloWorld', $payload, $options);
queueing options
- priority: The priority queue to run the task in. Valid values are 0, 1, and 2. 0 is the default.
- timeout: The maximum runtime of your task in seconds. No task can exceed 3600 seconds (60 minutes). The default is 3600 but can be set to a shorter duration.
- delay: The number of seconds to delay before actually queuing the task. Default is 0.
- label: Optional text label for your task.
- cluster: cluster name ex: "high-mem" or "dedicated". This is a premium feature for customers to have access to more powerful or custom built worker solutions. Dedicated worker clusters exist for users who want to reserve a set number of workers just for their queued tasks. If not set default is set to "default" which is the public IronWorker cluster.
Scheduling a Worker
postScheduleAdvanced($name, $payload, $start_at, $label = null, $run_every = null, $end_at = null, $run_times = null, $priority = null, $cluster = null)
If you want to run worker tasks in specific time intervals, once at a particular time, or n number of things starting at a specific time you should schedule it:
<?php $options = array('label' => 'label_name', 'cluster' => 'default'); $task_id = $worker->postSchedule('HelloWorkerRuby', $options);
scheduling options
- run_every: The amount of time, in seconds, between runs. By default, the task will only run once. run_every will return a 400 error if it is set to less than 60.
- end_at: The time tasks will stop being queued. Should be a time or datetime.
- run_times: The number of times a task will run.
- priority: The priority queue to run the job in. Valid values are 0, 1, and 2. The default is 0. Higher values means
- tasks spend less time in the queue once they come off the schedule.
- start_at: The time the scheduled task should first be run.
- label: Optional label for adding custom labels to scheduled tasks.
- cluster: cluster name ex: "high-mem" or "dedicated". If not set default is set to "default" which is the public IronWorker cluster.
Status of a Worker
To get the status of a worker, you can use the getTaskDetails()
method.
<?php $task_id = $worker->postTask('HelloWorld'); $details = $worker->getTaskDetails($task_id); echo $details->status; # prints 'queued', 'complete', 'error' etc.
Get Worker Log
Use any function that print text inside your worker to put messages to log.
<?php $task_id = $worker->postTask('HelloWorld'); sleep(10); $details = $worker->getTaskDetails($task_id); # Check log only if task is finished. if ($details->status != 'queued') { $log = $worker->getLog($task_id); echo $log; # prints "Hello PHP World!" }
Loading the Task Data Payload
To provide Payload to your worker simply put an array with any content you want.
<?php $payload = array( 'key_one' => 'Helpful text', 'key_two' => 2, 'options' => array( 'option 1', 'option 2' ) ); $worker->postTask('HelloWorld', $payload); $worker->postScheduleSimple('HelloWorld', $payload, 10) $worker->postScheduleAdvanced('HelloWorld', $payload, time()+3*60, 2*60, null, 5);
When your code is executed, it will be passed four program arguments:
- -id - The task id.
- -payload - the filename containing the data payload for this particular task.
- -d - the user writable directory that can be used while running your job.
- -config - the filename containing config data (if available) for particular code.
IronWorker provide functions getArgs()
, getPayload()
, getConfig()
in your worker to help you using payload:
<?php $args = getArgs(); echo "Hello PHP World!\n"; print_r($args);
Setting Task Priority
You can specify priority of the task by setting the corresponding parameter.
$options = array('priority' => 1); # Run task with medium priority $worker->postTask('HelloWorld', $payload, $options);
Value of priority parameter means the priority queue to run the task in. Valid values are 0, 1, and 2. 0 is the default.
Setting progress status
To set current task progress, just call setProgress($percent, $message)
inside your worker.
- percent - A percentage value that can be set to show how much progress a task is making
- msg - A human readable message string that can be used when showing the status of a task
To retrieve this data on client side, use $worker->getTaskDetails($task_id);
Troubleshooting
http error: 0
If you see Uncaught exception 'Http_Exception' with message 'http error: 0 | '
it most likely caused by misconfigured cURL https certificates.
There are two ways to fix this error:
- Disable SSL certificate verification - add this line after IronWorker initialization:
$worker->ssl_verifypeer = false;
- Switch to http protocol - add this to configuration options:
protocol = http
andport = 80
- Fix the error! Recommended solution: download actual certificates - cacert.pem and add them to
php.ini
:
[PHP]
curl.cainfo = "path\to\cacert.pem"
Full Documentation
You can find more documentation here:
- http://dev.iron.io Full documetation for iron.io products.
- IronWorker PHP reference.
- IronWorker PHP Wiki pages.
- IronWorker PHP Examples
Note for Developers
You can test this library by modifying it and setting up a symbolic link to your local code after you run composer install
on the Dockerworker example. See http://blog.grossi.io/2013/testing-your-packagistcomposer-package-locally/ for a detailed description on the Composer file layout and the symlinking strategy.