README

Rubika PHP

کتابخانهٔ PHP برای ساخت ابزارها و ربات‌های روبیکا

شروع سریع · امکانات · مستندات API · ورود و نشست · عیب‌یابی

معرفی

Rubika PHP یک کتابخانهٔ PHP برای ارتباط برنامه‌نویسی‌شده با روبیکا است. این پروژه ابزارهایی برای ورود و نگهداری نشست، ارسال و مدیریت پیام‌ها، کار با گروه و کانال، مخاطبین، رسانه‌ها، استوری‌ها، نظرسنجی، گفت‌وگوی صوتی و دریافت به‌روزرسانی‌ها فراهم می‌کند.

ساختار پروژه علاوه بر API سطح پایین، یک نقطهٔ شروع ساده برای ساخت ربات دارد. کدها و نمونه‌های این مستندات بر اساس ساختار همین مخزن نوشته شده‌اند؛ جزئیاتی که به حساب، نسخهٔ اپلیکیشن یا پاسخ سرور وابسته‌اند ممکن است در عمل نیاز به بررسی داشته باشند.

وضعیت پروژه: پیش از استفاده در حساب اصلی، ورود، ثبت دستگاه و پایداری نشست را روی حساب آزمایشی بررسی کنید. وجود یک متد در کتابخانه به معنی تضمین پشتیبانی همیشگی آن از سمت سرویس روبیکا نیست.

فهرست مطالب

ویژگی‌ها
نیازمندی‌ها
نصب
شروع سریع
دریافت و پاسخ به پیام‌ها
فرمان‌ها و Handlerها
ارسال و مدیریت پیام
فایل و رسانه
گروه‌ها و کانال‌ها
حساب، مخاطبین و حریم خصوصی
استوری، نظرسنجی و استیکر
گفت‌وگوی صوتی و تماس
ورود و مدیریت نشست
ذخیره‌سازی، لاگ و اجرای مداوم
راهنمای قابلیت‌های API
مدیریت خطا
امنیت
عیب‌یابی
مشارکت

ویژگی‌ها

کلاینت PHP با ساختار شی‌گرا و کلاس پایهٔ rubi\Rubika.
نقطهٔ شروع ربات با rubi\Runtime\Application.
تعریف Handler و فرمان با Attributeهایی مانند #[Handler] و #[Command].
دریافت و پردازش رویدادها و به‌روزرسانی‌ها.
ورود با شماره تلفن و کد تأیید و نگهداری اطلاعات نشست.
مدیریت پروفایل دستگاه و فرایند ثبت دستگاه.
ارسال متن، پاسخ به پیام، ویرایش، حذف، فوروارد، واکنش و سنجاق پیام.
ارسال عکس، ویدئو، فایل، صوت، ویس، GIF، استیکر، موقعیت مکانی و مخاطب.
ابزارهای مدیریت گروه، کانال، اعضا، مدیران، لینک دعوت و درخواست عضویت.
ابزارهای حساب، پروفایل، نام کاربری، مخاطبین، نشست‌ها و تنظیمات حریم خصوصی.
ابزارهای استوری، نظرسنجی، استیکر و گفت‌وگوی صوتی.
ذخیره‌سازی فایل‌محور، قفل‌گذاری و امکانات ثبت لاگ و عیب‌یابی.
کدهای کتابخانه برای استفاده از امکانات استاندارد PHP طراحی شده‌اند؛ Composer برای بارگذاری خودکار کلاس‌ها قابل استفاده است و در composer.json وابستگی شخص ثالثی تعریف نشده است.

نیازمندی‌ها

PHP نسخهٔ 8.4 یا بالاتر و پایین‌تر از 8.7 طبق composer.json فعلی.
افزونه‌ها و قابلیت‌های PHP موردنیاز نصب شما، به‌ویژه cURL و OpenSSL برای بخش‌های شبکه و رمزنگاری.
دسترسی نوشتن به مسیر ذخیره‌سازی نشست و لاگ.
برای اجرای دائمی Worker یا اتصال سوکت، محیط میزبانی باید اجرای پردازش طولانی‌مدت را اجازه دهد. بعضی از هاست‌های اشتراکی پردازش‌های دائمی را متوقف می‌کنند؛ در آن شرایط از روش اجرای زمان‌بندی‌شدهٔ سازگار با هاست استفاده کنید.

