saythanks / laravel-apex
SMS Portal Notification Channel for Apex in Laravel
Requires
- php: >=8.2
- illuminate/contracts: >=10.0
- illuminate/http: >=10.0
- illuminate/notifications: >=10.0
- illuminate/support: >=10.0
Requires (Dev)
- larastan/larastan: ^2.0 || ^3.0
- laravel/pint: ^1.14
- nunomaduro/collision: ^7.0 || ^8.0
- orchestra/testbench: ^9.0 || ^10.0
- pestphp/pest: ^2.0 || ^3.0
- pestphp/pest-plugin-arch: ^2.0 || ^3.0
- pestphp/pest-plugin-laravel: ^2.0 || ^3.0
- phpstan/extension-installer: ^1.4
- phpstan/phpstan-deprecation-rules: ^1.0 || ^2.0
- phpstan/phpstan-phpunit: ^1.0 || ^2.0
- spatie/laravel-ray: ^1.35
README
Send SMS notifications in Laravel powered by Apex Messaging. This package provides an easy-to-use notification channel for Laravel that integrates with the Apex Messaging API.
Installation
You can install the package via composer:
composer require saythanks/laravel-apex
The package will automatically register its service provider.
Configuration
You can publish the config file with:
php artisan vendor:publish --tag="laravel-apex-config"
Environment Variables
Add the following variables to your .env
file:
# Required Settings
APEX_API_TOKEN=your_api_token_here # Your Apex API token
APEX_SOURCE_ADDRESS=YOUR_SENDER_ID # Sender ID/From name
# Optional Settings with defaults
APEX_HOST=https://papi.apex-messaging.com/ # API endpoint (default shown)
APEX_MESSAGE_TYPE=1 # 1=Promotional, 2=Transactional, 3=OTP (default: 1)
APEX_MESSAGE_ENCODING=0 # 0=GSM, 1=ASCII, 8=UCS2 (Unicode) (default: 0)
APEX_CALLBACK_URL=https://your-domain.com/webhook # URL for delivery reports
APEX_DELIVERY_ENABLED=true # Enable/disable delivery reports
APEX_STORE_CACHE_ENABLED=false # Store message details in cache
APEX_STORE_CACHE_TTL=86400 # Cache TTL in seconds (24 hours)
Usage
Setting up your Notifiable Model
Add a routeNotificationForApex
method to your notifiable class:
public function routeNotificationForApex($notification)
{
return $this->phone_number; // Return the phone number to receive SMS
}
If you don't implement this method, the package will fall back to routeNotificationForSms
.
Creating Notifications
<?php
namespace App\Notifications;
use Illuminate\Notifications\Notification;
use LaravelApex\Messages\ApexMessage;
use LaravelApex\Enums\MessageType;
class AccountActivated extends Notification
{
public function via($notifiable)
{
return ['apex']; // Use the Apex channel
}
public function toApex($notifiable)
{
return (new ApexMessage("This is an example message!"))
->messageType(MessageType::TRANSACTIONAL)
->userReferenceId('account-'.$notifiable->id);
}
}
Available Message Methods
content($text)
: Set the message contentmessageType($type)
: Set the message type (1=Promotional, 2=Transactional, 3=OTP)messageEncoding($encoding)
: Set the message encoding (0=GSM, 1=ASCII, etc.)callbackUrl($url)
: Set a callback URL for delivery reportsuserReferenceId($id)
: Set a custom reference ID for tracking
Integration with Website Project
Setup as a Channel Option
To use Apex in your main application:
Publish the config file to your project:
php artisan vendor:publish --tag="laravel-apex-config"
Add the required environment variables to your
.env
file (see Environment Variables section above).Configure your notifiable models and create your notifications. ], ],
Tracking Delivery Reports
The application using this package should implement its own webhook handling for delivery reports. Configure the callback URL in your environment settings:
APEX_CALLBACK_URL=https://your-domain.com/api/webhooks/apex/delivery-report
Implement a controller in your application to process the delivery reports and update your database accordingly.
Data Encoding Values
Code | Encoding |
---|---|
0 | Default (GSM) |
1 | ASCII |
2 | Octet |
3 | Latin1 |
4 | Octet Unspecified |
6 | Cyrillic |
7 | Latin Hebrew |
8 | UCS2 |
Message Types
Code | Type |
---|---|
1 | Promotional |
2 | Transactional |
3 | OTP |
Testing
composer test
Changelog
Please see CHANGELOG for more information on what has changed recently.
License
The MIT License (MIT). Please see License File for more information.
TODO
- Add HLR when details are available