README

Mobily.ws 是海湾地区领先的短信服务提供商，但他们的许多 API 已过时且设计不良。这是他们PHP API客户端的非官方重写，您会发现它更加灵活和更新。

安装

您只需通过Composer要求它

$ composer require tamkeenlms/mobily-sms-api

如何使用

您首先定义一个API "客户端"，您可以定义多个API客户端，并在每个请求中选择要通过哪个客户端进行操作。以下是一个示例

  $client1 = new \MobilyAPI\Client( $username , $password , $paramDefaults, $setup );

新的 MobilyAPI\Client 接受以下参数

username: 您的账户用户名
password: 账户密码
paramDefault:
- "sender": 短信的默认 "发送者" 名称。
- "domainName": 您通过它使用API的应用程序/网站域名。 此字段将自动填充为主机名。
- "applicationType": 此值固定为 "68"（我不知道它是做什么的，但您必须发送它！）
- "lang": 此值也固定为 "3"，它表示请求中使用的编码为UTF-8。
setup
- "base_uri": API基础URI。您无需更改此值。
- "request_time_out": 请求的超时时间，以秒为单位
- "verify_ssl_certificate": (布尔值) 是否省略SSL证书验证。 默认为false

以下是一个示例

  $client1 = new \MobilyAPI\Client('username1', 'password2', ['sender' => 'Tamkeen LMS']);
  $client2 = new \MobilyAPI\Client('username2', 'password2', ['sender' => 'Tamkeen Company']);

请求

通过一个 Client，您可以对API进行 请求。当然，您做出的请求将影响您为客户端选择的账户。以下是一个检查服务/发送状态的请求示例

  // Create the request, under the $client1
  $request = $client1->createRequest('sendingStatus');
  
  // Send the request
  $response = $request->send(); // (Returns a "Response" instance)

Mobily的API具有特定的功能数量，每个功能在此库中都表示为一个 请求。每个请求都有自己的类，您可以直接调用它。因此，您可以直接通过 client 调用一个请求，而不是创建一个新的请求并将客户端传递给它。以下是如何操作

  $serviceStatus = new \MobilyAPI\requests\SendingStatus( $client1 ); // Pass the client instance to the request class
  $response = $serviceStatus->send();

每个请求都有自己的方法集，这些方法是特定于它的。以下是一个示例

  $request = $client1->createRequest('sendingStatus'); // Create
  $request->send(); // Send
  
  var_dump( $request->available() ); // The method "available" returns boolean whether the service is up or not

每个请求都有以下方法

send(): 将请求发送到服务API。
object(): 返回请求对象，该对象是 Guzzle HTTP Request 的实例。
getClient(): 返回您通过它进行请求的 Client。
getParams(): 返回您与请求一起传递的参数数组。
getResponse(): 返回请求的响应，该响应是 Response 的实例。
successful(): (布尔值) 告诉您对服务API的请求是否成功。
failed(): (布尔值)

  $request = $client1->createRequest('sendSMS', ['0123456789'], 'Hi there!');
  
  // The params
  $request->getParams(); // ['numbers' => ['0123456789'], 'message' => 'Hi there!']
  
  // The response
  $request->getResponse()->result(); // "message_sent"
  
  if($request->successful() && $request->sent()){
    // Request made successfully, and the message was sent successfully!
  }

  // The request client
  $request->getClient()->createRequest( ... )

顺便说一下，您可以在一行中完成此操作，如下所示

	(new Client(...))->request('SendSMS', ['0123456789'], 'Beep boop ...');
	
	//Or
	$client2->createRequest('SendingStatus')->getResponse()->available();

响应

您做出的每个 请求 都返回 Response 类的实例，该类提供以下功能

object(): 返回一个 Guzzle HTTP 响应实例。
raw(): 返回请求的原始响应体。
result()：返回请求结果。这是什么？嗯，每个请求都返回一个代表请求结果的数字代码。要获取这个数字值，可以使用raw()，但使用result()你会得到一个代码，例如："connection_failed"、"message_sent"、"not_enough_credit"等等。每个请求都有自己的响应代码集，这些代码可以在请求类内部找到。

示例

  $serviceStatus = new \MobilyAPI\requests\SendingStatus( $client1 );
  $response = $serviceStatus->send(); // Returns the Response
  
  var_dump( $response->result() ); // "available"
  var_dump( $response->raw() ); // "1"
  
  // Guzzle Response object
  $response->object()->getStatusCode(); // "200" for example
  
  // A method available with the request
  $request->available(); // Boolean (Notice using $request not $response)

