Download the PHP package afaztech/reactor without Composer

Reactor Application Skeleton

A production-ready starter project for building high-performance, asynchronous Telegram bots with the Reactor PHP framework.

Overview

This repository is the official application skeleton for Reactor, a modern, asynchronous PHP framework purpose-built for creating robust Telegram bots.

Under the hood, this skeleton is powered by three complementary technologies:

• Reactor — the framework itself. It provides the dependency injection container, attribute-based routing, middleware pipeline, service providers, config layering, migrations, queue system, scheduler, caching, event dispatcher, and the CLI.
• Amp — the asynchronous concurrency framework. Reactor is built on Amp's fiber-based event loop, which enables truly non-blocking I/O. This means your bot can handle many concurrent requests without spawning threads or processes, and long-running operations (HTTP calls, database queries, file I/O) never block the event loop.
• Neili — the asynchronous Telegram client library. Neili wraps the entire Telegram Bot API in non-blocking methods, provides a long-polling Poller with concurrency control, and handles webhook input parsing. It is what actually talks to Telegram on Reactor's behalf.

Together these three layers give you a bot that is fast, memory-efficient, and easy to reason about – while still feeling like a familiar, Laravel-inspired PHP application.

The skeleton ships with a fully configured project layout, working example handlers, middleware, migrations, localisation files, and CLI commands, so you can go from composer create-project to a running bot in under five minutes.

Table of Contents

1. Features
2. Architecture Overview
3. Requirements
4. Quick Start
5. Configuration
6. Project Structure
7. The Update Lifecycle
8. Writing Handlers
9. Writing Middleware
10. Keyboard Builder
11. Working with the Database
12. Queue System
13. Localisation
14. Webhook Mode
15. CLI Commands
16. Multi-Process Mode
17. Production Checklist
18. Contributing
19. License

Features

• Attribute-based routing — commands, text handlers, callbacks, step handlers, and fallbacks are all declared with PHP 8 attributes.
• Asynchronous by design — powered by Amp fibers and the Neili Telegram client, so I/O never blocks.
• Middleware pipeline — global, group, and local middleware, ordered by priority.
• Dependency injection — a powerful container with auto-resolution, contextual bindings, tags, and scoped instances.
• Service providers — modular registration and booting of services.
• Multi-source configuration — package defaults, application config, and runtime overrides are merged deterministically.
• Eloquent database layer — full ORM with migrations, seeders, and an interface-driven repository pattern.
• Database-backed queue — dispatch background jobs and process them via a worker command.
• Scheduler — cron-based task scheduling with overlap prevention.
• Caching — file, array, Redis, and Memcached drivers behind a single interface.
• Localisation — JSON translation files with fallback support.
• Package ecosystem — discover packages, auto-register their providers, and publish their assets.
• Structured logging — PSR-3 logger backed by Monolog with rotating file handler.
• Centralised error handling — user-friendly exceptions that respond in the user's own language.
• Both polling and webhook modes — switch with one environment variable.

Architecture Overview

Understanding how the three layers fit together is the key to getting the most out of this skeleton.

When an update arrives:

1. Neili receives and decodes it.
2. Amp schedules the processing fiber on the event loop.
3. Reactor resolves a handler, runs the middleware pipeline, invokes the handler, and lets the handler send a reply (again via Neili, again async).
4. The whole thing happens without blocking, so other updates can be processed concurrently.

This is what makes Reactor well suited for bots that talk to external APIs, do database work, or send many messages in a short time.

Requirements

• PHP >= 8.1 (Reactor uses enums, readonly properties, first-class callable syntax, and fibers)
• Composer
• PDO extension for your chosen database
• ext-json, ext-mbstring (usually enabled by default)
• Optional: ext-redis or ext-memcached if you switch the cache driver
• SQLite is used by default; MySQL is also fully supported

Quick Start

1. Create the project

2. Configure your environment

Open .env and set your bot token. The bare minimum:

3. Run migrations

This creates the users, jobs, and posts tables.

4. Start the bot

You should see output like:

5. Test it

Open Telegram, find your bot, and send /start. You should receive a welcome message with the main menu keyboard.

Configuration

All configuration lives in config/ and reads from .env via the env() helper. The skeleton ships with four config files.

config/app.php

config/bot.php

config/database.php

MySQL and other drivers are supported through illuminate/database. Just add a connection entry and change DB_CONNECTION.

config/cache.php

Project Structure

The Update Lifecycle

Every incoming Telegram update passes through the same pipeline. Understanding it is essential before writing handlers.

Key points:

