AMI - Laravel Asterisk Manager Interface

A powerful and easy-to-use Laravel package for connecting to VOIP servers on the Issabel and Asterisk platform via Asterisk Manager Interface (AMI).

✨ Key Features

🔗 Easy AMI Connection - Simplified connection management
📱 SMS Messaging - Send SMS via Chan Dongle
📞 Call Control - Complete call management and monitoring
🎧 Queue Management - Advanced call queue handling
📊 Real-time Monitoring - Live event monitoring and logging
�️ System Management - Server shutdown, restart, and configuration reload
�🔧 CLI Commands - Powerful command-line interface
📋 Interactive CLI - User-friendly interactive console
🌐 USSD Support - Execute USSD commands seamlessly
⚡ Async Processing - Asynchronous event handling with ReactPHP
🔒 High Security - Secure authentication and connection management
📅 Scheduled Operations - Queue-based scheduled system operations

📋 Requirements

PHP >= 8.0
Laravel >= 9.0
Asterisk/Issabel server with AMI enabled
Chan Dongle (for SMS and USSD functionality)
Extension ext-mbstring

🔄 Version Compatibility

Package Version	PHP Version	Laravel Version	Features	Status
2.2.5	8.0+	9.0-12	Console Command Fix, Docker	✅ Latest
2.2.x	8.0+	9.0-12	System Management, Queue Jobs	✅ Current
2.1.x	8.0+	9.0-11	Enhanced Features	✅ Stable
2.0.x	8.0+	9.0-10	Modern PHP Features	✅ LTS
1.x	5.6+	5.1+	Basic AMI Operations	⚠️ Legacy

Note: Version 2.2.5 includes Docker compatibility fixes and enhanced console command handling.

🚀 Installation

Step 1: Install via Composer

# Latest stable release (v2.2.5)
composer require shahkochaki/ami-laravel-asterisk-manager-interface

# Or specify exact version
composer require shahkochaki/ami-laravel-asterisk-manager-interface:^2.2.5

# For development version
composer require shahkochaki/ami-laravel-asterisk-manager-interface:dev-master

Docker Installation

For Docker environments, add a .dockerignore file to your project root:

vendor/
composer.lock
.git/
.env
node_modules/
*.patch
patches/

And use this in your Dockerfile:

# Install PHP dependencies
RUN composer install --no-interaction --prefer-dist --optimize-autoloader --no-cache

# Alternative for complex patch scenarios
RUN composer install --no-interaction --prefer-dist --optimize-autoloader --no-plugins

Step 2: Register Service Provider

For Laravel 9+: The service provider will be automatically discovered.

For older versions: Add to your config/app.php in the providers array:

'providers' => [
    // Other providers...
    Shahkochaki\Ami\Providers\AmiServiceProvider::class,
]

Step 3: Publish Configuration

php artisan vendor:publish --tag=ami

This will create the config/ami.php configuration file.

🔄 Upgrading from v1.x

If you're upgrading from an older version that supported PHP 5.6+ and Laravel 5.1+:

1. Update PHP and Laravel

# Make sure you have PHP 8.0+ and Laravel 9.0+
php --version
php artisan --version

2. Update the package

composer require shahkochaki/ami-laravel-asterisk-manager-interface

3. Update your code

Replace array_get() helper with Arr::get()
Update event listener syntax if needed
Check deprecated Laravel features

4. Test thoroughly

php artisan ami:action Ping

⚙️ Configuration

AMI Configuration in Asterisk

Before using the package, you need to create an AMI user in Asterisk. Edit /etc/asterisk/manager.conf:

[general]
enabled = yes
port = 5038
bindaddr = 0.0.0.0

[myuser]
secret = mypassword
read = all
write = all

After making changes, reload Asterisk:

asterisk -rx "manager reload"

Laravel Configuration

Edit the config/ami.php file:

<?php

return [
    'host' => env('AMI_HOST', '127.0.0.1'),
    'port' => env('AMI_PORT', 5038),
    'username' => env('AMI_USERNAME', 'myuser'),
    'secret' => env('AMI_SECRET', 'mypassword'),

    'dongle' => [
        'sms' => [
            'device' => env('AMI_SMS_DEVICE', 'dongle0'),
        ],
    ],

    'events' => [
        // Event handlers configuration
        'Dial' => [
            // Custom event handlers
        ],
        'Hangup' => [
            // Custom event handlers
        ],
        // More events...
    ],
];

Environment Variables (.env)

AMI_HOST=192.168.1.100
AMI_PORT=5038
AMI_USERNAME=myuser
AMI_SECRET=mypassword
AMI_SMS_DEVICE=dongle0

🎯 Usage

🎧 Event Listening

Listen to all AMI events:

php artisan ami:listen

With console logging:

php artisan ami:listen --monitor

In PHP code:

use Illuminate\Support\Facades\Artisan;

Artisan::call('ami:listen');

📞 Sending AMI Actions

# Example: Get channel status
php artisan ami:action Status

# Example: Originate a call
php artisan ami:action Originate --arguments=Channel:SIP/1001 --arguments=Context:default --arguments=Exten:1002 --arguments=Priority:1

# Example: Hangup a call
php artisan ami:action Hangup --arguments=Channel:SIP/1001-00000001

In PHP code:

use Illuminate\Support\Facades\Artisan;

// Get channel status
Artisan::call('ami:action', [
    'action' => 'Status'
]);

// Originate a call
Artisan::call('ami:action', [
    'action' => 'Originate',
    '--arguments' => [
        'Channel' => 'SIP/1001',
        'Context' => 'default',
        'Exten' => '1002',
        'Priority' => '1'
    ]
]);

📱 Sending SMS

Send regular SMS:

php artisan ami:dongle:sms 09123456789 "Hello, this is a test message"

Send long SMS (PDU mode):

php artisan ami:dongle:sms 09123456789 "Long message..." --pdu

Specify device:

