Download the PHP package calisero/laravel-sms without Composer

Laravel SMS Package for Calisero

A first-class Laravel package that wraps the Calisero PHP SDK and provides idiomatic Laravel features for sending SMS messages through the Calisero API. Supports Laravel 12 and Laravel 13.

Features

• 🚀 Laravel 12 & 13 ready with full support for the latest features
• 📱 Easy SMS sending via Facade, Notification channels, or direct client usage
• 🔐 Two-Factor Authentication with verification codes API
• 🔒 Webhook handling with token-based security
• ✅ Validation rules for phone numbers (E.164) and sender IDs
• 🎯 Queue support for reliable message delivery
• 🧪 Artisan commands for testing and development
• 📊 Comprehensive logging and error handling
• 🏗️ PSR-4 compliant with full test coverage

Internal package logging was removed. Add your own logging in event listeners/subscribers.

Requirements

Composer picks the right Laravel release for your PHP version automatically: on PHP 8.2 you get Laravel 12, and on PHP 8.3, 8.4 or 8.5 you can run either Laravel 12 or 13.

Installation

You can install the package via Composer:

Publish the configuration file

Configure your environment

Add your Calisero API credentials to your .env file:

Usage

Quick Start

Sending SMS via Facade

Verification Codes (2FA)

Send and verify one-time codes for two-factor authentication:

Note: Either brand OR template is required when sending verification codes. The template must contain {code} placeholder. Codes are 6 characters and sent via SMS.

Using Notifications

Create a notification class:

Send the notification:

For the notification to work, your User model should implement the routeNotificationForCalisero method:

Using the Direct Client

For more control, inject the client directly:

Validation Rules

Use the included validation rules in your form requests:

Webhook Handling

Enable webhooks by setting CALISERO_WEBHOOK_ENABLED=true. The package will register a POST endpoint at /calisero/webhook (or your configured CALISERO_WEBHOOK_PATH).

Securing the Webhook (Query Token)

If you also set CALISERO_WEBHOOK_TOKEN=your-shared-secret, the package will:

• Automatically append ?token=your-shared-secret to the injected callback_url sent to Calisero (only when you did not supply a custom callback_url).
• Register a middleware that rejects any incoming webhook request not containing the correct token query parameter.

Requirements when token security is enabled:

• Each webhook request from Calisero must include the query parameter token with the exact configured value.
• If you manually override callback_url, you are responsible for including the ?token=... segment yourself.
• If your explicit URL already contains a token= parameter, the library will not modify it.

Environment example:

Example of explicit override (token already present, no modification by the library):

Rotation tip: rotate the token by

1. Adding a temporary second endpoint (optional) or a maintenance window.
2. Updating CALISERO_WEBHOOK_TOKEN.
3. Redeploying and updating the callback URL in Calisero (or sending a new message to propagate the injected URL).

If you leave CALISERO_WEBHOOK_TOKEN empty, no token middleware is attached and the endpoint is publicly accessible (POST only). Consider other controls (IP allow-list, WAF) if you opt out of the token.

Listen for the events:

Statuses currently emitted (lifecycle):

• sent – the message was accepted and dispatched to the network
• delivered – the handset/network confirmed delivery
• failed – delivery permanently failed

Webhook payload example (flat structure):

When the same message is later delivered you will receive another webhook with:

A failed attempt would have "status": "failed" and usually a deliveredAt of null.

Automatic callback_url Injection

If CALISERO_WEBHOOK_ENABLED=true, every sendSms() call without an explicit callback_url (or callbackUrl) automatically includes one pointing to the named route calisero.webhook (if registered) or a URL built from app.url + the configured path.
To override, supply your own callback_url parameter.
To disable injection, set CALISERO_WEBHOOK_ENABLED=false or omit the env variable.

Edge cases:

• If app.url is not set and the route helper fails, a root-relative path like /calisero/webhook is used.
• Passing either callback_url or callbackUrl prevents injection.

Example (override):

Artisan Commands

The package provides several Artisan commands for testing and development:

Test SMS Sending

SMS Status

Verification Commands

Send a verification code with brand:

Send a verification code with custom template:

Check a verification code:

Webhook Verification

Verify webhook signatures offline:

Environment Variables Reference

Advanced Configuration

The configuration file (config/calisero.php) allows you to customize:

• API connection settings (timeouts, retries, backoff)
• Webhook path and middleware
• Logging channel preferences

Sender ID (Alphanumeric) Requirements

Custom alphanumeric sender IDs (the from field) must be pre‑approved by Calisero before they can be used in production traffic. If you send a message with an unapproved sender:

• The API may reject the request (validation / 422).
• Or the gateway may substitute a default system sender / numeric originator.
• Delivery performance and branding can be impacted if you skip approval.

Approval Guidelines:

• Length: 3–11 characters (enforced by the SenderId validation rule).
• Allowed characters: letters, digits, spaces, hyphens (-), dots (.).
• No fully numeric sender IDs unless explicitly provisioned (use phone numbers instead).
• Avoid trademarks you do not own.

How to Request Approval:

1. Log in to your Calisero dashboard (https) and navigate to Sender IDs
2. Submit each desired sender (case‑sensitive) with a brief business justification.
3. Wait for confirmation before deploying to production.

Best Practices:

• Keep a configurable default sender (e.g. via env: CALISERO_DEFAULT_SENDER=) and only override per message when approved.
• In multi‑tenant apps, map tenants to approved sender pools—never accept raw user input as a sender.
• Log or alert when the API response indicates a sender rejection so you can remediate quickly.

Example (with fallback logic):

NOTE: If you do not have an approved sender yet, omit from to let Calisero assign a default.

Credit Monitoring & Balance Alerts

Configure optional balance thresholds to emit events when your Calisero account credit becomes low or critical:

Environment variables:

Events:

• Calisero\\LaravelSms\\Events\\CreditLow (remainingBalance float)
• Calisero\\LaravelSms\\Events\\CreditCritical (remainingBalance float)

Example listener registration:

If a critical threshold is met, only CreditCritical is fired (not CreditLow). Leave variables unset (or null) to disable.

Examples

A curated set of runnable usage examples lives in the examples/ directory:

Quick peek (webhook event handling):

See the Examples README for setup & detailed walkthroughs.

Error Handling

The package provides comprehensive error handling:

Testing

Basic test run:

Quality Assurance (CI / Local)

The project ships with an automated GitHub Actions workflow (.github/workflows/ci.yml) that runs:

• Code Style (PHP CS Fixer) on PHP 8.2, 8.3, 8.4, 8.5
• Static Analysis (PHPStan) on PHP 8.2, 8.3, 8.4, 8.5 against Laravel 12 and 13
• Test Matrix on PHP 8.2, 8.3, 8.4, 8.5 against Laravel 12 and 13 (Laravel 13 is skipped on PHP 8.2, which it does not support)

Local commands:

To test against a specific Laravel version locally:

Notes:

• Running php-cs-fixer on a PHP version newer than the project minimum is allowed via setUnsupportedPhpVersionAllowed() in .php-cs-fixer.php (the older PHP_CS_FIXER_IGNORE_ENV environment variable is deprecated and no longer used).
• PHPUnit configuration uses the modern schema; tests pass with zero deprecations on both Laravel 12 and 13.

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• Calisero Team
• All Contributors

License

The MIT License (MIT). Please see License File for more information.

Links

• Calisero API Documentation
• Calisero PHP SDK
• Laravel Documentation

Calisero Laravel library allows you to send SMSs from your Laravel application using Calisero API