• Routing is priority-driven. A higher priority value wins. Ties are broken deterministically by file discovery order (sorted).
• Middleware can short-circuit. Returning true from MiddlewareInterface::handle() stops processing; the handler will not run.
• Handlers never need to construct the Telegram client. The BaseHandler already injects it via the container, and $this->reply(...) handles all the plumbing.
• Errors are caught centrally. ErrorHandler logs them and, for UserFriendlyException, sends a localised message to the user.

Writing Handlers

Handlers are plain PHP classes that extend App\Handlers\BaseHandler and use attributes to declare how they should be matched.

The Base Class

BaseHandler (in app/Handlers/BaseHandler.php) provides:

Available Attributes

Example 1 — A Command Handler

Notes:

• A class can carry multiple #[Text] attributes – the handler responds to all of them.
• isCommand: true tells the router to match against the parsed command name, stripping the @BotUsername suffix automatically.
• priority: 100 beats anything with a lower priority on the same trigger.

Example 2 — A Text/Button Handler

The name: 'about' refers to a translation key. The router compares the incoming message text against the translated value of that key in the user's language. This means the same handler responds to "ℹ️ About" in English and "ℹ️ درباره" in Persian – no extra code required.

Example 3 — A Callback Handler

Callback handlers can also use a regex pattern:

When a regex matches, the captured groups are passed to handle() as $params:

Example 4 — A Step Handler

Steps are used for multi-step conversations. When the user's step column matches a registered step name, that step's handler runs.

Generate step handlers with:

Example 5 — A Fallback Handler

The fallback runs when no other handler matches. Only one fallback is used — the one with the highest priority.

If you delete this file, Reactor will fall back to its built-in UnknownCommandHandler, which sends the same unknown_command translation. The application-level fallback exists so you can customise the response.

Nested Handlers

Handlers are discovered recursively. Any PHP file under app/Handlers/ (including subdirectories) is scanned. Subdirectory names become part of the class namespace.

For example, app/Handlers/Admin/PingHandler.php:

No additional registration is required — the router picks it up automatically.

Generating a Handler

This creates app/Handlers/EchoHandler.php with a starter template.

Writing Middleware

Middleware runs before the handler and can inspect, modify, or abort the update. Middleware is executed in three phases, in this order:

1. Global — runs for every update.
2. Group — runs when the handler's #[Group] matches.
3. Local — runs when the handler lists the middleware via #[UseMiddleware].

Within each phase, middleware is sorted by descending priority (higher runs first).

The Interface

Return true to stop processing. Return false to continue.

Example — Logging Middleware

Middleware is auto-discovered from app/Middleware/, so no registration is required.

Middleware Modes

• GLOBAL — always runs.
• GROUP — runs only for handlers whose #[Group] intersects the middleware's groups list.
• LOCAL — runs only when a handler explicitly lists it in #[UseMiddleware].

Restricting by Update Type

Generating a Middleware

Dependency Injection in Middleware

Middleware is resolved from the container, so you can type-hint any service in the constructor:

The container resolves all dependencies automatically.

Keyboard Builder

App\Keyboard is a small helper that wraps Neili's KeyboardBuilder and translates button labels automatically.

Main Menu

Back Button

Custom Menu

Pass a flat array of translation keys or an array of ['label' => 'key'] entries; buttons are laid out two per row.

Usage

Inline Keyboards

For inline keyboards (callback buttons), build the array manually and pass it to reply():

Handlers decorated with #[Callback(data: 'confirm')] will receive the callback.

Working with the Database

The skeleton uses illuminate/database (Eloquent) via the EloquentManager class, which implements the framework's DatabaseManagerInterface. Migrations are run through the CLI, and models are standard Eloquent models.

Models

Two models ship with the skeleton:

App\Models\User — stores Telegram users, language preference, current step, and temporary data.

App\Models\Job — represents a queued job record.

Repository Pattern

User persistence is abstracted behind UserRepositoryInterface (app/Contracts/Repository/UserRepositoryInterface.php). The concrete implementation is EloquentUserRepository.

The repository is registered in AppServiceProvider and both the framework-level UserProviderInterface and the application-level UserRepositoryInterface alias the same singleton, so consumers get a consistent instance.

Available methods:

Migrations

Migrations extend Reactor\Database\Migrations\Migration:

Generate a new migration:

Migration files are named YYYY_MM_DD_HHMMSS_snake_case_name.php. The class name is derived by CamelCasing the portion after the timestamp.

Seeding

Run with:

You can run a specific seeder class:

Using the Database Directly

Resolve the manager from the container:

Or just use Eloquent models directly:

Queue System