php artisan ami:dongle:sms 09123456789 "Hello" dongle1

In PHP code:

// Send regular SMS
Artisan::call('ami:dongle:sms', [
    'number' => '09123456789',
    'message' => 'Hello, this is a test message'
]);

// Send long SMS
Artisan::call('ami:dongle:sms', [
    'number' => '09123456789',
    'message' => 'Long message...',
    '--pdu' => true
]);

🌐 USSD Commands

php artisan ami:dongle:ussd dongle0 "*141#"

In PHP code:

Artisan::call('ami:dongle:ussd', [
    'device' => 'dongle0',
    'ussd' => '*141#'
]);

💻 Interactive CLI Interface

Start CLI interface:

php artisan ami:cli

Run command and auto-close:

php artisan ami:cli "core show channels" --autoclose

🔧 Usage without Laravel

php ./vendor/bin/ami ami:listen --host=192.168.1.100 --port=5038 --username=myuser --secret=mypass --monitor

📚 Advanced Examples

Event Management

// In a Service Provider or Event Listener
use Illuminate\Support\Facades\Event;

Event::listen('ami.event.dial', function ($event) {
    Log::info('New call started', [
        'caller' => $event['CallerIDNum'],
        'destination' => $event['Destination']
    ]);
});

Event::listen('ami.event.hangup', function ($event) {
    Log::info('Call ended', [
        'channel' => $event['Channel'],
        'cause' => $event['Cause']
    ]);
});

Custom Call Manager Class

<?php

namespace App\Services;

use Illuminate\Support\Facades\Artisan;

class CallManager
{
    public function makeCall($from, $to, $context = 'default')
    {
        return Artisan::call('ami:action', [
            'action' => 'Originate',
            '--arguments' => [
                'Channel' => "SIP/{$from}",
                'Context' => $context,
                'Exten' => $to,
                'Priority' => '1',
                'CallerID' => $from
            ]
        ]);
    }

    public function hangupCall($channel)
    {
        return Artisan::call('ami:action', [
            'action' => 'Hangup',
            '--arguments' => [
                'Channel' => $channel
            ]
        ]);
    }

    public function getChannelStatus()
    {
        return Artisan::call('ami:action', [
            'action' => 'Status'
        ]);
    }
}

Bulk SMS Service

<?php

namespace App\Services;

use Illuminate\Support\Facades\Artisan;
use Illuminate\Support\Collection;

class BulkSmsService
{
    protected $device;

    public function __construct($device = null)
    {
        $this->device = $device ?: config('ami.dongle.sms.device');
    }

    public function sendBulkSms(Collection $recipients, string $message)
    {
        $results = [];

        foreach ($recipients as $number) {
            try {
                $result = Artisan::call('ami:dongle:sms', [
                    'number' => $number,
                    'message' => $message,
                    'device' => $this->device,
                    '--pdu' => strlen($message) > 160
                ]);

                $results[$number] = ['status' => 'success', 'result' => $result];

                // Small delay between messages
                usleep(500000); // 0.5 second

            } catch (\Exception $e) {
                $results[$number] = ['status' => 'error', 'message' => $e->getMessage()];
            }
        }

        return $results;
    }
}

🔍 Supported Events

The library supports all standard Asterisk events:

Call Events: Dial, Hangup, NewChannel, Bridge
Agent Events: AgentConnect, AgentComplete, AgentLogin, AgentLogoff
Queue Events: QueueMember, QueueParams, QueueSummary
Dongle Events: DongleDeviceEntry, DongleSMSStatus, DongleUSSDStatus
System Events: Reload, Shutdown, PeerStatus

🐛 Troubleshooting

Common Issues

Connection Error:
```
Connection refused
```
- Check that Asterisk is running
- Verify port 5038 is open
- Check firewall settings
Authentication Error:
```
Authentication failed
```
- Verify username and password
- Check AMI user permissions
SMS Device Error:
```
Device not found
```
- Check Chan Dongle status: dongle show devices
- Verify device name is correct

Logging

Enable detailed logging:

php artisan ami:listen --monitor

Connection Testing

# Simple connection test
php artisan ami:action Ping

# Check dongle devices status
php artisan ami:action Command --arguments=Command:"dongle show devices"

Docker-Specific Issues (v2.2.5+)

Docker Build Failures:

No available patcher was able to apply patch

Solution: Add .dockerignore and use optimized Composer install:

RUN composer install --no-interaction --prefer-dist --optimize-autoloader --no-cache

Console Commands in Docker:

OutputStyle class not found

Solution: This is fixed in v2.2.5. Update to the latest version:

composer require shahkochaki/ami-laravel-asterisk-manager-interface:^2.2.5

Composer Cache Issues:

# Clear composer cache before Docker build
composer clear-cache

🔧 Development

Running Tests

composer test

Code Standards

composer phpcs

Project Structure

src/
├── Commands/          # Artisan commands
│   ├── AmiAbstract.php
│   ├── AmiAction.php
│   ├── AmiCli.php
│   ├── AmiListen.php
│   ├── AmiSms.php
│   └── AmiUssd.php
├── Providers/         # Service providers
│   └── AmiServiceProvider.php
├── Factory.php        # AMI connection factory
└── Parser.php         # AMI protocol parser

config/
└── ami.php           # Configuration file

tests/                # Test files
└── ...

🤝 Contributing

We welcome contributions! Please:

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Development Guidelines

Use PSR-4 autoloading
Run tests before committing
Add proper PHPDoc comments
Follow Laravel conventions

📄 License

This project is licensed under the MIT License.

👨‍💻 Author

Ali Shahkochaki

🙏 Acknowledgments

ReactPHP for event loop
clue/ami-react for AMI protocol
Laravel community for the amazing framework

📚 Useful Resources

⭐ If this project helped you, please give it a star!

AMI - رابط مدیریت Asterisk برای Laravel

یک کتابخانه قدرتمند و آسان برای اتصال سرورهای Laravel به سرورهای VOIP بر روی پلتفرم Issabel و Asterisk از طریق Asterisk Manager Interface (AMI).

