README

概述

MTN API SDK 提供了与 MTN 短信服务 (SMS) API 交互的 PHP 封装。此 SDK 简化了发送短信、管理订阅和处理异常的过程。

安装

您可以通过 Composer 安装 MTN API SDK。在您的项目目录中运行以下命令

composer mtn-sms/mtn-bulksms-php-sdk

用法

1. 获取访问令牌

在使用 SDK 之前，您需要使用提供的客户端凭证 OAuth 流获取访问令牌。您可以通过向令牌 URL 发送 POST 请求并使用客户端凭证来完成此操作。

use MtnApiSdk\AccessToken;

$accessToken = AccessToken::getAccessToken($clientId, $clientSecret);

将 $clientId 和 $clientSecret 替换为您的实际客户端凭证。

2. 发送短信

要发送短信，请使用 SmsSender 类。

use MtnApiSdk\SmsSender;

$senderAddress = "MTN";
$receiverAddress = ["23423456789", "23423456790"];
$message = "Hello from MTN API SDK";
$clientCorrelatorId = "123456";
$serviceCode = "11221";
$requestDeliveryReceipt = false;

$response = SmsSender::sendSms($accessToken, $senderAddress, $receiverAddress, $message, $clientCorrelatorId, $serviceCode, $requestDeliveryReceipt);

// Handle response
print_r($response);

3. 管理订阅

您可以使用 SubscriptionManager 类来管理订阅。

3.1 订阅

use MtnApiSdk\SubscriptionManager;

$callbackUrl = "https://example.com/callback";
$targetSystem = "YourSystem";
$serviceCode = "11221";

$response = SubscriptionManager::subscribe($accessToken, $callbackUrl, $targetSystem, $serviceCode);

// Handle response
print_r($response);

3.2 更新订阅

use MtnApiSdk\SubscriptionManager;

$subscriptionId = "your-subscription-id";
$body = [
    'serviceCode' => '11221',
    'callbackUrl' => 'https://example.com/callback',
    'deliveryReportUrl' => 'https://example.com/delivery-report',
    'targetSystem' => 'YourSystem'
];

$response = SubscriptionManager::updateSubscription($accessToken, $subscriptionId, $body);

// Handle response
print_r($response);

3.3 删除订阅

use MtnApiSdk\SubscriptionManager;

$subscriptionId = "your-subscription-id";

$response = SubscriptionManager::deleteSubscription($accessToken, $subscriptionId);

// Handle response
print_r($response);

4. 处理异常

在出现错误的情况下，SDK 会抛出 ApiException。您可以像以下这样捕获和处理这些异常

use MtnApiSdk\ApiException;

try {
    // Code that may throw an exception
} catch (ApiException $e) {
    // Handle API exception
    echo "Error occurred: " . $e->getMessage();
}

添加凭证

您应安全地存储您的客户端凭证。建议使用环境变量或配置文件来存储敏感信息。

使用环境变量

您可以在 .env 文件中设置环境变量

MTN_CLIENT_ID=your-client-id
MTN_CLIENT_SECRET=your-client-secret

然后，您可以在代码中访问这些变量

$clientId = getenv('MTN_CLIENT_ID');
$clientSecret = getenv('MTN_CLIENT_SECRET');

使用配置文件

您可以将凭证存储在配置文件中（例如，config.php）

<?php

return [
    'clientId' => 'your-client-id',
    'clientSecret' => 'your-client-secret'
];

然后，将此文件包含在您的代码中

$config = include('config.php');
$clientId = $config['clientId'];
$clientSecret = $config['clientSecret'];

示例测试

以下是一个示例脚本，演示了如何使用 MTN API SDK 发送短信

<?php

require_once 'vendor/autoload.php';

use MtnApiSdk\AccessToken;
use MtnApiSdk\SmsSender;
use MtnApiSdk\ApiException;

// Replace these values with your actual credentials
$clientId = getenv('MTN_CLIENT_ID');
$clientSecret = getenv('MTN_CLIENT_SECRET');

// Obtain access token
$accessToken = AccessToken::getAccessToken($clientId, $clientSecret);

// SMS details
$senderAddress = "MTN";
$receiverAddress = ["23423456789", "23423456790"];
$message = "Hello from MTN API SDK";
$clientCorrelatorId = "123456";
$serviceCode = "11221";
$requestDeliveryReceipt = false;

try {
    // Send SMS
    $response = SmsSender::sendSms($accessToken, $senderAddress, $receiverAddress, $message, $clientCorrelatorId, $serviceCode, $requestDeliveryReceipt);

    // Handle response
    print_r($response);
} catch (ApiException $e) {
    // Handle API exception
    echo "Error occurred: " . $e->getMessage();
}

请确保将 your-client-id 和 your-client-secret 替换为您的实际 MTN 客户端凭证。此外，请确保您已设置环境变量或配置文件以安全地存储凭证。

要测试此示例

1. 将脚本保存到文件中（例如，send_sms_example.php）。
2. 通过环境变量或配置文件设置客户端凭证。
3. 使用 PHP 运行脚本

php send_sms_example.php

此脚本将获取访问令牌，使用 MTN API SDK 发送短信，并打印响应或处理过程中发生的任何异常。根据您的用例调整短信细节和错误处理。

贡献

欢迎贡献！如果您发现任何问题或对改进有建议，请创建一个 pull request 或在 GitHub 上打开一个问题。

许可

此 SDK 是开源的，可在 MIT 许可证下使用。有关详细信息，请参阅 LICENSE 文件。