📋 راهنمای پیکربندی

🔧 مدیریت ربات - گزینه‌های پیکربندی

گزینه	نوع	توضیحات
`bots`	`array`	می‌توانید چند ربات را به‌طور همزمان با استفاده از کلاس مدیریت‌کننده پیکربندی کنید. هر رباتی که دارید باید اینجا تعریف شود.
`default`	`string`	در این قسمت مشخص کنید کدام ربات را به عنوان ربات پیش‌فرض برای استفاده عادی در نظر دارید.
`async_requests`	`bool` (اختیاری)	پیش‌فرض: `false` اگر مقدار `true` تنظیم شود، تمام درخواست‌ها به صورت غیرمسدودکننده (غیرهمزمان) ارسال می‌شوند.
`http_client_handler`	`string` (اختیاری)	پیش‌فرض: `EFive\Bale\HttpClients\GuzzleHttpClient` مسیر مربوط به کلاس مدیریت‌کننده HTTP سفارشی که باید نمونه‌ای از `EFive\Bale\HttpClients\HttpClientInterface` باشد.
`base_bot_url`	`string` (اختیاری)	Default: `https://tapi.bale.ai/bot` اگر می‌خواهید از یک آدرس URL سفارشی برای ربات استفاده کنید. می‌تواند یک نقطه‌پایانی محلی یا پروکسی برای API ربات باشد.
`resolve_command_dependencies`	`bool` (اختیاری)	پیش‌فرض (لاراول): `true` با استفاده از سیستم تزریق وابستگی، می‌توان به راحتی وابستگی‌ها را در سازنده دستورات مشخص کرد و آنها را به‌طور خودکار حل کرد. در لاراول، از IoC Container آن به طور پیش‌فرض استفاده می‌شود.
`commands`	`array` (اختیاری)	اگر می‌خواهید از سیستم مدیریت دستورات داخلی SDK استفاده کنید، می‌توانید همه دستورات عمومی را اینجا ثبت کنید. دستورات عمومی برای همه ربات‌ها فعال هستند. کلاس دستور باید از `EFive\Bale\Commands\Command` ارث‌بری کند. پیش‌فرض: SDK یک دستور `help` ثبت می‌کند که وقتی کاربر `/help` ارسال کند، لیست دستورات موجود و توضیحات آنها را نمایش می‌دهد یا در صورت عدم وجود دستوری، پاسخ مناسب ارسال می‌کند.
`command_groups`	`array` (اختیاری)	می‌توانید مجموعه‌ای از دستورات را در گروه‌هایی سازماندهی کنید تا بعداً در تمام ربات‌ها دوباره استفاده شوند. می‌توانید 4 نوع گروه ایجاد کنید: 1. گروه‌بندی با مسیر کامل کلاس دستورات. 2. گروه‌بندی با دستورات مشترک: با استفاده از نام کلیدی دستور مشترک، سیستم به‌طور خودکار دستور مناسب را حل می‌کند. 3. گروه‌بندی با سایر گروه‌های دستورات: می‌توانید گروهی ایجاد کنید که شامل سایر گروه‌های دستورات باشد. 4. ترکیب گروه‌ها: می‌توانید گروهی با ترکیبی از 1، 2 و 3 ایجاد کنید.
`shared_commands`	`array` (اختیاری)	دستورات مشترک به شما امکان می‌دهند دستورات را در یک یا چند ربات به اشتراک بگذارید. این دستورات به صورت پیش‌فرض فعال نیستند و باید در یک گروه یا تنظیمات ربات ثبت شوند.

بیایید این گزینه‌های پیکربندی را به صورت عمیق‌تر بررسی کنیم همراه با چند مثال.

🤖 ثبت چند ربات

برای استفاده همزمان از چند ربات، می‌توانید گزینه bots را با آرایه‌ای شامل نام و تنظیمات هر ربات پیکربندی کنید.

گزینه	نوع	توضیحات
`token`	string	توکن ربات بله شما.
`certificate_path`	string (اختیاری)	مسیر گواهی SSL شما.
`webhook_url`	string (اختیاری)	URL وبهوک ربات شما. استفاده از وبهوک توصیه می‌شود.
`commands`	array (اختیاری)	دستورات ثبت‌شده برای این ربات. پشتیبانی‌شده: "نام گروه دستورات"، "نام دستور مشترک"، "مسیر کامل کلاس". پیش‌فرض: دستورات عمومی ثبت‌شده.

