README

这个简单的PHP客户端使用Pushover REST API向移动设备发送推送通知。有关Pushover的更多信息，请参阅http://pushover.net

用法

use Capirussa\Pushover;

try {
    $client = Pushover\Client::init($applicationToken);
    $message = new Pushover\Message('userKey', 'message');

    $client->send($message);
} catch (Pushover\Exception $exception) {
    // something went wrong, fix it and try again!
}

Pushover\Client

初始化Pushover\Client时，您需要提供应用程序的令牌。您可以在登录Pushover后在其在线仪表板中找到此令牌。

在某些服务器上，通常是localhost开发服务器，您可能会遇到SSL错误。要跳过SSL验证，请调用 $client->disableSslVerification()。

要设置或检索应用程序令牌，您可以使用 $client->setToken() 或 $client->getToken()。要完全重置客户端，包括SSL验证标志，您还可以使用应用程序令牌调用 $client->init()。

要向特定用户或组发送推送通知，请使用Pushover\Message对象作为参数调用 $client->send()。默认情况下，此方法将返回null，但是，对于具有PRIORITY_EMERGENCY优先级的消息，它将返回消息收据令牌。您可以使用此令牌轮询Pushover API并检查消息是否已被确认。

要验证给定的用户或组是否有效，请使用Pushover\Validate对象作为参数调用 $client->validate()。

要验证您发送具有紧急优先级消息的确认，过期或是否已请求回调URL，请使用Pushover\Receipt对象作为参数调用 $client->pollReceipt()。

最后，您可以通过使用用户令牌作为参数调用 $client->getUserDevices() 来检索用户的设备列表。

Pushover\Message

要使用Pushover发送推送通知，您需要向客户端提供消息对象。消息具有以下属性（所有属性都可以使用相应的getter设置）

接收者 - 要发送消息的用户或组令牌。必须是30个字符的字母数字字符串。
消息 - 要发送的消息正文。与可选消息标题结合时，不得超过512个字符。
标题 - 可选的消息标题。不得超过100个字符，与消息正文结合时，总长度不得超过512个字符。
设备 - 可选的设备标识符，用于将消息发送到用户的设备，如果用户有多个设备且您只想将此消息发送到特定设备。
URL - 可选的要在消息中包含的URL。不得超过512个字符。
URL标题 - 可选的消息中显示的标题，而不是URL本身。不得超过100个字符。
优先级 - 此消息的优先级。必须是Pushover\Request接口中定义的优先级之一。默认为PRIORITY_NORMAL
时间戳 - 此消息的可选时间戳。设置器将接受DateTime对象以及时间戳。
声音 - 用于此消息的声音（默认为收件人用户的偏好设置）。必须是 Pushover\Sound 中定义的声音之一。
回调 URL - 对于优先级设置为 PRIORITY_EMERGENCY 的消息，可以提供一个回调 URL，当消息被确认时，Pushover 将调用该 URL。
过期 - 对于 PRIORITY_EMERGENCY 消息是必需的，表示消息过期的时间（秒）。默认为 3600（1小时），最大值为 86400（24小时）。
重试 - 对于 PRIORITY_EMERGENCY 消息是必需的，表示重新发送之间的时间间隔（秒）。默认为最小值 30 秒。

如上例所示，可以使用收件人和消息初始化 Pushover\Message 对象。这是可选的，您也可以使用它们的设置器来设置这些属性。

$message = new Pushover\Message();
$message->setRecipient('userKey');
$message->setMessage('message');
$message->setSound(Pushover\Sound::SPACE_ALARM);

Pushover\Receipt

收据对象必须提供给客户端，以轮询 PRIORITY_EMERGENCY 消息是否被确认或已过期，以及回调 URL 是否已被调用。

收据对象只有一个属性

收据 - 用于轮询其状态的收据令牌。

收据令牌可以在初始化对象时设置，或者使用设置器。

$receipt = new Pushover\Receipt();
$receipt->setReceipt('receiptToken');

收据令牌必须是一个 30 个字符的字母数字字符串。

Pushover\Validate

为了验证用户或组令牌是否有效，同时可选地验证特定设备是否属于给定用户，您必须向客户端提供一个 Validate 对象。此对象具有以下属性

收件人 - 要验证的用户或组令牌。必须是 30 个字符的字母数字字符串。
设备 - 要验证的特定设备。

$validate = new Pushover\Validate();
$validate->setRecipient('userToken');
$validate->setDevice('iphone');

Pushover\Response

通常，您不会看到响应。但是，当您轮询 Pushover API 以检查紧急消息是否已被确认时，您可能对各种属性感兴趣。我可以选择返回包含所有相关属性的数组，但我选择只返回 Response 对象，并允许您检索所需的数据。Response 对象具有以下属性

