README

Neili is an async-first PHP library built on Amp that streamlines creating robust Telegram bots. It provides a non-blocking HTTP client, wrappers for all Telegram Bot API methods, a long-polling Poller with concurrency control, and a flexible webhook handler. Neili is optimized for both constrained hosting environments and long-running worker processes.

If this project is helpful to you, you may wish to give it a🌟 to support future updates and feature additions!

Donate

Table of contents

• Introduction
• Features
• Requirements
• Installation
• Configuration
• Usage
• Multi-process
• Polling vs Webhook
• Settings
• Keyboard Builder
• Client Methods Reference
• TODO
• License

Introduction

Neili wraps the Telegram Bot API with Amp-based asynchronous primitives. It offers:

• Safe, non-blocking HTTP requests
• Async message sending, media uploads, and chat management
• Receiving updates via long polling or webhooks
• Lightweight, framework-agnostic architecture suitable for both short-lived webhook endpoints and long-running pollers

Features

• Async-first Telegram Bot API wrapper built on Amp HTTP client
• Poller implementation with configurable timeout, exponential backoff, and concurrency
• Webhook helper compatible with standard PHP and multi-process setups
• Minimal external dependencies for easy integration
• Multiprocess support for concurrent update handling
• Examples included for polling, webhook, sending messages/media, and keyboards

Requirements

Neili requires the following environment and extensions:

• PHP >= 8.1
• amphp/file ^3.2 — Async file handling
• amphp/http-client ^5.3 — Non-blocking HTTP requests
• PHP extensions: fileinfo, posix
• PHP function exec() — Required only if using multi-process mode in webhook

Installation

Install via Composer:

composer require afaztech/neili

Or clone repository:

git clone https://github.com/afaztech/neili.git
cd neili
composer install

Autoloading is PSR-4 (Neili\ → src/).

Configuration

Neili uses Neili\Settings for configuration.

Example:

use Neili\Settings;

$settings = (new Settings())
    ->setAccessToken('TELEGRAM_BOT_TOKEN')
    ->setApiUrl('https://api.telegram.org/bot')
    ->setPollerTimeout(5)
    ->setPollerMaxConcurrency(null);

Usage

Long Polling Example

use Neili\Client;
use Neili\Poller;
use Neili\Settings;

$settings = (new Settings())->setAccessToken('TELEGRAM_BOT_TOKEN');
$client = new Client($settings);

$poller = new Poller($client);

$poller->onUpdate(function(array $update) use ($client) {
    $chatId = $update['message']['chat']['id'] ?? null;
    $text = $update['message']['text'] ?? null;
    if ($chatId && $text) {
        $client->sendMessage((int)$chatId, 'Echo: '.$text);
    }
});

$poller->start();

Webhook Example

use Neili\Client;
use Neili\Settings;

$settings = (new Settings())->setAccessToken('TELEGRAM_BOT_TOKEN');
$client = new Client($settings);

$update = $client->handleUpdate('WEBHOOK_SECRET_TOKEN');
if ($update) {
    // Async dispatch example
}

Multi-process

Neili supports multi-process update handling in webhook mode using PHP exec().

$settings->setUseMultiProcess(true)
         ->setPhpBinary('/usr/bin/php');

Incoming webhook updates are automatically forked into separate PHP processes for non-blocking execution.

Polling vs Webhook

Settings

Logger

Neili’s Settings constructor directly accepts a PSR-3 logger:

• You can pass any PSR-3 compatible logger (e.g., Monolog).
• If you do not provide a logger, Neili will use its default lightweight async logger.

Example:

use Neili\Settings;
use Monolog\Logger as MonologLogger;
use Monolog\Handler\StreamHandler;

$logger = new MonologLogger('bot', [new StreamHandler('/path/to/logfile.log')]);

$settings = new Settings($logger)
    ->setAccessToken('TELEGRAM_BOT_TOKEN');

This ensures full async logging support in both long-polling and multi-process webhook modes.

Keyboard Builder

Neili\KeyboardBuilder provides a fluent interface for building either a reply keyboard or an inline keyboard. Important: You cannot mix inline and regular rows in the same keyboard.

Methods Table

Example: Reply Keyboard

use Neili\KeyboardBuilder;

$keyboard = (new KeyboardBuilder())
    ->row('Yes', 'No')
    ->row('Maybe')
    ->resize(true)
    ->oneTime(true)
    ->build();

Example: Inline Keyboard

use Neili\KeyboardBuilder;

$keyboard = (new KeyboardBuilder())
    ->inlineRow(['Button1' => 'callback_1', 'Button2' => 'callback_2'])
    ->inline()
    ->build();

Client Methods Reference

All Client methods in Neili are asynchronous and return Amp\Future objects. A Future represents a pending result; you can use onResolve() to handle the result or error when it completes.

How Future Works

Amp\Future lets you work asynchronously:

$future = $client->sendMessage($chatId, 'Hello async');

$future->onResolve(function($error, $result) {
    if ($error) {
        echo "Error: ".$error->getMessage();
    } else {
        print_r($result); // Telegram API response
    }
});

Or await() to block until the result is ready (inside an async context):

$result = $client->sendMessage($chatId, 'Hello')->await();
print_r($result);

Note: Every Client method returns a Future, which means all network requests are non-blocking by default, letting you run multiple requests concurrently without waiting.

TODO

• Add MTProto support
• Implement login with User Bot

License

MIT License — See LICENSE file.