Guzzle - SymfonyLive Portland

Slide 1

Slide 1 text

#VJMEJOHXFCTFSWJDF DMJFOUTXJUI (V[[MF Michael Dowling http://guzzlephp.org https://github.com/guzzle/guzzle

Slide 2

Slide 2 text

!NUEPXMJOH http://mtdowling.com https://github.com/mtdowling Amazon Web Services AWS SDK for PHP Author of Guzzle *`N.JDIBFM%PXMJOH

Slide 3

Slide 3 text

Part One 1)1)551$MJFOUT

Slide 4

Slide 4 text

IUUQTUSFBN XSBQQFS

Slide 5

Slide 5 text

IUUQTUSFBN XSBQQFS • Easy to send simple GET requests • Built-in to PHP

Slide 6

Slide 6 text

IUUQTUSFBN XSBQQFS • Need to work with stream contexts • No support for persistent connections • No support for parallel requests • Data must be loaded into memory • Easy to send simple GET requests • Built-in to PHP

Slide 7

Slide 7 text

Slide 8

Slide 8 text

// Send a POST request $context = stream_context_create([ 'http' => [ 'method' => 'POST', 'content' => http_build_query([ 'foo' => 'bar' ]) ) ]); $body = file_get_contents($url, false, $context); IUUQTUSFBN XSBQQFS

Slide 9

Slide 9 text

D63- • Fast • Supports HTTP/1.1 • Supports streaming requests & responses • Can do pretty much anything • Almost everyone uses it • Very cumbersome API

Slide 10

Slide 10 text

D63- $ch = curl_init('http://example.com'); curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PUT'); curl_setopt($ch, CURLOPT_UPLOAD, true); curl_setopt($ch, CURLOPT_HTTPHEADER, ['Transfer-Encoding: chunked']); // Open a stream to download the contents of Amazon.com $stream = fopen('http://www.amazon.com', 'r'); // Use a callback to read the body curl_setopt( $ch, CURLOPT_READFUNCTION, function ($ch, $fd, $length) use ($stream) { return fread($stream, $length) ? ''; } ); curl_exec($ch);

Slide 11

Slide 11 text

1&$-)551 • Supports HTTP/1.1 • Supports streaming requests • Does not stream responses • Requires uncommon extension

Slide 12

Slide 12 text

4PDLFUT • More control • Lots of effort because... •RFC 2616 is complicated e.g. fsockopen

Slide 13

Slide 13 text

1)1$MJFOUT • Guzzle • Buzz • Zend/Http • Requests • ...

Slide 14

Slide 14 text

