mirror_php/guzzle
1
0
Fork 0
mirror of https://github.com/guzzle/guzzle.git synced 2025-01-17 13:28:13 +01:00
Code Issues Releases Wiki Activity

Updating readme

Browse Source
This commit is contained in:
Michael Dowling 2011-03-02 17:34:42 -06:00
parent 0448c6d64c
commit 519fa1be42
1 changed files with 132 additions and 36 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

168
README.md
View File

@ -1,80 +1,176 @@
# Guzzle is a PHP framework for building RESTful web service clients
Overview
========
Most web service clients follow a specific pattern: create a client class, create methods for each action that can be taken on the API, create a cURL handle to transfer an HTTP request to the client, and return the response. You've probably had to interact with an API that either doesn't have a PHP webservice client or the currently available PHP clients are not up to an acceptable level of quality. When facing these types of situations, you probably find yourself writing a webservice client that lacks advanced features such as persistent HTTP connections, parallel requests, over the wire logging, a PHP based caching forward proxy, a service configuration object, or exponential backoff. Why would you spend the amount of time required to write those features though? It's just a simple webservice client for just one of the many APIs you might be using. But then you build another client... and another. Suddenly you find yourself with several web service clients to maintain, each reeking of code duplication and lacking most, if not all, of the aforementioned features. Enter Guzzle.
## What is Guzzle?
Guzzle gives PHP developers a simple to extend framework for building robust webservice clients that helps to eliminate code duplication by leveraging the patterns and solutions already coded into the framework.
Guzzle is a PHP framework for building REST webservice clients. Guzzle provides the tools necessary to quickly build a testable webservice client with complete control over preparing HTTP requests and processing HTTP responses. Guzzle helps on the HTTP layer by allowing requests to be sent in parallel, automatically managing persistent cURL connections between requests for multiple hosts, and providing various pluggable behaviors for HTTP transactions (exponential backoff, over the wire logging, caching, cookies, etc...).
## Guzzle gives PHP developers complete control over HTTP requests while utilizing HTTP/1.1 best practices.
Guzzle makes writing services an easy task by providing a simple pattern to follow:
### Control over HTTP requests
1. Extend the default client class
2. Create a client builder if needed
3. Create commands for each API action. Guzzle uses the command pattern.
4. Add the service definition to your services.xml file
Guzzle gives PHP developers a tremendous amount of control over HTTP requests. Guzzle's HTTP namespace provides a wrapper over the PHP libcurl bindings. Most of the functionality implemented in the libcurl bindings has been simplified and abstracted by Guzzle. Developers who need access to cURL specific functionality that is not abstracted by Guzzle (e.g. proxies) can still add cURL handle specific behavior to Guzzle HTTP requests.
Michael Dowling, lead developer of SHOEBACCA.com and the Guzzle project, has written many PHP webservice clients during his time at SHOEBACCA.com:
### Send HTTP requests in parallel
> With the growth of our company came the growth of our website's feature set and the amount of web services we had to interact with. We were consistently being tasked with integrating new web services. Some of the services we integrated with had existing PHP clients, but sadly, most PHP clients seemed like more of an afterthough or were written in 2005. After we created several clients with very similar functionality, I realized the need for a webservice client framework that could reduce code duplication, make it dead simple to create a testable client, and give developers access to a broad range of HTTP and webservice related functionality.
Guzzle helps PHP developers utilize HTTP/1.1 best practices including sending requests in parallel and utilizing persistent (keep-alive) HTTP connections. Sending many HTTP requests serially (one at a time) can cause an unnecessary delay in a script's execution. Each request must complete before a subsequent request can be sent. By sending requests in parallel, a pool of HTTP requests can complete at the speed of the slowest request in the pool, significantly reducing the amount of time needed to execute multiple HTTP requests. Guzzle provides a wrapper for the curl_multi functions in PHP.
Because of Guzzle, now I don't cringe as much when my boss comes into my office telling me that we have a new API to integrate into our application.
### Managed persistent HTTP connections
Most web service clients follow a specific pattern: create a client class, create methods for each action that can be taken on the API, create a cURL handle to transfer an HTTP request to the client, parse the response, implement error handling, and return the result. You've probably had to interact with an API that either doesn't have a PHP client or the currently available PHP clients are not up to an acceptable level of quality. When facing these types of situations, you probably find yourself writing a webservice that lacks most of the advanced features mentioned by Michael. It wouldn't make sense to spend all that time writing those features-- it's just a simple webservice client for just one API... But then you build another client... and another. Suddenly you find yourself with several web service clients to maintain, each client a God class, each reeking of code duplication and lacking most, if not all, of the aforementioned features. Enter Guzzle.
Another extremely important aspect of the HTTP/1.1 protocol that is often overlooked by PHP webservice clients is persistent HTTP connections. Persistent connections allows data to be transferred between a client and server without the need to reconnect each time a subsequent request is sent, providing a significant performance boost to applications that need to send many HTTP requests to the same host.
## Installing Guzzle
HTTP requests and cURL handles are separate entities in Guzzle. In order for a request to get a cURL handle to transfer its message to a server, a request retrieves a cURL handle from a cURL handle factory. The default cURL handle factory will maintain a pool of open cURL handles and return an already existent cURL handle (with a persistent HTTP connection) if available, or create a new cURL handle.
Contributors should install Guzzle using git::
### Plugins for common HTTP request behavior
git clone https://mtdowling@github.com/guzzle/guzzle.git
#### Over the wiring logging
Install Guzzle using pear when using Guzzle in production::
Easily troubleshoot errors by logging everything that goes over the wire upstream and downstream, including redirect requests and entity bodies.
pear channel-discover pearhub.org
pear install pearhub/guzzle
#### Truncated exponential backoff
You will need to add Guzzle to your application's autoloader. Guzzle ships with a few select classes from other vendors, one of which is the Symfony2 universal class loader. If your application does not already use an autoloader, you can use the autoloader distributed with Guzzle:
Automatically retries HTTP requests using truncated exponential backoff.
<?php
#### PHP-based caching forward proxy
require_once '/path/to/guzzle/library/vendor/Symfony/Component/ClassLoader/UniversalClassLoader.php';
Provides a simple private transparent proxy cache that caches HTTP responses using HTTP headers to control caching behavior, cache lifetime, and supports ETag and Last-Modified based revalidation.
$classLoader = new \Symfony\Component\ClassLoader\UniversalClassLoader();
$classLoader->registerNamespaces(array(
'Guzzle' => '/path/to/guzzle/library'
));
$classLoader->register();
#### Cookie session plugin
__Substitute '/path/to/' with the full path to your Guzzle installation. You can find the PEAR installation folder using pear config-get php_dir__
Maintains cookies between HTTP requests. Supports cookie version 1 and 2.
## Installing services
## Guzzle enables PHP developers to quickly create web service clients.
### Current Services
PHP webservice clients can be created in one of two ways in Guzzle: using a concrete client or a dynamic client. Concrete clients use a Command class for each action that can be taken on a webservice, while dynamic clients dynamically build HTTP requests based on an XML service description. Concrete clients are more feature rich and testable than dynamic clients, while dynamic clients are quicker to implement.
Guzzle services are distributed separately from the Guzzle framework. Guzzle officially supports a few webservice clients (these clients are currently what we use at SHOEBACCA.com), and hopefully there will be third-party created services coming soon:
## Guzzle provides a catalog of fully featured web service clients.
-[Amazon Webservices (AWS)](https://github.com/guzzle/guzzle-aws)
* Amazon S3
* Amazon SimpleDB
* Amazon SQS
* Amazon MWS
-[Unfuddle](https://github.com/guzzle/guzzle-unfuddle)
-[Cardinal Commerce](https://github.com/guzzle/guzzle-cardinal-commerce)
Guzzle currently provides web service clients for Amazon S3, Amazon SQS, Amazon SimpleDB, Amazon MWS, Cardinal Commerce, and Unfuddle. Many more APIs are to follow, and hopefully other developers can contribute to the growing catalog of Guzzle webservice clients.
When installing a Guzzle service, check the service's installation instructions for specific examples on how to install the service. Most services can be installed using a git submodule or, if available, a PEAR package through pearhub.org::
pear install pearhub/guzzle-aws # Note: this might not work while we're still finalizing our deployment methods
Services can also be installed using git submodules::
git submodule add git://github.com/guzzle/guzzle-aws.git /path/to/guzzle/library/Guzzle/Service/Aws
### Autoloading Services
Services that are installed within the path to Guzzle under the Service folder will be autoloaded automatically using the autoloader settings configured for the Guzzle library (e.g. /Guzzle/Service/Aws). If you install a Guzzle service outside of this directory structure, you will need to add the service to the autoloader.
## Using Services
Let's say you want to use the Amazon S3 client from the Guzzle AWS service.
1. Create a services.xml file:
Create a services.xml that your ServiceBuilder will use to create service clients. The services.xml file defines the clients you will be using and the arguments that will be passed into the client when it is constructed. Each client + arguments combination is given a name and referenced by name when retrieving a client from the ServiceBuilder.
<?xml version="1.0" ?>
<guzzle>
<clients>
<!-- Abstract service to store AWS account credentials -->
<client name="test.abstract.aws">
<param name="access_key_id" value="12345" />
<param name="secret_access_key" value="abcd" />
</client>
<client name="test.s3" builder="Guzzle.Service.Aws.S3.S3Builder" extends="test.abstract.aws">
<param name="devpay_product_token" value="" />
<param name="devpay_user_token" value="" />
</client>
</clients>
</guzzle>
2. Create a ServiceBuilder
<?php
use Guzzle\Service\Builder\ServiceBuilder;
$serviceBuilder = ServiceBuilder::factory('/path/to/services.xml');
3. Get the Amazon S3 client from the ServiceBuilder and execute a command
<?php
use Guzzle\Service\Aws\S3\Command\Object\GetObject;
$client = $serviceBuilder->getClient('test.s3');
$command = new GetObject();
$command->setBucket('mybucket')->setKey('mykey');
// The result of the GetObject command returns the HTTP response object
$httpResponse = $client->execute($command);
echo $httpResponse->getBody();
The GetObject command just returns the HTTP response object when it is executed. Other commands might return more valuable information when executed:
<?php
use Guzzle\Service\Aws\S3\Command\Bucket\ListBucket;
$command = new ListBucket();
$command->setBucket('mybucket');
$objects = $client->execute($command);
// Iterate over every single object in the bucket
// subsequent requests will be issued to retreive
// the next result of a truncated response
foreach ($objects as $object) {
echo "{$object['key']} {$object['size']}\n";
}
// You can get access to the HTTP request issued by the command and the response
echo $command->getRequest();
echo $command->getResponse();
The ListBucket command above returns a BucketIterator which will iterate over the entire contents of a bucket. As you can see, commands can be as simple or complex as you want.
If the above code samples seem a little verbose to you, you can take some shortcuts in your code by leveraging the Guzzle command factory inherent to each client:
<?php
$objects = $client->getCommand('bucket.list_bucket', array('bucket' => 'my_bucket'))->execute();
## Guzzle is extremely well tested
Guzzle is used in production a mutli-million dollar e-commerce company. Guzzle has 100% code coverage; every line of Guzzle has been tested using PHPUnit.
## Quick examples
## Examples of sending HTTP requests
### GET the google homepage
### GET the google.com homepage
<?php
use Guzzle\Http\Message\RequestFactory;
// Use the RequestFactory to create a GET request
$message = RequestFactory::getInstance()->newRequest('GET', 'http://www.google.com/');
// Send the request and retrieve the response object
$request = RequestFactory::getInstance()->newRequest('GET', 'http://www.google.com/');
$response = $message->send();
echo $response->getStatusCode() . "\n";
// Echo the raw HTTP request
echo $request;
// Echo the raw HTTP response
echo $response;
### Clear the contents of an Amazon S3 bucket
### POST to a Solr server
<?php
use Guzzle\Service\Aws\S3\Command\Bucket\ClearBucket;
$command = new ClearBucket();
$command->setBucket('test');
$client = $this->getServiceBuilder()->getClient('michael.s3');
$client->execute($command);
$request = RequestFactory::getInstance()->newRequest('POST', 'http://localhost:8983/solr/update');
$request->addPostFiles(array(
'file' => '/path/to/documents.xml'
));
$request->send();