PHPackages                             amirkateb/tgcore-client - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [HTTP & Networking](/categories/http)
4. /
5. amirkateb/tgcore-client

ActiveLibrary[HTTP & Networking](/categories/http)

amirkateb/tgcore-client
=======================

TGCore Client is a lightweight Laravel package that receives Telegram updates forwarded by a TGCore gateway, verifies HMAC signatures with replay protection, normalizes payloads into a clean DTO, and dispatches them to your project handlers or queue with idempotency.

1.0.2(4mo ago)0167MITPHPPHP ^8.1

Since Dec 19Pushed 4mo agoCompare

[ Source](https://github.com/amirkateb/tgcore-client)[ Packagist](https://packagist.org/packages/amirkateb/tgcore-client)[ RSS](/packages/amirkateb-tgcore-client/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (6)Dependencies (6)Versions (7)Used By (0)

Main Panel
==========

[](#main-panel)

برای دریافت توکن و پنل به ایدی @amir\_katebsaber در تلگرام پیام دهید

TGCore Client (amirkateb/tgcore-client)
=======================================

[](#tgcore-client-amirkatebtgcore-client)

این پکیج برای پروژه‌های Laravel طراحی شده تا **فقط از طریق TGCore (هسته مرکزی تلگرام)** با تلگرام کار کنند.

در این معماری:

- **TGCore** توکن بات را نگه می‌دارد، وبهوک تلگرام را دریافت می‌کند، همه‌چیز را لاگ/رصد می‌کند و آپدیت‌ها را به پروژه شما فوروارد می‌کند.
- **پروژه مصرف‌کننده (Consumer)** هیچ ارتباط مستقیمی با Telegram Bot API ندارد و فقط از طریق TGCore پیام/فایل ارسال می‌کند.
- **TGCore Client** داخل پروژه مصرف‌کننده نصب می‌شود تا:
    1. آپدیت‌های فوروارد‌شده از TGCore را دریافت کند و امضای HMAC را verify کند (با محافظت در برابر replay).
    2. payload را نرمال کند و به Handlerهای پروژه شما dispatch کند (مستقیم یا روی queue).
    3. یک Gateway Client بدهد تا **ارسال پیام/فایل فقط از طریق TGCore** انجام شود (JSON و Multipart واقعی).

---

سازگاری
-------

[](#سازگاری)

- PHP: `^8.1`
- Laravel: `10.x` و `11.x`

---

نصب
---

[](#نصب)

### روش 1: نصب از Packagist / VCS

[](#روش-1-نصب-از-packagist--vcs)

```
composer require amirkateb/tgcore-client
```

### روش 2: نصب به صورت لوکال (Path Repository)

[](#روش-2-نصب-به-صورت-لوکال-path-repository)

اگر پکیج را کنار پروژه نگه می‌دارید:

در `composer.json` پروژه مصرف‌کننده:

```
{
  "repositories": [
    {
      "type": "path",
      "url": "../tgcore-client"
    }
  ]
}
```

سپس:

```
composer require amirkateb/tgcore-client:dev-main
```

---

انتشار کانفیگ و اجرای مایگریشن
------------------------------

[](#انتشار-کانفیگ-و-اجرای-مایگریشن)

### Publish کانفیگ

[](#publish-کانفیگ)

```
php artisan vendor:publish --tag=tgcore-client-config
```

### اجرای مایگریشن‌ها

[](#اجرای-مایگریشن‌ها)

```
php artisan migrate
```

این جداول ساخته می‌شود:

- `tgcore_client_bots` (اختیاری، در صورت استفاده از resolver دیتابیس)
- `tgcore_client_update_receipts` (برای idempotency و ثبت وضعیت دریافت/هندل)

---

تنظیمات TGCore (در پنل مدیریت Core)
-----------------------------------

[](#تنظیمات-tgcore-در-پنل-مدیریت-core)

برای هر Bot در پنل TGCore این فیلدها باید تنظیم شود:

1. **consumer\_url**

- آدرس endpoint دریافت آپدیت در پروژه مصرف‌کننده
- پیش‌فرض پکیج:
    `/tgcore/ingest`
- مثال:
    - `https://consumer.example.com/tgcore/ingest`

2. **consumer\_secret**

- یک secret قوی که TGCore برای امضای درخواست‌های فوروارد به consumer استفاده می‌کند
- همین secret در پروژه مصرف‌کننده هم باید برای verify موجود باشد (با config یا database)

3. **Set Webhook**

- برای Bot باید webhook روی TGCore set شود (در خود پنل TGCore)

4. **Outbound (Consumer -> Core)**

- پروژه مصرف‌کننده برای ارسال پیام/فایل به TGCore از endpointهای Core استفاده می‌کند:
    - `/api/tgcore/consumer/bots/{botUuid}/send-message`
    - `/api/tgcore/consumer/bots/{botUuid}/send-photo`
    - `/api/tgcore/consumer/bots/{botUuid}/send-document`
    - `/api/tgcore/consumer/bots/{botUuid}/send-voice`
    - `/api/tgcore/consumer/bots/{botUuid}/send-audio`
    - `/api/tgcore/consumer/bots/{botUuid}/send-video`
    - `/api/tgcore/consumer/bots/{botUuid}/send-location`
    - `/api/tgcore/consumer/bots/{botUuid}/send-chat-action`
    - `/api/tgcore/consumer/bots/{botUuid}/edit-message-text`
    - `/api/tgcore/consumer/bots/{botUuid}/answer-callback-query`
    - `/api/tgcore/consumer/bots/{botUuid}/send-media-group`
    - `/api/tgcore/consumer/bots/{botUuid}/send-sticker`
    - `/api/tgcore/consumer/bots/{botUuid}/send-animation`
    - `/api/tgcore/consumer/bots/{botUuid}/send-invoice`

نکته: تمام این درخواست‌ها توسط TGCore با **consumer\_secret همان Bot** verify می‌شوند و سپس TGCore با توکن خودش به تلگرام ارسال می‌کند.

---

تنظیمات پروژه مصرف‌کننده (Consumer)
-----------------------------------

[](#تنظیمات-پروژه-مصرف‌کننده-consumer)

### 1) تنظیم مسیر ingest

[](#1-تنظیم-مسیر-ingest)

در `config/tgcore_client.php`:

- `route.path` پیش‌فرض `/tgcore/ingest` است.

اگر می‌خواهید تغییر دهید:

```
'route' => [
    'path' => '/my-ingest',
]
```

### 2) تنظیم middleware روت ingest

[](#2-تنظیم-middleware-روت-ingest)

پیش‌فرض:

- `api`
- `tgcore-client.verify`

اگر لازم دارید middleware دیگری اضافه کنید:

```
'route' => [
    'middleware' => ['api', 'tgcore-client.verify'],
]
```

### 3) Verify امضای TGCore (Core -> Consumer)

[](#3-verify-امضای-tgcore-core---consumer)

پکیج برای verify از این headerها استفاده می‌کند:

- `X-TGCore-Bot-UUID`
- `X-TGCore-Timestamp`
- `X-TGCore-Signature`

و با `tolerance_seconds` و `replay_ttl_seconds` از replay جلوگیری می‌کند:

```
'signature' => [
    'tolerance_seconds' => 300,
    'replay_ttl_seconds' => 600,
],
```

### 4) تعریف Secret برای هر Bot (Resolver)

[](#4-تعریف-secret-برای-هر-bot-resolver)

دو حالت دارید:

#### حالت A) Resolver از Config

[](#حالت-a-resolver-از-config)

در `.env`:

```
TGCORE_CLIENT_RESOLVER=config

```

در `config/tgcore_client.php`:

```
'bots' => [
    'BOT_UUID_1' => ['secret' => 'CONSUMER_SECRET_1'],
    'BOT_UUID_2' => ['secret' => 'CONSUMER_SECRET_2'],
],
```

#### حالت B) Resolver از Database

[](#حالت-b-resolver-از-database)

در `.env`:

```
TGCORE_CLIENT_RESOLVER=database

```

سپس در جدول `tgcore_client_bots` رکورد بسازید:

- `bot_uuid` = همان uuid بات در TGCore
- `secret` = consumer\_secret همان بات
- `is_active` = 1

---

صف (Queue) و نحوه پردازش آپدیت‌ها
---------------------------------

[](#صف-queue-و-نحوه-پردازش-آپدیت‌ها)

پکیج می‌تواند آپدیت‌ها را:

- مستقیم هندل کند (sync)
- یا به Job بفرستد (پیشنهادی برای production)

در `.env`:

```
TGCORE_CLIENT_QUEUE_ENABLED=true
TGCORE_CLIENT_QUEUE_NAME=default

```

اگر connection خاص می‌خواهید:

```
TGCORE_CLIENT_QUEUE_CONNECTION=redis

```

اجرای worker:

```
php artisan queue:work
```

---

تعریف Handlerها (Routing منطق ربات در Consumer)
-----------------------------------------------

[](#تعریف-handlerها-routing-منطق-ربات-در-consumer)

Handlerها داخل پروژه مصرف‌کننده هستند و فقط روی DTO کار می‌کنند.

### 1) نمونه Handler (Echo)

[](#1-نمونه-handler-echo)

فایل: `app/TGCore/Handlers/EchoHandler.php`

```