ronaldborla/chikka

使用 Chikka API 发送和接收短信

维护者

详细信息

github.com/ronaldborla/chikka

源代码

问题

安装次数: 1,114

依赖项: 1

建议者: 0

安全性: 0

星标: 8

关注者: 1

分支: 4

开放性问题: 6

2.1.1 2015-06-06 15:44 UTC

Requires

Suggests

MIT 17533afc8c986338e06ff9e05ebcc16b9b5b2026

  • Ronald Borla <ronald.borla.woop@yahoo.com>

smschikkaronaldborla

This package is not auto-updated.

Last update: 2024-09-28 17:59:59 UTC

README

Chikka API PHP SDK (v.2.1.1)

此存储库包含用于 Chikka API 的 PHP SDK。Chikka 是菲律宾本地使用的短信服务。它支持 3 个移动网络：Globe、Smart 和 Sun Cellular。要了解更多关于 API 的信息，请访问 https://api.chikka.com/docs/overview

安装

使用 Composer

在您的 composer.json 文件中添加以下行

"require": {
    "ronaldborla/chikka": "@dev"
},

虽然这是可选的，但此包将自动使用 Guzzle，如果它通过 Composer 包含

通过 Composer 使用 Guzzle

"require": {
    "guzzlehttp/guzzle": "~5.0",
    "ronaldborla/chikka": "@dev"
},

请注意，为了获取最新的错误修复，请使用 "@dev" 而不是稳定版本。未来的稳定版本将提供更新

Laravel 5

要在 Laravel 5 中使用此包，您需要在 /config/app.php 中添加其服务提供程序，在 'providers' 下添加以下行

'providers'=> [
    ...
    'Borla\Chikka\Service',
    ...
],

然后在 'aliases' 下

'aliases'=> [
    ...
    'Chikka'=> 'Borla\Chikka\Support\Facades\Chikka',
    ...
],

配置

要在 Laravel 5 中设置 Chikka 的配置，您需要通过在终端运行以下命令来发布配置（您需要 cd 到您当前项目的根目录）

php artisan vendor:publish

执行上述命令后，将在 '/config/chikka.php' 下创建一个配置文件。该配置文件将包含以下内容

return [
    // Shortcode to use
    'shortcode'=> 'YOUR_SHORTCODE',
    // Client ID
    'client_id'=> 'YOUR_CLIENT_ID',
    // Secret key
    'secret_key'=> 'YOUR_SECRET_KEY',
];

您需要根据您的 Chikka API 账户更改这些设置。如果您还没有 Chikka API 的账户，您可以在 https://api.chikka.com/ 上注册

用法

发送短信

首先，您需要初始化 Chikka

// Use namespace
use Borla\Chikka\Chikka;

// Require autoload generated by Composer
require('./vendor/autoload.php');

// Set configuration
$config = [
    'shortcode'=> '29290XXXX',
    'client_id'=> 'YOUR_CLIENT_ID',
    'secret_key'=> 'YOUR_SECRET_KEY',
];

// Create Chikka object
$chikka = new Chikka($config);

当您已经创建了一个 Chikka 对象后，您可以使用 send() 发送短信

// Mobile number of receiver and message to send
$mobile = '09081234567';
$message = 'Hello world';

// Send SMS
$chikka->send($mobile, $message);

稍后，您可能需要追踪您刚刚发送的消息。您需要检索消息的 ID。上面的代码发送的 \Borla\Chikka\Models\Message 对象将自动附加到 send() 函数返回的 \Borla\Chikka\Models\Response 对象。因此，要检索消息 ID，您可以执行以下操作

$mobile = '09081234567';
$message = 'Hello world';

// Send SMS and retrieve response
$response = $chikka->send($mobile, $message);

// Get message id
$messageId = $response->attachments->message->id;

Chikka API 在发送短信时自然需要唯一的 32 位 message_id，但此包会自动为您创建它。如果您需要指定自己的消息 ID，您可以在调用 send() 函数时传递第三个参数

$mobile = '09081234567';
$message = 'Hello world';
$messageId = 'UNIQUE_32-CHARACTER_MESSAGE_ID';

// Send SMS
$chikka->send($mobile, $message, $messageId);

Laravel 5 中的短信发送

请确保您已按照上述安装和配置步骤进行，然后在 Laravel 5 中发送短信将会简单得多。您只需执行以下操作

// Mobile number of receiver and message to send
$mobile = '09081234567';
$message = 'Hello world';

// Send SMS
Chikka::send($mobile, $message);

