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
UpdownSound

验证用户

在发送消息之前，可以使用 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

sqmk / pushy

维护者

详细信息