README

PHP bin to scrape Telegram bot API documentation page and convert it into PHP classes to use in Phenogram low level binding

Fork motivation

Promoted properties

The main reason is I like PHP 8 promoted properties, so in this repo the stubs are generated like that.

old:

class BotCommand implements TypeInterface
{
    /** @var string Text of the command; 1-32 characters. Can contain only lowercase English letters, digits and underscores. */
    public string $command;

    /** @var string Description of the command; 1-256 characters. */
    public string $description;
}

new:

/**
 * This object represents a bot command.
 */
class BotCommand implements TypeInterface
{
    /**
     * @param string $command     Text of the command; 1-32 characters. Can contain only lowercase English letters, digits and underscores.
     * @param string $description description of the command; 1-256 characters
     */
    public function __construct(
        public string $command,
        public string $description,
    ) {
    }
}

Change API type from Trait with abstract methods to a class utilizing the new Client interface

Traits are good, but I just don't think it's appropriate to use it in this case. And I think my approach allows for more flexibility.

old:

...
Trait API
{
    abstract public function sendRequest(string $method, array $args): mixed;
...

new:

// TelegramBotApi.php
// ...
class TelegramBotApi
{
	public function __construct(
		protected TelegramBotApiClientInterface $client,
	) {
	}

// TelegramBotApiClientInterface.php
// ...
interface TelegramBotApiClientInterface
{
	function sendRequest(string $method, array $args): mixed;
}

Misc.

1. Changed class/file names
2. Add comments to type classes
3. Sort class params from required to optional
4. Code style

Installation

Install the library with composer:

  $ composer require phenogram/scraper

Using from command line

Once installed, you can use the CLI to interact with the library.

For basic help and command list:

  $ vendor/bin/tgscraper help

JSON

Extract the latest schema in a human-readable JSON:

  $ vendor/bin/tgscraper app:export-schema --readable botapi.json

Or, if you want a Postman-compatible JSON (thanks to davtur19):

  $ vendor/bin/tgscraper app:export-schema --postman botapi_postman.json

YAML

Extract the latest schema in YAML format:

  $ vendor/bin/tgscraper app:export-schema --yaml botapi.yaml

OpenAPI

Extract the latest OpenAPI schema in JSON format:

  $ vendor/bin/tgscraper app:export-schema --openapi botapi_openapi.json

Or, if you prefer YAML:

  $ vendor/bin/tgscraper app:export-schema --openapi --yaml botapi_openapi.yaml

Stubs

Note: since Telegram may change the page format at any time, do NOT rely on the automagically generated stubs from this library, ALWAYS review the code!

TGScraper can also generate class stubs that you can use in your library. A sample implementation is available in the Sysbot Telegram module.

Create stubs in the out/ directory using Phenogram\Telegram as namespace prefix:

  $ vendor/bin/tgscraper app:create-stubs --namespace-prefix "Phenogram\Telegram" out

All versions

If you want to generate all schemas and stubs for every Bot API version, you can!

Here's an example on how to export everything to the out/ directory, with schemas in human-readable format and using Phenogram\Telegram as namespace prefix for the stubs:

  $ vendor/bin/tgscraper app:dump-schemas -r --namespace-prefix "Phenogram\Telegram" out

Custom format

If you're interested in the custom format generated by TGScraper, you can find its schema here.