نصب

روش اول: Composer در پروژه

git clone https://github.com/Amirmohammadpezeshkii/rubi.git
cd REPOSITORY
composer install

یا

composer require amirmohammadpezeshkii/rubi

OWNER/REPOSITORY را با آدرس واقعی مخزن جایگزین کنید. تا وقتی پروژه در Packagist منتشر نشده، دستور composer require برای نصب مستقیم با نام پکیج لزوماً کار نمی‌کند.

روش دوم: بارگذاری دستی

پوشهٔ src را همراه فایل‌های پروژه روی سرور قرار دهید. اگر vendor/autoload.php وجود ندارد، بارگذار داخلی را استفاده کنید:

require_once __DIR__ . '/src/autoload.php';

شروع سریع

فایل bot.php در مخزن نمونه‌ای اجرایی از ساختار فعلی پروژه است. حداقل الگوی ربات به این شکل است:

<?php

declare(strict_types=1);

require_once __DIR__ . '/src/autoload.php';

use rubi\Rubika;
use rubi\Update;
use rubi\Runtime\Application;
use rubi\Runtime\Attributes\Command;
use rubi\Runtime\Attributes\Handler;

final class Bot extends Rubika
{
    #[Handler(name: 'start', priority: 100)]
    #[Command('start')]
    public function start(Update $update): void
    {
        $update->reply("سلام! ربات آماده است. برای راهنما /help را بفرست.");
    }

    #[Handler(name: 'help', priority: 100)]
    #[Command('help')]
    public function help(Update $update): void
    {
        $update->reply("دستورات موجود:\n/start\n/help");
    }
}

Application::run(Bot::class);

نمونهٔ بالا نشان‌دهندهٔ الگوی Runtime موجود در مخزن است. فرایند ورود اولیه باید مطابق جریان ورود پروژه تکمیل شود؛ صرف اجرای Application::run() به معنی احراز هویت موفق در یک نصب تازه نیست.

دریافت و پاسخ به پیام‌ها

کلاس Update نمایندهٔ به‌روزرسانی پردازش‌شده در Runtime است. در نمونهٔ فعلی، متد reply() برای پاسخ به رویداد و replyAt() برای زمان‌بندی پیام استفاده شده‌اند.

#[Handler(name: 'welcome', priority: 100)]
public function welcome(Update $update): void
{
    $update->reply('پیامت دریافت شد.');
}

برای پاسخ فقط به متن مشخص، شرط را روی دادهٔ پیام در دسترس رویداد قرار دهید. ساختار دقیق فیلدها را از src/Rubika/Models/Update.php و دادهٔ واقعی Update بررسی کنید؛ همهٔ انواع Update الزاماً فیلدهای یکسان ندارند.

فرمان‌ها و Handlerها

#[Command('start')] برای معرفی یک فرمان.
#[Handler(name: '...', priority: 100)] برای ثبت Handler و اولویت اجرای آن.
چند متد مجزا برای فرمان‌های مختلف تعریف کنید تا منطق ربات قابل نگهداری بماند.
از نام فرمان‌ها و اولویت‌هایی استفاده کنید که با Handlerهای دیگر پروژه تداخل نداشته باشند.

ارسال و مدیریت پیام

متدهای پیام در src/Rubika/Modules/MessagesModule.php قرار دارند. امضای هر متد را پیش از استفاده در همان فایل بررسی کنید.

