Upgrade Guide

• Upgrading To 4.0 From 3.x

Upgrading To 4.0 From 3.x

Estimated Upgrade Time: 15 Minutes

NOTE

LaraGram 4 is a largely additive release with minimal breaking changes to the bot layer. Most of the new work is in brand-new components (MTProto, Luna, the web layer). Bumping the dependency plus the steps below is usually all that is required.

PHP 8.5 Required

Likelihood Of Impact: High

LaraGram 4 requires PHP 8.5. Update your environment before upgrading.

Updating Dependencies

Likelihood Of Impact: High

In composer.json, set laraxgram/laragram to ^4.0 (and update any first-party packages to their 4.x releases), then run:

composer update

Post-Upgrade Steps

Likelihood Of Impact: High

The new web layer needs a few directories and config files that did not exist in 3.x. Apply the ones relevant to your application:

0. Update index.php. Replace the contents of the public/index.php file completely with the following value:

<?php

$serverPath = __DIR__."/../vendor/laraxgram/core/src/Foundation/resources/server.php";

$rawInput = file_get_contents('php://input');
$content = json_decode($rawInput, true);

$isBotUpdate = json_last_error() === JSON_ERROR_NONE
    && is_array($content)
    && array_key_exists('update_id', $content);

if ($isBotUpdate) {
    $server = escapeshellarg(json_encode($_SERVER));
    $inputs = escapeshellarg($rawInput);

    $log = "/dev/null";

    popen("php \"{$serverPath}\" {$inputs} {$server} >> {$log} 2>&1 &", "r");
} else {
    require_once $serverPath;
}

1. Migrate the sessions table:

Schema::create('sessions', function (Blueprint $table) {
    $table->string('id')->primary();
    $table->foreignId('user_id')->nullable()->index();
    $table->string('ip_address', 45)->nullable();
    $table->text('user_agent')->nullable();
    $table->longText('payload');
    $table->integer('last_activity')->index();
});

2. Create the storage cache directories. Views are compiled to storage/framework and sessions save to storage/sessions:

mkdir -p storage/framework/{views,sessions}

3. Enable web routing (if used). To serve HTTP routes, register them in bootstrap/app.php:

->withRouting(
    web: __DIR__.'/../routes/web.php',
    api: __DIR__.'/../routes/api.php',
)

4. Add the routes and resources folders as needed. Create only what you use — e.g. routes/web.php, resources/views, resources/css, resources/js.

5. Publish the new config files from vendor (for example session.php):

php laragram vendor:publish

6. Update the LaraGram installer so laragram new scaffolds 4.x projects:

composer global require laraxgram/installer

Redirects Documentation

Likelihood Of Impact: Low

The standalone redirects page is merged into HTTP responses. Documentation change only — the helpers are unchanged.

Adopting New Features (Optional)

None of this is required to upgrade:

• MTProto & User Clients — full Telegram client, no Bot API limits.
• Luna — React / Vue / Svelte frontends and Mini Apps.
• Web layer — routing, HTTP requests / responses, HTTP client, Blade, views, Vite, sessions.
• Conversations — declarative multi-step Q&A flows.
• API Resources, pagination, Precognition.