✨ امکانات اصلی

🔗 اتصال آسان به AMI - مدیریت ساده اتصالات
📱 ارسال SMS - ارسال پیامک از طریق Chan Dongle
📞 کنترل تماس‌ها - مدیریت کامل و مانیتورینگ تماس‌ها
🎧 مدیریت صف تماس - مدیریت پیشرفته صف‌های تماس
📊 مانیتورینگ real-time - مانیتورینگ و لاگ‌گیری زنده رویدادها
�️ مدیریت سیستم - خاموش، ریست و بارگیری مجدد سرور
�🔧 دستورات CLI - رابط خط فرمان قدرتمند
📋 رابط کاربری تعاملی - کنسول تعاملی کاربرپسند
🌐 پشتیبانی از USSD - اجرای دستورات USSD به صورت یکپارچه
⚡ پردازش ناهمزمان - مدیریت رویدادهای ناهمزمان با ReactPHP
🔒 امنیت بالا - احراز هویت ایمن و مدیریت اتصال
📅 عملیات برنامه‌ریزی شده - عملیات زمان‌بندی شده با Queue

📋 پیش‌نیازها

PHP >= 8.0
Laravel >= 9.0
سرور Asterisk/Issabel با AMI فعال
Chan Dongle (برای عملکرد SMS و USSD)
Extension ext-mbstring

🔄 سازگاری نسخه‌ها

نسخه پکیج	نسخه PHP	نسخه Laravel	امکانات جدید	وضعیت
2.1+	8.0+	9.0+	System Management, Queue Jobs	✅ جدید
2.0	8.0+	9.0+	Modern PHP Features	✅ فعلی
1.x	5.6+	5.1+	Basic AMI Operations	⚠️ قدیمی

توجه: نسخه 2.1+ شامل مدیریت کامل سیستم، عملیات برنامه‌ریزی شده و ویژگی‌های پیشرفته است.

مقایسه امکانات نسخه‌ها

ویژگی	v1.x	v2.0	v2.1+
AMI Connection	✅	✅	✅
Event Listening	✅	✅	✅
SMS Sending	✅	✅	✅
USSD Commands	✅	✅	✅
Call Management	✅	✅	✅
Interactive CLI	✅	✅	✅
Modern PHP (8.0+)	❌	✅	✅
System Management	❌	❌	✅
Server Shutdown/Restart	❌	❌	✅
Configuration Reload	❌	❌	✅
Health Monitoring	❌	❌	✅
Scheduled Operations	❌	❌	✅
Queue Jobs	❌	❌	✅
SystemManager Service	❌	❌	✅
Facade Support	❌	❌	✅

🚀 شروع سریع / Quick Start

نصب و راه‌اندازی اولیه

# نصب پکیج
composer require shahkochaki/ami-laravel-asterisk-manager-interface

# انتشار فایل تنظیمات
php artisan vendor:publish --tag=ami

# تنظیم متغیرهای محیطی
# در فایل .env
AMI_HOST=192.168.1.100
AMI_PORT=5038
AMI_USERNAME=myuser
AMI_SECRET=mypassword

تست اتصال

# تست اتصال ساده
php artisan ami:action Ping

# گوش دادن به رویدادها
php artisan ami:listen --monitor

# دریافت وضعیت سرور
php artisan ami:system status

مثال سریع مدیریت سیستم

use Shahkochaki\Ami\Services\SystemManager;

// ایجاد instance
$systemManager = new SystemManager();

// دریافت وضعیت سرور
$status = $systemManager->getServerStatus();
echo "Server Status: " . json_encode($status);

// ریست امن سرور
$systemManager->restartServer(true, 'System update');

گام 1: نصب از طریق Composer

composer require shahkochaki/ami-laravel-asterisk-manager-interface

یا برای آخرین نسخه توسعه:

composer require shahkochaki/ami-laravel-asterisk-manager-interface:dev-master

گام 2: ثبت Service Provider

برای Laravel 9+: Service provider به صورت خودکار تشخیص داده می‌شود.

برای نسخه‌های قدیمی‌تر: در فایل config/app.php در آرایه providers اضافه کنید:

'providers' => [
    // سایر providers...
    Shahkochaki\Ami\Providers\AmiServiceProvider::class,
]

گام 3: انتشار فایل تنظیمات

php artisan vendor:publish --tag=ami

این دستور فایل config/ami.php را ایجاد می‌کند.

🔄 ارتقا از نسخه v1.x

اگر از نسخه قدیمی که از PHP 5.6+ و Laravel 5.1+ پشتیبانی می‌کرد، ارتقا می‌دهید:

1. به‌روزرسانی PHP و Laravel

# مطمئن شوید که PHP 8.0+ و Laravel 9.0+ دارید
php --version
php artisan --version

2. به‌روزرسانی پکیج

composer require shahkochaki/ami-laravel-asterisk-manager-interface

3. به‌روزرسانی کد شما

array_get() helper را با Arr::get() جایگزین کنید
syntax event listener را در صورت نیاز به‌روزرسانی کنید
ویژگی‌های deprecated Laravel را بررسی کنید

4. تست کامل

php artisan ami:action Ping

⚙️ تنظیمات

تنظیمات AMI در Asterisk

قبل از استفاده، باید یک کاربر AMI در Asterisk ایجاد کنید. فایل /etc/asterisk/manager.conf را ویرایش کنید:

[general]
enabled = yes
port = 5038
bindaddr = 0.0.0.0

[myuser]
secret = mypassword
read = all
write = all

پس از تغییرات، Asterisk را reload کنید:

asterisk -rx "manager reload"

تنظیمات Laravel

<?php