قابلیت	متدهای موجود
فهرست گفتگوها و پیام‌ها	`getChats`, `getMessages`, `getMessagesByID`, `getListMessagesByID`, `getMessagesInterval`
دریافت تغییرات	`getChatsUpdates`, `getMessagesUpdates`, `getChatAds`
ارسال متن	`sendText`, `sendMessage`
ویرایش و حذف	`editMessage`, `deleteMessages`, `deleteChatHistory`, `deleteUserChat`
فوروارد	`forwardMessages`
واکنش	`actionOnMessageReaction`, `getMessageReactions`
سنجاق	`pinChatMessage`, `unpinChatMessage`
وضعیت خواندن	`seenChats`
جست‌وجو	`searchChatMessages`, `searchGlobalMessages`
وضعیت تایپ و گفتگو	`sendChatActivity`, `setActionChat`
لینک پیام	`clickMessageUrl`, `getMessageShareUrl`

برای نمونه، شکل کلی ارسال متن در API این است:

$result = $bot->sendText($objectGuid, 'سلام از طرف ربات');

$objectGuid شناسهٔ گفتگو در قالب مورد انتظار API است. در این پروژه، برخی متدهای عمومی از طریق __call() به ماژول‌های مربوطه هدایت می‌شوند؛ در صورت ابهام، امضای متد در فایل ماژول مرجع اصلی است.

فایل و رسانه

متدهای موجود برای ارسال رسانه:

sendFile() برای فایل عمومی.
sendPhoto() برای تصویر.
sendVideo() برای ویدئو.
sendVoice() و sendAudio() برای صوت.
sendGif() برای GIF.
sendSticker() برای استیکر.
sendLocation() برای مختصات مکانی.
sendContact() برای ارسال مخاطب.
uploadFile(), uploadFileChunk(), uploadRaw() و downloadFile() برای مسیرهای انتقال فایل در کلاینت.

در متدهای ارسال فایل، مسیر فایل باید برای کاربر سیستم‌عاملِ اجراکننده قابل خواندن باشد. محدودیت حجم، MIME و پاسخ سرویس را کنترل کنید و فایل‌های موقت را پس از پایان کار پاک کنید.

گروه‌ها و کانال‌ها

گروه‌ها

متدهای گروه در GroupsModule.php شامل این حوزه‌ها هستند:

اطلاعات گروه: getGroupInfo, getGroupOnlineCount, getGroupStats.
اعضا: getGroupAllMembers, searchMemberGroup, getGroupAdminMembers, getBannedGroupMembers, getGroupMentionList.
ساخت و مدیریت: addGroup, addGroupMembers, editGroupInfo, removeGroup, deleteGroup.
مدیران و محدودیت‌ها: setGroupAdmin, setGroupUnAdmin, setGroupAdminTitle, banGroupMember, unBanGroupMember.
لینک و عضویت: setGroupLink, getGroupLink, recreateGroupLink, removeGroupLink, groupPreviewByJoinLink, joinGroupByLink, leaveGroup.
درخواست‌ها و دسترسی: getGroupJoinRequests, actionOnGroupJoinRequest, getGroupDefaultAccess, setGroupDefaultAccess.
تصویر و پیام: uploadGroupPhoto, deleteGroupPhoto, getGroupMessageReadParticipants, setAllReaction.

کانال‌ها

متدهای ChannelsModule.php امکانات زیر را پوشش می‌دهند:

اطلاعات و آمار: getChannelInfo, getChannelStats.
ایجاد و اعضا: addChannel, addChannelMembers, getChannelAllMembers, getChannelAdminMembers, getBannedChannelMembers.
مدیریت مدیران و مسدودسازی: setChannelAdmin, setChannelUnAdmin, setChannelAdminTitle, banChannelMember, unbanChannelMember.
نام کاربری و لینک: checkChannelUsername, updateChannelUsername, setChannelLink, getChannelLink, recreateChannelLink, removeChannelLink.
عضویت و درخواست‌ها: joinChannelAction, channelPreviewByJoinLink, joinChannelByLink, leaveChannel, getChannelJoinRequests, actionOnChannelJoinRequest.
تنظیم دسترسی و ویرایش: getChannelDefaultAccess, setChannelDefaultAccess, editChannelInfo, uploadChannelPhoto, deleteChannelPhoto, removeChannel, deleteChannel.