请注意，您不需要创建 \Borla\Chikka\Chikka 对象的实例。Laravel 会自动为您完成。借助 Facade，您可以通过上面的示例快速访问 Chikka

接收短信

要接收短信，您需要在您的服务器上设置一个接收器 URL，Chikka 将将其用作回调。当您的 Chikka API 账户收到来自手机用户的短信时，Chikka 将通过向您的接收器 URL 发送 POST 数据来通知您。此包将解释您的 PHP 脚本中的 $_POST 变量，并执行必要的步骤以帮助您简化代码

首先，您需要创建一个PHP接收文件。让我们称它为 receiver.php。将其上传到您的服务器，并将其放置在公开可访问的位置。例如：/website.com/public/sms/receiver.php。假设您可以通过 http://website.com/sms/receiver.php 访问此接收器，那么这将是您的接收器URL。接下来，您需要配置您的Chikka API账户设置。请访问您的Chikka API设置页面 https://api.chikka.com/api/settings。在“短信”部分下，点击“编辑”。将接收器URL粘贴到“消息接收器URL”下（您也可以将“通知接收器URL”设置为与“消息接收器URL”相同，但由于我们现在正在设置接收短信，因此可以稍后跳过它）

设置完成后，一旦您的Chikka API账户收到短信，POST数据将转发到此PHP接收器。为了处理此POST数据，使用以下内容编辑您的 receiver.php 文件

// Receive POST data from Chikka
echo $chikka->receive($_POST)
    // Process message
    ->message(function($message) {
        // Do whatever you want to do with the message
        $content = $message->content;
        $sender = $message->mobile;
        // Return true to tell Chikka that you have successfully received the message
        return true;
    });

让我们逐行分析上述代码。在第一行，我们使用 receive() 函数接收数据。在大多数情况下，由于Chikka将消息数据放在POST中，您可以通过PHP的 $_POST 变量访问它。将其作为参数传递给 receive()

此函数将返回一个 \Borla\Chikka\Receiver 实例。该 Receiver 对象将自动检测您的服务器是否刚刚从Chikka接收了一条消息或通知。如果此对象接收了一条消息，您可以通过其 message() 函数调用回调，然后允许您按上述第二行所示处理消息

message() 函数接受一个回调函数作为第一个参数。如果 Receiver 从Chikka接收了一条消息，它将执行您的回调函数，并传递一个包含发送到您的Chikka API账户的消息信息的 \Borla\Chikka\Models\Message 对象。您的回调必须返回 true 以让Chikka知道您已成功接收消息。如果您将其设置为返回 false，那么Chikka将将其视为错误，并将尝试将POST数据最多重发3次到您的接收器URL

您可以通过访问 \Borla\Chikka\Models\Message 对象的 message 或 content 属性（->content 是 ->message 的别名）来获取消息内容。要获取发送者的手机号码，您可以访问 mobile 属性。 ->mobile 返回一个包含关于使用手机号码的信息的 \Borla\Chikka\Models\Mobile 对象（包括国家代码和运营商）

接收和回复短信

您已经了解到，之前讨论的 \Borla\Chikka\Receiver 对象中的 message() 函数接受一个回调函数，并将 \Borla\Chikka\Models\Message 作为第一个参数。它还传递一个 \Borla\Chikka\Sender 对象作为第二个参数。此 Sender 对象负责回复短信。这也是之前在“发送短信”部分中讨论的发送短信的对象

您可以使用 Sender 对象的 reply() 函数来回复一条消息

// Receive POST data from Chikka
echo $chikka->receive($_POST)
    // Process message
    ->message(function($message, $sender) {
        // Get message content first
        $content = $message->content;
        
        // Set new content for replying to message
        $message->content = 'Hello to you, too';
        // Set message id as null (to force the Message object to generate a new message id)
        $message->id = null;
        // Set cost
        $message->cost = 2.50;
        // Send reply
        $response = $sender->reply($message);
        
        // New message id
        $messageId = $response->attachments->message->id;
        // Return true to tell Chikka that you have successfully received the message
        return true;
    });

请注意，我们现在在回调函数中将$sender作为第二个参数。这是我们需要执行的reply()函数的Sender对象。该reply()函数简单地将一个Message对象作为第一个参数。由于传递给回调函数的$message已经包含发送者的手机号码以及Chikka提供的唯一的请求ID，因此Sender对象将知道在哪里发送回复。请注意，根据Chikka API规范，为了识别要回复的消息，您必须提供Chikka随POST数据发送的request_id。此外，您还可以使用->cost设置消息的费用。任何金额都将自动根据手机号码的运营商调整为有效形式。默认情况下，费用为FREE