return [
    'host' => env('AMI_HOST', '127.0.0.1'),
    'port' => env('AMI_PORT', 5038),
    'username' => env('AMI_USERNAME', 'myuser'),
    'secret' => env('AMI_SECRET', 'mypassword'),

    'dongle' => [
        'sms' => [
            'device' => env('AMI_SMS_DEVICE', 'dongle0'),
        ],
    ],

    'events' => [
        // تنظیمات مدیریت رویدادها
        'Dial' => [
            // مدیریت‌کننده‌های سفارشی رویداد
        ],
        'Hangup' => [
            // مدیریت‌کننده‌های سفارشی رویداد
        ],
        // رویدادهای بیشتر...
    ],
];

متغیرهای محیطی (.env)

AMI_HOST=192.168.1.100
AMI_PORT=5038
AMI_USERNAME=myuser
AMI_SECRET=mypassword
AMI_SMS_DEVICE=dongle0

🎯 استفاده

🎧 گوش دادن به رویدادها

گوش دادن به تمام رویدادهای AMI:

php artisan ami:listen

با نمایش log در کنسول:

php artisan ami:listen --monitor

در کد PHP:

use Illuminate\Support\Facades\Artisan;

Artisan::call('ami:listen');

📞 ارسال دستورات AMI

# مثال: وضعیت کانال‌ها
php artisan ami:action Status

# مثال: برقراری تماس
php artisan ami:action Originate --arguments=Channel:SIP/1001 --arguments=Context:default --arguments=Exten:1002 --arguments=Priority:1

# مثال: قطع تماس
php artisan ami:action Hangup --arguments=Channel:SIP/1001-00000001

در کد PHP:

use Illuminate\Support\Facades\Artisan;

// دریافت وضعیت کانال‌ها
Artisan::call('ami:action', [
    'action' => 'Status'
]);

// برقراری تماس
Artisan::call('ami:action', [
    'action' => 'Originate',
    '--arguments' => [
        'Channel' => 'SIP/1001',
        'Context' => 'default',
        'Exten' => '1002',
        'Priority' => '1'
    ]
]);

📱 ارسال SMS

ارسال SMS معمولی:

php artisan ami:dongle:sms 09123456789 "سلام، این یک پیام تست است"

ارسال SMS طولانی (حالت PDU):

php artisan ami:dongle:sms 09123456789 "پیام طولانی..." --pdu

مشخص کردن دستگاه:

php artisan ami:dongle:sms 09123456789 "سلام" dongle1

در کد PHP:

// ارسال SMS معمولی
Artisan::call('ami:dongle:sms', [
    'number' => '09123456789',
    'message' => 'سلام، این یک پیام تست است'
]);

// ارسال SMS طولانی
Artisan::call('ami:dongle:sms', [
    'number' => '09123456789',
    'message' => 'پیام طولانی...',
    '--pdu' => true
]);

🌐 ارسال دستورات USSD

php artisan ami:dongle:ussd dongle0 "*141#"

در کد PHP:

Artisan::call('ami:dongle:ussd', [
    'device' => 'dongle0',
    'ussd' => '*141#'
]);

💻 رابط خط فرمان تعاملی

شروع رابط CLI:

php artisan ami:cli

اجرای دستور و بستن خودکار:

php artisan ami:cli "core show channels" --autoclose

🔧 استفاده بدون Laravel

php ./vendor/bin/ami ami:listen --host=192.168.1.100 --port=5038 --username=myuser --secret=mypass --monitor

📚 مثال‌های پیشرفته

مدیریت رویدادها

// در یک Service Provider یا Event Listener
use Illuminate\Support\Facades\Event;

Event::listen('ami.event.dial', function ($event) {
    Log::info('تماس جدید شروع شد', [
        'caller' => $event['CallerIDNum'],
        'destination' => $event['Destination']
    ]);
});

Event::listen('ami.event.hangup', function ($event) {
    Log::info('تماس پایان یافت', [
        'channel' => $event['Channel'],
        'cause' => $event['Cause']
    ]);
});

ایجاد کلاس سفارشی برای مدیریت تماس‌ها

<?php

namespace App\Services;

use Illuminate\Support\Facades\Artisan;

class CallManager
{
    public function makeCall($from, $to, $context = 'default')
    {
        return Artisan::call('ami:action', [
            'action' => 'Originate',
            '--arguments' => [
                'Channel' => "SIP/{$from}",
                'Context' => $context,
                'Exten' => $to,
                'Priority' => '1',
                'CallerID' => $from
            ]
        ]);
    }

    public function hangupCall($channel)
    {
        return Artisan::call('ami:action', [
            'action' => 'Hangup',
            '--arguments' => [
                'Channel' => $channel
            ]
        ]);
    }

    public function getChannelStatus()
    {
        return Artisan::call('ami:action', [
            'action' => 'Status'
        ]);
    }
}

سرویس ارسال SMS انبوه

<?php

namespace App\Services;

use Illuminate\Support\Facades\Artisan;
use Illuminate\Support\Collection;

class BulkSmsService
{
    protected $device;

    public function __construct($device = null)
    {
        $this->device = $device ?: config('ami.dongle.sms.device');
    }

    public function sendBulkSms(Collection $recipients, string $message)
    {
        $results = [];

        foreach ($recipients as $number) {
            try {
                $result = Artisan::call('ami:dongle:sms', [
                    'number' => $number,
                    'message' => $message,
                    'device' => $this->device,
                    '--pdu' => strlen($message) > 160
                ]);

                $results[$number] = ['status' => 'success', 'result' => $result];

                // تأخیر کوتاه بین ارسال پیام‌ها
                usleep(500000); // نیم ثانیه

            } catch (\Exception $e) {
                $results[$number] = ['status' => 'error', 'message' => $e->getMessage()];
            }
        }

        return $results;
    }
}

🔍 رویدادهای پشتیبانی شده

کتابخانه از تمام رویدادهای استاندارد Asterisk پشتیبانی می‌کند:

