Diving into guzzle

Diving Into Guzzle:
Getting the Most from Your Requests

Steven Wade - @stevenwadejrhttps://joind.in/talk/41978
About me
Steven Wade

• Husband, father

• Founder/Organizer of UpstatePHP

• Engineer at Follow Up Boss

Twitter: @stevenwadejr

Email: stevenwadejr@gmail.com

Austin, we have a problem

HTTP Requests are Hard

• URLs

• URLs
• Headers

• URLs
• Headers
• GET, POST, PUT, DELETE, ...

• URLs
• Headers
• Status codes

• URLs
• Headers
• Status codes
• Sending a request

• URLs
• Headers
• Status codes
• Parsing a response

• URLs
• Headers
• Status codes
• Parsing a response
• Handling errors

ﬁle_get_contents()
$apiKey = 'my_api_key:';
$people = file_get_contents(
'https://' . $apiKey . '@api.followupboss.com/v1/people'
);

How do we make HTTP
requests in PHP?

Streams

Streams
✓ Built-in to PHP - ﬁle_get_contents(), fopen()

Streams
๏ More complicated requests require stream contexts

Streams
๏ Don't support persistent connections

Streams
๏ Don't support persistent connections
๏ Don't support parallel requests

cURL

cURL
✓ Supports persistent connections

cURL
✓ Supports parallel requests

cURL
✓ Most common way of making external requests

cURL
๏ Not built-in: requires library and extension

cURL
๏ Clunky and confusing API

cURL
๏ Clunky and confusing API
๏ Cumbersome error handling

cURL - example
$baseUrl = 'https://api.followupboss.com/v1';
$headers = [
'Accept: application/json',
'Content-Type: application/json'
];
$handle = curl_init();
curl_setopt($handle, CURLOPT_URL, $baseUrl . '/people');
curl_setopt($handle, CURLOPT_HTTPHEADER, $headers);
curl_setopt($handle, CURLOPT_USERPWD, 'my_api_key:');
curl_setopt($handle, CURLOPT_CONNECTTIMEOUT, 2);
curl_setopt($handle, CURLOPT_RETURNTRANSFER, 1);
$people = curl_exec($handle);
curl_setopt($handle, CURLOPT_URL, $baseUrl . '/tasks');
$tasks = curl_exec($handle);
curl_close($handle);

cURL - errors?

cURL - error handling
$people = curl_exec($handle);
if(curl_errno($handle)){
echo 'Request Error:' . curl_error($handle);
}

• Understand the basics of making requests with Guzzle

• Understand the concept of middleware and how to use it
within your requests

• Be able to make asynchronous requests

• Be able to make asynchronous requests
• Know how to test your HTTP requests

GUZZLE
[angelic singing]

What is Guzzle?
"Guzzle is a PHP HTTP client that makes it easy to send HTTP requests
and trivial to integrate with web services."
http://docs.guzzlephp.org

Guzzle Provides:
•Simple interface for building query strings, POST requests, uploading JSON data, etc...
•Can send both synchronous and asynchronous requests using the same interface.
•Uses PSR-7 interfaces for requests, responses, and streams.
•Abstracts away the underlying HTTP transport (can use streams, cURL, other).
•Middleware system allows you to augment and compose client behavior.

Installing Guzzle
composer require guzzlehttp/guzzle

Basic Request with Guzzle
$client = new GuzzleHttpClient;
$response = $client->get('http://example.com/foo');

PSR-7

What is PSR-7?
"Describes common interfaces for representing HTTP messages as
described in RFC 7230 and RFC 7231, and URIs for use with HTTP
messages as described in RFC 3986."

Huh?

What is PSR-7?
POST /path HTTP/1.1
Host: example.com
foo=bar&baz=bat

What is PSR-7?
POST /path HTTP/1.1
Host: example.com
foo=bar&baz=bat
Request
Method

What is PSR-7?
POST /path HTTP/1.1
Host: example.com
foo=bar&baz=bat
Request
Method
Request
Target

What is PSR-7?
POST /path HTTP/1.1
Host: example.com
foo=bar&baz=bat
Request
Method
Request
Target
Protocol
Version

What is PSR-7?
POST /path HTTP/1.1
Host: example.com
foo=bar&baz=bat
Headers
Request
Method
Request
Target
Protocol
Version

What is PSR-7?
POST /path HTTP/1.1
Host: example.com
foo=bar&baz=batBody
Headers
Request
Method
Request
Target
Protocol
Version