在Laravel 5中接收和回复短信

您可以通过将其设置为Route来为您的服务器设置接收器URL。在您的/app/Http/routes.php文件中

// Add this to your routes
Route::post('/sms/receiver', 'SmsController@receiver');

现在，上面的路由可以通过http://website.com/sms/receiver访问，您需要在Chikka API设置中进行配置。在您的/app/Http/Controllers/SmsController.php文件中

<?php namespace App\Http\Controllers;

use Controller as BaseController;
use Borla\Chikka\Chikka;
use Input;

class SmsController extends BaseController {

    /**
     * The receiver
     */
    public function receiver() {
        // Return response as string
        return (string) Chikka::receive(Input::all())
            // Receive message
            ->message(array($this, 'processMessage'));
    }
    
    /**
     * Process message
     * @param Borla\Chikka\Models\Message $message The Message object
     * @param Borla\Chikka\Sender $sender The Sender object
     * @return bool
     */
    private function processMessage($message, $sender) {
        // Get message content
        $content = $message->content;
        
        // Set new content for replying to message
        $message->content = 'Hello to you, too';
        // Set message id as null (to force the Message object to generate a new message id)
        $message->id = null;
        // Set cost
        $message->cost = 2.50;
        // Send reply
        $response = $sender->reply($message);
    
        // New message id
        $messageId = $response->attachments->message->id;
        // Return true to tell Chikka that you have successfully received the message
        return true;
    }

}

手机号码格式

从技术上讲，Chikka将接受国际格式的手机号码：639*********（例如：639081234567），但此包会自动解析任何手机号码。因此，您可以输入任何格式的号码（例如：(+63)908-1234-567、09081234567、9081234567、0908-123-4567）。只要它包含有效的手机运营商前缀（Globe、Smart或Sun Cellular），它都会被识别。要获取支持的运营商前缀列表，可以打开位于codes()静态函数下的\Borla\Chikka\Models\Carrier模型。

一旦手机号码被实例化为一个\Borla\Chikka\Models\Mobile对象，则它可以转换为以下任何一种格式

use Borla\Chikka\Models\Mobile;

// Instantiate a Mobile object
$mobile = new Mobile('09081234567');

// Get short format: 9081234567
$short = $mobile->short();

// Get international format: 639081234567
$intl = $mobile->intl();

// Get local format: 09081234567
$local = $mobile->local();

// Get pretty format: (+63) 908-1234567
$pretty = $mobile->pretty();
// Or simply convert to string
$pretty = (string) $mobile;

接收通知

Receiver对象仍然负责以接收消息相同的方式处理来自Chikka的通知。它与message()函数非常相似，但这次使用的是notification()函数。

Receiver对象的notification()函数也接受一个回调函数，其中将作为第一个参数传递一个\Borla\Chikka\Models\Notification对象。

// Receive POST data from Chikka
echo $chikka->receive($_POST)
    // Process notification
    ->notification(function(notification) {
        // Do whatever you want to do with the notification
        // When the message sent failed
        if ($notification->failed()) {
            ...
        }
        // Or when it succeeded
        elseif ($notification->sent()) {
            ...
        }
        // Get credits cost
        $credits = $notification->credits;
        
        // Return true to tell Chikka that you have successfully received the message
        return true;
    });

在Laravel 5中接收通知

由于我们之前已经为接收器设置了Route，我们只需修改SmsController中的receiver()函数，使其能够处理接收到的通知。

    /**
     * The receiver
     */
    public function receiver() {
        // Return response as string
        return (string) Chikka::receive(Input::all())
            // Receive message
            ->message(array($this, 'processMessage'))
            // Receve notification
            ->notification(array($this, 'processNotification'));
    }
    
    ...
    private function processMessage()
    ...
    
    /**
     * Add a new function which can process the notification
     */
    private function processNotification($notification) {
        // Do whatever you want to do with the notification
        // When the message sent failed
        if ($notification->failed()) {
            ...
        }
        // Or when it succeeded
        elseif ($notification->sent()) {
            ...
        }
        // Get credits cost
        $credits = $notification->credits;
        
        // Return true to tell Chikka that you have successfully received the message
        return true;
    }

请注意，我们只在receiver()函数下的message()函数调用之后添加了->notification()调用。这使得接收消息和通知变得更加简单。Receiver对象的message()和notification()函数返回自身，以便进行方法链式调用。