رویدادهای تماس: Dial, Hangup, NewChannel, Bridge
رویدادهای اپراتور: AgentConnect, AgentComplete, AgentLogin, AgentLogoff
رویدادهای صف: QueueMember, QueueParams, QueueSummary
رویدادهای Dongle: DongleDeviceEntry, DongleSMSStatus, DongleUSSDStatus
رویدادهای سیستم: Reload, Shutdown, PeerStatus

🐛 عیب‌یابی

مشکلات رایج

خطای اتصال:
```
Connection refused
```
- بررسی کنید که Asterisk در حال اجرا باشد
- پورت 5038 باز باشد
- تنظیمات فایروال را بررسی کنید
خطای احراز هویت:
```
Authentication failed
```
- نام کاربری و رمز عبور را بررسی کنید
- دسترسی‌های کاربر AMI را بررسی کنید
مشکل ارسال SMS:
```
Device not found
```
- وضعیت Chan Dongle را بررسی کنید: dongle show devices
- نام دستگاه را درست وارد کرده‌اید

لاگ‌ها

برای فعال‌سازی لاگ‌های تفصیلی:

php artisan ami:listen --monitor

تست اتصال

# تست ساده اتصال
php artisan ami:action Ping

# بررسی وضعیت دستگاه‌های dongle
php artisan ami:action Command --arguments=Command:"dongle show devices"

🔧 توسعه

اجرای تست‌ها

composer test

استانداردهای کد

composer phpcs

ساختار پروژه

src/
├── Commands/          # دستورات Artisan
│   ├── AmiAbstract.php
│   ├── AmiAction.php
│   ├── AmiCli.php
│   ├── AmiListen.php
│   ├── AmiSms.php
│   └── AmiUssd.php
├── Providers/         # Service providers
│   └── AmiServiceProvider.php
├── Factory.php        # کارخانه اتصال AMI
└── Parser.php         # تجزیه‌کننده پروتکل AMI

config/
└── ami.php           # فایل تنظیمات

tests/                # فایل‌های تست
└── ...

🤝 مشارکت

از مشارکت شما استقبال می‌کنیم! لطفاً:

پروژه را Fork کنید
یک branch جدید ایجاد کنید (git checkout -b feature/amazing-feature)
تغییرات را commit کنید (git commit -m 'Add amazing feature')
به branch خود push کنید (git push origin feature/amazing-feature)
یک Pull Request ایجاد کنید

راهنمای توسعه

از PSR-4 autoloading استفاده کنید
تست‌ها را اجرا کنید قبل از commit
PHPDoc مناسب اضافه کنید
از استانداردهای Laravel پیروی کنید

📄 مجوز

این پروژه تحت مجوز MIT License منتشر شده است.

👨‍💻 سازنده

Ali Shahkochaki

وب‌سایت: shahkochaki.ir
ایمیل: ali.shahkochaki7@gmail.com
گیت‌هاب: @shahkochaki

🙏 تشکر

ReactPHP برای event loop
clue/ami-react برای پروتکل AMI
جامعه Laravel برای فریمورک فوق‌العاده

📚 منابع مفید

⭐ اگر این پروژه برایتان مفید بود، لطفاً ستاره بدهید!

Made with ❤️ for Iranian developers 'secret' => env('AMI_SECRET', 'mypassword'),

'dongle' => [
    'sms' => [
        'device' => env('AMI_SMS_DEVICE', 'dongle0'),
    ],
],

'events' => [
    // Event handlers configuration
    'Dial' => [
        // Custom event handlers
    ],
    'Hangup' => [
        // Custom event handlers
    ],
    // More events...
],

];


### متغیرهای محیطی (.env)

