{"id":25227245,"url":"https://github.com/php-telegram-bot/telegram-bot-manager","last_synced_at":"2025-04-04T14:05:07.338Z","repository":{"id":41247864,"uuid":"65904327","full_name":"php-telegram-bot/telegram-bot-manager","owner":"php-telegram-bot","description":"PHP Telegram Bot Manager","archived":false,"fork":false,"pushed_at":"2023-05-27T17:25:31.000Z","size":330,"stargazers_count":214,"open_issues_count":3,"forks_count":65,"subscribers_count":21,"default_branch":"develop","last_synced_at":"2025-03-28T13:05:09.189Z","etag":null,"topics":["bot","bot-manager","getupdates","manager","php","php-telegram-bot","telegram","telegram-bot","webhook"],"latest_commit_sha":null,"homepage":null,"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/php-telegram-bot.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"tidelift":"packagist/php-telegram-bot%2Ftelegram-bot-manager","patreon":"phptelegrambot","liberapay":"PHP-Telegram-Bot","open_collective":"php-telegram-bot","ko_fi":"phptelegrambot","custom":"https://github.com/php-telegram-bot/telegram-bot-manager#donate"}},"created_at":"2016-08-17T12:05:07.000Z","updated_at":"2025-03-06T01:26:09.000Z","dependencies_parsed_at":"2024-06-19T05:25:48.134Z","dependency_job_id":"0a04b783-1453-46c8-8ee5-43368973ef27","html_url":"https://github.com/php-telegram-bot/telegram-bot-manager","commit_stats":{"total_commits":134,"total_committers":4,"mean_commits":33.5,"dds":0.02985074626865669,"last_synced_commit":"e239de261adc4746e0b354906690e43ac8c44c79"},"previous_names":[],"tags_count":24,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/php-telegram-bot%2Ftelegram-bot-manager","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/php-telegram-bot%2Ftelegram-bot-manager/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/php-telegram-bot%2Ftelegram-bot-manager/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/php-telegram-bot%2Ftelegram-bot-manager/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/php-telegram-bot","download_url":"https://codeload.github.com/php-telegram-bot/telegram-bot-manager/tar.gz/refs/heads/develop","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247186064,"owners_count":20898088,"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":["bot","bot-manager","getupdates","manager","php","php-telegram-bot","telegram","telegram-bot","webhook"],"created_at":"2025-02-11T08:13:14.189Z","updated_at":"2025-04-04T14:05:07.318Z","avatar_url":"https://github.com/php-telegram-bot.png","language":"PHP","readme":"# PHP Telegram Bot Manager\n\n[![Join the bot support group on Telegram][support-group-badge]][support-group]\n[![Donate][donate-badge]](#donate)\n\n[![Scrutinizer Code Quality][code-quality-badge]][code-quality]\n[![Codecov][code-coverage-badge]][code-coverage]\n[![Tests Status][tests-status-badge]][tests-status]\n\n[![Latest Stable Version][latest-version-badge]][github-tgbot-manager]\n[![Dependencies][dependencies-badge]][Tidelift]\n[![Total Downloads][total-downloads-badge]][packagist-tgbot-manager]\n[![License][license-badge]][license]\n\nThis project builds on top of [PHP Telegram Bot][github-tgbot-core] and as such, depends on it!\n\nThe main purpose of this mini-library is to make the interaction between your webserver and Telegram easier.\nI strongly suggest your read the PHP Telegram Bot [instructions][github-tgbot-core-instructions] first, to understand what this library does exactly.\n\nInstallation and usage is pretty straight forward:\n\n### Require this package with [Composer]\n\n```bash\ncomposer require php-telegram-bot/telegram-bot-manager:^2.1\n```\n\n**NOTE:** This will automatically also install [PHP Telegram Bot][github-tgbot-core] into your project (if it isn't already).\n\n**Advanced:** Due to the fact that the core library is not a stable version yet, this project is partly locked to the core version, to ensure reliable functioning.\n\nIt is possible however, to override the core version that this library requires:\n\n```yaml\n\"require\": {\n    \"php-telegram-bot/telegram-bot-manager\": \"^2.1\",\n    \"longman/telegram-bot\": \"dev-master as 0.81\"\n}\n```\n\nThis example will pull the master version of the core library, making it appear to be version 0.81, which then satisfies the requirement.\n\n### Performing actions\n\nWhat use would this library be if you couldn't perform any actions?!\n\nThere are a few parameters available to get things rolling:\n\n| Parameter | Description |\n| --------- | ----------- |\n| s         | **s**ecret: This is a special secret value defined in the main `manager.php` file. |\n|           | This parameter is required to call the script via browser! |\n| a         | **a**ction: The actual action to perform. (handle (default), webhookinfo, cron, set, unset, reset) |\n|           | **handle** executes the `getUpdates` method; **webhookinfo** to get result from `getWebhookInfo`, **cron** executes cron commands; **set** / **unset** / **reset** the webhook. |\n| l         | **l**oop: Number of seconds to loop the script for (used for getUpdates method). |\n|           | This would be used mainly via CLI, to continually get updates for a certain period. |\n| i         | **i**nterval: Number of seconds to wait between getUpdates requests (used for getUpdates method, default is 2). |\n|           | This would be used mainly via CLI, to continually get updates for a certain period, every **i** seconds. |\n| g         | **g**roup: Commands group for cron (only used together with `cron` action, default group is `default`). |\n|           | Define which group of commands to execute via cron. Can be a comma separated list of groups. |\n\n#### via browser\n\nSimply point your browser to the `manager.php` file with the necessary **GET** parameters:\n- `http://example.com/manager.php?s=\u003csecret\u003e\u0026a=\u003caction\u003e\u0026l=\u003cloop\u003e\u0026i=\u003cinterval\u003e`\n\n**Webhook**\n\nSet, unset and reset the webhook:\n- `http://example.com/manager.php?s=super_secret\u0026a=set`\n- `http://example.com/manager.php?s=super_secret\u0026a=unset`\n- `http://example.com/manager.php?s=super_secret\u0026a=reset` (unset \u0026 set combined)\n\n**getUpdates**\n\nHandle updates once:\n- `http://example.com/manager.php?s=super_secret\u0026a=handle` or simply\n- `http://example.com/manager.php?s=super_secret` (`handle` action is the default)\n\nHandle updates for 30 seconds, fetching every 5 seconds:\n- `http://example.com/manager.php?s=super_secret\u0026l=30\u0026i=5`\n\n**cron**\n\nExecute commands via cron:\n- `http://example.com/manager.php?s=super_secret\u0026a=cron\u0026g=maintenance` or multiple groups\n- `http://example.com/manager.php?s=super_secret\u0026a=cron\u0026g=maintenance,cleanup`\n\n#### via CLI\n\nWhen using CLI, the secret is not necessary (since it could just be read from the file itself).\n\nCall the `manager.php` file directly using `php` and pass the parameters:\n- `$ php manager.php a=\u003caction\u003e l=\u003cloop\u003e i=\u003cinterval\u003e`\n\n**Webhook**\n\nSet, unset and reset the webhook:\n- `$ php manager.php a=set`\n- `$ php manager.php a=unset`\n- `$ php manager.php a=reset` (unset \u0026 set combined)\n\n**getUpdates**\n\nHandle updates once:\n- `$ php manager.php a=handle` or simply\n- `$ php manager.php` (`handle` action is the default)\n\nHandle updates for 30 seconds, fetching every 5 seconds:\n- `$ php manager.php l=30 i=5`\n\n**cron**\n\nExecute commands via cron:\n- `$ php manager.php a=cron g=maintenance` or multiple groups\n- `$ php manager.php a=cron g=maintenance,cleanup`\n\n### Create the manager PHP file\n\nYou can name this file whatever you like, it just has to be somewhere inside your PHP project (preferably in the root folder to make things easier).\n(Let's assume our file is called `manager.php`)\n\nLet's start off with a simple example that uses the webhook method:\n```php\n\u003c?php\n\nuse TelegramBot\\TelegramBotManager\\BotManager;\n\n// Load composer.\nrequire_once __DIR__ . '/vendor/autoload.php';\n\ntry {\n    $bot = new BotManager([\n        // Vitals!\n        'api_key'      =\u003e '12345:my_api_key',\n\n        // Extras.\n        'bot_username' =\u003e 'my_own_bot',\n        'secret'       =\u003e 'super_secret',\n        'webhook'      =\u003e [\n            'url' =\u003e 'https://example.com/manager.php',\n        ]\n    ]);\n    $bot-\u003erun();\n} catch (\\Exception $e) {\n    echo $e-\u003egetMessage() . PHP_EOL;\n}\n```\n\n### Set vital bot parameters\n\nThe only vital parameter is the API key:\n\n```php\n$bot = new BotManager([\n    // (string) Bot API key provided by @BotFather.\n    'api_key' =\u003e '12345:my_api_key',\n    ...\n]);\n```\n\n### Set extra bot parameters\n\nApart from the necessary API key, the bot can be easily configured using extra parameters.\n\nSet the webhook? Enable admins? Add custom command paths?\n\n**All no problem!**\n\nThe `secret` is a user-defined key that is required to execute any of the library's features via webhook.\nBest make it long, random and very unique!\n\nFor 84 random characters:\n- If you have `pwgen` installed, just execute `pwgen 84 1` and copy the output.\n- If you have `openssl` installed, use `openssl rand -hex 84`.\n- Or just go [here][random-characters] and put all the output onto a single line.\n\n(You get 2 guesses why 84 is a good number :wink:)\n\nBelow is a complete list of all available extra parameters.\n\n```php\n$bot = new BotManager([\n    ...\n    // (string) Bot username that was defined when creating the bot.\n    'bot_username'     =\u003e 'my_own_bot',\n\n    // (string) A secret password required to authorise access to the webhook.\n    'secret'           =\u003e 'super_secret',\n\n    // (array) All options that have to do with the webhook.\n    'webhook'          =\u003e [\n        // (string) URL to the manager PHP file used for setting up the webhook.\n        'url'             =\u003e 'https://example.com/manager.php',\n        // (string) Path to a self-signed certificate (if necessary).\n        'certificate'     =\u003e __DIR__ . '/server.crt',\n        // (int) Maximum allowed simultaneous HTTPS connections to the webhook.\n        'max_connections' =\u003e 20,\n        // (array) List the types of updates you want your bot to receive.\n        'allowed_updates' =\u003e ['message', 'edited_channel_post', 'callback_query'],\n        // (string) Secret token to validate webhook requests.\n        'secret_token'    =\u003e 'super_secret_token',\n    ],\n\n    // (bool) Only allow webhook access from valid Telegram API IPs.\n    'validate_request' =\u003e true,\n    // (array) When using `validate_request`, also allow these IPs.\n    'valid_ips'        =\u003e [\n        '1.2.3.4',         // single\n        '192.168.1.0/24',  // CIDR\n        '10/8',            // CIDR (short)\n        '5.6.*',           // wildcard\n        '1.1.1.1-2.2.2.2', // range\n    ],\n\n    // (array) All options that have to do with the limiter.\n    'limiter'          =\u003e [\n        // (bool) Enable or disable the limiter functionality.\n        'enabled' =\u003e true,\n        // (array) Any extra options to pass to the limiter.\n        'options' =\u003e [\n            // (float) Interval between request handles.\n            'interval' =\u003e 0.5,\n        ],\n    ],\n\n    // (array) An array of user ids that have admin access to your bot (must be integers).\n    'admins'           =\u003e [12345],\n\n    // (array) Mysql credentials to connect a database (necessary for [`getUpdates`](#using-getupdates-method) method!).\n    'mysql'            =\u003e [\n        'host'         =\u003e '127.0.0.1',\n        'port'         =\u003e 3306,           // optional\n        'user'         =\u003e 'root',\n        'password'     =\u003e 'root',\n        'database'     =\u003e 'telegram_bot',\n        'table_prefix' =\u003e 'tbl_prfx_',    // optional\n        'encoding'     =\u003e 'utf8mb4',      // optional\n    ],\n\n    // (array) List of configurable paths.\n    'paths'            =\u003e [\n        // (string) Custom download path.\n        'download' =\u003e __DIR__ . '/Download',\n        // (string) Custom upload path.\n        'upload'   =\u003e __DIR__ . '/Upload',\n    ],\n\n    // (array) All options that have to do with commands.\n    'commands'         =\u003e [\n        // (array) A list of custom commands paths.\n        'paths'   =\u003e [\n            __DIR__ . '/CustomCommands',\n        ],\n        // (array) A list of all custom command configs.\n        'configs' =\u003e [\n            'sendtochannel' =\u003e ['your_channel' =\u003e '@my_channel'],\n            'weather'       =\u003e ['owm_api_key' =\u003e 'owm_api_key_12345'],\n        ],\n    ],\n\n    // (array) All options that have to do with cron.\n    'cron'             =\u003e [\n        // (array) List of groups that contain the commands to execute.\n        'groups' =\u003e [\n            // Each group has a name and array of commands.\n            // When no group is defined, the default group gets executed.\n            'default'     =\u003e [\n                '/default_cron_command',\n            ],\n            'maintenance' =\u003e [\n                '/db_cleanup',\n                '/db_repair',\n                '/message_admins Maintenance completed',\n            ],\n        ],\n    ],\n\n    // (string) Override the custom input of your bot (mostly for testing purposes!).\n    'custom_input'     =\u003e '{\"some\":\"raw\", \"json\":\"update\"}',\n]);\n```\n\n### Using getUpdates method\n\nUsing the `getUpdates` method must not have a `webhook` parameter set and requires a MySQL database connection:\n```php\n$bot = new BotManager([\n    ...\n    // Extras.\n    'mysql' =\u003e [\n        'host'         =\u003e '127.0.0.1',\n        'port'         =\u003e 3306,           // optional\n        'user'         =\u003e 'root',\n        'password'     =\u003e 'root',\n        'database'     =\u003e 'telegram_bot',\n        'table_prefix' =\u003e 'tbl_prfx_',    // optional\n        'encoding'     =\u003e 'utf8mb4',      // optional\n    ],\n]);\n```\n\nNow, the updates can be done either through the [browser](#via-browser) or [via CLI](#via-cli).\n\n#### Custom getUpdates output\n\nA callback can be defined, to override the default output when updates are handled via getUpdates.\n\nExample of the default output:\n```\n...\n2017-07-10 14:59:25 - Updates processed: 1\n123456: \u003ctext\u003e\n2017-07-10 14:59:27 - Updates processed: 0\n2017-07-10 14:59:30 - Updates processed: 0\n2017-07-10 14:59:32 - Updates processed: 0\n2017-07-10 14:59:34 - Updates processed: 1\n123456: \u003cphoto\u003e\n2017-07-10 14:59:36 - Updates processed: 0\n...\n```\n\nUsing custom callback that must return a string:\n```php\n// In manager.php after $bot has been defined:\n$bot-\u003esetCustomGetUpdatesCallback(function (ServerResponse $get_updates_response) {\n    $results = array_filter((array) $get_updates_response-\u003egetResult());\n\n    return sprintf('There are %d update(s)' . PHP_EOL, count($results));\n});\n```\noutput:\n```\n...\nThere are 0 update(s)\nThere are 0 update(s)\nThere are 2 update(s)\nThere are 1 update(s)\n...\n```\n\n## Development\n\nWhen running live bot tests on a fork, you must enter the following environment variables to your [repository settings][github-actions-encrypted-secrets]:\n```\nAPI_KEY=\"12345:your_api_key\"\nBOT_USERNAME=\"username_of_your_bot\"\n```\nIt probably makes sense for you to create a new dummy bot for this.\n\n## Security\n\nSee [SECURITY](SECURITY.md) for more information.\n\n## Donate\n\nAll work on this bot consists of many hours of coding during our free time, to provide you with a Telegram Bot library that is easy to use and extend.\nIf you enjoy using this library and would like to say thank you, donations are a great way to show your support.\n\nDonations are invested back into the project :+1:\n\nThank you for keeping this project alive :pray:\n\n- [![Patreon](https://user-images.githubusercontent.com/9423417/59235980-a5fa6b80-8be3-11e9-8ae7-020bc4ae9baa.png) Patreon.com/phptelegrambot][Patreon]\n- [![OpenCollective](https://user-images.githubusercontent.com/9423417/59235978-a561d500-8be3-11e9-89be-82ec54be1546.png) OpenCollective.com/php-telegram-bot][OpenCollective]\n- [![Ko-fi](https://user-images.githubusercontent.com/9423417/59235976-a561d500-8be3-11e9-911d-b1908c3e6a33.png) Ko-fi.com/phptelegrambot][Ko-fi]\n- [![Tidelift](https://user-images.githubusercontent.com/9423417/59235982-a6930200-8be3-11e9-8ac2-bfb6991d80c5.png) Tidelift.com/longman/telegram-bot][Tidelift]\n- [![Liberapay](https://user-images.githubusercontent.com/9423417/59235977-a561d500-8be3-11e9-9d16-bc3b13d3ceba.png) Liberapay.com/PHP-Telegram-Bot][Liberapay]\n- [![PayPal](https://user-images.githubusercontent.com/9423417/59235981-a5fa6b80-8be3-11e9-9761-15eb7a524cb0.png) PayPal.me/noplanman][PayPal-noplanman] (account of @noplanman)\n\n---\n\n\u003cdiv align=\"center\"\u003e\n    \u003cb\u003e\n        \u003ca href=\"https://tidelift.com/subscription/pkg/packagist-php-telegram-bot-telegram-bot-manager?utm_source=packagist-php-telegram-bot-telegram-bot-manager\u0026utm_medium=referral\u0026utm_campaign=readme-footer\"\u003eGet professional support for this package with a Tidelift subscription\u003c/a\u003e\n    \u003c/b\u003e\n    \u003cbr\u003e\n    \u003csub\u003e\n        Tidelift helps make open source sustainable for maintainers while giving companies\u003cbr\u003eassurances about security, maintenance, and licensing for their dependencies.\n    \u003c/sub\u003e\n\u003c/div\u003e\n\n[github-tgbot-core]: https://github.com/php-telegram-bot/core \"PHP Telegram Bot on GitHub\"\n[github-tgbot-core-instructions]: https://github.com/php-telegram-bot/core#instructions \"PHP Telegram Bot instructions on GitHub\"\n[github-tgbot-manager]: https://github.com/php-telegram-bot/telegram-bot-manager \"PHP Telegram Bot Manager on GitHub\"\n[packagist-tgbot-manager]: https://packagist.org/packages/php-telegram-bot/telegram-bot-manager \"PHP Telegram Bot Manager on Packagist\"\n[license]: https://github.com/php-telegram-bot/telegram-bot-manager/blob/master/LICENSE \"PHP Telegram Bot Manager license\"\n\n[support-group-badge]: https://img.shields.io/badge/telegram-@PHP__Telegram__Bot__Support-64659d.svg\n[support-group]: https://telegram.me/PHP_Telegram_Bot_Support\n[donate-badge]: https://img.shields.io/badge/%F0%9F%92%99-Donate%20%2F%20Support%20Us-blue.svg\n[code-quality-badge]: https://img.shields.io/scrutinizer/g/php-telegram-bot/telegram-bot-manager.svg\n[code-quality]: https://scrutinizer-ci.com/g/php-telegram-bot/telegram-bot-manager/?branch=master \"Code quality on Scrutinizer\"\n[code-coverage-badge]: https://img.shields.io/codecov/c/github/php-telegram-bot/telegram-bot-manager.svg\n[code-coverage]: https://codecov.io/gh/php-telegram-bot/telegram-bot-manager \"Code coverage on Codecov\"\n[tests-status-badge]: https://github.com/php-telegram-bot/telegram-bot-manager/actions/workflows/tests.yml/badge.svg?branch=master\n[tests-status]: https://github.com/php-telegram-bot/telegram-bot-manager/workflows/tests.yml \"Tests status on GitHub Actions\"\n\n[latest-version-badge]: https://img.shields.io/packagist/v/php-telegram-bot/telegram-bot-manager.svg\n[dependencies-badge]: https://tidelift.com/badges/github/php-telegram-bot/core?style=flat\n[total-downloads-badge]: https://img.shields.io/packagist/dt/php-telegram-bot/telegram-bot-manager.svg\n[license-badge]: https://img.shields.io/packagist/l/php-telegram-bot/telegram-bot-manager.svg\n\n[random-characters]: https://www.random.org/strings/?num=7\u0026len=12\u0026digits=on\u0026upperalpha=on\u0026loweralpha=on\u0026unique=on\u0026format=plain\u0026rnd=new \"Generate random characters\"\n[github-actions-encrypted-secrets]: https://docs.github.com/en/actions/security-guides/encrypted-secrets \"Encrypted Secrets for GitHub Actions\"\n[Composer]: https://getcomposer.org/ \"Composer\"\n\n[Patreon]: https://www.patreon.com/phptelegrambot \"Support us on Patreon\"\n[OpenCollective]: https://opencollective.com/php-telegram-bot \"Support us on Open Collective\"\n[Ko-fi]: https://ko-fi.com/phptelegrambot \"Support us on Ko-fi\"\n[Tidelift]: https://tidelift.com/subscription/pkg/packagist-php-telegram-bot-telegram-bot-manager?utm_source=packagist-php-telegram-bot-telegram-bot-manager\u0026utm_medium=referral\u0026utm_campaign=readme \"Support us on Tidelift\"\n[Liberapay]: https://liberapay.com/PHP-Telegram-Bot \"Donate with Liberapay\"\n[PayPal-noplanman]: https://paypal.me/noplanman \"Donate with PayPal\"\n","funding_links":["https://tidelift.com/funding/github/packagist/php-telegram-bot%2Ftelegram-bot-manager","https://patreon.com/phptelegrambot","https://liberapay.com/PHP-Telegram-Bot","https://opencollective.com/php-telegram-bot","https://ko-fi.com/phptelegrambot","https://github.com/php-telegram-bot/telegram-bot-manager#donate","https://tidelift.com/subscription/pkg/packagist-php-telegram-bot-telegram-bot-manager?utm_source=packagist-php-telegram-bot-telegram-bot-manager\u0026utm_medium=referral\u0026utm_campaign=readme-footer","https://tidelift.com/badges/github/php-telegram-bot/core?style=flat","https://www.patreon.com/phptelegrambot","https://tidelift.com/subscription/pkg/packagist-php-telegram-bot-telegram-bot-manager?utm_source=packagist-php-telegram-bot-telegram-bot-manager\u0026utm_medium=referral\u0026utm_campaign=readme","https://paypal.me/noplanman"],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fphp-telegram-bot%2Ftelegram-bot-manager","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fphp-telegram-bot%2Ftelegram-bot-manager","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fphp-telegram-bot%2Ftelegram-bot-manager/lists"}