Skip to main content

​
Installation

MadelineProto offers multiple installation methods to suit different project setups. Choose the method that works best for you.
Recommended: Use Composer for production projects. The PHAR method is best for quick testing and prototyping.

​
Quick Start (PHAR)

The fastest way to get started is using the PHAR distribution. This method automatically downloads MadelineProto and handles all dependencies.
1

Download madeline.php

Create a new PHP file with this code:
<?php

if (!file_exists('madeline.php')) {
    copy('https://phar.madelineproto.xyz/madeline.php', 'madeline.php');
}
require 'madeline.php';

$MadelineProto = new \danog\MadelineProto\API('session.madeline');
$MadelineProto->start();

$me = $MadelineProto->getSelf();
$MadelineProto->logger($me);
2

Run the script

Execute via CLI or browser:
php bot.php
The script will download MadelineProto automatically on first run.
3

Follow login prompts

Enter your phone number or bot token when prompted. A session file will be created to persist your login.
Alpha Version Notice: The PHAR distribution may contain alpha versions. For production, use Composer to install stable releases.
For production projects, install MadelineProto via Composer to get stable versions and better dependency management.

​
From Scratch

Starting a new project? Set it up with these commands:
1

Create project directory

mkdir my-telegram-bot
cd my-telegram-bot
2

Initialize Composer

composer init --name="myname/mybot" --type=project --require="danog/madelineproto:^8.0"
3

Install dependencies

composer install
4

Create your bot file

Create bot.php:
<?php

require 'vendor/autoload.php';

use danog\MadelineProto\EventHandler\Attributes\Handler;
use danog\MadelineProto\EventHandler\Message;
use danog\MadelineProto\EventHandler\SimpleFilter\Incoming;
use danog\MadelineProto\SimpleEventHandler;

class MyBot extends SimpleEventHandler
{
    public const ADMIN = "@me"; // Change this!
    
    public function getReportPeers()
    {
        return [self::ADMIN];
    }
    
    #[Handler]
    public function handleMessage(Incoming&Message $message): void
    {
        $message->reply("Hello from MadelineProto!");
    }
}

MyBot::startAndLoop('bot.madeline');
5

Run your bot

php bot.php

​
Add to Existing Project

Already have a Composer project? Just add MadelineProto: 
composer require danog/madelineproto
Then require the autoloader in your code: 
<?php

require 'vendor/autoload.php';

use danog\MadelineProto\API;

$MadelineProto = new API('session.madeline');
$MadelineProto->start();

​
Docker Installation

MadelineProto provides official Docker images for multiple platforms.

​
Supported Platforms

  • linux/amd64
  • linux/arm64
  • linux/riscv64
1

Create bot.php

Create your bot file with event handlers (see examples above).
2

Create Dockerfile

FROM hub.madelineproto.xyz/danog/madelineproto:latest

COPY bot.php /app/

CMD ["php", "/app/bot.php"]
3

Build and run

docker build -t my-telegram-bot .
docker run -it --name telegram-bot my-telegram-bot

​
Web Docker

For web-based bots served via HTTP: 
FROM hub.madelineproto.xyz/danog/madelineproto:latest

COPY . /app/

EXPOSE 8080

CMD ["php", "-S", "0.0.0.0:8080", "-t", "/app"]

​
Using Databases with Docker

To use MySQL, PostgreSQL, or Redis with Docker, use docker-compose: 
version: '3.8'
services:
  bot:
    image: hub.madelineproto.xyz/danog/madelineproto:latest
    volumes:
      - ./bot.php:/app/bot.php
    depends_on:
      - redis
    command: php /app/bot.php
  
  redis:
    image: redis:alpine
    volumes:
      - redis_data:/data

volumes:
  redis_data:
Then configure Redis in your bot: 
use danog\MadelineProto\Settings;
use danog\MadelineProto\Settings\Database\Redis;

$settings = new Settings;
$settings->setDb(
    (new Redis)
        ->setDatabase(0)
        ->setPassword('your_password')
);

MyBot::startAndLoop('bot.madeline', $settings);

​
Verification

Verify your installation by checking the MadelineProto version: 
<?php

require 'vendor/autoload.php'; // or require 'madeline.php';

use danog\MadelineProto\API;

echo "MadelineProto version: " . API::RELEASE . "\n";

​
Version Selection

# Latest stable version (recommended)
composer require danog/madelineproto

# Specific version
composer require danog/madelineproto:^8.0

# Development version
composer require danog/madelineproto:dev-master

​
Updating

​
Composer

composer update danog/madelineproto

​
PHAR

Delete madeline.php and run your script again - it will download the latest version: 
rm madeline.php
php bot.php

​
Next Steps

Check Requirements

Ensure all PHP extensions are installed

Quick Start Guide

Build your first bot in minutes

​
Troubleshooting

Increase PHP memory limit:
php -d memory_limit=512M composer install
Check Requirements and install missing extensions. On Ubuntu:
sudo apt install php8.2-mbstring php8.2-xml php8.2-gmp php8.2-curl
Download manually:
wget https://phar.madelineproto.xyz/madeline.php
Or use Composer instead for more reliable installation.
Always verify you’re running PHP 8.2 or higher (64-bit). Check with:
php -v
php -r "echo PHP_INT_SIZE * 8 . ' bit';"

Build docs developers (and LLMs) love

Get started for freeTalk to us