Iran SMS Laravel

https://github.com/amyavari/iran-sms-laravel
Admin
Iran SMS Laravel is a simple and convenient PHP library that allows developers to send SMS messages...
Tokens:3,915
Snippets:55
Trust Score:6.5
License:MIT
Update:3 months ago
Show doc for...
Tokens:
Raw
### Install Dependencies

Source: https://github.com/amyavari/iran-sms-laravel/blob/main/CONTRIBUTING.md

Install the project's development dependencies.

```bash
composer install
```

--------------------------------

### Install Package via Composer

Source: https://github.com/amyavari/iran-sms-laravel/blob/main/README.md

Run this command in your terminal to add the package to your Laravel project.

```bash
composer require amyavari/iran-sms-laravel
```

--------------------------------

### Publish Vendor Files

Source: https://github.com/amyavari/iran-sms-laravel/blob/main/README.md

Commands to publish configuration and migration files, followed by running migrations to set up the database.

```bash
php artisan iran-sms:install
```

```bash
php artisan migrate
```

```bash
php artisan vendor:publish --tag=iran-sms-config
```

```bash
php artisan vendor:publish --tag=iran-sms-migrations
```

--------------------------------

### Create SMS Instances

Source: https://github.com/amyavari/iran-sms-laravel/blob/main/README.md

Initialize SMS messages using the facade with default or specific providers.

```php
use AliYavari
anSms\Facades\Sms;

// Using the default provider
$sms = Sms::otp(string $phone, string $message);
$sms = Sms::text(string|array $phones, string $message);
$sms = Sms::pattern(string|array $phones, string $patternCode, array $variables);

// Using a specific provider
$sms = Sms::provider(string $provider)->otp(...);
$sms = Sms::provider(string $provider)->text(...);
$sms = Sms::provider(string $provider)->pattern(...);
```

--------------------------------

### Configure Multiple Providers

Source: https://github.com/amyavari/iran-sms-laravel/blob/main/README.md

Define provider settings in the config file and corresponding environment variables in .env.

```php
'providers' => [

    'trez' => [
        'username' => env('SMS_TREZ_USERNAME', ''), // Previously: env('SMS_USERNAME', '')
        'password' => env('SMS_TREZ_PASSWORD', ''), // Previously: env('SMS_PASSWORD', '')
        'token'    => env('SMS_TREZ_TOKEN', ''),    // Previously: env('SMS_TOKEN', '')
        'from'     => env('SMS_TREZ_FROM', ''),     // Previously: env('SMS_FROM', '')
    ],

    // Repeat this structure for any other providers you want to configure
],
```

```env
SMS_TREZ_USERNAME=<your_username>
SMS_TREZ_PASSWORD=<your_password>
SMS_TREZ_TOKEN=<your_token>
SMS_TREZ_FROM=<your_sender_number>

# Repeat for other providers you defined
```

--------------------------------

### Run Tests

Source: https://github.com/amyavari/iran-sms-laravel/blob/main/CONTRIBUTING.md

Execute various test suites and quality checks.

```bash
composer test
```

```bash
composer test:types
```

```bash
composer test:unit
```

--------------------------------

### Fluent Logging Configuration

Source: https://github.com/amyavari/iran-sms-laravel/blob/main/README.md

Chain multiple logging methods to define complex log behavior.

```php
// Example: Log all message types except OTPs, only if they are sent successfully
$sms->log()->logOtp(false)->logSuccessful();
```

--------------------------------

### Configure Single Provider

Source: https://github.com/amyavari/iran-sms-laravel/blob/main/README.md

Add these variables to your .env file to set up a default SMS provider.

```env
# Default provider
SMS_PROVIDER=<default_provider>

# If provider uses username and password
SMS_USERNAME=<username>
SMS_PASSWORD=<password>

# If provider uses an API token
SMS_TOKEN=<api_token>

# Default sender number
SMS_FROM=<default_sender_number>
```

--------------------------------

### Register Driver in Service Provider

Source: https://github.com/amyavari/iran-sms-laravel/blob/main/CONTRIBUTING.md

Bind the new driver class in the package service provider.

```php
public function packageRegistered(): void
{
    // Other driver bindings...

    $this->app->bind(
        YourNameDriver::class,
        fn () => new YourNameDriver(...config('iran-sms.providers.your_name'))
    );
}
```

--------------------------------

### Lint Code

Source: https://github.com/amyavari/iran-sms-laravel/blob/main/CONTRIBUTING.md

Run the linter to ensure code style compliance.

```bash
composer lint
```

--------------------------------

### Create Driver Class

Source: https://github.com/amyavari/iran-sms-laravel/blob/main/CONTRIBUTING.md

Implement a new driver class extending the base Driver class and defining required SMS methods.