What is PSR-7?
MessageInterface
- getHeaders()
- hasHeader()
- getHeader()
- getBody()
- withHeader()
- withBody()
RequestInterface
- getMethod()
- getUri()
- withMethod()
- withUri()
ResponseInterface
- getStatusCode()
- getReasonPhrase()
- withStatus()

PSR-7 - Why?
Who uses it? Why use it?

PSR-7 - Why?
By default:

PSR-7 - Why?
By default:
• Guzzle

PSR-7 - Why?
By default:
• Guzzle
• LeagueRoute

PSR-7 - Why?
By default:
• Guzzle
• LeagueRoute
• Slim Framework

PSR-7 - Why?
By default:
• Guzzle
• LeagueRoute
• Slim Framework
Via a bridge:

PSR-7 - Why?
By default:
• Guzzle
• LeagueRoute
• Slim Framework
Via a bridge:
• Laravel

PSR-7 - Why?
By default:
• Guzzle
• LeagueRoute
• Slim Framework
Via a bridge:
• Laravel
• Symfony

PSR-7 - Why?
By default:
• Guzzle
• LeagueRoute
• Slim Framework
Via a bridge:
• Laravel
• Symfony
• Standard representation of
HTTP requests and responses

PSR-7 - Why?
By default:
• Guzzle
• LeagueRoute
• Slim Framework
Via a bridge:
• Laravel
• Symfony
• Standard representation of
HTTP requests and responses
• Useful in an API proxy/gateway
and combined with a PSR-7
router

Middleware

What is middleware?

What is middleware?
Diagram stolen from Slim Framework showing how HTTP middleware layers wrap an application.

What is middleware?
Diagram stolen from Slim Framework showing how HTTP middleware layers wrap an application.
Request
Response
cURL

Middleware
Examples

Middleware - Defaults

• HTTP Errors

• HTTP Errors
• Redirect

• HTTP Errors
• Redirect
• Cookies

• HTTP Errors
• Redirect
• Cookies
• Prepare Body

• HTTP Errors
• Redirect
• Cookies
• Prepare Body
• HandlerStack::create()

Middleware - Tap
GuzzleHttpMiddleware::tap($before, $after);

Middleware - Tap
use LeagueStatsDClient as StatsD;
$stack = GuzzleHttpHandlerStack::create();
$statsd = new StatsD;
$statsd->configure([...]);
$stack->push(GuzzleHttpMiddleware::tap(function () use ($statsd) {
$statsd->increment('apikey.usage');
}));

Middleware - Tap
$stack->push(Middleware::tap(function ($request) use ($statsd) {
$authHeader = $request->getHeader('Authorization');
$encoded = str_replace('Basic ', '', $authHeader[0]);
$auth = base64_decode($encoded);
[$username] = explode(':', $auth);
$statsd->increment('apikey.usage.username.' . $username);
}));

Middleware - Tap
$stack->push(Middleware::tap(app()->make(ApiKeyUsage::class)));
class ApiKeyUsage {
private $statsd;
public function __construct(StatsD $statsd) {
$this->statsd = $statsd;
}
public function __invoke(RequestInterface $request, array $options) {
$this->statsd->increment('apikey.usage');
}
}

Middleware - Log
GuzzleHttpMiddleware::log($logger, $messageFormatter);

Middleware - Log
$logger = new MonologLogger('http');
$logger->pushHandler(
new MonologHandlerStreamHandler(
'path/to/your.log',
MonologLogger::INFO
)
);
$stack = GuzzleHttpHandlerStack::create();
$stack->push(GuzzleHttpMiddleware::log(
$logger,
new GuzzleHttpMessageFormatter
));

Middleware - Retry
GuzzleHttpMiddleware::retry($decider, $delay);

Middleware - Retry
$stack->push(GuzzleHttpMiddleware::retry(
function ($retries, $request, $response) {
return $response->getStatusCode() >= 500 && $retries < 4;
},
function ($retries) {
return ++$retries * 1000;
}
));

Middleware - Retry

