85 lines
3.4 KiB
Markdown
85 lines
3.4 KiB
Markdown
# rust-telegram-php5-generator
|
|
|
|
A small Rust CLI utility that parses the Telegram Bot API HTML documentation (saved from https://core.telegram.org/bots/api) and generates PHP methods for every API method, preserving argument order and copying documentation. Designed for projects stuck on PHP 5.6 that cannot use modern Telegram bindings.
|
|
|
|
---
|
|
|
|
## Features
|
|
|
|
- Parses a saved HTML page of the Telegram Bot API documentation.
|
|
- Generates PHP method stubs for every API method found.
|
|
- Preserves documentation (method description, parameter descriptions) and original argument order.
|
|
- Outputs generated PHP code to stdout; errors are written to stderr.
|
|
- Accepts optional prefix and suffix files to inject custom code around the generated method list.
|
|
|
|
---
|
|
|
|
## Usage
|
|
|
|
Build and run the utility (example assumes the compiled binary is named `tgphpgen`):
|
|
|
|
```
|
|
tgphpgen /path/to/bots_api.html [/path/to/prefix.php] [/path/to/suffix.php]
|
|
```
|
|
|
|
- First argument (required): **path to the saved HTML documentation file** (the page from core.telegram.org/bots/api).
|
|
- Second argument (optional): **path to a prefix file** whose contents will be prepended before the generated methods.
|
|
- Third argument (optional): **path to a suffix file** whose contents will be appended after the generated methods.
|
|
|
|
Output:
|
|
- Generated PHP code is written to **stdout**.
|
|
- Parsing or file errors are written to **stderr** and the program exits with a non-zero exit code.
|
|
|
|
---
|
|
|
|
## Generated PHP style
|
|
|
|
- Each Telegram API method becomes a PHP method inside a class.
|
|
- Argument names and order match the documentation.
|
|
- Required arguments are checked against emptiness. When detected an error is returned in `['1' => ...]` for easier destructive assignment using golang-inspired `list ($res, $err) = `
|
|
- Parameter types and descriptions are included as PHPDoc above each function when available.
|
|
- Optional parameters are given default values to maintain compatibility with PHP 5.6.
|
|
- All methods internally invoke `$this->trySend($apiMethodName, $apiMethodArgs)` implementation of which should be provided by user in a prefix/suffix file
|
|
|
|
---
|
|
|
|
## Implementation notes
|
|
|
|
- The parser expects the HTML structure from core.telegram.org/bots/api as saved by a browser. Minor variations in formatting may require adjusting the parser.
|
|
- The tool focuses on robustness for PHP 5.6 compatibility:
|
|
- No type hints in generated PHP function signatures.
|
|
- Optional params default to `null`.
|
|
- Uses associative arrays and simple return values (arrays) so integration with existing PHP5.6 code is straightforward. The errors returned in the `1` key as to be easily extractable using golang-like syntax of `list ($result, $error) = ...`.
|
|
- The utility prints helpful errors to stderr for:
|
|
- Missing input file
|
|
- Invalid HTML structure (unable to locate API method sections)
|
|
- File read errors for prefix/suffix
|
|
|
|
---
|
|
|
|
## Examples
|
|
|
|
Generate methods only:
|
|
|
|
```
|
|
tgphpgen bots_api.html > telegram_methods.php
|
|
```
|
|
|
|
Generate with a wrapper class (prefix contains class header, suffix contains closing brace):
|
|
|
|
```
|
|
tgphpgen bots_api.html prefix.php suffix.php > TelegramApi.php
|
|
```
|
|
|
|
---
|
|
|
|
## Contributing
|
|
|
|
- Fixes for parsing edge cases welcome — the HTML layout on core.telegram.org may change; tests and example saved HTML files help keep the parser resilient.
|
|
- Please include a saved copy of the documentation page that reproduces any parsing bug you report.
|
|
|
|
---
|
|
|
|
## License
|
|
|
|
MIT License.
|