madarlan / aitu-messenger-php
PHP SDK для работы с Aitu Messenger и Aitu Passport API с поддержкой Laravel
Installs: 0
Dependents: 0
Suggesters: 0
Security: 0
Stars: 0
Watchers: 0
Forks: 0
pkg:composer/madarlan/aitu-messenger-php
Requires
- php: ^8.0
- firebase/php-jwt: ^6.0
- guzzlehttp/guzzle: ^7.0
- illuminate/support: ^8.0|^9.0|^10.0|^11.0
Requires (Dev)
- mockery/mockery: ^1.4
- orchestra/testbench: ^6.0|^7.0|^8.0|^9.0
- phpunit/phpunit: ^9.0|^10.0
This package is auto-updated.
Last update: 2025-10-24 05:11:33 UTC
README
🚀 Aitu Messenger PHP SDK
🇰🇿 Қазақ тіліндегі құжаттама | 🇷🇺 Русская версия
🎯 Aitu Messenger API-мен интеграциялауға арналған заманауи PHP SDK
⚡ Laravel-мен терең интеграциясы бар Aitu Passport (OAuth) және Aitu Apps (Push хабарландырулар) толық қолдауы
📖 Құжаттама • 🚀 Жылдам бастау • 💡 Мысалдар • 🤝 Қолдау
✨ Мүмкіндіктер
🛠️ Қосымша мүмкіндіктер
- 📊 Аналитика - Хабарландыру жеткізу статистикасы
- 🧪 Толық тестілеу - Unit, Feature және Integration тесттер
- 📚 Толық құжаттама - Мысалдар мен нұсқаулықтар
- 🔄 Автоматты қалпына келтіру - API сұраулары үшін Retry механизмдері
- 🌐 Көптілділік - Хабарландыруларды локализациялау қолдауы
📋 Талаптар
|
PHP 8.1+ |
Laravel 10.0+ |
Guzzle HTTP 7.0+ |
Composer |
📦 Орнату
🎯 Composer арқылы жылдам орнату
composer require madarlan/aitu-messenger-php-sdk
⚡ Laravel үшін автоматты баптау
Толық автоматты баптау үшін Artisan командасын пайдаланыңыз:
php artisan aitu:install
🔧 Орнату командасы не істейді?
- ✅ Конфигурация файлдарын жариялайды
- ✅ Webhook үшін маршруттар жасайды
- ✅ Дерекқор миграцияларын жариялайды
- ✅
.envфайлына орта айнымалыларын қосады - ✅ Келесі баптау қадамдарын көрсетеді
🎛️ Орнату опциялары
# Тек Aitu Passport орнату php artisan aitu:install --passport # Тек Aitu Apps орнату php artisan aitu:install --apps # Бар файлдарды қайта жазу php artisan aitu:install --force
🔧 Қолмен орнату
Қолмен орнату нұсқаулықтарын ашу
# 1. Конфигурацияны жариялау php artisan vendor:publish --tag="aitu-messenger-config" # 2. Маршруттарды жариялау php artisan vendor:publish --tag="aitu-messenger-routes" # 3. Миграцияларды жариялау php artisan vendor:publish --tag="aitu-messenger-migrations" # 4. Миграцияларды орындау php artisan migrate
⚙️ Конфигурация
🔑 Орта айнымалылары
Келесі айнымалыларды .env файлыңызға қосыңыз:
# 🔐 Aitu Passport OAuth AITU_PASSPORT_CLIENT_ID=your_passport_client_id AITU_PASSPORT_CLIENT_SECRET=your_passport_client_secret AITU_PASSPORT_REDIRECT_URI=https://yourapp.com/auth/aitu/callback # 📱 Aitu Apps Push хабарландырулары AITU_APPS_APP_ID=your_apps_app_id AITU_APPS_APP_SECRET=your_apps_app_secret # 🔒 Webhook қауіпсіздігі AITU_WEBHOOK_SECRET=your_webhook_secret AITU_WEBHOOK_VERIFY_SIGNATURE=true # 🛠️ Қосымша баптаулар AITU_LOGGING_ENABLED=true AITU_CACHE_ENABLED=true AITU_API_TIMEOUT=30 AITU_RETRY_ATTEMPTS=3
🏗️ Aitu Passport баптау
Aitu Passport қадамдық баптау
-
Қосымша жасау
- Aitu Passport басқару панеліне өтіңіз
- Жаңа қосымша жасаңыз
Client IDжәнеClient Secretалыңыз
-
Redirect URI баптау
https://your-domain.com/auth/aitu/callback -
Webhook баптау
- Authorization webhook:
https://your-domain.com/api/webhooks/aitu/passport - General webhook:
https://your-domain.com/api/webhooks/aitu
- Authorization webhook:
📱 Aitu Apps баптау
Aitu Apps қадамдық баптау
-
Қосымша жасау
- Aitu Apps басқару панеліне өтіңіз
- Жаңа қосымша жасаңыз
App IDжәнеApp Secretалыңыз
-
Webhook баптау
- Apps webhook:
https://your-domain.com/api/webhooks/aitu/apps - General webhook:
https://your-domain.com/api/webhooks/aitu
- Apps webhook:
🚀 Жылдам бастау
🔐 Aitu Passport OAuth
use MadArlan\AituMessenger\Facades\AituPassport; // 🎯 Авторизация URL алу $authUrl = AituPassport::getAuthorizationUrl(['profile', 'email']); return redirect($authUrl); // 🔄 Callback өңдеу $tokens = AituPassport::exchangeCodeForTokens($request->get('code')); $userInfo = AituPassport::getUserInfo($tokens['access_token']); // 👤 Пайдаланушы туралы ақпарат echo "👋 Сәлем, " . $userInfo->getName(); echo "📧 Email: " . $userInfo->getEmail(); echo "📱 Телефон: " . $userInfo->getPhone();
📱 Aitu Apps Push хабарландырулары
use MadArlan\AituMessenger\Facades\AituApps; // 🎯 Нақты пайдаланушыға хабарландыру $result = AituApps::sendTargetedNotification( userId: 'user_123', title: '🎉 Құттықтаймыз!', body: 'Сіздің тапсырысыңыз сәтті рәсімделді', data: ['order_id' => 12345, 'status' => 'confirmed'] ); // 👥 Топтық хабарландыру $result = AituApps::sendGroupNotification( groupId: 'group_456', title: '📢 Маңызды хабарландыру', body: 'Жаңа функциялар енді қолжетімді!' ); // ⏰ Жоспарланған хабарландыру $scheduledTime = now()->addHours(2); $result = AituApps::scheduleNotification( userId: 'user_123', title: '⏰ Еске салу', body: '15:00-де кездесуді ұмытпаңыз', scheduledAt: $scheduledTime );
🔗 Webhook өңдеу
Webhook-тар қолтаңбаны тексеру үшін aitu.webhook middleware арқылы автоматты өңделеді:
// 🌐 Автоматты қосылған маршруттар Route::post('/api/webhooks/aitu', [WebhookController::class, 'handleGeneralWebhook']) ->middleware('aitu.webhook'); Route::post('/api/webhooks/aitu/passport', [WebhookController::class, 'handlePassportWebhook']) ->middleware('aitu.webhook'); Route::post('/api/webhooks/aitu/apps', [WebhookController::class, 'handleAppsWebhook']) ->middleware('aitu.webhook');
🔒 Қауіпсіздік:
aitu.webhookmiddleware конфигурациядан құпия кілтті пайдаланып webhook қолтаңбасын автоматты тексереді.
💡 Пайдалану мысалдары
🔐 OAuth авторизациясының толық циклі
Авторизация контроллері
<?php namespace App\Http\Controllers; use Illuminate\Http\Request; use MadArlan\AituMessenger\Facades\AituPassport; use App\Models\User; use Illuminate\Support\Facades\Auth; class AituAuthController extends Controller { /** * 🚀 Авторизацияға бағыттау */ public function login() { $authUrl = AituPassport::getAuthorizationUrl([ 'profile', 'email', 'phone' ], 'custom_state_' . time()); return redirect($authUrl); } /** * 🔄 Callback өңдеу */ public function callback(Request $request) { try { // Қауіпсіздік үшін state тексереміз if (!$request->has('state') || !str_starts_with($request->state, 'custom_state_')) { throw new \Exception('Invalid state parameter'); } // Кодты токенге айырбастаймыз $tokenData = AituPassport::exchangeCodeForTokens($request->code); $user = AituPassport::getUserInfo($tokenData['access_token']); // Пайдаланушыны жасаймыз немесе жаңартамыз $localUser = User::updateOrCreate( ['aitu_id' => $user->getId()], [ 'name' => $user->getName(), 'email' => $user->getEmail(), 'phone' => $user->getPhone(), 'avatar' => $user->getAvatar(), 'aitu_access_token' => $tokenData['access_token'], 'aitu_refresh_token' => $tokenData['refresh_token'], 'aitu_token_expires_at' => now()->addSeconds($tokenData['expires_in']), ] ); Auth::login($localUser); return redirect('/dashboard')->with('success', '🎉 Aitu арқылы сәтті авторизация!'); } catch (\Exception $e) { return redirect('/login')->with('error', '❌ Авторизация қатесі: ' . $e->getMessage()); } } /** * 🚪 Жүйеден шығу */ public function logout(Request $request) { $user = Auth::user(); if ($user && $user->aitu_access_token) { // Aitu-да токенді кері қайтарамыз AituPassport::revokeToken($user->aitu_access_token); } Auth::logout(); $request->session()->invalidate(); $request->session()->regenerateToken(); return redirect('/')->with('success', '👋 Сау болыңыз!'); } }
📱 Хабарландыру жүйесі
Хабарландыру жіберу үшін Job
<?php namespace App\Jobs; use Illuminate\Bus\Queueable; use Illuminate\Contracts\Queue\ShouldQueue; use Illuminate\Foundation\Bus\Dispatchable; use Illuminate\Queue\InteractsWithQueue; use Illuminate\Queue\SerializesModels; use MadArlan\AituMessenger\Facades\AituApps; use Illuminate\Support\Facades\Log; class SendAituNotificationJob implements ShouldQueue { use Dispatchable, InteractsWithQueue, Queueable, SerializesModels; public function __construct( private string $userId, private string $title, private string $body, private array $data = [], private ?string $icon = null, private ?string $image = null, private ?string $clickAction = null ) {} /** * 🚀 Тапсырманы орындау */ public function handle(): void { try { $notification = [ 'title' => $this->title, 'body' => $this->body, 'user_id' => $this->userId, 'data' => $this->data, ]; // Қосымша параметрлер бар болса қосамыз if ($this->icon) { $notification['icon'] = $this->icon; } if ($this->image) { $notification['image'] = $this->image; } if ($this->clickAction) { $notification['click_action'] = $this->clickAction; } $response = AituApps::sendTargetedNotification($notification); if ($response->isSuccessful()) { Log::info('✅ Aitu хабарландыруы сәтті жіберілді', [ 'user_id' => $this->userId, 'notification_id' => $response->getData('notification_id') ]); } else { Log::error('❌ Aitu хабарландыруын жіберу сәтсіз', [ 'user_id' => $this->userId, 'error' => $response->getError() ]); } } catch (\Exception $e) { Log::error('💥 Aitu хабарландыруын жіберу кезінде қате', [ 'user_id' => $this->userId, 'error' => $e->getMessage(), 'trace' => $e->getTraceAsString() ]); throw $e; // Retry механизмі үшін қатені қайта лақтырамыз } } }
Пайдалану:
// 🎯 Қарапайым хабарландыру SendAituNotificationJob::dispatch( userId: 'user-uuid-123', title: '🛒 Жаңа тапсырыс', body: 'Сіздің #12345 тапсырысыңыз өңдеуге қабылданды' ); // 🎨 Медиа және әрекетпен хабарландыру SendAituNotificationJob::dispatch( userId: 'user-uuid-123', title: '🎉 Арнайы ұсыныс!', body: 'Апта соңына дейін барлық тауарларға 50% жеңілдік', data: ['promo_code' => 'SALE50', 'discount' => 50], icon: 'https://example.com/sale-icon.png', image: 'https://example.com/sale-banner.jpg', clickAction: 'https://example.com/sale' ); // ⏰ Кейінге қалдырылған жіберу SendAituNotificationJob::dispatch( userId: 'user-uuid-123', title: '⏰ Еске салу', body: 'Бір сағаттан кейін сіздің кездесуіңіз басталады' )->delay(now()->addMinutes(50));
🔔 Кеңейтілген хабарландырулар
Әртүрлі хабарландыру түрлері
use MadArlan\AituMessenger\Facades\AituApps; // 🎯 Толық параметрлермен мақсатты хабарландыру $response = AituApps::sendTargetedNotification([ 'title' => '🎁 Жеке ұсыныс', 'body' => 'Арнайы сіз үшін 30% жеңілдік!', 'user_id' => 'user-uuid-123', 'icon' => 'https://example.com/gift-icon.png', 'image' => 'https://example.com/personal-offer.jpg', 'click_action' => 'https://example.com/personal-offer', 'data' => [ 'offer_id' => 'PERSONAL_30', 'discount' => 30, 'expires_at' => '2024-12-31T23:59:59Z' ], 'badge' => 1, 'sound' => 'default', 'priority' => 'high' ]); // 👥 Жаппай жіберу $userIds = ['user-1', 'user-2', 'user-3', 'user-4', 'user-5']; $response = AituApps::sendMultipleNotifications([ 'title' => '📢 Маңызды хабарландыру', 'body' => 'Жүйені жаңарту ертең 02:00-де жоспарланған' ], $userIds); // 🏷️ Тегтер бойынша хабарландырулар $response = AituApps::sendNotificationByTags([ 'title' => '⭐ VIP клиенттер үшін', body: 'Тек сіз үшін эксклюзивті сауда!' ], ['vip', 'premium']); // 📡 Барлық пайдаланушыларға Broadcast $response = AituApps::sendBroadcastNotification([ 'title' => '🚨 Жүйелік хабарландыру', 'body' => 'Жоспарлы техникалық жұмыстар 02:00-ден 04:00-ге дейін' ]); // ⏰ Жоспарланған хабарландыру $scheduledTime = now()->addDays(1)->setTime(9, 0); // Ертең 9:00-де $response = AituApps::scheduleNotification( userId: 'user-uuid-123', title: '☀️ Қайырлы таң!', body: 'Күнді біздің жаңалықтармен бастаңыз', scheduledAt: $scheduledTime, data: ['type' => 'morning_digest'] );
📊 Аналитика және статистика
Хабарландыру жеткізуін бақылау
use MadArlan\AituMessenger\Facades\AituApps; // 📊 Хабарландыру статистикасын алу $notificationId = 'notification-uuid-from-response'; $stats = AituApps::getNotificationStatistics($notificationId); if ($stats->isSuccessful()) { $data = $stats->getData(); echo "📤 Жіберілді: " . $data['sent_count'] . "\n"; echo "✅ Жеткізілді: " . $data['delivered_count'] . "\n"; echo "👀 Қаралды: " . $data['viewed_count'] . "\n"; echo "👆 Басылды: " . $data['clicked_count'] . "\n"; echo "📈 CTR: " . round(($data['clicked_count'] / $data['delivered_count']) * 100, 2) . "%\n"; } // 🔍 Хабарландыру күйін тексеру $status = AituApps::getNotificationStatus($notificationId); if ($status->isSuccessful()) { $statusData = $status->getData(); switch ($statusData['status']) { case 'pending': echo "⏳ Хабарландыру жіберу кезегінде"; break; case 'sending': echo "🚀 Хабарландыру жіберіліп жатыр"; break; case 'sent': echo "✅ Хабарландыру жіберілді"; break; case 'failed': echo "❌ Жіберу қатесі: " . $statusData['error_message']; break; } } // ❌ Жоспарланған хабарландыруды болдырмау $scheduledNotificationId = 'scheduled-notification-uuid'; $cancelResponse = AituApps::cancelScheduledNotification($scheduledNotificationId); if ($cancelResponse->isSuccessful()) { echo "✅ Жоспарланған хабарландыру болдырылмады"; } else { echo "❌ Хабарландыруды болдырмау мүмкін болмады: " . $cancelResponse->getError()['message']; }
🛠️ Laravel-сыз пайдалану
SDK кез келген PHP жобасында пайдаланылуы мүмкін:
use MadArlan\AituMessenger\AituPassportClient; use MadArlan\AituMessenger\AituAppsClient; // 🔐 Aitu Passport $passportClient = new AituPassportClient( clientId: 'your_client_id', clientSecret: 'your_client_secret', redirectUri: 'https://yourapp.com/callback' ); $authUrl = $passportClient->getAuthorizationUrl(['profile', 'email']); $tokens = $passportClient->exchangeCodeForTokens($authorizationCode); $user = $passportClient->getUserInfo($tokens['access_token']); // 📱 Aitu Apps $appsClient = new AituAppsClient( appId: 'your_app_id', appSecret: 'your_app_secret' ); $response = $appsClient->sendTargetedNotification([ 'title' => 'Тақырып', 'body' => 'Хабарландыру мәтіні', 'user_id' => 'user-uuid-123' ]);
🧪 Тестілеу
🚀 Тесттерді іске қосу
# Барлық тесттер composer test # Код жамылуымен тесттер composer test-coverage # Тек unit тесттер composer test -- --testsuite=Unit # Тек feature тесттер composer test -- --testsuite=Feature # Тек integration тесттер composer test -- --testsuite=Integration
📊 Код талдау
# PHPStan талдау composer analyse # PHP CS Fixer composer format # Код стилін тексеру composer check-style
✅ Орнатуды тексеру
Тест маршрутын жасаңыз:
// routes/web.php Route::get('/test-aitu', function () { try { // 🧪 Aitu Passport тесті $passportClient = app(\MadArlan\AituMessenger\AituPassportClient::class); $authUrl = $passportClient->getAuthorizationUrl(['profile']); // 🧪 Aitu Apps тесті $appsClient = app(\MadArlan\AituMessenger\AituAppsClient::class); return response()->json([ 'status' => '✅ success', 'passport_auth_url' => $authUrl, 'apps_client' => '✅ initialized', 'timestamp' => now()->toISOString() ]); } catch (\Exception $e) { return response()->json([ 'status' => '❌ error', 'message' => $e->getMessage(), 'timestamp' => now()->toISOString() ], 500); } });
🔧 Мәселелерді шешу
Жиі кездесетін мәселелер мен олардың шешімдері
🚫 Автожүктеу мәселесі
composer dump-autoload php artisan optimize:clear
🗂️ Кэш мәселелері
# Барлық кэштерді тазалау php artisan optimize:clear # Немесе жеке-жеке php artisan config:clear php artisan cache:clear php artisan route:clear php artisan view:clear
🔐 Рұқсат мәселелері
# Linux/Mac sudo chown -R www-data:www-data storage/ sudo chmod -R 775 storage/ # Windows (PowerShell администратор ретінде) icacls storage /grant "IIS_IUSRS:(OI)(CI)F" /T
🌐 Webhook мәселелері
- Aitu басқару панелінде webhook URL-дерін тексеріңіз
- HTTPS дұрыс бапталғанына көз жеткізіңіз
.envфайлындағы құпия кілтті тексеріңіз- Жөндеу үшін логтауды қосыңыз:
AITU_LOGGING_ENABLED=true LOG_LEVEL=debug
📡 API сұраулар мәселелері
// Конфигурацияда таймаутты ұлғайтыңыз 'http' => [ 'timeout' => 60, // секунд 'retry_attempts' => 5, 'retry_delay' => 1000, // миллисекунд ],
📖 Құжаттама
📚 Толық нұсқаулықтар
- 📋 Талаптар мен орнату - Орнатудың толық нұсқаулығы
- ⚙️ Конфигурация - Барлық параметрлерді баптау
- 🚀 Жылдам бастау - 5 минутта пайдалануды бастаңыз
- 💡 Пайдалану мысалдары - Дайын шешімдер
- 🧪 Тестілеу - Кодыңызды қалай тестілеу керек
📁 Код мысалдары
examples/ қалтасында дайын мысалдарды табасыз:
- 🔐
passport_oauth.php- OAuth авторизациясы - 📱
apps_notifications.php- Push хабарландырулары - 🔗
webhook_handler.php- Webhook өңдеу
🧪 Тесттер
Барлық мүмкіндіктерді түсіну үшін тесттерді зерттеңіз:
- 🔬
tests/Unit/- Unit тесттер - 🎯
tests/Feature/- Feature тесттер - 🔗
tests/Integration/- Integration тесттер
🤝 Қолдау
💬 Бізбен байланыс
🆘 Көмек алу
- 📖 Алдымен құжаттаманы тексеріңіз - сұрақтардың көпшілігі жауабы бар
- 🔍 Issues-та іздеңіз - мүмкін сіздің сұрағыңыз талқыланған
- 🐛 Жаңа Issue жасаңыз - жауап таппасаңыз
- 📧 Бізге жазыңыз - шұғыл сұрақтар үшін
🚨 Қауіпсіздік туралы хабарлау
Қауіпсіздік осалдығын тапсаңыз, жария Issue жасамаңыз. madinovarlan@gmail.com мекенжайына email жіберіңіз.
🤝 Дамытуға қатысу
Біз дамытуға қатысуды қуаттаймыз!
🛠️ Үлес қосу жолы
- 🍴 Репозиторийді Fork жасаңыз
- 🌿 Функцияңыз үшін тармақ жасаңыз (
git checkout -b feature/amazing-feature) - ✅ Жаңа функционалдық үшін тесттер қосыңыз
- 🧪 Барлық тесттер өтетініне көз жеткізіңіз (
composer test) - 📝 Өзгерістеріңізді Commit жасаңыз (
git commit -m 'Add amazing feature') - 📤 Тармаққа Push жасаңыз (
git push origin feature/amazing-feature) - 🔄 Pull Request жасаңыз
📋 Дамыту ережелері
- ✅ PSR-12 кодтау стандартын ұстаныңыз
- 🧪 Жаңа функционалдықты тесттермен жабыңыз
- 📝 Коддағы өзгерістерді құжаттаңыз
- 🔄 Қажет болса CHANGELOG.md жаңартыңыз
📄 Лицензия
Бұл жоба MIT License лицензиясымен лицензияланған - толық ақпарат LICENSE файлында.
MIT License
Copyright (c) 2025 Madinov Arlan
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
⭐ Жоба пайдалы болса, жұлдызша қойыңыз!
Күрделі интеграцияларды қарапайым шешімдерге айналдырамыз