عملیات مدیریتی تنها در صورتی موفق می‌شوند که حساب، دسترسی لازم را در گروه یا کانال داشته باشد.

حساب، مخاطبین و حریم خصوصی

متدهای InfoModule.php قابلیت‌های زیر را ارائه می‌کنند:

اطلاعات کاربر و سرویس: getUserInfo, getInfoByUsername, getServiceInfo, getAbsObjects, getDCs.
پروفایل: updateProfile, uploadAvatar, deleteProfilePhoto, getAvatars, updateUsername, checkUserUsername.
مخاطبین: getContacts, getContactsUpdates, addAddressBook, getContactsLastOnline, deleteContact.
مسدودسازی: getBlockedUsers, blockUser, unblockUser.
حریم خصوصی و رمز دومرحله‌ای: getPrivacySetting, setPrivacySetting, getTwoPasscodeStatus, setupTwoStepVerification, setupTwoStepPasscode, checkTwoStepPasscode, turnOffTwoStepPasscode, changeTwoStepPasscode, setTwoStepPasscodeEmail, confirmTwoStepPasscodeEmail, resendTwoStepPasscodeEmailCode.
نشست‌های حساب: getMySessions, terminateSession, terminateAllOtherSessions, getUnconfirmedSessions, confirmUnconfirmedSession, denyUnconfirmedSession.
عملیات حساب: logout, requestDeleteAccount, deleteAccount.

عملیات حساس حساب، مانند تغییر رمز دومرحله‌ای، پایان‌دادن به نشست‌ها یا حذف حساب، باید آگاهانه و پس از بررسی پاسخ سرویس اجرا شوند.

استوری، نظرسنجی و استیکر

استوری

در StoriesModule.php:

getStories() و getArchivedStories() برای دریافت استوری‌ها و آرشیو.
sendStory() و deleteStory() برای انتشار و حذف.
getStoryViews() و seenStory() برای بازدیدها.
pinStory() و unpinStory() برای سنجاق‌کردن یا برداشتن سنجاق.
sendStoryReaction() و sendStoryReply() برای واکنش و پاسخ.
getStoryReplies() برای دریافت پاسخ‌ها.

نظرسنجی

در ExtrasModule.php:

createPoll() برای ساخت نظرسنجی.
votePoll() برای ثبت رأی.
getPollStatus() برای وضعیت نظرسنجی.
getPollOptionVoters() برای دریافت رأی‌دهندگان یک گزینه.

استیکر

getMyStickerSets(), getStickerSetByID().
getStickersByEmoji(), getStickersBySetIDs(), getStickersBySet().
searchStickers(), getTrendStickerSets().
actionOnStickerSet() برای عملیات روی مجموعهٔ استیکر.

گفت‌وگوی صوتی و تماس

در VoiceChatModule.php، متدهایی برای ساخت، پیوستن و ترک گفت‌وگوی صوتی، دریافت اعضا، دعوت کاربران، بی‌صداکردن شرکت‌کننده، تغییر عنوان، بالا بردن دست، مدیریت نقش شرکت‌کننده و پیوند گفت‌وگو وجود دارد.

متدهای تماس شامل requestCall, acceptCall, getCalls, receivedCall, callStarted, getSignalingData, sendSignalingData, sendSignalData, rateCall و discardCall هستند. عملکرد این بخش به پشتیبانی سرویس، مجوزهای حساب و سازگاری نسخهٔ سرور وابسته است و باید جداگانه آزمایش شود.

ورود و مدیریت نشست

کلاس اصلی امکاناتی برای جریان ورود از جمله sendCode(), signIn(), login() و registerDevice() دارد. مسیر ورود ممکن است بر اساس وضعیت حساب و پاسخ سرویس، به مراحل اضافی نیاز داشته باشد.

