fv-player / includes / mailchimp-api / README.md

README.md in FV Player 8 trunk, at includes/mailchimp-api/README.md

224 lines 8.1 KB

Raw Download Zip

1	MailChimp API
2	=============
3
4	Super-simple, minimum abstraction MailChimp API v3 wrapper, in PHP.
5
6	I hate complex wrappers. This lets you get from the MailChimp API docs to the code as directly as possible.
7
8	Requires PHP 5.3 and a pulse. Abstraction is for chimps.
9
10	[](https://travis-ci.org/drewm/mailchimp-api![Build Status](https://travis-ci.org/drewm/mailchimp-api.svg?branch=master)](https://travis-ci.org/drewm/mailchimp-api](https://travis-ci.org/drewm/mailchimp-api)
11	[](https://scrutinizer-ci.com/g/drewm/mailchimp-api/?branch=master![Scrutinizer Code Quality](https://scrutinizer-ci.com/g/drewm/mailchimp-api/badges/quality-score.png?b=master)](https://scrutinizer-ci.com/g/drewm/mailchimp-api/?branch=master](https://scrutinizer-ci.com/g/drewm/mailchimp-api/?branch=master)
12	[](https://packagist.org/packages/drewm/mailchimp-api![Packagist](https://img.shields.io/packagist/dt/drewm/mailchimp-api.svg?maxAge=2592000)](https://packagist.org/packages/drewm/mailchimp-api](https://packagist.org/packages/drewm/mailchimp-api)
13
14	Installation
15	------------
16
17	You can install mailchimp-api using Composer:
18
19	```
20	composer require drewm/mailchimp-api
21	```
22
23	You will then need to:
24	* run ``composer install`` to get these dependencies added to your vendor directory
25	* add the autoloader to your application with this line: ``require("vendor/autoload.php")``
26
27	Alternatively you can just download the `MailChimp.php` file and include it manually:
28
29	```php
30	include('./MailChimp.php');
31	```
32
33	If you wish to use the batch request or webhook interfaces, you'll also need to download and include the `Batch.php` or `Webhook.php` files:
34
35	```php
36	include('./Batch.php');
37	include('./Webhook.php');
38	```
39
40	These are optional. If you're not using batches or webhooks you can just skip them. You can always come back and add them later.
41
42	Examples
43	--------
44
45	Start by `use`-ing the class and creating an instance with your API key
46
47	```php
48	use \DrewM\MailChimp\MailChimp;
49
50	$MailChimp = new MailChimp('abc123abc123abc123abc123abc123-us1');
51	```
52
53	Then, list all the mailing lists (with a `get` on the `lists` method)
54
55	```php
56	$result = $MailChimp->get('lists');
57
58	print_r($result);
59	```
60
61	Subscribe someone to a list (with a `post` to the `lists/{listID}/members` method):
62
63	```php
64	$list_id = 'b1234346';
65
66	$result = $MailChimp->post("lists/$list_id/members", [
67	'email_address' => 'davy@example.com',
68	'status' => 'subscribed',
69	]);
70
71	print_r($result);
72	```
73
74	Update a list member with more information (using `patch` to update):
75
76	```php
77	$list_id = 'b1234346';
78	$subscriber_hash = $MailChimp->subscriberHash('davy@example.com');
79
80	$result = $MailChimp->patch("lists/$list_id/members/$subscriber_hash", [
81	'merge_fields' => ['FNAME'=>'Davy', 'LNAME'=>'Jones'],
82	'interests' => ['2s3a384h' => true],
83	]);
84
85	print_r($result);
86	```
87
88	Remove a list member using the `delete` method:
89
90	```php
91	$list_id = 'b1234346';
92	$subscriber_hash = $MailChimp->subscriberHash('davy@example.com');
93
94	$MailChimp->delete("lists/$list_id/members/$subscriber_hash");
95	```
96
97	Quickly test for a successful action with the `success()` method:
98
99	```php
100	$list_id = 'b1234346';
101
102	$result = $MailChimp->post("lists/$list_id/members", [
103	'email_address' => 'davy@example.com',
104	'status' => 'subscribed',
105	]);
106
107	if ($MailChimp->success()) {
108	print_r($result);
109	} else {
110	echo $MailChimp->getLastError();
111	}
112	```
113
114	Batch Operations
115	----------------
116
117	The MailChimp [](http://developer.mailchimp.com/documentation/mailchimp/guides/how-to-use-batch-operations/Batch Operations](http://developer.mailchimp.com/documentation/mailchimp/guides/how-to-use-batch-operations/](http://developer.mailchimp.com/documentation/mailchimp/guides/how-to-use-batch-operations/) functionality enables you to complete multiple operations with a single call. A good example is adding thousands of members to a list - you can perform this in one request rather than thousands.
118
119	```php
120	use \DrewM\MailChimp\MailChimp;
121	use \DrewM\MailChimp\Batch;
122
123	$MailChimp = new MailChimp('abc123abc123abc123abc123abc123-us1');
124	$Batch = $MailChimp->new_batch();
125	```
126
127	You can then make requests on the `Batch` object just as you would normally with the `MailChimp` object. The difference is that you need to set an ID for the operation as the first argument, and also that you won't get a response. The ID is used for finding the result of this request in the combined response from the batch operation.
128
129	```php
130	$Batch->post("op1", "lists/$list_id/members", [
131	'email_address' => 'micky@example.com',
132	'status' => 'subscribed',
133	]);
134
135	$Batch->post("op2", "lists/$list_id/members", [
136	'email_address' => 'michael@example.com',
137	'status' => 'subscribed',
138	]);
139
140	$Batch->post("op3", "lists/$list_id/members", [
141	'email_address' => 'peter@example.com',
142	'status' => 'subscribed',
143	]);
144	```
145
146	Once you've finished all the requests that should be in the batch, you need to execute it.
147
148	```php
149	$result = $Batch->execute();
150	```
151
152	The result includes a batch ID. At a later point, you can check the status of your batch:
153
154	```php
155	$MailChimp->new_batch($batch_id);
156	$result = $Batch->check_status();
157	```
158
159	When your batch is finished, you can download the results from the URL given in the response. In the JSON, the result of each operation will be keyed by the ID you used as the first argument for the request.
160
161	Webhooks
162	--------
163
164	Note: Use of the Webhooks functionality requires at least PHP 5.4.
165
166	MailChimp [](http://kb.mailchimp.com/integrations/other-integrations/how-to-set-up-webhookswebhooks](http://kb.mailchimp.com/integrations/other-integrations/how-to-set-up-webhooks](http://kb.mailchimp.com/integrations/other-integrations/how-to-set-up-webhooks) enable your code to be notified of changes to lists and campaigns.
167
168	When you set up a webhook you specify a URL on your server for the data to be sent to. This wrapper's Webhook class helps you catch that incoming webhook in a tidy way. It uses a subscription model, with your code subscribing to whichever webhook events it wants to listen for. You provide a callback function that the webhook data is passed to.
169
170	To listen for the `unsubscribe` webhook:
171
172	```php
173	use \DrewM\MailChimp\Webhook;
174
175	Webhook::subscribe('unsubscribe', function($data){
176	print_r($data);
177	});
178	```
179
180	At first glance the _subscribe/unsubscribe_ looks confusing - your code is subscribing to the MailChimp `unsubscribe` webhook event. The callback function is passed as single argument - an associative array containing the webhook data.
181
182	If you'd rather just catch all webhooks and deal with them yourself, you can use:
183
184	```php
185	use \DrewM\MailChimp\Webhook;
186
187	$result = Webhook::receive();
188	print_r($result);
189	```
190
191	There doesn't appear to be any documentation for the content of the webhook data. It's helpful to use something like [](https://ngrok.comngrok](https://ngrok.com](https://ngrok.com) for tunneling the webhooks to your development machine - you can then use its web interface to inspect what's been sent and to replay incoming webhooks while you debug your code.
192
193	Troubleshooting
194	---------------
195
196	To get the last error returned by either the HTTP client or by the API, use `getLastError()`:
197
198	```php
199	echo $MailChimp->getLastError();
200	```
201
202	For further debugging, you can inspect the headers and body of the response:
203
204	```php
205	print_r($MailChimp->getLastResponse());
206	```
207
208	If you suspect you're sending data in the wrong format, you can look at what was sent to MailChimp by the wrapper:
209
210	```php
211	print_r($MailChimp->getLastRequest());
212	```
213
214	If your server's CA root certificates are not up to date you may find that SSL verification fails and you don't get a response. The correction solution for this [](http://snippets.webaware.com.au/howto/stop-turning-off-curlopt_ssl_verifypeer-and-fix-your-php-config/is not to disable SSL verification](http://snippets.webaware.com.au/howto/stop-turning-off-curlopt_ssl_verifypeer-and-fix-your-php-config/](http://snippets.webaware.com.au/howto/stop-turning-off-curlopt_ssl_verifypeer-and-fix-your-php-config/). The solution is to update your certificates. If you can't do that, there's an option at the top of the class file. Please don't just switch it off without at least attempting to update your certs -- that's lazy and dangerous. You're not a lazy, dangerous developer are you?
215
216	Contributing
217	------------
218
219	This is a fairly simple wrapper, but it has been made much better by contributions from those using it. If you'd like to suggest an improvement, please raise an issue to discuss it before making your pull request.
220
221	Pull requests for bugs are more than welcome - please explain the bug you're trying to fix in the message.
222
223	There are a small number of PHPUnit unit tests. To get up and running, copy `.env.example` to `.env` and add your API key details. Unit testing against an API is obviously a bit tricky, but I'd welcome any contributions to this. It would be great to have more test coverage.
224