Download the PHP package parables/arkesel-sdk without Composer

Arkesel SDK

Contents

• Arkesel SDK
  • Contents
  • About
  • Features
  • Installation
    • Setting up the Arkesel service
  • Usage
    • Bulk SMS
      • Notifications to the arkesel channel
      • SMS Recipients
    • Composing SMS
    • Available methods
      • ArkeselMessageBuilder)
      • ArkeselSms
  • FAQ
    • ArkeselChannel
  • Changelog
  • Testing
  • Security
  • Contributing
  • Credits
  • License

About

This is an unofficial SDK for Arkesel which is a wrapper around [Arkesel API] for PHP and Laravel applications.

Features

• [x] Bulk SMS
• [ ] Payment
• [ ] Voice
• [ ] Email
• [ ] USSD

This SDK includes a Laravel Notification channel that makes it possible to send out Laravel notifications as a SMS using Arkesel API

Installation

You can install this package via composer:

The service provider gets loaded automatically.

Then publish the config file

Setting up the Arkesel service

First, create Sign up for an account. You will be taken to your SMS Dashboard where you can find the SMS API keys.

Then add your API key to the .env file

The following env variables can be used to customize the package. Refer to the Arkesel Docs for more info

Usage

Bulk SMS

Notifications to the arkesel channel

Create a notification class. Refer to Laravel's documentation on Notifications.

1. Add the Notifiable trait to your model

2. Create a Notification

   Then specify the channel with the via() method and the message to be sent using the toArkesel($notifiable) method

3. Send the notification

• Option 1: using the notify() method that is provided by the Notifiable trait

• Option 2: using the Notification Facade

• Option 3: On demand notification using the Notification's facade route method

SMS Recipients

For on-demand notifications, recipients are directly passed to the Notification::route method.

For all other cases, it is highly recommend to be explicit about specifying the recipients of your notification using the recipients() method on the ArkeselMessageBuilder instance or ArkeselSms instance/facade/helper function

However, you may want to return a string as the sms message for the toArkesel($notifiable) method.

In such cases, please make sure to define a routeNotificationForArkesel($notification) method which will receive the Notification instance $notification being sent on your notifiable class and return a comma-separated string or an array of string of phone numbers.

This ensures that the package doesn't attempt to figure out the recipients.

If a routeNotificationForArkesel($notification) method is not defined in your notifiable class, this package will attempt to get the recipients using any of these methods or properties defined on the notifiable class in the following order of preference.

TL'DR: it prefers:

1. a plural method over a singular method
2. a plural property over a singular property
3. a camelCased property over a snake_case property

with these specific names: routeNotificationForArkesel, recipients, recipient, phoneNumbers, phone_numbers, phoneNumber, phone_number

Under the hood, it uses the code snippets below to decide how to get the recipients:

This is the order of preference to get the recipients:

Notice that all the methods above receives the Notification instance $notification being sent.

If there is none of these methods or properties is defined, it will throw an exception: ArkeselSmsBuilderException: 'No recipients were specified for this sms'

Composing SMS

You can fluently compose the SMS by chaining the setter methods exposed by the ArkeselMessageBuilder;

Available methods

ArkeselMessageBuilder

• message(string $message): self

  set the message to be sent.

• getMessage(): string

  get the sms message to be sent

• sender(string $sender): self

  set the name or number that identifies the sender of an SMS message.

• getSender(): null|string

  get the name or number that identifies the sender of the SMS message.

• recipients(string|array $recipients):self

  set the phone numbers to receive the sms.

  This method will trim empty strings and filter out unique recipients

• getRecipients(string $apiVersion = 'v2'): string|array

  get the phone numbers to receive the sms.

  returns a comma-separated string for SMS API version v1 and array of strings for v2

• schedule(string|Carbon $schedule): self

  set/schedule when the message should be sent.

  refer https://carbon.nesbot.com/docs/ for more information

• getSchedule(string $apiVersion = 'v2'): null|string

  get when the message should be sent for the SMS API version specified.

• callbackUrl(string $callbackUrl): self

  set a URL that will be called to notify you about the status of the message to a particular number.

• getCallbackUrl(): null|string

  set a URL that will be called to notify you about the status of the message to a particular number.

• sandbox(bool $sandbox = true): self

  set the environment for sending sms. if true, sms messages are not forwarded to the mobile network providers for delivery hence you are not billed for the operation. Use this to test your application.

• getSandbox()

  Get the SMS environment mode

• smsApiKey(string $apiKey): self

  sets the API key to used to authenticate the request.

  Overrides the API key set in the .env file.

• getSmsApiKey(): null|string

  get arkesel SMS API Key to use for this request.

• smsApiVersion(string $smsApiVersion = 'v2'): self

  sets the SMS API Version to use for this request

  Overrides the ARKESEL_SMS_API_VERSION set in the .env file.

• getSmsApiVersion(): null|string

  Get arkesel SMS API version to use for this request.

ArkeselSms

The ArkeselSms class it used to send the SMS and get the SMS balance.

• make(ArkeselMessageBuilder $builder): self

  Must be called first when using the ArkeselSms as a facade

• send(): array

  sends the sms to the recipients

• static getSmsBalance(string $smsApiVersion = null, string $smsApiKey = null): array

  get the sms balance

FAQ

• Send SMS in sandbox mode

  By default, the SDK sends SMS with the sandbox mode is set to false. You have to be explicit if you prefer to send sms in sandbox mode by calling the sandbox() or sandbox(true) setter method

ArkeselChannel

The ArkeselChannel class exposes the send methods to send notifications.

• send($notifiable, Notification $notification): array

  Sends the given notification through ArkeselSms.

Changelog

Please see CHANGELOG for more information what has changed recently.

Testing

Security

If you discover any security related issues, please email [email protected] instead of using the issue tracker.

Contributing

Please see CONTRIBUTING for details.

Credits

• Parables Boltnoel
• All Contributors

License

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