Integrating the `SmsEngine` PHP Library into Your Project using Arkesel SMS API Key.

This article guides you through the steps to integrate and use the provided SmsEngine PHP library for sending SMS messages within your PHP applications. This library seems designed to interact with an SMS gateway, likely Arkesel, given the API URLs present in the code.

Prerequisites:

Before you begin, ensure you have the following:

1. A PHP Environment: You need a working PHP installation (version 7.0 or higher is recommended) on your server or local development machine.
2. Composer (Recommended): While not strictly required for this specific library as it's provided as a single class file, Composer is a dependency management tool for PHP and is highly recommended for managing larger projects.
3. An SMS Gateway Account and API Key: This library requires an API key and API URL from your chosen SMS gateway provider (likely Arkesel). You'll need to sign up for an account with them to obtain these credentials.
4. Basic Understanding of PHP: Familiarity with PHP classes, namespaces, and making HTTP requests will be beneficial.

Step 1: Saving the Library Code

The first step is to save the provided PHP code as a file within your project. A common practice is to create a dedicated directory for your custom libraries or modules.

1. Create a folder named modules (or any other name you prefer) in the root directory of your PHP project.
2. Inside the modules folder, create a new PHP file named SmsEngine.php.
3. Copy and paste the entire code block provided in your query into this SmsEngine.php file.

Step 2: Including the Library in Your Project

Now, you need to include this library in the PHP file where you want to send SMS messages. You can do this using PHP's require or require_once statement.

If you are not using Composer or an autoloader:

require_once 'modules/SmsEngine.php';

// Or, if your file structure is different
// require_once '../modules/SmsEngine.php';

If you are using Composer, you would typically define an autoload rule in your composer.json file to automatically load your custom classes. For example, under the autoload section:

"autoload": {
    "psr-4": {
        "modules\\": "modules/"
    }
}

After adding this, run composer dump-autoload in your project's root directory. Then, you can use the library like this:

require_once 'vendor/autoload.php';

use modules\SmsEngine;

Step 3: Configuring the SmsEngine

To use the SmsEngine, you need to instantiate the class and provide your API key and API URL from your SMS gateway provider.

// Replace with your actual API key and API URL
$apiKey = 'YOUR_API_KEY';
$apiUrl = 'YOUR_SMS_GATEWAY_API_URL';

$smsEngine = new SmsEngine($apiKey, $apiUrl);

Step 4: Setting Sender, Message, and Recipients

Before sending an SMS, you need to define the sender, the message content, and the recipients.

• Setting the Sender:
  

  $smsEngine->sender('MyBusinessName'); // Use your approved sender ID
  

• Setting the Message:
  

  $smsEngine->message('This is a test SMS message sent using the SmsEngine library.');
  

• Adding Recipients: You can add recipients one by one or as an array.
  

  // Adding a single recipient
  $smsEngine->addRecipient('233501234567'); // Example Ghanaian phone number
  
  // Adding multiple recipients
  $recipients = ['233249876543', '233550001111'];
  $smsEngine->recipients($recipients);
  

Step 5: Sending SMS Messages

The SmsEngine provides two main methods for sending messages: execute() for immediate sending and exeSchedule() for scheduling messages.

• Sending Immediately:
  

  try {
      $response = $smsEngine->execute();
      print_r($response); // Output the API response
      if ($response['status'] === 'success') {
          echo "SMS message sent successfully!\n";
      } else {
          echo "SMS message failed: " . $response['message'] . "\n";
      }
  } catch (Exception $e) {
      echo "Error: " . $e->getMessage() . "\n";
  }
  

• Scheduling a Message: To schedule a message, you need to set the scheduledDate before calling exeSchedule(). The format of the date will depend on the requirements of your SMS gateway provider. Consult their documentation for the correct format.
  

  $smsEngine->scheduledDate('2025-03-20 10:00'); // Example date and time
  
  try {
      $response = $smsEngine->exeSchedule();
      print_r($response); // Output the API response
      if ($response['status'] === 'success') {
          echo "SMS message scheduled successfully!\n";
      } else {
          echo "SMS message scheduling failed: " . $response['message'] . "\n";
      }
  } catch (Exception $e) {
      echo "Error: " . $e->getMessage() . "\n";
  }
  

Step 6: Checking Your SMS Balance

The library also provides a method to check your SMS balance:

try {
    $balance = $smsEngine->getBalance();
    print_r($balance); // Output the balance details
    echo "Your current balance is: " . $balance['balance'] . " " . $balance['currency'] . "\n";
} catch (Exception $e) {
    echo "Error fetching balance: " . $e->getMessage() . "\n";
}

Error Handling:

The SmsEngine includes basic error handling. The getBalance() method throws an Exception if the API returns an error status. The send() method checks the HTTP status code and returns an error array if it's not 200. It's important to wrap your API calls in try...catch blocks to gracefully handle potential errors. The library also includes a private getErrorMessage() function to provide more specific error messages based on error codes returned by the SMS gateway.

Example Usage:

Here's a complete example demonstrating how to use the SmsEngine to send an immediate SMS message:

<?php

require_once 'modules/SmsEngine.php';

use modules\SmsEngine;

$apiKey = 'YOUR_API_KEY'; // Replace with your API key
$apiUrl = 'YOUR_SMS_GATEWAY_API_URL'; // Replace with your API URL

$smsEngine = new SmsEngine($apiKey, $apiUrl);
$smsEngine->sender('MyWebApp');
$smsEngine->message('Hello! This is a test message.');
$smsEngine->addRecipient('23350XXXXXXX'); // Replace with a valid recipient number

try {
    $response = $smsEngine->execute();
    print_r($response);
    if ($response['status'] === 'success') {
        echo "SMS sent successfully.\n";
    } else {
        echo "SMS sending failed: " . $response['message'] . "\n";
    }
} catch (Exception $e) {
    echo "Error: " . $e->getMessage() . "\n";
}

?>

Remember to replace 'YOUR_API_KEY', 'YOUR_SMS_GATEWAY_API_URL', and the recipient phone number with your actual credentials and intended recipient.

By following these steps, you should be able to successfully integrate and use the provided SmsEngine PHP library to send SMS messages from your PHP applications. Always refer to your SMS gateway provider's documentation for specific details regarding API endpoints, request parameters, and error codes.