(V[[MF • Supports HTTP/1.1 • Parallel & persistent requests • Streaming requests and responses • Extensible with plugins • Web service framework

Slide 15

Slide 15 text

IT REQUIRES CURL!

Slide 16

Slide 16 text

D63-BTB EFQFOEFODZ

Slide 17

Slide 17 text

D63-BTB EFQFOEFODZ • Popular libs require cURL • AWS, Magento, Facebook, Google, ...

Slide 18

Slide 18 text

D63-BTB EFQFOEFODZ • Popular libs require cURL • AWS, Magento, Facebook, Google, ... • Most shared hosts include it • GoDaddy, DreamHost, ServerGrove...

Slide 19

Slide 19 text

D63-BTB EFQFOEFODZ • Popular libs require cURL • AWS, Magento, Facebook, Google, ... • Most shared hosts include it • GoDaddy, DreamHost, ServerGrove... d.JOTUBMMT http://daniel.haxx.se/blog/2012/05/16/300m-users/

Slide 20

Slide 20 text

*OTUBMMJOH(V[[MF { "require": { "guzzle/guzzle": "3.5.*" } } composer.json composer.phar install

Slide 21

Slide 21 text

IT’S NOT LIGHTWEIGHT!

Slide 22

Slide 22 text

(V[[MF$PNQPOFOUT guzzle/common guzzle/http guzzle/parser guzzle/batch guzzle/cache guzzle/inflection guzzle/iterator guzzle/log guzzle/plugin guzzle/plugin-‐async guzzle/plugin-‐backoff guzzle/plugin-‐cache guzzle/plugin-‐cookie guzzle/plugin-‐curlauth guzzle/plugin-‐error-‐response guzzle/plugin-‐history guzzle/plugin-‐log guzzle/plugin-‐md5 guzzle/plugin-‐mock guzzle/plugin-‐oauth guzzle/service guzzle/stream { "require": { "guzzle/http": "3.*" } } Minimal installation Piece by piece { "require": { "guzzle/http": "3.*", "guzzle/plugin-mock": "3.*" } }

Slide 23

Slide 23 text

• AWS SDK for PHP • Drupal 8 • Goutte • Tumblr (V[[MFJOUIF8JME

Slide 24

Slide 24 text

• Guzzle is now part of Drupal 8 core • Replaced drupal_http_request() [2] • Evaluated HTTP libs & chose Guzzle [1] • Helped make Guzzle better [3] (V[[MF%SVQBM [1] http://groups.drupal.org/node/233173 [2] http://drupal.org/node/1862398 [3] https://github.com/guzzle/guzzle/contributors

Slide 25

Slide 25 text

No content

Slide 26

Slide 26 text

• Clients are the glue • Clients create and send Requests • Base URLs (V[[MFa)UUQa$MJFOU

Slide 27

Slide 27 text

get('statuses/user_timeline.json'); $response = $request->send(); $MJFOU#BTF63-T RFC 3986

Slide 28

Slide 28 text

use Guzzle\Http\Client; // Create a client that uses a URI template $client = new Client( 'https://api.twitter.com/{version}', ['version' => '1.1'] ); 63*UFNQMBUFT RFC 6570

Slide 29

Slide 29 text

$client = new Guzzle\Http\Client(); $url = 'http://www.amazon.com?foo=bar'; $response = $client->get($url)->send(); 4JNQMF(&5 SFRVFTU

Slide 30

Slide 30 text

$client = new Guzzle\Http\Client(); $url = 'http://www.amazon.com?foo=bar'; $response = $client->get($url)->send(); 4JNQMF(&5 SFRVFTU GET /?foo=bar HTTP/1.1 Host: www.amazon.com User-‐Agent: Guzzle/3.5.0 curl/7.21.4 PHP/5.3.15

Slide 31

Slide 31 text

DEFINT A-Z OPTION BASE 1 ' Include the Guzzle TYPE definitions '$INCLUDE: 'GUZZLE.BI' DIM CLIENT AS GuzzleClient DIM REQUEST AS GuzzleRequest DIM RESPONSE AS GuzzleResponse ' Initialize the client and request CLIENT.BASE_URL = "http://www.amazon.com" ' Create a request with a relative base URL REQUEST.URL = "?foo=bar" ' Response is passed by reference GuzzleSend (CLIENT, REQUEST, RESPONSE) PRINT RESPONSE.BODY END

Slide 32

Slide 32 text

// Response body echo $response->getBody(); // Read as array if the response was JSON $data = $response->json(); // Read as XML if the response was XML $xml = $response->xml(); 3FTQPOTFT

Slide 33

Slide 33 text

// Get response status line values echo $response->getStatusCode(); echo $response->getReasonPhrase(); // Read response headers echo $response->getHeader('Content-Length'); echo $response->getContentLength(); echo $response->getContentType(); foreach ($response->getHeaders() as $k => $v) { echo "{$k}: {$v}\n"; } 3FTQPOTFT

Slide 34

Slide 34 text

$request = $client->post('/', [], [ 'Foo' => 'Baz', 'Bar' => 'Bam' ]); echo $request; 10453FRVFTUT

Slide 35

Slide 35 text

$request = $client->post('/', [], [ 'Foo' => 'Baz', 'Bar' => 'Bam' ]); echo $request; POST / HTTP/1.1 Host: example.com Content-Type: application/x-www-form-urlencoded User-Agent: Guzzle/3.5.0 curl/7.21.4 PHP/5.3.15 Foo=Baz&Bar=Bam 10453FRVFTUT

Slide 36

Slide 36 text

DEFINT A-Z OPTION BASE 1 '$INCLUDE: 'GUZZLE.BI' DIM CLIENT AS GuzzleClient DIM REQUEST AS GuzzleRequest DIM RESPONSE AS GuzzleResponse CLIENT.BASE_URL = "http://www.amazon.com" REQUEST.METHOD = "POST" REQUEST.POST_BODY = "Foo=Baz&Bar=Bam" REQUEST.URL = "/" GuzzleSend (CLIENT, REQUEST, RESPONSE) PRINT RESPONSE.BODY END

Slide 37

Slide 37 text

// Stream data from amazon.com $request = $client->post('http://example.com', [ 'Content-Type' => 'text/html', ], fopen('http://www.amazon.com', 'r')); // Stream the response to a file $request->setResponseBody('/path/to/file'); $response = $request->send(); 4USFBNJOHEBUB

Slide 38

Slide 38 text

Slide 39

Slide 39 text

&SSPS)BOEMJOH

Slide 40

Slide 40 text

&SSPS)BOEMJOH •Application / Protocol errors • HTTP status-code >=400,<=599

Slide 41

Slide 41 text

&SSPS)BOEMJOH •Application / Protocol errors • HTTP status-code >=400,<=599 •Transport / Network errors • cURL errors

Slide 42

Slide 42 text

)551FSSPST use Guzzle\Http\Exception\BadResponseException; $request = $client->get('/not_found.xml'); try { $response = $request->send(); } catch (BadResponseException $e) { echo $e->getMessage() . "\n"; echo $e->getRequest()->getUrl() . "\n"; echo $e->getResponse()->getRawHeaders() . "\n"; }

Slide 43

Slide 43 text

DEFINT A-Z OPTION BASE 1 '$INCLUDE: 'GUZZLE.BI' DIM CLIENT AS GuzzleClient DIM REQUEST AS GuzzleRequest DIM RESPONSE AS GuzzleResponse ' Register the error handler ON ERROR GOTO Err1 CLIENT.BASE_URL = "http://www.amazon.com" REQUEST.URL = "/not_found.xml" GuzzleSend (CLIENT, REQUEST, RESPONSE) Err1: IF ERR = 404 THEN PRINT "File not found: " + REQUEST.URL END IF END

Slide 44

Slide 44 text

use Guzzle\Common\Exception\MultiTransferException; try { $responses = $client->send([ $client->get('http://www.amazon.com/'), $client->head('http://www.google.com/'), $client->get('https://www.github.com/') ]); } catch (MultiTransferException $e) { foreach ($e->getFailedRequests() as $request) { echo "Failure:\n{$request}\n"; } foreach ($e->getSuccessfulRequests() as $request) { echo "Success:\n{$request}\n"; } } 1BSBMMFM3FRVFTUT

Slide 45

Slide 45 text

No content

Slide 46

Slide 46 text

No content

Slide 47

Slide 47 text

No content

Slide 48

Slide 48 text

4ZNGPOZ&WFOU %JTQBUDIFS

Slide 49

Slide 49 text

4ZNGPOZ&WFOU %JTQBUDIFS • Glue of Guzzle

Slide 50

Slide 50 text

4ZNGPOZ&WFOU %JTQBUDIFS • Glue of Guzzle • Extensible through events

Slide 51

Slide 51 text

4ZNGPOZ&WFOU %JTQBUDIFS • Glue of Guzzle • Extensible through events • HasDispatcherInterface

Slide 52

Slide 52 text

4ZNGPOZ&WFOU %JTQBUDIFS • Glue of Guzzle • Extensible through events • HasDispatcherInterface • Subscribers and listeners

Slide 53

Slide 53 text

$client->getEventDispatcher()->addListener( 'request.error', function (Event $event) { if ($event['response']->getStatusCode() != 401) { return; } $req = $event['request']->clone(); $req->setHeader('X-Auth-Header', MyApp::getAuthToken()); $res = $req->send(); $event['request']->setResponse($res); $event->stopPropagation(); } ); $VTUPNFSSPS IBOEMJOH Event listener

Slide 54

Slide 54 text

1MVHJOT BLB &WFOU4VCTDSJCFST • Encapsulate the events used to modify a client or request • Can work across request lifecycle • Easier to share

Slide 55

Slide 55 text

(V[[MF1MVHJOT • Async • Backoff • Cache • Cookie • Authentication • ErrorResponse • History • Wire logging • MD5 validation • Mock • OAuth 4ZNGPOZ&WFOU4VCTDSJCFST

Slide 56

Slide 56 text

"OBUPNZPGB 1MVHJO • public static function getSubscribedEvents() • Returns array mapping event names to methods • Methods should accept a Guzzle\Common\Event object

Slide 57

Slide 57 text

use Symfony\Component\EventDispatcher\EventSubscriberInterface; class CurlAuthPlugin implements EventSubscriberInterface { private $username; private $password; private $scheme; public function __construct($username, $password, $scheme = CURLAUTH_BASIC) { $this->username = $username; $this->password = $password; $this->scheme = $scheme; } public static function getSubscribedEvents() { return ['client.create_request' => ['onRequestCreate', 255]]; } public function onRequestCreate(\Guzzle\Common\Event $event) { $event['request']->setAuth( $this->username, $this->password, $this->scheme ); } } CurlAuthPlugin

Slide 58

Slide 58 text

use Guzzle\Plugin\CurlAuth\CurlAuthPlugin; // Add the auth plugin to the client object $authPlugin = new CurlAuthPlugin('user', 'pass'); $client->addSubscriber($authPlugin);

Slide 59

Slide 59 text

Part Two 8FCTFSWJDFDMJFOUT

Slide 60

Slide 60 text

8IBUEPFTBXFC TFSWJDFDMJFOUEP

Slide 61

Slide 61 text

.PTUXFC TFSWJDFDMJFOUT

Slide 62

Slide 62 text

.PTUXFC TFSWJDFDMJFOUT • Usually wrap cURL

Slide 63

Slide 63 text

.PTUXFC TFSWJDFDMJFOUT • Usually wrap cURL • Functions for each API operation

Slide 64

Slide 64 text

.PTUXFC TFSWJDFDMJFOUT • Usually wrap cURL • Functions for each API operation • Error handling? Extensibility?

Slide 65

Slide 65 text

.PTUXFC TFSWJDFDMJFOUT • Usually wrap cURL • Functions for each API operation • Error handling? Extensibility? • Are written in a bubble

Slide 66

Slide 66 text

.PTUXFC TFSWJDFDMJFOUT • Usually wrap cURL (poorly) • Functions for each API operation • Error handling? Extensibility? • Are written in a bubble

Slide 67

Slide 67 text

(V[[MFa4FSWJDFa$MJFOU • Extends from Guzzle\Http\Client • Creates and executes Command objects • Owns a Service Description • Created by a Service Builder

Slide 68

Slide 68 text

$PNNBOET • Encapsulate actions of an API • Input validation • Request serialization • Response parsing

Slide 69

Slide 69 text

$PODSFUF $PNNBOET

Slide 70

Slide 70 text

$PODSFUF $PNNBOET • Actual PHP class . ├── Commands │ └── Foo.php └── MyClient.php

Slide 71

Slide 71 text

$PODSFUF $PNNBOET • Actual PHP class • Low level . ├── Commands │ └── Foo.php └── MyClient.php

Slide 72

Slide 72 text

$PODSFUF $PNNBOET • Actual PHP class • Low level • Tight coupling to an API . ├── Commands │ └── Foo.php └── MyClient.php

Slide 73

Slide 73 text

0QFSBUJPO $PNNBOET • Powered by a Service Description • Requires no PHP code • High level

Slide 74

Slide 74 text

Part Three %FpOJOH"1*T

Slide 75

Slide 75 text

4FSWJDF EFTDSJQUJPOT

Slide 76

Slide 76 text

4FSWJDF EFTDSJQUJPOT • Deﬁne an API using a JSON document

Slide 77

Slide 77 text

4FSWJDF EFTDSJQUJPOT • Deﬁne an API using a JSON document • Deﬁnes inputs and outputs

Slide 78

Slide 78 text

4FSWJDF EFTDSJQUJPOT • Deﬁne an API using a JSON document • Deﬁnes inputs and outputs • Versioned descriptions are swappable

Slide 79

Slide 79 text

4FSWJDF EFTDSJQUJPOT • Deﬁne an API using a JSON document • Deﬁnes inputs and outputs • Versioned descriptions are swappable • API docs? Other language clients?

Slide 80

Slide 80 text

{ "name": "string", "apiVersion": "string|number", "baseUrl": "string", "description": "string", "operations": {}, "models": {}, "includes": ["string.php", "string.json"] }

Slide 81

Slide 81 text

{ "operations": { "operationName": { "extends": "string", "httpMethod": "GET|POST|PUT|DELETE|PATCH|string", "uri": "string", "summary": "string", "class": "string", "responseClass": "string", "responseNotes": { "type": "string", "description": "string", "responseType": "primitive|class|model|etc", "deprecated": false, "errorResponses": [ { "code": 500, "phrase": "Unexpected Error", "class": "string" } ] "parameters": {} } } }

Slide 82

Slide 82 text

1BSBNFUFST • Follow JSON schema • Types: object, array, string, number, etc • Required / default values • Validation • locations: header, query, uri, body, etc...

Slide 83

Slide 83 text

• Rewrote the AWS SDK for PHP on Guzzle • Support 31 services w/ multiple versions • Only possible because of service descriptions (V[[MFBOE"84

Slide 84

Slide 84 text

'PutObject': { 'httpMethod': 'PUT', 'uri': '/{Bucket}{/Key*}', 'responseClass': 'PutObjectOutput', 'parameters': { 'Bucket': { 'required': true, 'type': 'string', 'location': 'uri', }, 'Key': { 'required': true, 'type': 'string', 'location': 'uri' }, 'Body': { 'type': [ 'string', 'object' ], 'location': 'body', }, 'ContentType': { 'type': 'string', 'location': 'header', 'sentAs': 'Content-Type', } } } $client->putObject([ 'Bucket' => 'foo', 'Key' => 'baz', 'Body' => 'bar' ]); Input Request GET /foo/baz HTTP/1.1 Host: s3.amazonaws.com Content-‐Length: 3 bar

Slide 85

Slide 85 text

Slide 86

Slide 86 text

Slide 87

Slide 87 text

Slide 88

Slide 88 text

'PutObjectOutput': { 'type': 'object', 'properties': { 'Expiration': { 'type': 'string', 'location': 'header', 'sentAs': 'x-amz-expiration', }, 'ETag': { 'type': 'string', 'location': 'header', }, 'VersionId': { 'type': 'string', 'location': 'header', 'sentAs': 'x-amz-version-id', }, 'RequestId': { 'type': 'string', 'location': 'header', 'sentAs': 'x-amz-request-id', } } } Response Model HTTP/1.1 200 OK x-‐amz-‐id-‐2: 1234 x-‐amz-‐request-‐id: 5490 Date: Thu, 16 May 2013 00:01:48 GMT ETag: "3a4f009649c38ef10c..." Content-‐Length: 0 Server: AmazonS3 print_r($result->toArray()); Array ( [Expiration] => [ETag] => "3a4f009649c38ef10c..." [VersionId] => [RequestId] => "5490" )

Slide 89

Slide 89 text

Slide 90

Slide 90 text

Slide 91

Slide 91 text

5XJUUFSDMJFOU

Slide 92

Slide 92 text

No content

Slide 93

Slide 93 text

{ "name": "Twitter", "apiVersion": "1.1", "baseUrl": "https://api.twitter.com/1.1", "operations": { "GetMentions": { "httpMethod": "GET", "uri": "statuses/mentions_timeline.json", "responseClass": "GetMentionsOutput", "additionalParameters": { "location": "query" } } }, "models": { "GetMentionsOutput": { "type": "object", "additionalProperties": { "location": "json" } } } }

Slide 94

Slide 94 text

use Guzzle\Service\Description\ServiceDescription as S; // Set the description on the client $description = S::factory('/path/client.json'); $client->setDescription($description);

Slide 95

Slide 95 text

8IBUBCPVU 0"VUI use Guzzle\Plugin\Oauth\OauthPlugin; $plugin = new OauthPlugin([ 'consumer_key' => '***', 'consumer_secret' => '***', 'token' => '***', 'token_secret' => '***' ]); // Sign all requests with the OauthPlugin $client->addSubscriber($plugin);

Slide 96

Slide 96 text

// Create and execute the GetMentions operation $model = $client->getMentions(['count' => 3]); // The “model” is a Guzzle Model object echo $model['status'];

Slide 97

Slide 97 text

No content

Slide 98

Slide 98 text

$MJFOU'BDUPSZ

Slide 99

Slide 99 text

$MJFOU'BDUPSZ • Encapsulates bootstrapping of client

Slide 100

Slide 100 text

$MJFOU'BDUPSZ • Encapsulates bootstrapping of client • Provides input validation

Slide 101

Slide 101 text

$MJFOU'BDUPSZ • Encapsulates bootstrapping of client • Provides input validation • Used with a ServiceBuilder

Slide 102

Slide 102 text

use Guzzle\Common\Collection; use Guzzle\Plugin\Oauth\OauthPlugin; use Guzzle\Service\Description\ServiceDescription; class TwitterClient extends Guzzle\Service\Client { public static function factory($config = []) { $required = [ 'consumer_key', 'consumer_secret', 'token', 'token_secret' ]; // Merge in default settings and validate the config $config = Collection::fromConfig($config, [], $required); // Create a new Twitter client $client = new self(); $client->setConfing($config); $client->addSubscriber(new OauthPlugin($config->toArray())); return $client; } }

Slide 103

Slide 103 text

$twitter = TwitterClient::factory([ 'consumer_key' => '****', 'consumer_secret' => '****', 'token' => '****', 'token_secret' => '****' ]); $model = $client->getMentions(['count' => 3]);

Slide 104

Slide 104 text

0UIFSGFBUVSFT • Service builder conﬁgs • Resource iterators • Batching abstractions

Slide 105

Slide 105 text

'VUVSFPG(V[[MF • More tooling • OAuth2 Plugin • Simpliﬁed procedural API • What would you like to see?