README

Laravel notification channel and API client for the Aruba SMS API Service. See the official API documentation.

Requirements

• PHP ^8.4
• Laravel ^12.0 or ^13.0

Installation

From Packagist (when published)

composer require offline-agency/laravel-aruba-sms

Local development (path repository)

Add to your project's composer.json:

{
    "repositories": [
        {
            "type": "path",
            "url": "packages/offline-agency/laravel-aruba-sms",
            "options": {
                "symlink": true
            }
        }
    ]
}

Then:

composer require offline-agency/laravel-aruba-sms

Publish config

php artisan vendor:publish --tag=aruba-sms-config

Configuration

Copy .env.example or add these to your .env:

# Required
ARUBA_SMS_ID=your_username
ARUBA_SMS_PASSWORD=your_password

# Optional
ARUBA_SMS_SENDER=YourBrand              # Default: YourBrand
ARUBA_SMS_SANDBOX=true                  # Default: false (set true for dev/test)
ARUBA_SMS_MINIMUM_SMS=50                # Low credit threshold
ARUBA_SMS_LOW_CREDIT_RECIPIENTS=admin@example.com,dev@example.com

Usage

Via Notification Channel

Create a notification that uses the aruba-sms channel:

use Illuminate\Notifications\Notification;
use OfflineAgency\ArubaSms\ArubaSmsMessage;

class OrderShippedNotification extends Notification
{
    public function via($notifiable): array
    {
        return ['aruba-sms'];
    }

    public function toArubaSms($notifiable): ArubaSmsMessage
    {
        return (new ArubaSmsMessage())
            ->content("Your order #{$this->order->id} has been shipped")
            ->to($notifiable->phone_number);
    }
}

Using the Built-in Generic Notification

use OfflineAgency\ArubaSms\Notifications\SendSmsNotification;
use Illuminate\Support\Facades\Notification;

// Send to an on-demand notifiable (no User model needed)
Notification::route('aruba-sms', null)
    ->notify(new SendSmsNotification('Your message', '+393331234567'));

// Or send via a notifiable model
$user->notify(new SendSmsNotification('Your message', '+393331234567'));

Direct Client Usage

use OfflineAgency\ArubaSms\ArubaSmsClient;
use OfflineAgency\ArubaSms\ArubaSmsMessage;

$client = app(ArubaSmsClient::class);
$message = new ArubaSmsMessage('Hello!', '+393331234567');
$response = $client->sendMessage($message);

Via Facade

use OfflineAgency\ArubaSms\Facades\ArubaSms;
use OfflineAgency\ArubaSms\ArubaSmsMessage;

// Send a message
$message = new ArubaSmsMessage('Hello!', '+393331234567');
ArubaSms::sendMessage($message);

// Check remaining credits
$response = ArubaSms::checkSmsStatus();

// Get sending history
$response = ArubaSms::getSmsHistory('20260101000001');

Backward Compatibility (Legacy Pattern)

Notifications with public $message, $recipient, $message_type properties work without implementing toArubaSms():

class LegacyNotification extends Notification
{
    public string $message = 'Hello';
    public string $recipient = '+393331234567';
    public string $message_type = 'N';

    public function via($notifiable): array
    {
        return ['aruba-sms'];
    }
}

Artisan Commands

aruba:sms

Manage the Aruba SMS Panel from the command line:

# Check remaining SMS credits
php artisan aruba:sms status

# View sending history
php artisan aruba:sms history --from=20260101000001 --to=20260201000001

# View history for a specific recipient
php artisan aruba:sms recipient-history --recipient=+393331234567 --from=20260101000001

# Send a test SMS
php artisan aruba:sms notification --phoneNumber=+393331234567

# Get raw remaining credit count (for scripting)
php artisan aruba:sms remaining-credit-raw

aruba:check-remaining-sms

Check remaining credits and send email alerts if below threshold:

php artisan aruba:check-remaining-sms

Configure alert recipients via ARUBA_SMS_LOW_CREDIT_RECIPIENTS env variable.

Phone Number Formatting

The package provides a PhoneNumberFormatter utility for Italian phone numbers:

use OfflineAgency\ArubaSms\Support\PhoneNumberFormatter;

// Add +39 prefix and strip spaces
PhoneNumberFormatter::format('333 123 4567');    // '+393331234567'
PhoneNumberFormatter::format('+393331234567');   // '+393331234567' (unchanged)
PhoneNumberFormatter::format('+447911123456');   // '+447911123456' (non-IT preserved)

// Strip spaces only
PhoneNumberFormatter::stripSpaces('+39 333 123 4567'); // '+393331234567'

Sandbox Mode

When ARUBA_SMS_SANDBOX=true, SMS messages are logged to the Laravel log instead of being sent to the Aruba API. This is useful for development and testing:

[2026-02-19 10:30:00] local.INFO: *** Aruba SMS DEBUG ***
[2026-02-19 10:30:00] local.INFO: Notification sent successfully!
[2026-02-19 10:30:00] local.INFO: Recipient: +393331234567
[2026-02-19 10:30:00] local.INFO: Message: Your code is 123456
[2026-02-19 10:30:00] local.INFO: Message Type: N
[2026-02-19 10:30:00] local.INFO: *** *** ***

Testing

composer test              # Run tests
composer test:coverage     # Run with coverage (100% minimum)
composer analyse           # PHPStan level 6
composer format            # Fix code style (Pint)
composer format:check      # Check code style without fixing

All tests use Pest with Http::fake() and never call the real Aruba API.

License

MIT