BalePhp

PHP 8.2 SDK for the Bale Bot API — typed objects, inline keyboards,
long polling & webhooks, first-class Laravel integration.

PHP ≥ 8.2 · zero runtime dependencies · PHPUnit tested · PSR-4

---

English

Bale is the messenger millions of Iranians use daily, yet its bot API is usually consumed through raw cURL snippets and associative arrays. BalePhp wraps it in a small, typed, dependency-free SDK:

• Typed update objects — Update::command(), chatId(), callbackData(), fromId() handle the annoying parsing (/start@Bot heads, missing sections) once, correctly
• Inline keyboards — fluent builder: InlineKeyboard::make()->row([...])
• Both transports — long polling (pollUpdates() with internal offset bookkeeping) and webhooks (BaleClient::fromWebhook($request->getContent()))
• Laravel integration — service provider + facade, token from .env, published config with one artisan command
• Testable transport — inject a fake callable(string, array): mixed and assert exact payloads without touching the network

Standalone usage

use BalePhp\BaleClient;
use BalePhp\Objects\InlineButton;
use BalePhp\Objects\InlineKeyboard;

$bale = new BaleClient(getenv('BALE_TOKEN'));

$keyboard = InlineKeyboard::make()->row([
    InlineButton::callback('وضعیت سیستم', 'status'),
    InlineButton::url('وب‌سایت', 'https://example.com'),
]);

$bale->sendMessage($chatId, 'سلام! چه کمکی می‌تونم بکنم؟', $keyboard);

Webhook endpoint (framework-free)

$update = BaleClient::fromWebhook(file_get_contents('php://input'));

match ($update->command()) {
    'start' => $bale->sendMessage($update->chatId(), 'خوش آمدید!'),
    'help'  => $bale->sendMessage($update->chatId(), 'راهنما…'),
    default => $bale->sendMessage($update->chatId(), $update->text() ?? '؟'),
};

http_response_code(200);

Laravel

composer require godde3s/bale-php
php artisan vendor:publish --tag=bale-config
# .env → BALE_TOKEN=123:abc

use BalePhp\Laravel\BaleFacade as Bale;

Route::post('/bale/webhook', function (\Illuminate\Http\Request $request) {
    $update = \BalePhp\BaleClient::fromWebhook($request->getContent());
    Bale::sendMessage($update->chatId(), 'از لاراول سلام! 👋');
    return 'ok';
});

Testing your integration

$fakeTransport = function (string $method, array $payload) {
    expect($payload['text'])->toBe('سلام');
    return ['message_id' => 1];
};
$client = new BaleClient('TEST', $fakeTransport);   // no network involved

---

فارسی

بalePhp یک SDK سبک و تایپ‌دار برای API ربات بله است: بدون وابستگی اجراzeit، با آبجکت‌های تایپ‌دار، کیبوردهای شیشه‌ای (inline)، پشتیبانی از هم long-polling و هم webhook، و سرویس‌پروایدر آماده برای لاراول. توکن را در .env بگذارید و با Bale::sendMessage() پیام بفرستید — همین‌قدر ساده.

Running the SDK's own tests

composer install
composer test          # 6 tests: payloads, offsets, webhooks, error mapping

License

MIT © Reza Bazdar (Godde3s)