Download the PHP package aiobale/aiobalephpapi without Composer
On this page you can find all versions of the php package aiobale/aiobalephpapi. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Download aiobale/aiobalephpapi
More information about aiobale/aiobalephpapi
Files in aiobale/aiobalephpapi
Package aiobalephpapi
Short Description Local-first Laravel HTTP API for the Bale platform.
License MIT
Homepage https://github.com/MirAbolfazl/aiobalephpapi
Informations about the package aiobalephpapi
رابط HTTP برای Bale
این پروژه یک API مبتنی بر Laravel برای استفاده از قابلیتهای کتابخانهٔ PHP بله است. حسابهای بله، نشستها، فایلها و webhookها در دیتابیس نگهداری میشوند. API از توکن Bearer استفاده میکند و مستندات OpenAPI و پنل مدیریت Filament دارد.
این نسخه برای اجرای محلی طراحی شده است. پیش از انتشار عمومی، تنظیمات محیط، دامنهها، محدودیتهای شبکه، پشتیبانگیری و سیاست نگهداری داده را متناسب با زیرساخت خود بازبینی کنید.
قابلیتها
- ثبتنام و ورود کاربر و ساخت توکن API
- اتصال حساب بله با شماره تلفن، کد ورود و در صورت نیاز رمز دومرحلهای
- نگهداری رمزگذاریشدهٔ نشست بله و جداسازی دادههای کاربران
- فهرست و اجرای عملیات موجود در
aiobalephpبا اعتبارسنجی schema - آپلود خصوصی و دانلود کنترلشدهٔ رسانهها
- webhook امضاشده، صف ارسال، retry و ثبت نتیجه
- پنل مدیریت Filament و مستندات OpenAPI
نیازمندیها
- PHP 8.3 یا بالاتر بههمراه افزونههای
curl,fileinfo,mbstring,openssl,pdo_mysqlوsodium - Composer
- MySQL 8 یا نسخهٔ سازگار
- پوشهٔ کتابخانهٔ
aiobalephpدر کنار این پروژه؛ مقدار پیشفرض Composer به../aiobalephpاشاره میکند
نصب و راهاندازی
از پوشهٔ پروژه اجرا کنید:
در MySQL یک دیتابیس بسازید:
مقادیر اتصال دیتابیس را در .env تنظیم کنید:
سپس جداول را بسازید:
APP_KEY برای رمزگذاری نشستهای بله، رمز webhook و challenge ورود استفاده میشود. آن را ثابت و محرمانه نگه دارید؛ تغییر آن اطلاعات رمزگذاریشدهٔ قبلی را غیرقابلخواندن میکند. فایل .env را در مخزن کد قرار ندهید.
اجرای محلی
سرور HTTP:
در ترمینالی دیگر، worker صف را اجرا کنید تا webhookها تحویل داده شوند:
برای دریافت رخدادهای زندهٔ یک حساب بله و قراردادن آنها در صف webhook:
عدد 1 شناسهٔ حساب بله در دیتابیس است. این فرایند باید فعال بماند؛ برای هر حسابی که باید رخدادهای زندهاش دریافت شود، یک watcher اجرا کنید. برای توقف watcher از Ctrl+C استفاده کنید.
مستندات API و پنل مدیریت
- مستندات تعاملی OpenAPI 3.1:
http://127.0.0.1:8000/docs/api - سند OpenAPI برای Swagger UI، Postman و تولید client:
http://127.0.0.1:8000/docs/api.json - پنل مدیریت:
http://127.0.0.1:8000/admin
در صفحهٔ مستندات از Authorize برای واردکردن توکن API استفاده کنید؛ مسیرهای محافظتشده از Bearer authentication استفاده میکنند. سند بهصورت خودکار از routeها، validation و توضیحات controllerها ساخته میشود. برای بررسی یا خروجیگرفتن از سند:
مستندات و پنل را در محیط محلی باز کنید. دسترسی ادمین بهصورت پیشفرض برای همه غیرفعال است و هیچ حساب یا رمز پیشفرضی ساخته نمیشود.
احراز هویت API
ثبتنام، توکن Bearer برمیگرداند:
برای ورود از POST /api/v1/auth/login با فیلدهای email و password استفاده کنید. در درخواستهای محافظتشده توکن را بفرستید:
خروج از API با POST /api/v1/auth/logout توکن جاری را باطل میکند. برای درخواستهای محافظتشده، هدر Accept: application/json را بفرستید تا خطاها در قالب JSON برگردند.
اتصال حساب بله
۱. درخواست ارسال کد ورود:
شناسهٔ challenge_id را از پاسخ بردارید. سپس کد دریافتشده را تأیید کنید:
اگر حساب بله رمز دومرحلهای داشته باشد، این درخواست با وضعیت 409 و کد two_step_password_required پاسخ میدهد. در آن صورت:
challengeها پس از مدت محدود منقضی میشوند و تعداد تلاشهای ورود نیز محدود است. نشستهای ذخیرهشده را از GET /api/v1/bale/accounts ببینید. عملیات خروج از حساب بله:
فهرست و اجرای عملیات بله
فهرست عملیات و schema ورودی آنها:
برای مرور آفلاین همهٔ ۶۹۰ کلید رجیستری و ۶۸۹ زوج یکتای سرویس/متد، به مرجع کامل RPC مراجعه کنید. مرجع شامل نام دقیق RPC، فیلدهای درخواست، شمارههای protobuf، فیلدهای اجباری و مدل پاسخ است. endpoint بالا schemaهای تودرتو را نیز بهصورت بازشده برمیگرداند و منبع بهروز برای ساخت payload است.
این فایل از MethodRegistry کتابخانه تولید میشود. برای بهروزرسانی کپی API در workspaceای که
دو پروژه کنار هم هستند:
هر عملیات ثبتشده در MethodRegistry از مسیر زیر قابل اجراست؛ عملیات چرخهٔ ورود از این مسیر عمومی مستثنا هستند:
بدنه باید ورودی را در payload قرار دهد. نمونهٔ ساختاری برای SendMessage:
schema دقیق هر عملیات و فیلدهای لازم را از endpoint فهرست عملیات دریافت کنید. پاسخهای کتابخانه به JSON تبدیل میشوند؛ مقدارهای باینری بهصورت Base64 همراه با مشخصکردن encoding برگردانده میشوند.
نمونههای آماده برای REST Client در VS Code در examples/rpc.http قرار دارند؛ شامل فهرست schemaها، فراخوانی GetMyWallets بدون payload و ارسال متن با SendMessage. برای RPCهای دیگر، نام مسیر را از فهرست یا مرجع کامل بردارید و فیلدها را داخل payload بفرستید.
رسانهها
فایلها روی دیسک خصوصی Laravel ذخیره میشوند و برای دانلود باید از همان کاربر API احراز هویت شود. نمونهٔ آپلود:
مسیرهای رسانه:
GET /api/v1/media— فهرست فایلهای کاربر جاریPOST /api/v1/media— آپلود فایلGET /api/v1/media/{media_id}/download— دانلود فایل متعلق به کاربر جاریDELETE /api/v1/media/{media_id}— حذف فایل
حد پیشفرض آپلود محلی ۵۰ مگابایت است و با BALE_MAX_UPLOAD_KB تغییر میکند.
برای آپلود مستقیم به فضای Bale، حساب بله را در مسیر انتخاب و فایل را multipart بفرستید:
POST /api/v1/bale/accounts/{account}/files فقط فایل را در Bale ذخیره میکند و آن را
به چت نمیفرستد یا در دیسک API نگه نمیدارد. پاسخ شامل file_id, access_hash,
size, name و mime_type است؛ این مقادیر را میتوان در payload هر عملیات Bale
مطابق schema همان عملیات استفاده کرد. این مسیر هم از حد BALE_MAX_UPLOAD_KB استفاده میکند.
برای اتصال آپلود به مقصدی که بعداً فایل را در آن میفرستید، peer_id و peer_type
را هم بفرستید (1 برای کاربر خصوصی و 2 برای گروه).
Webhookها
برای ساخت webhook، حساب بله باید فعال باشد. فقط رخدادهای تعریفشده در config/bale.php پذیرفته میشوند. نمونه:
راز webhook در پاسخ ساخت یا چرخاندن راز نمایش داده میشود و بعداً قابل بازیابی نیست؛ آن را امن نگه دارید. رخدادها در صف ذخیره و با worker تحویل داده میشوند. درخواست شامل هدرهای X-Bale-Event, X-Bale-Delivery, X-Bale-Timestamp و X-Bale-Signature است. امضا برابر HMAC-SHA256 روی متن timestamp.body با راز webhook است و به شکل sha256=<hex> ارسال میشود.
URL webhook باید HTTPS، بدون اطلاعات کاربری و روی پورت پیشفرض باشد. میزبانهای محلی، IPهای خصوصی/رزروشده و مقصدهایی که به آنها resolve میشوند رد میشوند. هنگام ارسال، DNS دوباره اعتبارسنجی و به IP عمومی بررسیشده pin میشود؛ redirect نیز دنبال نمیشود. نتیجه و وضعیت retry را از مسیرهای زیر ببینید:
GET /api/v1/webhooksPATCH /api/v1/webhooks/{webhook_id}DELETE /api/v1/webhooks/{webhook_id}GET /api/v1/webhooks/{webhook_id}/deliveries
مدیریت کاربران
کاربر موردنظر را ابتدا با endpoint ثبتنام API ایجاد کنید. سپس در ترمینال پروژه دسترسی پنل را به او بدهید:
بعد از آن همان کاربر میتواند وارد /admin شود. برای لغو دسترسی ادمین، مقدار is_admin کاربر را در دیتابیس false کنید.
پیکربندیهای مهم
| متغیر | کاربرد | مقدار پیشفرض |
|---|---|---|
BALE_AUTH_CHALLENGE_TTL_MINUTES |
عمر challenge ورود بله | 10 |
BALE_MAX_UPLOAD_KB |
حداکثر اندازهٔ فایل آپلودی | 51200 |
BALE_WEBHOOK_MAX_ATTEMPTS |
تعداد تلاش برای تحویل webhook | 5 |
BALE_WEBHOOK_TIMEOUT_SECONDS |
مهلت پاسخ مقصد webhook | 8 |
QUEUE_CONNECTION |
درایور صف | database |
برای اجرای production، APP_DEBUG=false بگذارید، از HTTPS استفاده کنید، صف را با process manager پایدار اجرا کنید و دسترسی دیتابیس و فایل .env را محدود نگه دارید.
آزمونها
اجرای تستهای API:
اجرای تستهای کتابخانهٔ PHP در پوشهٔ همسایه:
All versions of aiobalephpapi with dependencies
aiobale/aiobale-php Version ^1.0.3
dedoc/scramble Version ^0.13.53
filament/filament Version ^5.11
laravel/framework Version ^13.17
laravel/sanctum Version ^4.0
laravel/tinker Version ^3.0