Reactor ships with a database-backed queue. Jobs are dispatched through the QueueManager and processed by a worker command.

Writing a Job

Extend Reactor\Queue\BaseJob and implement JobInterface:

BaseJob provides:

• $this->client — the Neili client
• $this->logger
• $this->language
• $this->userProvider

Dispatching a Job

Processing Jobs

• --queue (or -q): queue name (default: default)
• --max (or -m): maximum jobs to process before exiting (default: 10)

The worker:

1. Pops a job inside a transaction.
2. Resolves the job class from the container (so constructor DI works).
3. Calls handle($payload['data']).
4. On success, deletes the job.
5. On failure, releases the job back onto the queue with a 60-second delay.

For production, run the worker under a supervisor (systemd, supervisord, etc.) so it restarts on crash.

Localisation

Translations are stored as flat JSON files under lang/, keyed by language code.

Adding Strings

lang/en.json:

lang/fa.json:

Using Translations

If a key is missing in the requested language, the default language's value is used. If it's missing there too, the key itself is returned.

Managing the User's Language

The SyncUserMiddleware sets the language automatically from Telegram's language_code the first time a user is seen. To update a user's language:

Adding a New Language

1. Create lang/<code>.json (e.g. lang/ar.json).
2. Add the translated keys.
3. Optionally add the language name to app.language_names in config/app.php.

No code changes are needed — the Language service loads all JSON files at boot.

Webhook Mode

Webhook mode is faster and cheaper than polling because Telegram pushes updates directly to your server instead of your bot repeatedly asking for them. Use it in production.

Enabling Webhook Mode

In .env:

public_html/webhook.php is the entry point:

Registering the Webhook

Point Telegram at your public URL and pass the same secret:

Important Notes

• The webhook endpoint must be HTTPS with a valid certificate. Telegram rejects HTTP.
• public_html/ is the document root on your server. Point your vhost (Apache, Nginx, Caddy) at it.
• No long-running process is needed in webhook mode. Every update is a fresh PHP request.
• The webhook_secret must match Telegram's secret_token. Reactor verifies the X-Telegram-Bot-Api-Secret-Token header automatically.

Nginx Example

CLI Commands

The reactor.php script at the project root bootstraps Reactor and exposes a Symfony Console application.

Migration Commands

Database Seeding

Code Generation

Queue & Scheduling

Packages

Scheduling

Run schedule:run every minute via cron:

Define scheduled tasks in a ScheduleKernel subclass (see config/app.php → schedule_kernel).

Multi-Process Mode

Reactor can process updates using multiple concurrent worker processes. Enable it in .env:

When enabled, TelegramBootstrapper configures Neili's Settings with setMultiProcess(true) and passes the PHP binary path. Neili then forks worker processes to handle updates in parallel.

Choose multi-process mode when:

• You receive a very high volume of updates.
• Handlers perform blocking operations that you cannot easily make async.
• You want to isolate a crashing handler from the rest of the bot.

Leave it disabled when:

• Your handlers are already async (they usually are, since Reactor + Neili are async).
• You are running on shared hosting where pcntl or proc_open is restricted.
• You need a single, deterministic execution order.

Production Checklist

Before deploying your bot, make sure you have:

• [ ] Set APP_ENV=production and DEBUG_MODE=false in .env.
• [ ] Set TELEGRAM_VERIFY_SSL=true (never disable TLS verification in production).
• [ ] Protected your .env – it should never be committed to Git and should be readable only by the web/CLI user.
• [ ] Run migrations with php reactor.php migrate before starting.
• [ ] Configure a supervisor for the queue worker and (in polling mode) for bot.php.
• [ ] Set up log rotation – Monolog writes to storage/logs/app.log with a 30-day rotation policy out of the box.
• [ ] Add a cron entry for schedule:run if you use the scheduler.
• [ ] Prefer webhook mode over polling on any serious deployment – it's cheaper and lower latency.
• [ ] Firewall your SQLite or MySQL instance so it's only reachable from your application.
• [ ] Back up your database regularly. For SQLite, a simple file copy is enough.

Example: systemd Unit for the Polling Process

Example: systemd Unit for the Queue Worker

Contributing

Contributions to the skeleton are welcome. Please:

1. Fork the repository.
2. Create a feature branch: git checkout -b feature/amazing-feature.
3. Commit your changes: git commit -m 'Add some amazing feature'.
4. Push the branch: git push origin feature/amazing-feature.
5. Open a Pull Request.

Please keep your code consistent with the existing style and ensure existing tests still pass. If you add functionality, add a corresponding test where practical.

License

This project is licensed under the MIT License. See the LICENSE file for details.