به عنوان مثال، برای پیکربندی دو ربات با نام‌های "mybot" و "anotherbot"، از سینتکس زیر استفاده می‌کنید:

[
    'bots' => [
        'mybot' => [
            'token'       => '123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11',
            'webhook_url' => 'https://domain.com/bale/webhook',
            'commands'    => [
                App\Bale\Commands\StartCommand::class,
            ],
        ],

        'anotherbot' => [
            'token' => '654321:DEF-GHI5678jkL-mno34pqr9stu456vwx',
            'commands' => ['admin', 'help', 'info'],
        ],

        'default' => 'mybot'
    ]
];

👉 در این مثال، mybot با یک توکن ربات و یک دستور محلی به نام "start" پیکربندی شده است، در حالی که anotherbot با توکن ربات متفاوت و سه دستور مختلف ("admin"، "help" و "info") از آرایه دستورات مشترک تنظیم شده است. همچنین، mybot به عنوان ربات default برای استفاده عادی تنظیم شده است.

برای ارسال درخواست با یک ربات خاص، می‌توانید از متد bot() با نام ربات به عنوان آرگومان استفاده کنید:

Standalone
Laravel

$response = $bale->bot('mybot')->getMe();

$response = Bale::bot('mybot')->getMe();

اگر از متد bot() استفاده نشود، درخواست‌های API برای ربات پیش‌فرض انتخاب‌شده ارسال خواهند شد. به عنوان مثال، درخواست زیر برای mybot ارسال می‌شود:

Standalone
Laravel

$response = $bale->getMe();

$response = Bale::getMe();

می‌توانید از فاساد EFive\Bale\Laravel\Facades\Bale برای ارسال درخواست‌های API استفاده کنید.

مثال:

use EFive\Bale\Laravel\Facades\Bale;

$response = Bale::bot('mybot')->getMe();

🔁 درخواست‌های غیرهمزمان

به طور پیش‌فرض، تمامی درخواست‌های ارسال‌شده با استفاده از SDK به صورت همزمان (blocking) هستند، به این معنی که اجرای اسکریپت قبل از دریافت پاسخ متوقف می‌شود. شما می‌توانید درخواست‌ها را به صورت غیرهمزمان (async) با تنظیم گزینه پیکربندی async_requests به true ارسال کنید.

[
    'async_requests' => true,
    // ...
];

👉 In this example, we're enabling async requests that is applicable for all the bots.

🚚 مدیریت‌کننده HTTP Client

به طور پیش‌فرض، SDK از GuzzleHttpClient که یک پیاده‌سازی از GuzzlePHP است، استفاده می‌کند. با این حال، شما می‌توانید با تنظیم گزینه پیکربندی http_client_handler به مسیر کلاس مدیریت‌کننده، از یک مدیریت‌کننده HTTP سفارشی استفاده کنید. کلاس مدیریت‌کننده باید رابط \EFive\Bale\HttpClients\HttpClientInterface را پیاده‌سازی کند.

[
    'http_client_handler' => App\CustomHttpClient::class,
    // ...
];

👉 در این مثال، ما از یک مدیریت‌کننده HTTP سفارشی به نام CustomHttpClient استفاده می‌کنیم.

🌐 آدرس پایه ربات

به طور پیش‌فرض، SDK از نقطه پایانی رسمی API بله به عنوان URL پایه برای همه درخواست‌های API استفاده می‌کند. با این حال، شما می‌توانید با تنظیم گزینه پیکربندی base_bot_url به URL نقطه پایانی سفارشی خود، از یک آدرس پایه سفارشی استفاده کنید که به‌ویژه در صورتی که نقطه پایانی رسمی در کشور شما مسدود باشد، مفید است.

[
    'base_bot_url' => 'http://mycustomurl.com/api',
    // ...
];

🔗 حل وابستگی‌های دستورها

با کمک ظرف تزریق وابستگی، می‌توانیم به راحتی وابستگی‌ها را در سازنده دستور خود مشخص کرده و آن‌ها را به طور خودکار حل کنیم. در لاراول، به طور پیش‌فرض از ظرف IoC خود استفاده می‌کند.

Standalone
Laravel

به طور پیش‌فرض این گزینه برای توسعه‌دهندگان مستقل غیرفعال است، اما می‌توان آن را با تنظیم گزینه در پیکربندی و ارائه یک پیاده‌سازی سازگار با PSR-11 برای BotsManager فعال کرد.