```php
use AliYavari\IranSms\Abstracts\Driver;
use AliYavari\IranSms\Exceptions\UnsupportedMethodException;

final class YourNameDriver extends Driver
{
    public function __construct(
        private readonly string $username,
        private readonly string $password,
        private readonly string $token,
        private readonly string $from,
    ) {}

    protected function getDefaultSender(): string
    {
        return $this->from;
    }

    protected function sendOtp(string $phone, string $message, string $from): static
    {
        // Implement OTP sending logic here
        return $this;
    }

    protected function sendPattern(array $phones, string $patternCode, array $variables, string $from): static
    {
        // Implement pattern SMS logic here
        return $this;
    }

    protected function sendText(array $phones, string $message, string $from): static
    {
        // Implement plain text SMS logic here
        return $this;
    }

    protected function isSuccessful(): bool
    {
        // Return true or false based on the provider response
    }

    protected function getErrorMessage(): string
    {
        // Return a human-readable error message from the provider
    }

    protected function getErrorCode(): string
    {
        // Return raw error code from the provider
    }
}
```

--------------------------------

### Sms::otp

Source: https://github.com/amyavari/iran-sms-laravel/blob/main/README.md

Creates an OTP SMS instance using the default provider.

```APIDOC
## Sms::otp(string $phone, string $message)

### Description
Creates an OTP SMS instance using the default provider.

### Parameters
- **$phone** (string) - Required - The recipient phone number.
- **$message** (string) - Required - The OTP message content.
```

--------------------------------

### Send SMS

Source: https://github.com/amyavari/iran-sms-laravel/blob/main/README.md

Execute the sending process for the configured SMS instance.

```php
$sms->send();
```

--------------------------------

### Sms::text

Source: https://github.com/amyavari/iran-sms-laravel/blob/main/README.md

Creates a text SMS instance using the default provider.

```APIDOC
## Sms::text(string|array $phones, string $message)

### Description
Creates a text SMS instance using the default provider.

### Parameters
- **$phones** (string|array) - Required - The recipient phone number or array of numbers.
- **$message** (string) - Required - The message content.
```

--------------------------------

### Configure SMS Driver

Source: https://github.com/amyavari/iran-sms-laravel/blob/main/CONTRIBUTING.md

Add the new driver configuration to the providers array in the configuration file.

```php
'providers' => [

    // Other drivers...

    'your_name' => [
        'username' => env('SMS_USERNAME', ''),
        'password' => env('SMS_PASSWORD', ''),
        'token' => env('SMS_TOKEN', ''),
        'from' => env('SMS_FROM', ''),
    ],
],
```

--------------------------------

### SmsInstance::send

Source: https://github.com/amyavari/iran-sms-laravel/blob/main/README.md

Sends the configured SMS message.

```APIDOC
## $sms->send()

### Description
Sends the configured SMS message. Throws an exception on failure.
```

--------------------------------

### Sms::pattern

Source: https://github.com/amyavari/iran-sms-laravel/blob/main/README.md

Creates a pattern-based SMS instance using the default provider.

```APIDOC
## Sms::pattern(string|array $phones, string $patternCode, array $variables)

### Description
Creates a pattern-based SMS instance using the default provider.

### Parameters
- **$phones** (string|array) - Required - The recipient phone number or array of numbers.
- **$patternCode** (string) - Required - The registered pattern code.
- **$variables** (array) - Required - The variables to inject into the pattern.
```

--------------------------------

### Configure Logging by Status

Source: https://github.com/amyavari/iran-sms-laravel/blob/main/README.md

Filter logs based on whether the message sending succeeded or failed.

```php
$sms->logSuccessful(); // Log only if the message was sent successfully
$sms->logFailed();     // Log only if the message failed to send
```

--------------------------------

### Add Factory Method to SmsManager

Source: https://github.com/amyavari/iran-sms-laravel/blob/main/CONTRIBUTING.md

Implement the factory method in the SmsManager to instantiate the new driver.

```php
use AliYavari\IranSms\Drivers\YourNameDriver;

final class SmsManager extends Manager
{
    // Other methods...

    protected function createYourNameDriver(): YourNameDriver
    {
        return $this->container->make(YourNameDriver::class);
    }
}
```

--------------------------------

### Retrieve Credit Balance

Source: https://github.com/amyavari/iran-sms-laravel/blob/main/README.md

Fetch the current credit balance from the default or a specific provider.

```php
use AliYavari\IranSms\Facades\Sms;

// Default provider credit balance
$credit = Sms::credit();                                // int

// Specific provider credit balance
$credit = Sms::provider(string $provider)->credit();    // int
```

--------------------------------

### Configure Logging by Type

Source: https://github.com/amyavari/iran-sms-laravel/blob/main/README.md

Enable or disable logging for specific SMS categories.

```php
$sms->log(bool $log = true);           // Log any type of SMS
$sms->logOtp(bool $log = true);        // Log only OTP messages
$sms->logText(bool $log = true);       // Log only text messages
$sms->logPattern(bool $log = true);    // Log only pattern messages
```

--------------------------------

### Dispatching SMS via Laravel Queues

Source: https://github.com/amyavari/iran-sms-laravel/blob/main/README.md

Use the Sms interface as a constructor type-hint to inject the SMS instance into a queued job.

