nutgram is a PHP 8.2 Telegram bot framework with a Laravel path

The smallest useful bot is about ten lines

nutgram is described as the Telegram bot framework that doesn't drive you nuts, and the README makes the case that it takes advantage of the latest PHP 8.2 features while treating speed, scalability and flexibility as its strength, letting you quickly make simple bots while still providing advanced features for complicated flows. The example shows how little ceremony that takes:

<?php

use SergiX44\Nutgram\Nutgram;

$bot = new Nutgram($_ENV['TOKEN']);

$bot->onCommand('start', function(Nutgram $bot) {
    $bot->sendMessage('Ciao!');
});

$bot->onText('My name is {name}', function(Nutgram $bot, string $name) {
    $bot->sendMessage("Hi $name");
});

$bot->run();

Two things in that snippet are worth noticing. The handler is a closure that receives the bot instance, and the pattern matcher interpolates a named placeholder into the callback signature, so the captured name arrives as a typed PHP string rather than something you parse by hand. The second is that the same Nutgram object is the handler and the sender, so a bot that needs to call a method does not need a separate service injected. The install is a single composer command, and the framework is also usable through a plain PHP Starter Kit, a Laravel package or a Symfony bundle.

A feature list that maps to real bot problems

The feature list is long, and a few entries do more work than the rest. The framework agnostic line is the foundation, since a bot can run in a plain PHP project, in Laravel or in Symfony, and the official integrations are separate repositories rather than something bolted on. The handlers system and the middleware system are the core of the design, and the grouping system exists to apply middleware and scopes to multiple handlers at once, which is what keeps a growing bot from becoming a switch statement. Auto-registration of bot commands with scope support means the command list published to Telegram is derived from your code rather than maintained by hand. The conversations system is how you model multi step flows, since a bot that asks for a name and then a date needs state that survives between updates, and the storage system provides global and user data for the same reason. Enhanced keyboard management and the InlineMenu class for easy creation of inline menu messages cover the reply markup cases that every bot hits, and the rate limiting system is the one that saves the most time, because a bot that exceeds the API limits gets throttled or cut off.

Swappable cache, logger and storage keep it framework agnostic

The framework agnostic claim rests on specific extension points rather than on an aspiration. The cache system is described as one where you can use your own cache system that implements PSR-16 CacheInterface, and the logging system the same, with your own logger implementing PSR-3 LoggerInterface. That matters more than it sounds. In a Laravel application you want the framework's cache and the framework's logger, so a bot shares the same Redis instance and the same log stream as the rest of the application rather than opening a second connection and a second log file. In a plain PHP project, or a Symfony one, you supply your own implementations of the same two interfaces. The same reasoning applies to the storage system, which holds global and user data, and to the middleware system, since middleware is how a Laravel application would attach its own concerns to bot handlers. The API version the framework targets is Telegram Bot API 10.3 as of August 24, 2026, and the documentation says it supports all types and methods according to the last Telegram Bot API update, so the method surface follows Telegram rather than being curated.

Type safety and the request types as a design choice

Several of the listed features point at the same underlying decision, which is to treat the Telegram API as typed data rather than as an array of mixed values. Using enums where possible, extending the Nutgram class and Telegram types with user-created methods, and having all types and methods according to the last Bot API update are three faces of it. A bot that handles inline callbacks or payments touches deeply nested payloads, and with untyped arrays a field rename in the Telegram API becomes a runtime surprise rather than a static error. The web validation feature is the same idea applied to inbound data, and the flexible update processing is how the framework routes an update to the right handler. It also explains the deep linking helper class and the proxy methods for a shorter syntax, which exist so that the common calls do not need a full payload object when the long form is verbose.

Error handling, testing and bulk sending

Three features are about operating the bot rather than building it. Customizable error handling means a failed update does not have to become an unhandled exception that kills the worker, and the framework lets you decide what a failure looks like. The testing system matters more than bot frameworks usually admit, because a bot is a state machine that responds to messages from strangers, and being able to assert on how a handler replies without going through Telegram is what makes a bot refactor safe. Bulk message sending and chunked message sending cover the two halves of the same problem, where a broadcast to a large audience has to be split because the API limits message length, and a bulk operation has to be paced so you do not hit the rate limit while sending. The Deep Link helper class is the small feature that saves the most time in practice, since building a correct deep link for a user, a chat or a start parameter is fiddly and easy to get subtly wrong.

Version support, packaging and the shape of the repository

The supported versions table is short and it settles the version question for most teams. Nutgram 3.0 requires PHP 8.0 and is listed as EOL, while Nutgram 4.0 requires PHP 8.2 and is listed as On going, so the current line is 4.x on PHP 8.2 and older. The recent releases show steady maintenance in that line, with 4.50.3 published on 2026-10-04, 4.50.2 on 2026-10-01 and 4.50.1 on 2026-09-15, and the last push on 2026-10-04. The package is published on Packagist as nutgram/nutgram, is licensed under MIT, and the repository carries a CHANGELOG.md, a CODE_OF_CONDUCT.md and a psalm.xml for static analysis, with phpunit.xml.dist for the test suite. The examples directory has four small programs, an echobot, a photo downloader, an album sender and a bulk messenger, and those are the fastest way to see a pattern such as album sending or bulk delivery working end to end before you write it inside your own application.

Editorial conclusion

Adopt nutgram when you are building a Telegram bot in PHP and want a typed API covering the Bot API surface with handlers, middleware and conversations rather than raw update parsing, and when you can work with PHP 8.2. Do not adopt it if your runtime is on PHP 8.0 or 8.1, since the 4.x line requires 8.2 and the 3.x line is listed as end of life. Verify first that the Bot API version the package targets matches what your bot needs, that the Laravel or Symfony integration you intend to use is on a compatible version, and that you read the CHANGELOG before a major bump, because the 3.x to 4.x jump also moved the PHP floor.

Frequently asked questions

Official sources

1. License: MIT
2. nutgram/nutgram on GitHub
3. Project website
4. README
5. Releases