Skip to content

Commit 3226049

Browse files
jeremeamiajeremeamia
committed
Updating README with more documentation [ci-skip]
1 parent 926cf23 commit 3226049

File tree

1 file changed

+131
-10
lines changed

1 file changed

+131
-10
lines changed

‎README.md‎

Lines changed: 131 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,26 @@
1-
# Amazon SNS message Validator for PHP
1+
# Amazon SNS Message Validator for PHP
22

33
[![@awsforphp on Twitter](http://img.shields.io/badge/twitter-%40awsforphp-blue.svg?style=flat)](https://twitter.com/awsforphp)
44
[![Total Downloads](https://img.shields.io/packagist/dt/aws/aws-php-sns-message-validator.svg?style=flat)](https://packagist.org/packages/aws/aws-php-sns-message-validator)
55
[![Build Status](https://img.shields.io/travis/aws/aws-php-sns-message-validator.svg?style=flat)](https://travis-ci.org/aws/aws-php-sns-message-validator)
66
[![Apache 2 License](https://img.shields.io/packagist/l/aws/aws-php-sns-message-validator.svg?style=flat)](http://aws.amazon.com/apache-2-0/)
77

8-
The **Amazon SNS Message Validator for PHP** allows you to validate that incoming
9-
HTTP(S) messages are legitimate SNS notifications. This library does not depend
10-
on the AWS SDK for PHP or Guzzle, but it does require that the OpenSSL PHP
11-
extension be installed.
8+
The **Amazon SNS Message Validator for PHP** library allows you to validate that
9+
incoming HTTP(S) POST messages are valid Amazon SNS notifications. This library
10+
is standalone and does not depend on the AWS SDK for PHP or Guzzle; however, it
11+
does require PHP 5.4+ and that the OpenSSL PHP extension is installed.
1212

13-
## Usage
13+
## Basic Usage
14+
15+
To validate a message, you can instantiate a `Message` object from the POST
16+
data using the `Message::fromRawPostData`. This reads the raw POST data from
17+
the [`php://input` stream][php-input], decodes the JSON data, and validates
18+
the message's type and structure.
19+
20+
Next, you must create an instance of `MessageValidator`, and then use either
21+
the `isValid()` or `validate()`, methods to validate the message. The
22+
message validator checks the `SigningCertURL`, `SignatureVersion`, and
23+
`Signature` to make sure they are valid and consistent with the message data.
1424

1525
```php
1626
<?php
@@ -29,8 +39,119 @@ if ($validator->isValid($message)) {
2939
}
3040
```
3141

32-
### Thanks
42+
## Installation
43+
44+
The SNS Message Validator can be installed via [Composer][].
45+
46+
$ composer require aws/aws-php-sns-message-validator
47+
48+
Since the library has no other PHP dependencies, you can also easily install
49+
the library from the [source code][] here on GitHub.
50+
51+
## About Amazon SNS
52+
53+
[Amazon Simple Notification Service (Amazon SNS)][sns] is a fast, fully-managed,
54+
push messaging service. Amazon SNS can deliver messages to email, mobile devices
55+
(i.e., SMS; iOS, Android and FireOS push notifications), Amazon SQS queues,and
56+
— of course — HTTP/HTTPS endpoints.
57+
58+
With Amazon SNS, you can setup topics to publish custom messages to subscribed
59+
endpoints. However, SNS messages are used by many of the other AWS services to
60+
communicate information asynchronously about your AWS resources. Some examples
61+
include:
62+
63+
* Configuring Amazon Glacier to notify you when a retrieval job is complete.
64+
* Configuring AWS CloudTrail to notify you when a new log file has been written.
65+
* Configuring Amazon Elastic Transcoder to notify you when a transcoding job
66+
changes status (e.g., from "Progressing" to "Complete")
67+
68+
Though you can certainly subscribe your email address to receive SNS messages
69+
from service events like these, your inbox would fill up rather quickly. There
70+
is great power, however, in being able to subscribe an HTTP/HTTPS endpoint to
71+
receive the messages. This allows you to program webhooks for your applications
72+
to easily respond to various events.
73+
74+
## Handling Messages
75+
76+
### Confirming a Subscription to a Topic
77+
78+
In order to handle a `SubscriptionConfirmation` message, you must use the
79+
`SubscribeURL` value in the incoming message:
80+
81+
```php
82+
use Aws\Sns\Message;
83+
use Aws\Sns\MessageValidator;
84+
use Aws\Sns\Exception\InvalidSnsMessageException;
85+
86+
// Instantiate the Message and Validator
87+
$message = Message::fromRawPostData();
88+
$validator = new MessageValidator();
89+
90+
// Validate the message and log errors if invalid.
91+
try {
92+
$validator->validate($message);
93+
} catch (InvalidSnsMessageException $e) {
94+
// Pretend we're not here if the message is invalid.
95+
http_response_code(404);
96+
error_log('SNS Message Validation Error: ' . $e->getMessage);
97+
die();
98+
}
99+
100+
// Check the type of the message and handle the subscription.
101+
if ($message['Type'] === 'SubscriptionConfirmation') {
102+
// Confirm the subscription by sending a GET request to the SubscribeURL
103+
file_get_contents($message['SubscribeURL']);
104+
}
105+
```
106+
107+
### Receiving a Notification
108+
109+
To receive a notification, use the same code as the preceding example, but
110+
check for the `Notification` message type.
111+
112+
```php
113+
if ($message['Type'] === 'Notification') {
114+
// Do whatever you want with the message body.
115+
}
116+
```
117+
118+
The message body will be a string, and will hold whatever data was published
119+
to the SNS topic.
120+
121+
### Unsubscribing
122+
123+
Unsubscribing looks the same as subscribing, except the message type will be
124+
`UnsubscribeConfirmation`.
125+
126+
```php
127+
if ($message['Type'] === 'UnsubscribeConfirmation') {
128+
file_get_contents($message['SubscribeURL']);
129+
}
130+
```
131+
132+
## Testing Locally
133+
134+
One challenge of using webhooks in a web application is testing the integration
135+
with the service. Testing integrations with SNS notifications can be fairly easy
136+
using tools like [ngrok][] and [PHP's built-in webserver][php-service]. Our blog
137+
post, [*Testing Webhooks Locally for Amazon SNS*][blogpost], illustrates a good
138+
technique for testing.
139+
140+
> **NOTE:** the code samples in that blog post are specific to Message Validator
141+
> in Version 2 of the SDK, but can be easily adapted to using this version.
142+
143+
### Special Thank You
144+
145+
A special thanks goes out to [Julian Vidal][] who helped create the [initial
146+
implementation][] in Version 2 of the [AWS SDK for PHP][].
33147

34-
A special thanks goes out to [Julian Vidal](https://github.com/poisa) who helped
35-
create the [initial implementation](https://github.com/aws/aws-sdk-php/tree/2.8/src/Aws/Sns/MessageValidator)
36-
in Version 2 of the [AWS SDK for PHP](https://github.com/aws/aws-sdk-php).
148+
[php-input]: http://php.net/manual/en/wrappers.php.php#wrappers.php.input
149+
[composer]: https://getcomposer.org/
150+
[source code]: https://github.com/aws/aws-php-sns-message-validator/archive/master.zip
151+
[sns]: http://aws.amazon.com/sns/
152+
[ngrok]: https://ngrok.com/
153+
[php-server]: http://www.php.net/manual/en/features.commandline.webserver.php
154+
[blogpost]: http://blogs.aws.amazon.com/php/post/Tx2CO24DVG9CAK0/Testing-Webhooks-Locally-for-Amazon-SNS
155+
[Julian Vidal]: https://github.com/poisa
156+
[initial implementation]: https://github.com/aws/aws-sdk-php/tree/2.8/src/Aws/Sns/MessageValidator
157+
[AWS SDK for PHP]: https://github.com/aws/aws-sdk-php

0 commit comments

Comments
 (0)