状态 - 可以是 Response::STATUS_SUCCESS 或 Response::STATUS_FAILURE 之一。
组 - 用于响应 Validate 请求，包含组令牌。
设备 - 用于响应 Validate 请求，包含此用户的设备列表。
请求 - 包含提交给 Pushover 的请求的唯一请求标识符。
错误 - 包含 Pushover 返回的错误列表（如果有）。
AppLimit - 包含您的应用程序每月允许提交的消息总数。
AppRemaining - 包含您本月仍可提交的消息数。
AppReset - 包含一个 DateTime 对象，指示您的应用程序的消息配额何时将重置。
已确认 - 表示此收据的消息是否被确认。可以是 Response::ACKNOWLEDGED_YES 或 Response::ACKNOWLEDGED_NO 之一。
确认时间 - 包含一个 DateTime 对象，指示此收据的消息何时被确认。
确认者 - 包含确认此收据消息的用户令牌（如果有的话）。
最后送达时间 - 包含一个 DateTime 对象，指示此收据的消息最后一次发送给用户的时间。
已过期 - 表示此收据的消息是否已过期。可以是 Response::EXPIRED_YES 或 Response::EXPIRED_NO 之一。
过期时间 - 包含一个 DateTime 对象，指示此收据的消息何时将过期（如果尚未过期）。
CalledBack - 表示该收据的消息回调URL是否已被调用。可以是 Response::CALLED_BACK_YES 或 Response::CALLED_BACK_NO 之一。
CalledBackAt - 包含一个 DateTime 对象，表示为该请求的消息调用回调URL的时间。
Receipt - 包含刚刚发送的消息的收据令牌。

这很好，但我是如何将所有这些整合在一起的呢？

这里有一些示例。假设应用程序令牌为 '123apptoken'，用户令牌为 'usertoken123'。这些显然是无效的，但这只是一个示例。

use Capirussa\Pushover;

// initialize the client
$client = new Pushover\Client('123apptoken');

// optional: when running on an ill-configured development server
if ($sslIsBroken) {
    $client->disableSslVerification();
}

// let's verify whether the user token is valid
$validateRequest = new Pushover\Validate('usertoken123');
if (!$client->validate($validateRequest)) {
    echo 'Hey, "usertoken123" is not a valid token!';
} else {
    // let's send a message with regular priority
    $messageRequest = new Pushover\Message('usertoken123');
    $messageRequest->setTitle('Normal priority message');
    $messageRequest->setMessage('This is just a regular message.');

    $client->send($messageRequest);

    // now let's get a list of all devices for this user
    $devices = $client->getUserDevices('usertoken123');

    // now let's send a message with emergency priority to the user's first device
    $emergency = new Pushover\Message('usertoken123');
    $emergency->setDevice($devices[0]);
    $emergency->setPriority(Pushover\Request::PRIORITY_EMERGENCY);
    $emergency->setSound(Pushover\Sound::SIREN);
    $emergency->setTitle('Everything is broken');
    $emergency->setMessage('You must fix it, now!');
    $emergency->setCallbackUrl('http://example.com/fixitnow');

    $receiptToken = $client->send($emergency);

    // now let's see whether the user has acknowledged the message
    $receiptRequest = new Pushover\Receipt($receiptToken);

    $response = $client->pollReceipt($receiptRequest);

    // check whether that request was successful
    if ($response->getStatus() === Pushover\Response::STATUS_SUCCESS) {
        // check whether the request was acknowledged
        $acknowledged = ($response->getAcknowledged() === Pushover\Response::ACKNOWLEDGED_YES);
        if ($acknowledged) {
            // get the user token of the user who acknowledged the request
            $userToken = $response->getAcknowledgedBy();

            // get the DateTime at which the token was acknowledged
            $when = $response->getAcknowledgedAt();

            echo 'The emergency was acknowledged by ' . $userToken . ' on ' . $when->format('Y-m-d') . ' at ' . $when->format('H:i:s');

            // get whether the callback URL was called
            $calledBack = ($response->getCalledBack() === Pushover\Response::CALLED_BACK_YES);
            if ($calledBack) {
                echo 'The callback URL was requested by Pushover on ' . $response->getCalledBackAt()->format('Y-m-d') . ' at ' . $response->getCalledBackAt()->format('H:i:s');
            }
        } else {
            // check whether the message has expired
            $expired = ($response->getExpired() == Pushover\Response::EXPIRED_YES);

            if ($expired) {
                echo 'The message has not been acknowledged, and has expired. Tough cookie.';
            } else {
                echo 'The message has not been acknowledged yet, it was last sent to the user at ' . $response->getLastDeliveredAt()->format('H:i:s') . ' and will expire on ' . $response->getExpiresAt()->format('Y-m-d') . ' at ' . $response->getExpiresAt()->format('H:i:s');
            }
        }
    }
}

请注意，如果您直接复制粘贴此代码并运行它，您将在极短的时间内向 Pushover API 发送大量请求。他们不喜欢这样，所以您不应该这样做。使用这些类时，请记住他们的友好规则。

如果您在此代码中发现任何错误，请在 Github 上提出问题，或者分支此项目并创建一个 pull request。

祝您编码愉快！

capirussa / pushover-php

维护者

详细信息