README

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

安装

您只需要通过Composer引入它

$ composer require isaadsalman/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)

Mobilys的API具有特定数量的功能，每个功能在这个库中都被表示为 request。每个请求都有自己的类，您可以直接调用它。因此，您不必通过 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();

响应

您发出的每个 request 都返回 Response 类的一个实例，该类提供以下功能

object(): 这是一个 Guzzle HTTP 响应实例。
raw(): 返回请求的原始响应体。
result()：返回请求结果。这是什么？嗯，每个请求都会返回一个代表请求结果的数值代码。要获取这个数值，可以使用raw()，但使用result()你会得到一个代码，如：“连接失败”、“消息已发送”、“信用不足”等。每个请求都有自己的响应代码集，这些代码可以在请求类中找到。

示例

  $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：[可选] 取消/删除计划消息需要此消息的“删除密钥”，这是您传递此密钥的地方。默认情况下，也会使用消息ID。

Requests\SendSMS类具有以下方法

sent()：(布尔值) 如果消息成功发送和投递，则返回true。
timeTillSending()：(DateInterval) 如果消息计划稍后发送，此方法返回现在与消息发送时间之间的时间差。
getMessageId()：返回消息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

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

isaadsalman / mobily-sms-api

维护者

详细信息