به عنوان مثال، اگر بخواهید از ظرف لاراول استفاده کنید، می‌توانید بسته illuminate/container را به عنوان وابستگی در پروژه خود اضافه کرده و سپس آن را به عنوان ظرف برای BotsManager تنظیم کنید:

$config = [
    'resolve_command_dependencies' => true,
    // ...
];

$bale = new BotsManager($config);
$bale->setContainer(new \Illuminate\Container\Container());

در لاراول، به طور پیش‌فرض SDK وابستگی‌ها را برای دستورات بات شما با استفاده از ظرف IoC لاراول به طور خودکار حل می‌کند. برای غیرفعال کردن این رفتار، می‌توانید گزینه resolve_command_dependencies را روی false تنظیم کنید.

config/bale.php
[
    'resolve_command_dependencies' => false,
    // ...
];

📜 ثبت دستورات سراسری

دستورات سراسری دستورات هستند که برای تمامی ربات‌ها در سیستم ثبت شده و همیشه فعال هستند. شما می‌توانید دستورات سراسری را با استفاده از گزینه پیکربندی commands ثبت کنید. در اینجا یک مثال آورده شده است:

[
    'commands' => [
        App\Bale\Commands\HelpCommand::class,
        App\Bale\Commands\StartCommand::class,
        // ...
    ],
    // ...
]

👉 در این مثال، دو دستور را ثبت می‌کنیم: App\Bale\Commands\HelpCommand و App\Bale\Commands\StartCommand. این دستورات برای تمام ربات‌ها در سیستم فعال خواهند بود.

اطلاع

برای درک جامع‌تر از دستورات، لطفاً به راهنمای سیستم دستورات مراجعه کنید که اطلاعات دقیقی در این زمینه ارائه می‌دهد.

👨‍💻 گروه‌بندی دستورات [پیشرفته]

شما می‌توانید مجموعه‌ای از دستورات را در گروه‌هایی سازماندهی کنید که بعداً در تمام ربات‌های شما قابل استفاده مجدد باشند. این ویژگی به توسعه‌دهندگان ربات کمک می‌کند تا دستورات مشترک ربات‌ها را در چندین ربات مدیریت کرده و نگهداری آن‌ها را به‌صورت کارآمدتری انجام دهند.

شما می‌توانید ۴ نوع گروه ایجاد کنید:

📚 1. استفاده از مسیر کامل کلاس‌های دستور

در این نوع گروه، می‌توانید آرایه‌ای از نام‌های کلاس دستورات را برای ایجاد یک گروه ارائه دهید. در اینجا یک مثال آمده است:

[
    'command_groups' => [
        'my_commands' => [
            App\Bale\Commands\HelpCommand::class,
            App\Bale\Commands\StartCommand::class,
            // ...
        ],
        // ...
    ],
    // ...
]

👉 در این مثال، ما یک گروه به نام my_commands ایجاد می‌کنیم که شامل HelpCommand و StartCommand است. هر زمان که به این دو دستور نیاز داشته باشیم، فقط کافی است که کلید my_commands را در گزینه commands پیکربندی ربات وارد کنیم.

🤝 2. استفاده از دستورات مشترک

در این نوع گروه، می‌توانید آرایه‌ای از نام‌های دستورات مشترک را برای ایجاد یک گروه ارائه دهید. در اینجا یک مثال آمده است:

[
    'shared_commands' => [
        'greeting' => App\Bale\Commands\GreetingCommand::class,
        'farewell' => App\Bale\Commands\FarewellCommand::class,
        // ...
    ],
    'command_groups' => [
        'greeting_and_farewell' => [
            'greeting',
            'farewell',
            // ...
        ],
        // ...
    ],
    // ...
]

👉 در این مثال، ما یک گروه به نام greeting_and_farewell ایجاد می‌کنیم که شامل دو دستور مشترک است: greeting و farewell. دستورات مشترک خود در آرایه shared_commands تعریف شده‌اند.

🖇️ 3. استفاده از سایر گروه‌های دستورات

در این نوع گروه، می‌توانید آرایه‌ای از سایر گروه‌های دستوری را برای ایجاد یک گروه ارائه دهید. در اینجا یک مثال آمده است:

[
    'command_groups' => [
        'my_commands' => [
            'greeting_and_farewell',
            App\Bale\Commands\StartCommand::class,
            // ...
        ],
        'greeting_and_farewell' => [
            'greeting',
            'farewell',
            // ...
        ],
        // ...
    ],
    // ...
]

👉 در این مثال، ما یک گروه به نام my_commands ایجاد می‌کنیم که شامل گروه دیگری به نام greeting_and_farewell به همراه دستور StartCommand است.

💬 4. ترکیب گروه‌های دستوری

در این نوع گروه، می‌توانید یک گروه با ترکیب از سه نوع بالا ایجاد کنید. شما می‌توانید دستورات مشترک، گروه‌ها و کلاس‌های دستوری را همزمان در یک گروه ثبت کنید. در اینجا یک مثال آمده است:

[
    'shared_commands' => [
        'greeting' => App\Bale\Commands\GreetingCommand::class,
        // ...
    ],
    'command_groups' => [
        'my_commands' => [
            'greeting_and_farewell',
            'other_commands',
            App\Bale\Commands\StopCommand::class,
            // ...
        ],
        'greeting_and_farewell' => [
            'greeting',
            'farewell',
            App\Bale\Commands\StartCommand::class,
            // ...
        ],
        'other_commands' => [
            App\Bale\Commands\InfoCommand::class,
            // ...
        ]
        // ...
    ]
]

👉 در این مثال، ما یک دستور مشترک به نام greeting تعریف کرده‌ایم. سپس یک گروه به نام greeting_and_farewell ایجاد کرده‌ایم که شامل دستور greeting، دستور farewell و کلاس StartCommand است.

در مرحله بعد، یک گروه دیگر به نام other_commands ایجاد کرده‌ایم که شامل کلاس InfoCommand است.

در نهایت، یک گروه به نام my_commands ایجاد کرده‌ایم که شامل گروه greeting_and_farewell، گروه other_commands و کلاس StopCommand است. به این ترتیب، می‌توانیم این گروه‌ها را در چندین ربات دوباره استفاده کنیم و مدیریت دستورات را آسان‌تر کنیم.

اطلاع

اگرچه ممکن است این ویژگی پیچیده به نظر برسد، اما به‌طور عمدی طراحی شده است تا جریان کاری شما را ساده‌تر کند و مدیریت ربات‌های متعدد را با استفاده از همان کدپایه امکان‌پذیر سازد.

🤝 دستورات مشترک

دستورات مشترک به شما این امکان را می‌دهند که دستورات را بین یک یا چند ربات در سراسر پروژه به اشتراک بگذارید.

این ویژگی کمک می‌کند که از ثبت دوباره مجموعه دستورات برای هر ربات جلوگیری کنید و نگهداری آن‌ها را آسان‌تر سازید.

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

این را به‌عنوان یک ذخیره‌سازی مرکزی در نظر بگیرید که به شما این امکان را می‌دهد که دستورات را ثبت، دوباره استفاده و در سراسر تمام ربات‌ها نگهداری کنید.

شما می‌توانید دستورات مشترک بین چندین ربات را با استفاده از گزینه shared_commands در فایل پیکربندی ثبت کنید.

[
    'shared_commands' => [
        'admin' => App\Bale\Commands\AdminCommand::class,
        'info' => App\Bale\Commands\InfoCommand::class,
    ],
    // ...
];

نمونه‌هایی از نحوه استفاده از دستورات مشترک در بخش‌های گروه‌بندی دستورات با استفاده از دستورات مشترک و ثبت چندین ربات برای درک بهتر ارائه شده است.

تمام! حالا شما آماده‌اید تا پیکربندی Bale Bot SDK خود را انجام داده و شروع به ساخت ربات Bale خود کنید. کدنویسی خوش بگذره! 🎉

🔧 مدیریت ربات - گزینه‌های پیکربندی​

🤖 ثبت چند ربات​

🔁 درخواست‌های غیرهمزمان​

🚚 مدیریت‌کننده HTTP Client​

🌐 آدرس پایه ربات​

🔗 حل وابستگی‌های دستورها​

📜 ثبت دستورات سراسری​

👨‍💻 گروه‌بندی دستورات [پیشرفته]​

📚 1. استفاده از مسیر کامل کلاس‌های دستور​

🤝 2. استفاده از دستورات مشترک​

🖇️ 3. استفاده از سایر گروه‌های دستورات​

💬 4. ترکیب گروه‌های دستوری​

🤝 دستورات مشترک​