Middleware - Retry
class RetryMiddleware {
public function shouldRetry(int $retries, $request, $response): bool {
// normal checks go here
$body = json_encode($response->getBody()->getContents(), true);
$error = $body['error'] ?? null;
if ($response->getStatusCode() === 400
&& $error === 'expired_token'
) {
$this->accessToken->expiresAt = 0;
$this->accessToken->save();
return true;
}
return false;
}

Middleware - Retry
$retryMiddleware = new RetryMiddleware($accessToken);
$stack->push(Middleware::retry(
[$retryMiddleware, 'shouldRetry'],
[$retryMiddleware, 'getDelay']
));

Middleware - Custom
$stack->push(function (callable $handler) {
return function (
RequestInterface $request,
array $options
) use ($handler) {
// do stuff
return $handler($request, $options);
};
});

Middleware - Custom (OAuth)
class OAuthTokenMiddleware {
public function __invoke(RequestInterface $request, array $options) {
if ($this->accessToken->hasExpired()) {
$this->accessToken = $this->provider->refreshToken(
$this->accessToken
);
}
$request = $request->withHeader(
'Authentication',
'Bearer ' . (string) $this->accessToken
);
return $this->nextHandler($request, $options);
}
}

Middleware
• Handling failed requests

Middleware
• Modify responses

Middleware
• Cache

Middleware
• Cache
• More...

Let's build something

New Lead - cURL

New Lead - cURL
$baseUrl = 'https://api.followupboss.com/v1';
$headers = [
'Accept: application/json',
'Content-Type: application/json'
];
$payload = json_encode([
'source' => 'longhornphp.com',
'system' => 'LonghornPHP',
'type' => 'General Inquiry',
'person' => [
'firstName' => 'Fox',
'lastName' => 'Mulder',
'source' => 'cURL',
'emails' => [
['value' => 'fox.mulder@fbi.gov'],
['value' => 'spooky@iwanttobelieve.org']
]
]
]);

New Lead - cURL
$handle = curl_init();
curl_setopt($handle, CURLOPT_URL, $baseUrl . '/events');
curl_setopt($handle, CURLOPT_HTTPHEADER, $headers);
curl_setopt($handle, CURLOPT_USERPWD, 'my_api_key:');
curl_setopt($handle, CURLOPT_CONNECTTIMEOUT, 2);
curl_setopt($handle, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($handle, CURLINFO_HEADER_OUT, 1);
curl_setopt($handle, CURLOPT_POST, 1);
curl_setopt($handle, CURLOPT_POSTFIELDS, $payload);
$response = curl_exec($handle);
curl_close($handle);
echo $response;

New Lead - Guzzle
use GuzzleHttpClient;
$client = new Client([
'base_uri' => 'https://api.followupboss.com/v1/',
'auth' => ['my_api_key', '']
]);
try {
$response = $client->post(
'events',
['json' => $leadData, 'headers' => $headers]
);
$lead = json_decode($response->getBody()->getContents(), true);
print_r($lead);
} catch (Exception $e) {
echo $e->getMessage();
}

Get /people - via Guzzle
$client = new GuzzleHttpClient([
'base_uri' => $baseUrl,
'auth' => ['my_api_key', '']
]);
try {
$response = $client->get('people', ['headers' => $headers]);
$people = json_decode($response->getBody()->getContents(), true);
// handle errors
}

Dashboard
$request = new GuzzleHttpPsr7Request('GET', 'people', $headers);
try {
$response = $client->send($request);
$people = json_decode($response->getBody()->getContents(), true);
$response = $client->send($request->withUri(
new GuzzleHttpPsr7Uri('tasks')
));
$tasks = json_decode($response->getBody()->getContents(), true);
// handle errors
}

JsonStream
use GuzzleHttpPsr7StreamDecoratorTrait;
use PsrHttpMessageStreamInterface;
class JsonStream implements StreamInterface {
use StreamDecoratorTrait;
public function json(): ?array {
return json_decode((string) $this->getContents(), true);
}
}

JsonStream
$stack = HandlerStack::create();
$stack->push(Middleware::mapResponse(
function (ResponseInterface $response) {
$jsonStream = new JsonStream($response->getBody());
return $response->withBody($jsonStream);
}
));

Dashboard
try {
$people = $response->getBody()->json();
$response = $client->send($request->withUri(new Uri('tasks')));
$tasks = $response->getBody()->json();
// handle errors
}

Dashboard
$request = new Request('GET', 'people', $headers);
$people = $response->getBody()->json();
$response = $client->send($request->withUri(new Uri('tasks')));
$tasks = $response->getBody()->json();
$response = $client->send($request->withUri(new Uri('events')));
$events = $response->getBody()->json();
$response = $client->send($request->withUri(new Uri('calls')));
$calls = $response->getBody()->json();

Async Requests

Blocking Requests
$delays = [5000, 2500, 1000, 500, 0];
foreach ($delays as $delay) {
echo "Making request [delay = $delay]n";
$client->get('https://mockbin.org/delay/' . $delay);
echo "Response received [delay = $delay]n";
}

Blocking Requests

Concurrent Requests
$delays = [5000, 2500, 1000, 500, 0];
$promises = [];
foreach ($delays as $delay) {
echo "Making request [delay = $delay]n";
$url = 'https://mockbin.org/delay/' . $delay;
$promises[] = $client->getAsync($url)
->then(function() use ($delay) {
echo "Response received [delay = $delay]n";
});
}
GuzzleHttpPromiseunwrap($promises);

Concurrent Requests

How do we send async requests?
$client->send($request)

How do we send async requests?
$client->send($request)
$client->sendAsync($request)

What is a Promise?

What is a Promise?
"A Promise is an object representing the eventual
result of an asynchronous operation"
https://amphp.org/amp/promises/

Promises
$promise = $client->sendAsync($request);
$promise->then(
echo $response->getStatusCode() . "n";
},
function (RequestException $e) {
echo $e->getMessage() . "n";
echo $e->getRequest()->getMethod();
}
);

Promises
$promise = $promise->then(
return json_decode(
$response->getBody()->getContents(),
true
);
});