检查服务状态

  $serviceStatus = new \MobilyAPI\requests\SendingStatus( $client1 );
  $serviceStatus->send();
  
  $serviceStatus->available(); // Available or not

发送新的短信

通过此客户端发送新的短信是通过Requests\SendSMS请求类完成的

  $newSMS = new \MobilyAPI\requests\sendSMS( client, numbers, $message, $time, variableSets, messageId, sender, deletionKey );
  $newSMS->send();
  
  $newSMS->sent() // Boolea, marks whether the message was sent or not

以下是它接受的参数

client：您想要通过它发送短信的Client实例
numbers：(数组) 收件人号码。原始API文档规定，每个号码应采用全球格式，并且没有00或+开头。
message：您想要发送的消息，UTF-8编码。
time：[可选] 如果您想安排稍后发送此消息，请使用。在这里，您应提供您想要安排的时间的有效日期/时间/日期时间格式。您还可以传递Carbon实例（以下为示例）。
variableSets：[可选] 您可以使用此功能向多个收件人发送消息，每个收件人的值不同。这意味着消息将成为一个模板，每个收件人都有他/她的特定值/信息，这些值/信息将嵌入到相关的消息中（以下为示例）。
messageId：[可选] 消息的唯一ID。您真的需要回到官方API的原始文档，并尝试理解它做了什么。但一般来说，它可以锁定在相同小时内向相同号码发送相同消息。如果省略此参数，库将自动传递一个唯一的ID。
sender：[可选] 如果您想为这条消息使用不同的“发件人”名称，否则将使用默认的发件人。
deletionKey：[可选] 取消/删除计划中的消息需要此消息的“deleteKey”，您应在这里传递此键。默认情况下，也会在这里使用消息ID。

Requests\SendSMS类具有以下方法

sent()：(布尔值) 告诉您消息是否已成功发送和交付。
timeTillSending()：(日期间隔) 如果消息计划稍后发送，此方法将返回现在与消息将发送的时间之间的时间差。
getMessageId()：返回消息ID，您选择的ID，或者当然，库为您生成的ID。
getDeletionKey()：返回消息删除键。
cancel()：使用此方法取消计划中的消息

以下是示例

  $client->createRequest('SendSMS', ['0123456789', '9876543210'], 'I AM YOUR FATHER')->send();

稍后安排

  $client->createRequest('SendSMS', ['0123456789'], 'Bazinga', '2016-12-31 00:00:00');
  $client->createRequest('SendSMS', ['0123456789'], 'Stop googling your name!', Carbon::tomorrow()); // Send tomorrow the same time
  $client->createRequest('SendSMS', ['0123456789'], 'Smilly cat, Smilly cat', Carbon::today()->addDays(3)); // 12 AM 3 days from now

您可能想查看Carbon，它非常棒。

您可以通过这种方式取消计划的新消息

  $request = $client->createRequest('SendSMS', ['0123456789'], 'How you doin', '2016-12-31 18:30:00');
  
  $request->send(); // Schedule
  $request->cancel(); // Canel

发送模板消息

  $values = [
    ['name' => 'Michael', 'website' => 'Tamkeenlms.com'],
    ['name' => 'John', 'website' => 'Workflowy.com']
  ];
  
  $client->createRequest('SendSMS', ['0123456789', '9876543210'], 'Hey (name), check (website)', null, $values);

删除计划中的消息

要删除计划中的消息，您需要消息删除键

  $request = $client->createRequest('deleteSMS', ['messageXYZ']);
  $request->deleted(); // (Boolean) Marking whether the message was deleted or not

如果您通过Requests\SendSMS发送消息，可以使用getDeletionKey()获取此消息删除键。示例

  $request = $client->createRequest('SendSMS', ['0123456789'], 'Yo!');
  $request->send();
  
  $messageDeletionKey = $request->getDeletionKey();
  
  // ...
  
  $request2 = $client->createRequest('deleteSMS', [$messageDeletionKey]);

检索您的余额

  $request = $client->createRequest('GetBalance');
  $request->send();
  
  $request->balance(); // ['remaining' => 50, 'total' => 100]
  $request->remaining(); // 50
  $request->total(); // 100
  $request->available(); // (Boolean) Has credit or not

希望这对您有帮助，并且请随时与我们联系，提出任何问题。祝您好运

tamkeenlms / mobily-sms-api

维护者

详细信息