```php
namespace App\Jobs;

use AliYavari\IranSms\Contracts\Sms;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Foundation\Queue\Queueable;

final class SendSms implements ShouldQueue
{
    use Queueable;

    /**
     * Create a new job instance.
     */
    public function __construct(private Sms $sms) {}

    /**
     * Execute the job.
     */
    public function handle(): void
    {
        $this->sms->log(true)->send();
    }
}
```

--------------------------------

### Implementing SMS Notifications

Source: https://github.com/amyavari/iran-sms-laravel/blob/main/README.md

Define a toSms method and include SmsChannel in the via method of your notification class.

```php
namespace App\Notifications;

use AliYavari\IranSms\Channels\SmsChannel;
use AliYavari\IranSms\Facades\Sms;
use Illuminate\Bus\Queueable;
use Illuminate\Notifications\Notification;

final class MyNotification extends Notification
{
    use Queueable;

    /**
     * Get the notification channels.
     */
    public function via(object $notifiable): array
    {
        return [SmsChannel::class];
    }

    /**
     * Get the SMS representation of the notification.
     */
    public function toSms(object $notifiable)
    {
        return Sms::text($notifiable->phone, 'Hi')->logFailed();
    }
}
```

--------------------------------

### Fake SMS Provider Responses

Source: https://github.com/amyavari/iran-sms-laravel/blob/main/README.md

Use these methods to simulate various SMS provider outcomes. Ensure you use either global behavior or per-provider behavior in a single call, as mixing them is not supported.

```php
use AliYavari\IranSms\Facades\Sms;

/**
 * Fake the default provider to return successful response
 */
Sms::fake();

/**
 * Fake specific providers to return successful responses
 *
 * Note: Use `default` as the provider key to target the default provider
 */
Sms::fake([/* provider keys */]);

/**
 * Equivalent to the above (explicit success definition)
 */
Sms::fake([...], Sms::successfulRequest());

/**
 * Fake providers to return failed responses
 *
 * Optional: custom error message and error code
 */
Sms::fake([...], Sms::failedRequest(string $errorMessage = 'Error Message', string|int $errorCode = 0));

/**
 * Fake providers to throw a ConnectionException
 */
Sms::fake([...], Sms::failedConnection());

/**
 * Define different behaviors per provider
 */
Sms::fake([
    'provider_one' => Sms::successfulRequest(),
    'provider_two' => Sms::failedRequest(),
    'provider_three' => Sms::failedConnection(),
]);
```

--------------------------------

### Prune Old Logs

Source: https://github.com/amyavari/iran-sms-laravel/blob/main/README.md

Schedule the cleanup of old log records using Laravel's task scheduler.

```php
use Illuminate\Support\Facades\Schedule;

Schedule::command('iran-sms:prune-logs --days=30')->daily();
```

--------------------------------

### Sms::credit

Source: https://github.com/amyavari/iran-sms-laravel/blob/main/README.md

Retrieves the current credit balance from the provider.

```APIDOC
## Sms::credit()

### Description
Retrieves the current credit balance in Rials.
```

--------------------------------

### Sms::fake()

Source: https://github.com/amyavari/iran-sms-laravel/blob/main/README.md

The fake method allows you to intercept SMS sending calls and define custom behaviors for providers during testing.

```APIDOC
## Sms::fake()

### Description
Intercepts SMS sending calls to simulate provider responses without actually sending messages.

### Signature
`Sms::fake(array $providers = [], $behavior = null)`

### Parameters
- **providers** (array) - Optional - An array of provider keys to fake. Use 'default' to target the default provider.
- **behavior** (mixed) - Optional - The response behavior to simulate. Use `Sms::successfulRequest()`, `Sms::failedRequest()`, or `Sms::failedConnection()`.

### Usage Examples
```php
// Fake default provider success
Sms::fake();

// Fake specific providers with custom behaviors
Sms::fake([
    'provider_one' => Sms::successfulRequest(),
    'provider_two' => Sms::failedRequest('Error Message', 0),
    'provider_three' => Sms::failedConnection(),
]);
```
```

--------------------------------

### Check Sending Status

Source: https://github.com/amyavari/iran-sms-laravel/blob/main/README.md

Verify if the message was sent successfully and retrieve error details if applicable.

```php
$sms->successful(); // bool
$sms->failed();     // bool

// Get the error message (returns null if successful)
$sms->error();      // string|null
```

--------------------------------

### Sms::provider

Source: https://github.com/amyavari/iran-sms-laravel/blob/main/README.md

Selects a specific SMS provider for subsequent operations.

```APIDOC
## Sms::provider(string $provider)

### Description
Selects a specific SMS provider for subsequent operations.

### Parameters
- **$provider** (string) - Required - The provider key.
```

--------------------------------

### Change Sender Number

Source: https://github.com/amyavari/iran-sms-laravel/blob/main/README.md

Override the default SMS_FROM configuration at runtime.

```php
$sms->from(string $from);
```
Tokens:
Raw