اطلاعات ورود و کد تأیید را در فایل عمومی، مخزن Git یا لاگ قرار ندهید.
پوشهٔ نشست باید قابل نوشتن باشد و در معرض دانلود عمومی وب قرار نگیرد.
پس از ورود، نتیجهٔ ثبت دستگاه و پاسخ احراز هویت را بررسی کنید؛ موفقیت signIn به‌تنهایی موفقیت registerDevice را ثابت نمی‌کند.
اگر نشست پس از مدتی نامعتبر شد، لاگ زمان‌دارِ نوع خطا را بررسی کنید؛ خطای شبکه، خطای RPC و رد صریح احراز هویت را یکی فرض نکنید.
مسیرها و گزینه‌های سازنده را مطابق امضای نسخهٔ نصب‌شده تنظیم کنید؛ مثال‌های قدیمی ممکن است با نسخهٔ فعلی سازگار نباشند.

ذخیره‌سازی، لاگ و اجرای مداوم

پروژه شامل اجزای ذخیره‌سازی و Runtime برای کار با نشست و پردازش به‌روزرسانی است. محل ذخیره‌سازی را خارج از مسیر عمومی وب قرار دهید، دسترسی فایل‌ها را محدود کنید و از نسخهٔ پشتیبان امن استفاده کنید.

برای اجرای مداوم، محدودیت‌های هاست را در نظر بگیرید: محدودیت زمان اجرا، توقف پردازش‌های طولانی، محدودیت اتصال خروجی یا قطع سوکت ممکن است باعث توقف ربات شود. در محیطی که اجرای دائمی پشتیبانی نمی‌شود، از cron یا سازوکار supervisor مجاز همان میزبان استفاده کنید؛ این راهکار جایگزین پشتیبانی واقعی از WebSocket دائمی نیست.

راهنمای قابلیت‌های API

این جدول نمای کلی متدهای عمومیِ قابل مشاهده در سورس است. برای پارامترهای اجباری، مقادیر مجاز، نوع خروجی و مثال دقیق، امضای متد را در فایل مربوطه بخوانید.

دسته	متدهای کلیدی	فایل مرجع
پیام‌ها	`sendText`, `sendMessage`, `editMessage`, `deleteMessages`, `forwardMessages`, `getMessages`, `getChats`	`Modules/MessagesModule.php`
به‌روزرسانی‌ها	`getChatsUpdates`, `getMessagesUpdates`, `getContactsUpdates`	`Modules/MessagesModule.php`, `Modules/InfoModule.php`
رسانه	`sendFile`, `sendPhoto`, `sendVideo`, `sendVoice`, `sendAudio`, `sendGif`, `sendSticker`, `sendLocation`, `sendContact`	`Modules/MessagesModule.php`
گروه‌ها	`getGroupInfo`, `addGroup`, `setGroupAdmin`, `banGroupMember`, `joinGroupByLink`	`Modules/GroupsModule.php`
کانال‌ها	`getChannelInfo`, `addChannel`, `setChannelAdmin`, `joinChannelByLink`	`Modules/ChannelsModule.php`
پروفایل و حساب	`getUserInfo`, `updateProfile`, `updateUsername`, `logout`	`Modules/InfoModule.php`
مخاطبین	`getContacts`, `addAddressBook`, `deleteContact`, `blockUser`, `unblockUser`	`Modules/InfoModule.php`
نشست‌ها	`getMySessions`, `terminateSession`, `terminateAllOtherSessions`	`Modules/InfoModule.php`
استوری	`getStories`, `sendStory`, `deleteStory`, `sendStoryReply`	`Modules/StoriesModule.php`
نظرسنجی و استیکر	`createPoll`, `votePoll`, `searchStickers`, `getTrendStickerSets`	`Modules/ExtrasModule.php`
گفت‌وگوی صوتی	`createVoiceChat`, `joinVoiceChat`, `leaveVoiceChat`, `getVoiceChatMembers`	`Modules/VoiceChatModule.php`
تماس	`requestCall`, `acceptCall`, `discardCall`, `sendSignalingData`	`Modules/VoiceChatModule.php`
عملیات پیشرفته	`getMessageShareUrl`, `getMessagesById`, `setSetting`, `getPollStatus`	`Modules/AdvancedRpcModule.php`

مدیریت خطا

کلاس‌های خطا در src/Exception/ قرار دارند:

RubikaException: خطای پایهٔ کتابخانه.
RubikaAuthException: خطاهای مرتبط با احراز هویت.
RubikaNetworkException: خطاهای شبکه و انتقال.
RubikaFileException: خطاهای مرتبط با فایل.

در کد برنامه، خطاها را مدیریت کنید و جزئیات محرمانهٔ پاسخ یا نشست را به کاربر نهایی نمایش ندهید. پاسخ API ممکن است اطلاعات خطا را در ساختار داده برگرداند؛ همیشه نتیجه را مطابق قرارداد همان متد بررسی کنید.

امنیت

فایل‌های نشست، کدهای تأیید، توکن‌ها و کلیدهای رمزنگاری را commit نکنید.
فایل‌های ذخیره‌سازی را از document root وب خارج کنید.
فایل .gitignore را برای نشست‌ها، لاگ‌ها، تنظیمات محلی و فایل‌های موقت تنظیم کنید.
دسترسی به پنل مدیریتی را محدود و احراز هویت آن را فعال نگه دارید.
پیش از اجرای عملیات مدیریتی یا حذف حساب، شناسهٔ مقصد و نتیجهٔ API را بررسی کنید.
برای گزارش خطا، شماره تلفن، توکن، کد ورود و محتوای محرمانه را حذف یا ماسک کنید.

نمونهٔ .gitignore پیشنهادی:

/vendor/
/storage/
/sessions/
/logs/
.env
*.log
*.session

مسیرهای واقعی را با تنظیمات پروژهٔ خود هماهنگ کنید و فایل‌های لازم برای اجرای کتابخانه را به‌اشتباه نادیده نگیرید.

عیب‌یابی

ربات وارد حساب نمی‌شود

بررسی کنید PHP و افزونه‌های لازم نصب باشند.
مرحلهٔ ارسال کد، پاسخ ورود و ثبت دستگاه را جداگانه بررسی کنید.
از ثبت کد تأیید یا داده‌های احراز هویت در لاگ خودداری کنید.

نشست بعد از مدتی از دست می‌رود

زمان و نوع پاسخ سرور را ثبت کنید.
مشخص کنید آیا سرور نشست را صریحاً رد کرده یا ارتباط شبکه قطع شده است.
مسیر ذخیره‌سازی، مجوزها و باقی‌ماندن اطلاعات دستگاه و نشست را بررسی کنید.
نتیجهٔ registerDevice را جدا از signIn ثبت و تحلیل کنید.

سوکت یا Worker متوقف می‌شود

محدودیت زمان اجرای هاست و پردازش‌های طولانی را بررسی کنید.
لاگ اتصال، قطع ارتباط و راه‌اندازی مجدد را بررسی کنید.
بررسی کنید که سرویس میزبان اتصال خروجی و پردازش مداوم را اجازه می‌دهد.

متدی پاسخ مورد انتظار نمی‌دهد

پارامترها و نوع داده‌ها را با امضای متد در نسخهٔ نصب‌شده تطبیق دهید.
پاسخ خام را فقط پس از حذف اطلاعات محرمانه بررسی کنید.
ممکن است قرارداد سمت سرویس تغییر کرده باشد؛ رفتار را در حساب آزمایشی بازتولید کنید.

مشارکت

برای پیشنهاد قابلیت یا گزارش خطا، یک Issue با مراحل بازتولید، نسخهٔ PHP، نسخهٔ پروژه و پیام خطای پاک‌سازی‌شده ثبت کنید. برای ارسال Pull Request، تغییرات را کوچک نگه دارید و تست‌های مرتبط را اجرا کنید.

مجوز

پیش از انتشار عمومی، فایل مجوز پروژه را اضافه کنید و شرایط استفاده و بازتوزیع را روشن سازید. تا زمانی که مجوزی در مخزن قرار نگرفته، مجوز خاصی را فرض نکنید.

Rubika PHP — مستندات را مطابق نسخهٔ واقعی پروژه به‌روز نگه دارید.

amirmohammadpezeshkii / rubi

Package info

Security

Statistics