Promises
$result = $promise->then(
return json_decode(
$response->getBody()->getContents(),
true
);
})
->wait();

Dashboard - Async
$endpoints = ['people', 'tasks', 'events', 'calls'];
$promises = [];
foreach ($endpoints as $endpoint) {
$request = new Request('GET', $endpoint, $headers);
$promises[$endpoint] = $client->sendAsync($request)
->then(function (ResponseInterface $response) use ($endpoint) {
$json = $response->getBody()->json();
return $json[$endpoint] ?? [];
});
}
try {
$results = GuzzleHttpPromiseunwrap($promises);
echo $e->getMessage();
}

GuzzleHttpPromisefunctions

// Waits on all of the provided promises
// and returns the fulfilled values.
unwrap($promises);

unwrap($promises);
// Returns a promise that is fulfilled when
// all the items in the array are fulfilled.
all($promises);

unwrap($promises);
// all the items in the array are fulfilled.
all($promises);
// all of the provided promises have
// been fulfilled or rejected.
settle($promises);

Coroutines
"Coroutines are a general control structure whereby ﬂow control is
cooperatively passed between two different routines without returning."
- user21714
https://stackoverflow.com/questions/553704/what-is-a-coroutine

Coroutines
"Coroutines are interruptible functions"
https://amphp.org/amp/coroutines/

Dashboard - Coroutines
$endpoints = ['people', 'tasks', 'events', 'calls'];
$promises = [];
foreach ($endpoints as $endpoint) {
$promises[$endpoint] = new GuzzleHttpPromiseCoroutine(
function() use ($client, $endpoint, $headers) {
$response = yield $client->sendAsync($request);
yield $json[$endpoint] ?? [];
}
);
}

Dashboard - Coroutines
new GuzzleHttpPromiseCoroutine(
function() use ($client, $endpoint, $headers) {
$response = yield $client->sendAsync($request);
yield $json[$endpoint] ?? [];
}
);

Why use coroutines?

Why use coroutines?
• Avoid multiple/chained callbacks

Why use coroutines?
• Code ﬂows more naturally

Why use coroutines?
• Code ﬂows more naturally
• Use try/catch to handle errors

Testing

Mock Handler
// Create a mock and queue two responses.
$mock = new GuzzleHttpHandlerMockHandler([
new Response(200, ['X-Foo' => 'Bar']),
new Response(202, ['Content-Length' => 0]),
new RequestException('Server error', new Request('GET', 'test'))
]);
$handler = GuzzleHttpHandlerStack::create($mock);
$client = new GuzzleHttpClient(['handler' => $handler]);
// The first request is intercepted with the first response.
echo $client->request('GET', '/')->getStatusCode(); //> 200
// The second request is intercepted with the second response.
echo $client->request('GET', '/')->getStatusCode(); //> 202

History Middleware
$container = [];
$history = Middleware::history($container);
$mockHandler = new GuzzleHttpHandlerMockHandler([
new Response(200)
]);
$stack = HandlerStack::create($mockHandler);
$stack->push($history);
$client = new Client([
'base_uri' => $baseUrl,
'handler' => $stack
]);

History Middleware
$client->request('GET', 'people', ['headers' => $headers]);
foreach ($container as $transaction) {
echo $transaction['request']->getMethod();
if ($transaction['response']) {
echo $transaction['response']->getStatusCode();
} elseif ($transaction['error']) {
echo $transaction['error'];
}
}

History Middleware
$this->assertEquals(
'Swade-Co',
$transaction['request']->getHeader('X-System')[0]
);

Comments/Questions/Concerns/Hate Mail
Twitter: @stevenwadejr

Email: stevenwadejr@gmail.com
https://joind.in/talk/41978

Diving into guzzle

More Related Content

Similar to Diving into guzzle

Recently uploaded

Diving into guzzle