SMS plugins

Contents...

SMS plugins are used for the integration with fast messaging services. Those are usually SMS providers but they may also send messages via online messengers or even save messages somewhere as files for certain purposes.

The messaging provider connection credentials are entered by a user in the account’s system settings. One standard field for that is always available for any SMS plugin, which is used to enter a sender ID. Each plugin may also add custom extra fields if necessary.

The main part of the SMS plugin development is the implementation of method send() in its main PHP class, which must send exactly one message. The main plugin class must extend system class waSMSAdapter.

<?php

class mySMS extends waSMSAdapter
{
    public function send ($to, $text, $from = null)
    {
        // here must be implemented the sending of a message $text
        // to a recipient with phone number $to
        // by optionally specifying a sender $from, if available
    }
}

File structure

SMS plugin source files must reside within the framework’s subdirectory wa-plugins/sms/[plugin_id]/, where [plugin_id] stands for a plugin identifier.

Below is shown a basic file structure of an SMS plugin:

Yo can quickly create a prototype of a new SMS plugin using console command createSystemplugin. An example of creating a plugin with the identifier my:

php wa.php createSystemplugin sms my

Main plugin class methods

  • send

    Sends a message.

  • getControls

    Defines plugin’s custom settings fields.

public function send ($to, $text, $from = null)

Sends a message. For sending requests to a provider server, it is advisable to use the waNet class.

Parameters

  • $to

    Recipient phone number.

  • $text

    Message text.

  • $from

    Optional sender name.

public function getControls()

Defines plugin’s custom settings fields as an array. Each array item must be a subarray with the following keys:

  • title: Localized field name.
  • description: Optional field description.
  • control_type: Optional field type, supported by waHtmlControl class, from the list below:
    • waHtmlControl::INPUT (default type): one-line text field,
    • waHtmlControl::TEXTAREA: multi-line text field,
    • waHtmlControl::CHECKBOX: checkbox.

Example

public function getControls()
{
    return [
        'api_id' => [
            'title'=> 'api_id',
            'description' => 'The <em>api_id</em> value from your personal account on the provider’s website.',
            // you may skip specifying default type waHtmlControl::INPUT
            // 'control_type' => waHtmlControl::INPUT,
        ],
        'api_key' => [
            'title'=> 'api_key',
            'description' => 'A <em>api_key</em> key from your personal account on the provider’s website.',
            'control_type' => waHtmlControl::TEXTAREA,
        ],
        'use_custom_sender' => [
            'title'=> 'Custom sender name',
            'description' => 'Whether a custom sender name must be used, which can be set up in your personal account on the provider’s website.',
            'control_type' => waHtmlControl::CHECKBOX,
        ],
    ];
}