README

简介

Pushy 是一个 PHP 客户端，使与 Pushover.net 的 API 通信变得简单。

Pushy 充分利用了 Pushover 的 API。这包括发送消息、验证用户和检索消息状态。

想要从您的 Web 应用程序向您的 iOS 或 Android 设备发送实时移动通知吗？请查看 Pushover.net。API 使用免费，并且与 Pushy 一起使用非常简单！

要求

• PHP 5.4+
• cURL 扩展

安装

您可以使用 composer 安装 Pushy。只需将依赖项添加到您的 composer.json 配置中即可。

{
  "require": {
    "sqmk/pushy": "dev-master"
  }
}

有关更多信息，请参阅 composer 和 packagist。

用法

假设您的 composer 生成或自定义的自动加载器可以正确加载 Pushy 文件，使用它很简单！

如果您对完整的 API 感兴趣，您可以在 GitApiDoc 上查看自动生成的文档。

初始化客户端

为了发送消息、验证用户或获取消息状态，您首先需要一个应用程序 API 密钥。您可以在 Pushover.net 上注册一个新的应用程序来获取 API 密钥。

一旦您获得了应用程序密钥，现在您可以实例化一个 Pushy 客户端对象。

// Instantiate a client object with application key
$pushy = new Pushy\Client('KzGDORePK8gMaC0QOYAMyEEuzJnyUi');

发送消息

您已经创建了一个客户端实例，现在您可以发送消息。但首先，您要为接收用户构建一个用户对象。

您需要在 Pushover.net 上获取您的用户标识符（或用户密钥）。如果您想向单个设备发送消息，还需要一个已注册的设备名称。现在，您可以使用这些详细信息创建一个用户对象。

// Instantiate a user object (targets all devices)
$user = new Pushy\User('pQiRzpo4DXghDmr9QzzfQu27cmVRsG');

// Alternatively, instantiate a user object with a targeted device
$user = new Pushy\User('pQiRzpo4DXghDmr9QzzfQu27cmVRsG', 'droid2');

// Setting properties by chaining is also possible
$user = (new Pushy\User('pQiRzpo4DXghDmr9QzzfQu27cmVRsG'))
  ->setDeviceName('droid2');

创建用户后，您就有足够的信息开始创建消息。

// Instantiate a message object with a message body
$message = new Pushy\Message('Your message body');

// Set the recipient of the message
$message->setUser($user);

// Set the title
$message->setTitle('You message title');

// Set a priority (defaults to NormalPriority)
$message->setPriority(
  new Pushy\Priority\LowPriority
);

// Set a sound (defaults to PushoverSound)
$message->setSound(
  new Pushy\Sound\AlienSound
);

// Set a supplementary URL and title
$message->setUrl(
  'http://example.org'
);

$message->setUrlTitle(
  'Example.org'
);

// Set a custom sent timestamp
$message->setTimestamp(1369111110);

// All methods above are chainable
$message = (new Pushy\Message)
  ->setMessage('Your message body')
  ->setTitle('Your message title')
  ->setUser($user);

要发送消息，请将消息对象传递给客户端。

// Send the previous created message
$pushy->sendMessage($message);

如果没有抛出异常，则表示消息已成功发送。sendMessage 方法不会返回数据，除非消息具有紧急优先级。

紧急优先级消息

您可以使用紧急优先级发送消息并获取收据 ID。紧急优先级还有其他选项。

// Create a message with emergency priority
$message = (new Pushy\Message)
  ->setMessage('Important message')
  ->setTitle('Important subject')
  ->setUser($user)
  ->setPriority(
    (new Pushy\Priority\EmergencyPriority)
      // Resend message to user every X seconds
      ->setRetry(30)
      // Expire message after X seconds
      ->setExpire(3600)
      // Set callback URL to hit when user acknowledges message
      ->setCallback('http://example.org/api')
  );

// Send message and get receipt id
$receiptId = $pushy->sendMessage($message);

使用收据 ID，您可以取消具有紧急优先级的消息

$pushy->cancelEmergency($receiptId);

优先级

Pushy\Priority 中可用的优先级列表

• LowestPriority
• LowPriority
• NormalPriority（默认值）
• HighPriority
• EmergencyPriority

声音

Pushy\Sound 中可用的声音列表

• AlienSound
• BikeSound
• BugleSound
• CashregisterSound
• ClassicalSound
• ClimbSound
• CosmicSound
• EchoSound
• FallingSound
• GamelanSound
• IncomingSound
• IntermissionSound
• MagicSound
• MechanicalSound
• NoSound
• PersistentSound
• PianobarSound
• PushoverSound（默认值）
• SirenSound
• TugboatSound
• 上下文音效

验证用户

在发送消息之前，可以使用Pushover对用户对象进行验证。

// Pass previous instantiated user object to the client
try {
  $pushy->verifyUser($user);
  
  echo 'User is valid';
} catch (Pushy\Transport\Exception\ApiException $e) {
  echo 'User is not valid';
}

获取消息状态

在使用紧急优先级发送消息时，成功发送消息后，您将获得一个收据代码。您可以通过发送收据代码通过getMessageStatus来获取消息的状态。

// Get message with the receipt code
$messageStatus = $pushy->getMessageStatus($receiptCode);

// Was the message acknowledged? (true or false)
$messageStatus->isAcknowledged();

// When the message was acknowledged (DateTime or null)
$messageStatus->acknowledgedAt();

// When the message was last delivered (DateTime or null)
$messageStatus->lastDeliveredAt();

// Is the message expired? (true or false)
$messageStatus->isExpired();

// When the message expired (DateTime or null)
$messageStatus->expiresAt();

// Has Pushover contacted the callback URL? (true or false)
$messageStatus->hasCalledBack();

// When Pushover contacted the callback URL (DateTime or null)
$messageStatus->calledBackAt();

获取应用程序限制

Pushover.net允许您为每个您拥有的应用程序每月发送7,500条消息。超过该限制将导致服务拒绝请求。

Pushy在客户端提供了3个方便的方法来检索您应用程序的消息限制、剩余消息以及限制重置的时间戳。这些值在其他任何请求Pushover之后都可用。

// Call limit for the application per month.
$pushy->getAppLimit();

// Calls remaining for the month.
$pushy->getAppRemaining();

// Timestamp for when calls remaining is reset to limit.
$pushy->getAppReset();

命令行界面

Pushy包含一个方便的脚本来从命令行发送消息。

您可以像这样调用它

$ bin/pushy --token=yourtokenhere --user-id=useridhere --message="Message here" --title="Title here" --url="http://example.org" --url-title="Example.org" --timestamp=123456 --sound=echo --priority=high