```env
AMI_HOST=192.168.1.100
AMI_PORT=5038
AMI_USERNAME=myuser
AMI_SECRET=mypassword
AMI_SMS_DEVICE=dongle0

🎯 استفاده / Usage

🎧 گوش دادن به رویدادها / Event Listening

گوش دادن به تمام رویدادهای AMI:

php artisan ami:listen

با نمایش log در کنسول:

php artisan ami:listen --monitor

در کد PHP:

use Illuminate\Support\Facades\Artisan;

Artisan::call('ami:listen');

📞 ارسال دستورات AMI / Sending AMI Actions

# مثال: وضعیت کانال‌ها
php artisan ami:action Status

# مثال: برقراری تماس
php artisan ami:action Originate --arguments=Channel:SIP/1001 --arguments=Context:default --arguments=Exten:1002 --arguments=Priority:1

# مثال: قطع تماس
php artisan ami:action Hangup --arguments=Channel:SIP/1001-00000001

در کد PHP:

use Illuminate\Support\Facades\Artisan;

// دریافت وضعیت کانال‌ها
Artisan::call('ami:action', [
    'action' => 'Status'
]);

// برقراری تماس
Artisan::call('ami:action', [
    'action' => 'Originate',
    '--arguments' => [
        'Channel' => 'SIP/1001',
        'Context' => 'default',
        'Exten' => '1002',
        'Priority' => '1'
    ]
]);

📱 ارسال SMS / Sending SMS

ارسال SMS معمولی:

php artisan ami:dongle:sms 09123456789 "سلام، این یک پیام تست است"

ارسال SMS طولانی (PDU mode):

php artisan ami:dongle:sms 09123456789 "پیام طولانی..." --pdu

مشخص کردن دستگاه:

php artisan ami:dongle:sms 09123456789 "سلام" dongle1

در کد PHP:

// ارسال SMS معمولی
Artisan::call('ami:dongle:sms', [
    'number' => '09123456789',
    'message' => 'سلام، این یک پیام تست است'
]);

// ارسال SMS طولانی
Artisan::call('ami:dongle:sms', [
    'number' => '09123456789',
    'message' => 'پیام طولانی...',
    '--pdu' => true
]);

🌐 ارسال دستورات USSD / USSD Commands

php artisan ami:dongle:ussd dongle0 "*141#"

در کد PHP:

Artisan::call('ami:dongle:ussd', [
    'device' => 'dongle0',
    'ussd' => '*141#'
]);

💻 رابط خط فرمان تعاملی / Interactive CLI

شروع رابط CLI:

php artisan ami:cli

اجرای دستور و بستن خودکار:

php artisan ami:cli "core show channels" --autoclose

🔧 استفاده بدون Laravel / Without Laravel

php ./vendor/bin/ami ami:listen --host=192.168.1.100 --port=5038 --username=myuser --secret=mypass --monitor

🖥️ مدیریت سیستم / System Management

جدید! امکان کنترل کامل سرور Asterisk/Issabel:

خاموش کردن و ریست سرور / Server Shutdown & Restart

# خاموش کردن تدریجی سرور
php artisan ami:system shutdown --graceful

# ریست فوری سرور
php artisan ami:system restart --force

# دریافت وضعیت سرور
php artisan ami:system status

# بارگیری مجدد تنظیمات
php artisan ami:system reload --module=sip

استفاده از SystemManager Service

use Shahkochaki\Ami\Services\SystemManager;

$systemManager = new SystemManager([
    'host' => 'localhost',
    'port' => 5038,
    'username' => 'admin',
    'secret' => 'amp111'
]);

// خاموش کردن تدریجی
$systemManager->shutdownServer(true, 'System maintenance');

// ریست فوری
$systemManager->restartServer(false, 'Emergency restart');

// بارگیری مجدد تنظیمات SIP
$systemManager->reloadConfiguration('sip');

// دریافت وضعیت کامل سرور
$status = $systemManager->getServerStatus();

// برنامه‌ریزی ریست برای 30 دقیقه آینده
$schedule = $systemManager->scheduleRestart(30, true, 'Scheduled maintenance');

استفاده از Facade

use Shahkochaki\Ami\Facades\SystemManager;

// خاموش کردن تدریجی
SystemManager::shutdownServer(true, 'Scheduled maintenance');

// ریست اضطراری
SystemManager::emergencyRestart();

// دریافت کانال‌های فعال
$channels = SystemManager::getActiveChannels();

// نظارت بر منابع سیستم
$resources = SystemManager::getSystemResources();

عملیات برنامه‌ریزی شده با Queue

use Shahkochaki\Ami\Jobs\SystemManagementJob;

// برنامه‌ریزی ریست برای 1 ساعت آینده
SystemManagementJob::scheduleRestart(60, true, 'Nightly maintenance');

// برنامه‌ریزی خاموش کردن برای 2 ساعت آینده
SystemManagementJob::scheduleShutdown(120, true, 'End of business hours');

// برنامه‌ریزی بارگیری مجدد تنظیمات
SystemManagementJob::scheduleReload(30, 'dialplan');

📚 مثال‌های پیشرفته / Advanced Examples

مدیریت رویدادها

// در یک Service Provider یا Event Listener
use Illuminate\Support\Facades\Event;

Event::listen('ami.event.dial', function ($event) {
    Log::info('New call started', [
        'caller' => $event['CallerIDNum'],
        'destination' => $event['Destination']
    ]);
});

Event::listen('ami.event.hangup', function ($event) {
    Log::info('Call ended', [
        'channel' => $event['Channel'],
        'cause' => $event['Cause']
    ]);
});

ایجاد کلاس سفارشی برای مدیریت تماس‌ها

<?php

namespace App\Services;

use Illuminate\Support\Facades\Artisan;

class CallManager
{
    public function makeCall($from, $to, $context = 'default')
    {
        return Artisan::call('ami:action', [
            'action' => 'Originate',
            '--arguments' => [
                'Channel' => "SIP/{$from}",
                'Context' => $context,
                'Exten' => $to,
                'Priority' => '1',
                'CallerID' => $from
            ]
        ]);
    }

    public function hangupCall($channel)
    {
        return Artisan::call('ami:action', [
            'action' => 'Hangup',
            '--arguments' => [
                'Channel' => $channel
            ]
        ]);
    }

    public function getChannelStatus()
    {
        return Artisan::call('ami:action', [
            'action' => 'Status'
        ]);
    }
}

سرویس ارسال SMS انبوه

<?php

namespace App\Services;

use Illuminate\Support\Facades\Artisan;
use Illuminate\Support\Collection;

class BulkSmsService
{
    protected $device;

    public function __construct($device = null)
    {
        $this->device = $device ?: config('ami.dongle.sms.device');
    }

    public function sendBulkSms(Collection $recipients, string $message)
    {
        $results = [];

        foreach ($recipients as $number) {
            try {
                $result = Artisan::call('ami:dongle:sms', [
                    'number' => $number,
                    'message' => $message,
                    'device' => $this->device,
                    '--pdu' => strlen($message) > 160
                ]);

                $results[$number] = ['status' => 'success', 'result' => $result];

                // تأخیر کوتاه بین ارسال پیام‌ها
                usleep(500000); // 0.5 second

            } catch (\Exception $e) {
                $results[$number] = ['status' => 'error', 'message' => $e->getMessage()];
            }
        }

        return $results;
    }
}

سرویس مدیریت سیستم پیشرفته

<?php

namespace App\Services;

use Shahkochaki\Ami\Services\SystemManager;
use Illuminate\Support\Facades\Log;

class AdvancedSystemManager
{
    protected $systemManager;

    public function __construct()
    {
        $this->systemManager = new SystemManager();
    }

    /**
     * بررسی سلامت سیستم و اقدام در صورت نیاز
     */
    public function performHealthCheck()
    {
        $status = $this->systemManager->getServerStatus();
        $resources = $this->systemManager->getSystemResources();
        $channels = $this->systemManager->getActiveChannels();

        $issues = [];

        // بررسی خطاها
        if (isset($status['error'])) {
            $issues[] = 'Server status error: ' . $status['error'];
        }

        // بررسی مصرف بالای کانال‌ها
        $channelCount = is_array($channels) ? count($channels) : 0;
        if ($channelCount > 100) {
            $issues[] = "High channel usage: {$channelCount} active channels";
        }

        // لاگ مشکلات
        if (!empty($issues)) {
            Log::warning('System health issues detected', $issues);

            // ارسال اعلان یا اقدام خودکار
            $this->handleHealthIssues($issues);
        }

        return [
            'healthy' => empty($issues),
            'issues' => $issues,
            'channel_count' => $channelCount,
            'timestamp' => now()
        ];
    }

    /**
     * خاموش کردن امن با بررسی شرایط
     */
    public function safeShutdown($reason = 'System maintenance')
    {
        // بررسی کانال‌های فعال
        $channels = $this->systemManager->getActiveChannels();

        if (empty($channels)) {
            Log::info('No active calls, proceeding with immediate shutdown');
            return $this->systemManager->shutdownServer(false, $reason);
        } else {
            Log::info('Active calls detected, using graceful shutdown', [
                'active_channels' => count($channels)
            ]);
            return $this->systemManager->shutdownServer(true, $reason);
        }
    }

    /**
     * مدیریت مشکلات سلامت سیستم
     */
    protected function handleHealthIssues(array $issues)
    {
        foreach ($issues as $issue) {
            if (str_contains($issue, 'High channel usage')) {
                // اقدام برای کاهش بار
                Log::warning('Implementing load reduction measures');
                // می‌توانید اینجا اقدامات خاصی انجام دهید
            }
        }
    }
}

🔍 رویدادهای پشتیبانی شده / Supported Events

کتابخانه از تمام رویدادهای استاندارد Asterisk پشتیبانی می‌کند:

Call Events: Dial, Hangup, NewChannel, Bridge
Agent Events: AgentConnect, AgentComplete, AgentLogin, AgentLogoff
Queue Events: QueueMember, QueueParams, QueueSummary
Dongle Events: DongleDeviceEntry, DongleSMSStatus, DongleUSSDStatus
System Events: Reload, Shutdown, PeerStatus
Management Events: ami.system.operation.sent, ami.system.operation.completed

🐛 عیب‌یابی / Troubleshooting

مشکلات رایج

خطای اتصال:
```
Connection refused
```
- بررسی کنید که Asterisk در حال اجرا باشد
- پورت 5038 باز باشد
- تنظیمات فایروال
خطای احراز هویت:
```
Authentication failed
```
- نام کاربری و رمز عبور را بررسی کنید
- دسترسی‌های کاربر AMI را بررسی کنید
مشکل ارسال SMS:
```
Device not found
```
- وضعیت Chan Dongle را بررسی کنید: dongle show devices
- نام دستگاه را درست وارد کرده‌اید

لاگ‌ها

برای فعال‌سازی لاگ‌های تفصیلی:

php artisan ami:listen --monitor

تست اتصال

# تست ساده اتصال
php artisan ami:action Ping

# بررسی وضعیت دستگاه‌های dongle
php artisan ami:action Command --arguments=Command:"dongle show devices"

🔧 توسعه / Development

اجرای تست‌ها

composer test

استانداردهای کد

composer phpcs

ساختار پروژه

src/
├── Commands/          # Artisan commands
│   ├── AmiAbstract.php
│   ├── AmiAction.php
│   ├── AmiCli.php
│   ├── AmiListen.php
│   ├── AmiSms.php
│   ├── AmiUssd.php
│   └── AmiSystemControl.php   # NEW: System management command
├── Services/          # Service classes
│   ├── BulkSmsService.php
│   ├── CallManager.php
│   └── SystemManager.php      # NEW: System management service
├── Jobs/              # Queue jobs
│   ├── BulkSmsJob.php
│   └── SystemManagementJob.php # NEW: Scheduled system operations
├── Facades/           # Laravel facades
│   ├── Ami.php
│   └── SystemManager.php      # NEW: System management facade
├── Providers/         # Service providers
│   └── AmiServiceProvider.php
├── Factory.php        # AMI connection factory
└── Parser.php         # AMI protocol parser

config/
└── ami.php           # Configuration file

docs/                 # Documentation
├── SYSTEM_MANAGEMENT.md    # NEW: System management guide
└── ...

examples/             # Usage examples
├── system_management_examples.php  # NEW: System management examples
└── ...

tests/                # Test files
└── ...

🤝 مشارکت / Contributing

از مشارکت شما استقبال می‌کنیم! لطفاً:

Fork کنید
یک branch جدید ایجاد کنید (git checkout -b feature/amazing-feature)
تغییرات را commit کنید (git commit -m 'Add amazing feature')
به branch خود push کنید (git push origin feature/amazing-feature)
یک Pull Request ایجاد کنید

راهنمای توسعه

از PSR-4 autoloading استفاده کنید
تست‌ها را اجرا کنید قبل از commit
PHPDoc مناسب اضافه کنید
از استانداردهای Laravel پیروی کنید

📄 مجوز / License

این پروژه تحت مجوز MIT License منتشر شده است.

👨‍💻 سازنده / Author

Ali Shahkochaki

🙏 تشکر / Acknowledgments

ReactPHP برای event loop
clue/ami-react برای AMI protocol
جامعه Laravel برای فریمورک عالی

📚 منابع مفید / Useful Resources

Asterisk Manager Interface
Chan Dongle Documentation
Issabel Documentation
System Management Guide - راهنمای کامل مدیریت سیستم
System Management Examples - مثال‌های عملی
Troubleshooting Guide - راهنمای عیب‌یابی و حل مشکلات

🆕 What's New in v2.2.5

🐛 Critical Fixes

✅ Docker Compatibility: Fixed console command execution in Docker environments
✅ Composer Issues: Resolved patch application failures during Docker builds
✅ Production Stability: Enhanced error handling and class loading
✅ Console Commands: Fixed OutputStyle class resolution issues

🚀 Enhancements

🔧 Docker Support: Added .dockerignore template and build optimizations
📚 Documentation: Updated with Docker best practices and troubleshooting
🛡️ Error Handling: Improved exception handling in command execution
⚡ Performance: Optimized dependency loading and command initialization

📦 Quick Update

composer update shahkochaki/ami-laravel-asterisk-manager-interface

🆕 Previous Features - System Management (v2.1+)

Core System Management

✅ SystemManager Service: Complete control of Asterisk/Issabel server
✅ System Commands: CLI commands for system management
✅ Scheduled Operations: Queue-based scheduled operations
✅ Health Monitoring: System health and resource monitoring
✅ Safe Operations: Safe operations with condition checking
✅ Event Integration: Integration with Laravel event system

امکانات جدید:

// خاموش کردن و ریست سرور
SystemManager::shutdownServer(true, 'Maintenance');
SystemManager::restartServer(false, 'Emergency');

// نظارت بر سیستم
$status = SystemManager::getServerStatus();
$resources = SystemManager::getSystemResources();

// عملیات برنامه‌ریزی شده
SystemManagementJob::scheduleRestart(60, true, 'Nightly restart');

دستورات جدید CLI:

php artisan ami:system shutdown --graceful
php artisan ami:system restart --force
php artisan ami:system reload --module=sip
php artisan ami:system status

📈 Release History

Version	Date	Key Features
v2.2.5	2025-11-10	🐛 Docker fixes, Console command improvements
v2.2.4	2025-10-20	🔧 React Socket API compatibility
v2.2.3	2025-09-15	🚀 Performance improvements
v2.1.x	2025-08-xx	🖥️ System Management features
v2.0.x	2025-06-xx	🎯 Modern PHP 8.0+ support

🎯 Quick Links

📦 Packagist: shahkochaki/ami-laravel-asterisk-manager-interface
📋 Changelog: CHANGELOG.md
📄 Release Notes: Latest Release
🐛 Issues: GitHub Issues
💡 Discussions: GitHub Discussions

⭐ اگر این پروژه برایتان مفید بود، لطفاً ستاره بدهید!

Made with ❤️ for Iranian developers and global PHP community

Name		Name	Last commit message	Last commit date
Latest commit History 46 Commits
.vscode		.vscode
bin		bin
config		config
docs		docs
examples		examples
src		src
tests		tests
vendor		vendor
.dockerignore		.dockerignore
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
DOCKER_GUIDE.md		DOCKER_GUIDE.md
LICENSE.md		LICENSE.md
README.md		README.md
RELEASE_NOTES.md		RELEASE_NOTES.md
RELEASE_NOTES_v2.1.1.md		RELEASE_NOTES_v2.1.1.md
RELEASE_NOTES_v2.1.2.md		RELEASE_NOTES_v2.1.2.md
RELEASE_NOTES_v2.1.3.md		RELEASE_NOTES_v2.1.3.md
RELEASE_NOTES_v2.1.4.md		RELEASE_NOTES_v2.1.4.md
RELEASE_NOTES_v2.1.5.md		RELEASE_NOTES_v2.1.5.md
RELEASE_NOTES_v2.2.1.md		RELEASE_NOTES_v2.2.1.md
RELEASE_NOTES_v2.2.3.md		RELEASE_NOTES_v2.2.3.md
RELEASE_NOTES_v2.2.4.md		RELEASE_NOTES_v2.2.4.md
RELEASE_NOTES_v2.2.5.md		RELEASE_NOTES_v2.2.5.md
RELEASE_NOTES_v2.2.6.md		RELEASE_NOTES_v2.2.6.md
composer.json		composer.json
composer.lock		composer.lock
logo.png		logo.png
phpunit.xml		phpunit.xml

License

shahkochaki/ami-laravel-asterisk-manager-interface

Folders and files

Latest commit

History

Repository files navigation

AMI - Laravel Asterisk Manager Interface

✨ Key Features

📋 Requirements

🔄 Version Compatibility

🚀 Installation

Step 1: Install via Composer

Docker Installation

Step 2: Register Service Provider

Step 3: Publish Configuration

🔄 Upgrading from v1.x

1. Update PHP and Laravel

2. Update the package

3. Update your code

4. Test thoroughly

⚙️ Configuration

AMI Configuration in Asterisk

Laravel Configuration

Environment Variables (.env)

🎯 Usage

🎧 Event Listening

📞 Sending AMI Actions

📱 Sending SMS

🌐 USSD Commands

💻 Interactive CLI Interface

🔧 Usage without Laravel

📚 Advanced Examples

Event Management

Custom Call Manager Class

Bulk SMS Service

🔍 Supported Events

🐛 Troubleshooting

Common Issues

Logging

Connection Testing

Docker-Specific Issues (v2.2.5+)

🔧 Development

Running Tests

Code Standards

Project Structure

🤝 Contributing

Development Guidelines

📄 License

👨‍💻 Author

🙏 Acknowledgments

📚 Useful Resources

AMI - رابط مدیریت Asterisk برای Laravel

✨ امکانات اصلی

📋 پیش‌نیازها

🔄 سازگاری نسخه‌ها

مقایسه امکانات نسخه‌ها

🚀 شروع سریع / Quick Start

نصب و راه‌اندازی اولیه

تست اتصال

مثال سریع مدیریت سیستم

گام 1: نصب از طریق Composer

گام 2: ثبت Service Provider

گام 3: انتشار فایل تنظیمات

🔄 ارتقا از نسخه v1.x

1. به‌روزرسانی PHP و Laravel

2. به‌روزرسانی پکیج

3. به‌روزرسانی کد شما

4. تست کامل

⚙️ تنظیمات

تنظیمات AMI در Asterisk

تنظیمات Laravel

متغیرهای محیطی (.env)

🎯 استفاده

🎧 گوش دادن به رویدادها

📞 ارسال دستورات AMI

📱 ارسال SMS

🌐 ارسال دستورات USSD

💻 رابط خط فرمان تعاملی

🔧 استفاده بدون Laravel

📚 مثال‌های پیشرفته