README

This is a simple implementation of bulk sms for Codeigniter4 for Hostpinnacle in Kenya. This library includes functionality to send single or batch messages.

Composer Installation

You can install the package via composer:

composer require eddieodira/messager

Initial Setup

To start using the Bulk SMS library in your CodeIgniter 4 project, there are a few setup steps you need to complete so the package integrates smoothly with your app:

1. Run the following command. This command handles steps 1(a), 1(b) and 1(c) of the steps below.

     php spark bulksms:publish

   Config Setup: Copy the Bulksms.php from vendor/odiraeddie/src/Config/ into your project's config folder and update the namespace to Config. You will also need to have these classes extend the original classes. These files contain all the settings that you will need to be modified to meet the needs of your site.

   Helper Setup: The setting helpers need to be included in almost every page. The simplest way to do this is to add it to the app/Config/Autoload.php.

   Migration: Run the migrations.

     php spark migrate --all

2. Update Validation Rules Add your custom rules to:

     app/Config/Validation.php

     public array $ruleSets = [
       Rules::class,
       FormatRules::class,
       FileRules::class,
       CreditCardRules::class,
       \Eddieodira\Messager\Validation\TemplateRules::class, // Bulk SMS rules goes here
   ];

Registration

To use this library you need create an account with Hostpinnacle (https://www.hostpinnacle.co.ke). They will help to create account from which you will get the following credentials:

1. API End Point
2. User ID
3. Password
4. API Key
5. Sender ID

Configuration

Inside the class, set the values provided by your SMS gateway:

<?php

declare(strict_types=1);

namespace Eddieodira\Messager\Config;

use CodeIgniter\Config\BaseConfig;

class Bulksms extends BaseConfig
{
    /**
     * Here you can set the connection that the email Teemplate should use when
     * storing and restoring a cart.
     */
    public string $emailTemplateTable = 'email_templates';

    /**
     * Here you can set the connection that the shoppingcart should use when
     * storing and restoring a cart.
    */
    public string $smsTemplateTable = 'sms_templates';

    /**
    * Unique identifier assigned to your HostPinnacle account.
    * Often required for authentication alongside password or API key.
    */
    public string $userId = 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx';

    /**
     * Secret password linked to your HostPinnacle account.
     * Used for authentication in some API endpoints. 
     * Should always be stored securely (e.g., in .env, not hardcoded).
     */
    public string $password = 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx';

    /**
     * API key generated by HostPinnacle for secure access to their SMS API.
     * This is the primary credential used to authorize requests.
     * Keep this private and never expose it in client-side code.
     */
    public string $apiKey = 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx';

    /**
     * Sender ID that appears as the "from" field when recipients receive SMS.
     * It can be a name, brand, or shortcode registered with HostPinnacle.
     * Helps recipients identify the sender of the message.
     */
    public string $senderId = 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx';

    /**
     * Base URL of HostPinnacle’s SMS API.
     * All requests (send, bulk, balance, etc.) will be appended to this root URL.
     * Centralizing it here makes the library easier to maintain if the endpoint changes.
     */
    public string $baseUrl = 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx';

    /**
     * Maximum time (in seconds) to wait for the entire request to complete.
     * If the API takes longer than this, the request will fail.
     * Helps prevent hanging requests in production.
     */
    public int $timeout = 10;

    /**
     * Maximum time (in seconds) to wait for the initial connection to the API server.
     * If the server cannot be reached within this time, the request will fail.
     * Useful for failing fast when the API endpoint is down.
     */
    public int $connectTimeout = 5;

    /**
     * Whether to verify SSL certificates when making requests.
     * Enabled in production for security, but automatically disabled in development
     * to allow local testing with self-signed certificates.
     */
    public bool $verify = (ENVIRONMENT !== 'development');

    /**
     * Whether HTTP errors (4xx/5xx) should throw exceptions automatically.
     * Disabled here so the library can handle errors manually and return
     * standardized responses instead of breaking execution.
     */
    public bool $httpErrors = false;

    /**
     * Whether to enable verbose debugging output for requests.
     * Enabled only in development mode to log request/response details
     * for troubleshooting, but disabled in production for performance and security.
     */
    public bool $debug = (ENVIRONMENT === 'development');

}

Usage

Example how to load library

// Via services 1
$bulksms = \Eddieodira\Messager\Config\Services::bulksms(); 
$bulksms->send(...);

//Or
use Eddieodira\Messager\Config\Services;
$bulksms = Services::bulksms();
$bulksms->send(...);

// Via services 2
$bulksms = service('bulksms');
$bulksms->send(...);

// Traditional way
$bulksms = new \Eddieodira\Messager\Bulksms();
$bulksms->send(...);

//Or
use Eddieodira\Messager\Bulksms;
$bulksms = new Bulksms();
$bulksms->send(...);

// Statically as
use Eddieodira\Messager\Facades\Bulksms;

Bulksms::send(...);

The Codeigniter4 Bulk SMS Library gives you the following methods to use:

Bulksms::send(...)

use Eddieodira\Messager\Bulksms;

$bulksms = new Bulksms();
$bulksms->send('2547xxxxxxxx', 'Hello, I am just testing this applications');

Send one message to more than one number:

use Eddieodira\Messager\Bulksms;

$bulksms = new Bulksms();
$bulksms->send(['25472xxxxxxx, 25475xxxxxxx, 25476xxxxxxx'], 'Hello, I am just testing this applications');

Schedule Bulk Messages

In order to send schedule messages, add a third argument on the method send() $bulksms->send('2547xxxxxxxx', 'Hello, I am just testing this applications', '2026-04-25 09:46:00'); , with date and time as the argument:

use Eddieodira\Messager\Bulksms;

$bulksms = new Bulksms();
$bulksms->send(['25472xxxxxxx, 25475xxxxxxx, 25476xxxxxxx'], 'Hello, I am just testing this applications', '2026-04-25 09:46:00');

Template SMS with Dynamic Placeholders (Optional)

SMS templates are now stored in the database. • Templates can include dynamic placeholders like {name} or {name:User}. • Placeholders are automatically validated and replaced with runtime values. • Defaults can be defined inside placeholders (e.g., uses “User” if no name is provided in {name:User}). • This makes bulk messaging more flexible and professional, allowing you to reuse and personalize messages without hardcoding text.

  use Eddieodira\Messager\Bulksms;

  $bulksms = new Bulksms();
  $sms = $bulksms->render('fees_increase', [
      'name'          => 'John Doe',
      'contact'       => 'Jane Doe',
      'organisation'  => '....' //Name of Organisation goes here
  ]);
  $bulksms->send(['254715070754', '254707362220'], $sms);

Extracting Placeholders

To know the placeholders in a particular sms template, do the follwing:

  use Eddieodira\Messager\Bulksms;

  $bulksms = new Bulksms();
  $extractedPlaceholders = $bulksms->extractPlaceholders('fees_increase');

Here the string argument 'fees_increase' is the template code. This is found in the database table. It give the list in array form including any default value given or null if no default is specified.

  array (size=3)
  'name'          => string 'User' (length=4)
  'contact'       => string 'Representative' (length=14)
  'organisation'  => null

Other methods: Add SMS Template with Placeholders

  use Eddieodira\Messager\Bulksms;

  $bulksms = new Bulksms();
  $bulksms->create(["code" => ..., "name" => ..., "content" => ...]);

Update SMS Template with Placeholders

  use Eddieodira\Messager\Bulksms;

  $bulksms = new Bulksms();
  $bulksms->update(["code" => ..., "name" => ..., "content" => ...], 2);

Find ALL SMS Template

  use Eddieodira\Messager\Bulksms;

  $bulksms = new Bulksms();
  $sms = $bulksms->findTemplates();

Find 1 SMS Template by ID

  use Eddieodira\Messager\Bulksms;

  $bulksms = new Bulksms();
  $sms = $bulksms->findTemplate(1);

Find 1 SMS Template by any other column

  use Eddieodira\Messager\Bulksms;

  $bulksms = new Bulksms();
  $sms = $bulksms->findByWhere('column', value);

Contact

Please open an issue on GitHub if you have any problems or suggestions or you can contact me on +254707362220 or okumuvion@gmail.com.

License

I have released the contents of this repository under the MIT license.