{"id":13623562,"url":"https://github.com/tarantool-php/queue","last_synced_at":"2025-05-07T17:51:42.825Z","repository":{"id":46153060,"uuid":"37842031","full_name":"tarantool-php/queue","owner":"tarantool-php","description":"PHP bindings for Tarantool Queue.","archived":false,"fork":false,"pushed_at":"2025-03-08T23:29:27.000Z","size":125,"stargazers_count":64,"open_issues_count":2,"forks_count":7,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-05-07T17:51:36.435Z","etag":null,"topics":["nosql","php","queue","tarantool"],"latest_commit_sha":null,"homepage":"","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/tarantool-php.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":["rybakit"]}},"created_at":"2015-06-22T07:13:16.000Z","updated_at":"2025-03-08T23:29:31.000Z","dependencies_parsed_at":"2024-03-14T20:32:46.234Z","dependency_job_id":"aa1b9041-e95c-4d1a-a355-9f130fb082e8","html_url":"https://github.com/tarantool-php/queue","commit_stats":null,"previous_names":[],"tags_count":12,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tarantool-php%2Fqueue","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tarantool-php%2Fqueue/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tarantool-php%2Fqueue/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tarantool-php%2Fqueue/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tarantool-php","download_url":"https://codeload.github.com/tarantool-php/queue/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252931391,"owners_count":21827104,"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":["nosql","php","queue","tarantool"],"created_at":"2024-08-01T21:01:33.154Z","updated_at":"2025-05-07T17:51:42.789Z","avatar_url":"https://github.com/tarantool-php.png","language":"PHP","readme":"# Tarantool Queue\n\n[![Quality Assurance](https://github.com/tarantool-php/queue/workflows/QA/badge.svg)](https://github.com/tarantool-php/queue/actions?query=workflow%3AQA)\n[![Scrutinizer Code Quality](https://scrutinizer-ci.com/g/tarantool-php/queue/badges/quality-score.png?b=master)](https://scrutinizer-ci.com/g/tarantool-php/queue/?branch=master)\n[![Code Coverage](https://scrutinizer-ci.com/g/tarantool-php/queue/badges/coverage.png?b=master)](https://scrutinizer-ci.com/g/tarantool-php/queue/?branch=master)\n[![Mentioned in Awesome PHP](https://awesome.re/mentioned-badge.svg)](https://github.com/ziadoz/awesome-php)\n[![Telegram](https://img.shields.io/badge/Telegram-join%20chat-blue.svg)](https://t.me/tarantool_php)\n\n[Tarantool](https://www.tarantool.io/en/developers/) is a NoSQL database running in a Lua application server. It integrates\nLua modules, called [LuaRocks](https://luarocks.org/). This package provides PHP bindings for\n[Tarantool Queue LuaRock](https://github.com/tarantool/queue/).\n\n\n## Table of contents\n\n * [Installation](#installation)\n * [Before start](#before-start)\n * [Working with queue](#working-with-queue)\n   * [Data types](#data-types)\n   * [Tasks](#tasks)\n   * [Producer API](#producer-api)\n   * [Consumer API](#consumer-api)\n   * [Statistics](#statistics)\n   * [Custom methods](#custom-methods)\n * [Testing](#testing)\n * [License](#license)\n\n\n## Installation\n\nThe recommended way to install the library is through [Composer](http://getcomposer.org):\n\n```bash\ncomposer require tarantool/queue\n```\n\n\n## Before start\n\nIn order to use queue, you first need to make sure that your Tarantool instance\nis configured, up and running. The minimal required configuration might look like this:\n\n```lua\n-- queues.lua\n\nbox.cfg {listen = 3301}\n\nqueue = require('queue')\nqueue.create_tube('foobar', 'fifottl', {if_not_exists = true})\n```\n\n\u003e *You can read more about the box configuration in the official Tarantool [documentation](http://tarantool.org/doc/book/configuration/index.html#initialization-file).\n\u003e More information on queue configuration can be found [here](https://github.com/tarantool/queue/blob/master/README.md).*\n\nTo start the instance you need to copy (or symlink) `queues.lua` file into the `/etc/tarantool/instances.enabled`\ndirectory and run the following command:\n\n```bash\nsudo tarantoolctl start queues\n```\n\n\n## Working with queue\n\nOnce you have your instance running, you can start by creating a queue object with the queue (tube) name you defined\nin the Lua script:\n\n```php\nuse Tarantool\\Queue\\Queue;\n\n...\n\n$queue = new Queue($client, 'foobar');\n```\n\nwhere `$client` is an instance of `Tarantool\\Client\\Client` from the [tarantool/client](https://github.com/tarantool-php/client) package.\n\n\n### Data types\n\nUnder the hood Tarantool uses [MessagePack](http://msgpack.org/) binary format to serialize/deserialize\ndata being stored in a queue. It can handle most of the PHP data types (except resources and closures) without \nany manual pre- or post-processing:\n\n```php\n$queue-\u003eput('foo');\n$queue-\u003eput(true);\n$queue-\u003eput(42);\n$queue-\u003eput(4.2);\n$queue-\u003eput(['foo' =\u003e ['bar' =\u003e ['baz' =\u003e null]]]);\n$queue-\u003eput(new MyObject());\n```\n\n\u003e *To learn more about object serialization, please follow this [link](https://github.com/tarantool-php/client#user-defined-types).*\n\n\n### Tasks\n\nMost of the [Queue API](src/Queue.php) methods return a [Task](src/Task.php) object\ncontaining the following getters:\n\n```php\nTask::getId()\nTask::getState() // States::READY, States::TAKEN, States::DONE, States::BURY or States::DELAYED\nTask::getData()\n```\n\nAnd some sugar methods:\n\n```php\nTask::isReady()\nTask::isTaken()\nTask::isDone()\nTask::isBuried()\nTask::isDelayed()\n```\n\n\n### Producer API\n\nAs you've already seen, to insert a task into a queue you need to call `put()` method, which accepts\ntwo arguments: the data you want to process and optional array of task options, which this particular\nqueue supports. For example, `fifottl` queue (which we defined [earlier](#before-start) in our Lua config \nfile), supports `delay`, `ttl`, `ttr` and `pri` options:\n\n```php\nuse Tarantool\\Queue\\Options;\n\n$queue-\u003eput('foo', [Options::DELAY =\u003e 30.0]);\n$queue-\u003eput('bar', [Options::TTL =\u003e 5.0]);\n$queue-\u003eput('baz', [Options::TTR =\u003e 10.0, Options::PRI =\u003e 42]);\n```\n\n\u003e *See the full list of available options [here](https://github.com/tarantool/queue#queue-types).*\n\n\n### Consumer API\n\nTo reserve a task for execution, call `take()` method. It accepts an optional `timeout` parameter.\nIf a timeout value is supplied the call will wait `timeout` seconds until a `READY` task appears in the queue.\nThe method returns either a [Task](#tasks) object or `null`:\n\n```php\n$taskOrNull = $queue-\u003etake();\n\n// wait 2 seconds\n$taskOrNull = $queue-\u003etake(2.0);\n\n// wait 100 milliseconds\n$taskOrNull = $queue-\u003etake(.1);\n```\n\nAfter successful execution, a task can be marked as acknowledged (that will also delete the task from a queue):\n\n```php\n$data = $task-\u003egetData();\n\n// process $data\n\n$task = $queue-\u003eack($task-\u003egetId());\n```\n\nOr put back into the queue in case it cannot be executed:\n\n```php\n$task = $queue-\u003erelease($task-\u003egetId());\n\n// for *ttl queues you can specify a delay\n$task = $queue-\u003erelease($task-\u003egetId(), [Options::DELAY =\u003e 30.0]);\n```\n\nTo look at a task without changing its state, use:\n\n```php\n$task = $queue-\u003epeek($task-\u003egetId());\n```\n\nTo bury (disable) a task:\n\n```php\n$task = $queue-\u003ebury($task-\u003egetId());\n```\n\nTo reset buried task(s) back to `READY` state:\n\n```php\n$count = $queue-\u003ekick(3); // kick 3 buried tasks\n```\n\nTo increase TTR and/or TTL of a running task (only for *ttl queues):\n\n```php\n$taskOrNull = $queue-\u003etouch($takenTask-\u003egetId(), 5.0); // increase ttr/ttl to 5 seconds\n```\n\nA task (in any state) can be deleted permanently with `delete()`:\n\n```php\n$task = $queue-\u003edelete($task-\u003egetId());\n```\n\nTo delete all tasks in a queue:\n\n```php\n$queue-\u003etruncate();\n```\n\n\u003e *For a detailed API documentation, please read the section \n\u003e \"[Using the queue module](https://github.com/tarantool/queue#using-the-queue-module)\" \n\u003e of the queue README.*\n\n\n### Statistics\n\nThe `stats()` method provides access to the statistical information accumulated\nsince a queue was created:\n\n```php\n$stats = $queue-\u003estats();\n```\n\nThe result of this call might look like this:\n\n```php\n[\n    'tasks' =\u003e [\n        'taken'   =\u003e 1,\n        'buried'  =\u003e 1,\n        'ready'   =\u003e 1,\n        'done'    =\u003e 0,\n        'delayed' =\u003e 0,\n        'total'   =\u003e 3,\n    ],\n    'calls' =\u003e [\n        'bury' =\u003e 1,\n        'put'  =\u003e 3,\n        'take' =\u003e 1,\n        ...\n    ],\n]\n```\n\nIn addition, you can specify a key to return only a subset of the array:\n\n```php\n$calls = $queue-\u003estats('calls');\n$total = $queue-\u003estats('tasks.total');\n```\n\n\n### Custom methods\n\nThanks to flexible nature of the [queue](https://github.com/tarantool/queue/) Lua module, you can easily create\nyour own queue drivers or extend existing ones with an additional functionality. For example, suppose you added\nthe `put_many` method to your `foobar` queue, which inserts multiple tasks atomically:\n\n```lua\n-- queues.lua\n\n...\n\nqueue.tube.foobar.put_many = function(self, items)\n    local put = {}\n\n    box.begin()\n    for k, item in pairs(items) do\n        put[k] = tube:put(unpack(item))\n    end\n    box.commit()\n\n    return put\nend\n```\n\nTo invoke this method from php, use `Queue::call()`:\n\n```php\n$result = $queue-\u003ecall('put_many', [\n    'foo' =\u003e ['foo', [Options::DELAY =\u003e 30.0]],\n    'bar' =\u003e ['bar'],\n]);\n```\n\n\n## Testing\n\nThe easiest way to run tests is with Docker. First, build an image using the [dockerfile.sh](dockerfile.sh) generator:\n\n```bash\n./dockerfile.sh | docker build -t queue -\n```\n\nThen run a Tarantool instance (needed for integration tests):\n\n```bash\ndocker network create tarantool-php\ndocker run -d --net=tarantool-php -p 3301:3301 --name=tarantool \\\n    -v $(pwd)/tests/Integration/queues.lua:/queues.lua \\\n    tarantool/tarantool:2 tarantool /queues.lua\n```\n\nAnd then run both unit and integration tests:\n\n```bash\ndocker run --rm --net=tarantool-php -v $(pwd):/queue -w /queue queue\n```\n\nThe library uses [PHPUnit](https://phpunit.de/) under the hood, and if needed,\nyou can pass additional arguments and options to the `phpunit` command.\nFor example, to run only unit tests, execute:\n\n```bash\ndocker run --rm --net=tarantool-php -v $(pwd):/queue -w /queue queue \\\n    vendor/bin/phpunit --testsuite=unit\n```\n\n\n## License\n\nThe library is released under the MIT License. See the bundled [LICENSE](LICENSE) file for details.\n","funding_links":["https://github.com/sponsors/rybakit"],"categories":["目录","Table of Contents","PHP","队列 Queue"],"sub_categories":["队列 Queue","Queue"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftarantool-php%2Fqueue","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftarantool-php%2Fqueue","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftarantool-php%2Fqueue/lists"}