{"id":27158891,"url":"https://github.com/activecollab/jobsqueue","last_synced_at":"2025-04-08T22:39:19.707Z","repository":{"id":36044308,"uuid":"40341740","full_name":"activecollab/jobsqueue","owner":"activecollab","description":"Simple jobs queue","archived":false,"fork":false,"pushed_at":"2024-11-06T20:32:59.000Z","size":470,"stargazers_count":5,"open_issues_count":1,"forks_count":2,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-03-30T13:03:28.483Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://labs.activecollab.com","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/activecollab.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-08-07T04:51:00.000Z","updated_at":"2021-10-02T22:14:31.000Z","dependencies_parsed_at":"2022-08-21T06:50:55.688Z","dependency_job_id":null,"html_url":"https://github.com/activecollab/jobsqueue","commit_stats":null,"previous_names":[],"tags_count":35,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/activecollab%2Fjobsqueue","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/activecollab%2Fjobsqueue/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/activecollab%2Fjobsqueue/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/activecollab%2Fjobsqueue/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/activecollab","download_url":"https://codeload.github.com/activecollab/jobsqueue/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247941718,"owners_count":21022035,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-04-08T22:39:19.237Z","updated_at":"2025-04-08T22:39:19.700Z","avatar_url":"https://github.com/activecollab.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# JobsQueue Library\n\n[![Build Status](https://travis-ci.org/activecollab/jobsqueue.svg?branch=master)](https://travis-ci.org/activecollab/jobsqueue)\n\nReason for existence: it's light, with very few dependencies. It can be used with cron + database powered queues for people who are not allowed to run a proper messaging or job management server. Or you can execute jobs through proper messaging or job manager with it.\n\n## Installation\n\nTo install it, use Composer:\n\n```json\n{\n    \"require\": {\n        \"activecollab/jobsqueue\": \"^1.0.0\"\n    }\n}\n```\n\n## Basic Usage\n\nThis library uses three elements:\n\n1. Dispatcher is here to dispatch jobs,\n2. Queues make sure that jobs can be queued,\n3. Jobs perform the actual work.\n\nAs a demonstration, we'll create a simple job that increments a number:\n\n```php\n\u003c?php\n\nuse ActiveCollab\\JobsQueue\\Jobs\\Job;\n\nclass Inc extends Job\n{\n    /**\n     * Increment a number\n     */\n    public function execute(): mixed\n    {\n      return $this-\u003egetData()['number'] + 1;\n    }\n}\n```\n\nTip: To fail an attempt, just throw an exception from within `execute()` method.\n\nNow, lets create a dispatcher instance that manages one MySQL powered queue:\n\n```php\n\u003c?php\n\nuse ActiveCollab\\JobsQueue\\JobsDispatcher;\nuse ActiveCollab\\JobsQueue\\Queue\\MySqlQueue;\nuse mysqli;\nuse RuntimeException;\n\n$database_link = new MySQLi('localhost', 'root', '', 'activecollab_jobs_queue_test');\n\nif ($database_link-\u003econnect_error) {\n    throw new RuntimeException('Failed to connect to database. MySQL said: ' . $database_link-\u003econnect_error);\n}\n\n$queue = new MySqlQueue($database_link);\n\n// Not required but gives you flexibility with failure handling\n$queue-\u003eonJobFailure(function(Job $job, Exception $reason) {\n    throw new Exception('Job ' . get_class($job) . ' failed', 0, $reason);\n});\n\n$dispatcher = new JobsDispatcher($queue);\n```\n\nLets add a job to the queue:\n\n```php\n$dispatcher-\u003edispatch(new Inc([ 'number' =\u003e 123 ]));\n```\n\nCode that executes jobs from the queue will get this job as next available job:\n\n```php\n$next_in_line = $dispatcher-\u003egetQueue()-\u003enextInLine();\n$dispatcher-\u003egetQueue()-\u003eexecute($next_in_line);\n```\n\nTo run a job and wait for the result, use `execute()` instead of `dispatch()`:\n\n```php\n$result = $dispatcher-\u003eexecute(new Inc([ 'number' =\u003e 123 ]));\n```\n\nWhen called like this, jobs are executed right away. `execute()` suppresses exceptions by default, so you should set `$silent` to `false` if you want exceptions to bubble out:\n\n```php\n$result = $dispatcher-\u003eexecute(new Inc([ ‘number’ =\u003e 123 ]), false);\n```\n\n## Job Properties\n\nWhen constructing a new `Job` instance, you can set an array of job data, as well as following job properties:\n\n1. `priority` - Value between 0 and 4294967295 that determins how important the job is (a job with higher value has higher priority). Default is 0 (job is not a priority),\n2. `attempts` - Number of attempts before job is considered to fail and is removed from the queue. Value can be between 1 and 256. Default is 1 (try once and fail if it does not go well),\n3. `delay` - Number of seconds to wait before first execution (in case when `first_attempt_delay` is not set), as well as retries if the job fails and needs to be retried. Value can be between 1 and 7776000 (90 days). Default is 0 (no delay),\n4. `first_attempt_delay` - Number of seconds to wait before the first job execution.\n\n```php\n$job = new Inc([\n    'number'              =\u003e 123,\n    'priority'            =\u003e Job::HAS_HIGHEST_PRIORITY,\n    'attempts'            =\u003e 5,\n    'delay'               =\u003e 5,\n    'first_attempt_delay' =\u003e 1\n]);\n```\n\n### Accessing Properties in a Job\n\nOnce in an job's `execute()` method, you can access job properties using `getData()` method:\n\n```php\npublic function execute(): mixed\n{\n    print_r($this-\u003egetData()); // Print all job properties\n    print $this-\u003egetData('number') . \"\\n\"; // Print only number\n}\n```\n\n## Batches\n\nJobs can be added to the queue in batches. Once in a batch, job queue will execute them as any other job, but you will be able to track progress of batch:\n\n```php\n$batch = $dispatcher-\u003ebatch('Testing batch', function(BatchInterface \u0026$batch) {\n    for ($i = 1; $i \u003c= 1000; $i++) {\n        $batch-\u003edispatch(new Inc(['number' =\u003e $i]));\n    }\n});\n\nsleep(1);\n\nprint $batch-\u003ecountJobs() . \" jobs in a batch\\n\";\nprint $batch-\u003ecountPendingJobs() . \" batch jobs still pending for execution\\n\";\nprint $batch-\u003ecountFailedJobs() . \" batch jobs have failed to complete\\n\";\nprint $batch-\u003ecountCompletedJobs() . \" batch jobs were completed successfully\\n\";\n```\n\nAll batches have name, so they are easy to find using command line tools.\n\n## Channels\n\nIn some situations, it is useful to have multiple channels and consumer listening on them. For example, you can have a consumer on a mailing server listening only on `mail` channel, but not listening on other channels (which jobs it is not suited to perform).\n\nBy default, all jobs go to main channel (`QueueInterface::MAIN_CHANNEL`), but channel can be specified when job is added to the queue:\n\n```php\n$dispatcher-\u003eregisterChannels('new');\n$dispatcher-\u003eexecute(new Inc(['number' =\u003e 123]), 'new');\n```\n\nBy default, dispatcher will throw an exception if you try to add a job to an unknown channel. This can be turned off:\n\n```php\n$dispatcher-\u003eexceptionOnUnregisteredChannel(false);\n\n// This job will end up in the 'main' channel, but exception will not be thrown\n$dispatcher-\u003eexecute(new Inc(['number' =\u003e 123]), 'unknown channel');\n```\n\n## Background Process\n\nJobs can report that they launched a process:\n\n```php\nclass ListAndForget extends Job\n{\n    /**\n     * Report that we launched a background process\n     */\n    public function execute(): mixed\n    {\n        $output = [];\n        exec(\"nohup ls -la \u003e /dev/null 2\u003e\u00261 \u0026 echo $!\", $output);\n\n        $pid = (integer) $output[1];\n\n        if ($pid \u003e 0) {\n            $this-\u003ereportBackgroundProcess($pid);\n        }\n    }\n}\n```\n\nWhen they do, queue clean up and maintenance routines will not consider this job as stuck as long as process with the given PID is running. When process is done (we can't find it), job is considered to be done.\n\nInformation about jobs that launched processes can be found using `QueueInterface::getBackgroundProcesses()` method. This method returns an array, where each record in an array contains a job ID, job type and process ID:\n\n```php\nprint_r($dispatcher-\u003egetQueue()-\u003egetBackgroundProcesses());\n\n```\n\nwill output something like this:\n\n```\nArray\n(\n    [0] =\u003e Array\n        (\n            [id] =\u003e 1\n            [type] =\u003e ActiveCollab\\JobsQueue\\Test\\Jobs\\ProcessLauncher\n            [process_id] =\u003e 12345\n        )\n\n)\n```\n\nNote: Process reporting and watching is not supported on Windows systems at the moment.\n\n## Executing CLI commands from jobs\n\nIf you need a job to simply run CLI command, there is a handy trait `ExecuteCliCommand`. You can pass a command call signature, arguments and environment variables to the command.\n\nExample usage:\n\n```php\nclass RunCommand extends Job\n{\n    use ExecuteCliCommand;\n    \n    public function __construct(array $data = null)\n    {\n        $this-\u003evalidateCommand($data);\n\n        parent::__construct($data);\n    }\n    \n    public function execute(): mixed\n    {\n        $data['command'] = 'php foobar.php'\n        $data['command_environement_variables'] = ['foo' =\u003e 'bar'];\n        $data['command_arguments'] = ['--baz' =\u003e 1];\n        return $this-\u003eprepareCommandFromData($this-\u003egetData());\n    }\n} \n```\n\nwill produce a CLI command:\n\n```bash\nexport FOO='bar' \u0026\u0026 php foobar.php --baz=1 \n```\n\n## Version 5.0 upgrade\n\nBackward compatibility notes:\n\n1. Check all calls to `JobsDispatcher::batch()` method, and make sure that callbacks do not expect `$batch` to be passed on by reference.\n2. Remove `ActiveCollab\\JobsQueue\\DispatcherInterface` and `ActiveCollab\\JobsQueue\\Dispatcher` if used in client code.\n\n## To do\n\n1. Add logging to all relevant methods in MySQL queue\n2. Implement job quarantine\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Factivecollab%2Fjobsqueue","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Factivecollab%2Fjobsqueue","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Factivecollab%2Fjobsqueue/lists"}