Esta página fornece uma rápida introdução ao Guzzle e exemplos introdutórios. Se ainda não instalou, Guzzle, dirija-se à Installation página.
Pode enviar pedidos com Guzzle usando um objecto GuzzleHttp\ClientInterface
.
use GuzzleHttp\Client;
$client = new Client([
// Base URI is used with relative requests
'base_uri' => 'http://httpbin.org',
// You can set any number of default request options.
'timeout' => 2.0,
]);
Os clientes são imutáveis em Guzzle, o que significa que não se pode alterar os padrões utilizados por um cliente após a sua criação.
O construtor cliente aceita um leque associativo de opções:
base_uri
(string|UriInterface) URI base do cliente que é fundido em relativo URIs. Pode ser um fio ou instância de UriInterface. Quando um URI relativo é fornecido a um cliente, o cliente irá combinar o URI de base com o URI relativa usando as regras descritas em RFC 3986, secção 5.2.
// Criar um cliente com um URI base
$client = novo GuzzleHttp\Client(['base_uri' => 'https://foo.com/api/']);
// Envie um pedido para https://foo.com/api/test
$resposta = $client->pedido('GET', 'teste');
// Enviar um pedido para https://foo.com/root
$response = $client->request('GET', '/root');
Não lhe apetece ler o RFC 3986? Aqui estão alguns exemplos rápidos sobre como um base_uri
é resolvido com outro URI.
base_uri
URI
Resultado
http://foo.com
/bar
http://foo.com/bar
http://foo.com/foo
/bar
http://foo.com/bar
http://foo.com/foo
bar
http://foo.com/bar
http://foo.com/foo/
bar
http://foo.com/foo/bar
http://foo.com
http://baz.com
http://baz.com
http://foo.com/?bar
bar
http://foo.com/bar
handler
Psr7\Http\Message\RequestInterface
e array
de opções de transferência, e deve devolver um
GuzzleHttp\Promise\PromiseInterface
que é cumprida com um
Psr7\Http\Message\ResponseInterface
sobre o sucesso....
Os métodos mágicos sobre o cliente facilitam o envio de pedidos síncronos:
$response = $client->get('http://httpbin.org/get');
$response = $client->delete('http://httpbin.org/delete');
$response = $client->head('http://httpbin.org/get');
$response = $client->options('http://httpbin.org/get');
$response = $client->patch('http://httpbin.org/patch');
$response = $client->post('http://httpbin.org/post');
$response = $client->put('http://httpbin.org/put');
Pode criar um pedido e depois enviar o pedido com o cliente quando estiver pronto:
use GuzzleHttp\Psr7\Request;
$request = new Request('PUT', 'http://httpbin.org/put');
$response = $client->send($request, ['timeout' => 2]);
Os objectos do cliente proporcionam uma grande flexibilidade na forma como os pedidos são transferido, incluindo opções de pedido padrão, middleware de pilha de manipuladores padrão que são utilizados por cada pedido, e uma URI de base que lhe permite enviar pedidos com URIs relativas.
Pode saber mais sobre middleware de clientes na página Handlers and Middleware page of the documentation.
Pode enviar pedidos assíncronos utilizando os métodos mágicos fornecidos por um cliente:
$promise = $client->getAsync('http://httpbin.org/get');
$promise = $client->deleteAsync('http://httpbin.org/delete');
$promise = $client->headAsync('http://httpbin.org/get');
$promise = $client->optionsAsync('http://httpbin.org/get');
$promise = $client->patchAsync('http://httpbin.org/patch');
$promise = $client->postAsync('http://httpbin.org/post');
$promise = $client->putAsync('http://httpbin.org/put');
Também pode utilizar os métodos sendAsync() e requestAsync() de um cliente:
use GuzzleHttp\Psr7\Request;
// Create a PSR-7 request object to send
$headers = ['X-Foo' => 'Bar'];
$body = 'Hello!';
$request = new Request('HEAD', 'http://httpbin.org/head', $headers, $body);
$promise = $client->sendAsync($request);
// Or, if you don't need to pass in a request instance:
$promise = $client->requestAsync('GET', 'http://httpbin.org/get');
A promessa devolvida por estes métodos implementa a
Promises/A+ spec, fornecido pela
Guzzle promete biblioteca. Isto significa
que se pode encadear then()
cancelamentos da promessa. Estas chamadas são então
ou cumprida com sucesso Psr\Http\Message\ResponseInterface
ou
rejeitado, com uma excepção.
use Psr\Http\Message\ResponseInterface;
use GuzzleHttp\Exception\RequestException;
$promise = $client->requestAsync('GET', 'http://httpbin.org/get');
$promise->then(
function (ResponseInterface $res) {
echo $res->getStatusCode() . "\n";
},
function (RequestException $e) {
echo $e->getMessage() . "\n";
echo $e->getRequest()->getMethod();
}
);
Pode enviar vários pedidos em simultâneo usando promessas e pedidos assíncronos.
use GuzzleHttp\Client;
use GuzzleHttp\Promise;
$client = new Client(['base_uri' => 'http://httpbin.org/']);
// Initiate each request but do not block
$promises = [
'image' => $client->getAsync('/image'),
'png' => $client->getAsync('/image/png'),
'jpeg' => $client->getAsync('/image/jpeg'),
'webp' => $client->getAsync('/image/webp')
];
// Wait for the requests to complete; throws a ConnectException
// if any of the requests fail
$responses = Promise\Utils::unwrap($promises);
// You can access each response using the key of the promise
echo $responses['image']->getHeader('Content-Length')[0];
echo $responses['png']->getHeader('Content-Length')[0];
// Wait for the requests to complete, even if some of them fail
$responses = Promise\Utils::settle($promises)->wait();
// Values returned above are wrapped in an array with 2 keys: "state" (either fulfilled or rejected) and "value" (contains the response)
echo $responses['image']['state']; // returns "fulfilled"
echo $responses['image']['value']->getHeader('Content-Length')[0];
echo $responses['png']['value']->getHeader('Content-Length')[0];
Pode usar o objecto GuzzleHttp\Pool
quando tem uma quantidade indeterminada de pedidos que deseja enviar.
use GuzzleHttp\Client;
use GuzzleHttp\Exception\RequestException;
use GuzzleHttp\Pool;
use GuzzleHttp\Psr7\Request;
use GuzzleHttp\Psr7\Response;
$client = new Client();
$requests = function ($total) {
$uri = 'http://127.0.0.1:8126/guzzle-server/perf';
for ($i = 0; $i < $total; $i++) {
yield new Request('GET', $uri);
}
};
$pool = new Pool($client, $requests(100), [
'concurrency' => 5,
'fulfilled' => function (Response $response, $index) {
// this is delivered each successful response
},
'rejected' => function (RequestException $reason, $index) {
// this is delivered each failed request
},
]);
// Initiate the transfers and create a promise
$promise = $pool->promise();
// Force the pool of requests to complete.
$promise->wait();
Ou utilizando um encerramento que retribuirá uma promessa assim que a piscina chamar o encerramento.
$client = new Client();
$requests = function ($total) use ($client) {
$uri = 'http://127.0.0.1:8126/guzzle-server/perf';
for ($i = 0; $i < $total; $i++) {
yield function() use ($client, $uri) {
return $client->getAsync($uri);
};
}
};
$pool = new Pool($client, $requests(100));
Nos exemplos anteriores, recuperámos uma variável $response
ou éramos
deu uma resposta a partir de uma promessa. O objecto de resposta implementa uma PSR-7
resposta, Psr\Http\Message\ResponseInterface
, e contém muitos
informação útil.
É possível obter o código de estado e a frase de razão da resposta:
$code = $response->getStatusCode(); // 200
$reason = $response->getReasonPhrase(); // OK
É possível recuperar os cabeçalhos da resposta:
// Check if a header exists.
if ($response->hasHeader('Content-Length')) {
echo "It exists";
}
// Get a header from the response.
echo $response->getHeader('Content-Length')[0];
// Get all of the response headers.
foreach ($response->getHeaders() as $name => $values) {
echo $name . ': ' . implode(', ', $values) . "\r\n";
}
O corpo de uma resposta pode ser recuperado usando o método getBody
. O corpo pode ser usado como uma corda, fundido a uma corda, ou usado como um fluxo como um objecto.
$body = $response->getBody();
// Implicitly cast the body to a string and echo it
echo $body;
// Explicitly cast the body to a string
$stringBody = (string) $body;
// Read 10 bytes from the body
$tenBytes = $body->read(10);
// Read the remaining contents of the body as a string
$remainingBytes = $body->getContents();
Pode fornecer parâmetros de cadeia de consulta com um pedido de várias maneiras.
Pode definir os parâmetros da cadeia de consulta no URI do pedido:
$response = $client->request('GET', 'http://httpbin.org?foo=bar');
Pode especificar os parâmetros da cadeia de consulta usando a opção de pedido query
como um array.
$client->request('GET', 'http://httpbin.org', [
'query' => ['foo' => 'bar']
]);
Fornecendo a opção como um array irá utilizar a função http_build_query
do PHP para formatar a string de consulta.
E finalmente, pode fornecer a opção query
request option as a string.
$client->request('GET', 'http://httpbin.org', ['query' => 'foo=bar']);
Guzzle fornece vários métodos para o carregamento de dados.
Pode enviar pedidos que contenham um fluxo de dados passando um fio,
recurso devolvido de fopen
, ou uma instância de um
Psr\Http\Message\StreamInterface
para a opção de pedido body
.
use GuzzleHttp\Psr7;
// Provide the body as a string.
$r = $client->request('POST', 'http://httpbin.org/post', [
'body' => 'raw data'
]);
// Provide an fopen resource.
$body = Psr7\Utils::tryFopen('/path/to/file', 'r');
$r = $client->request('POST', 'http://httpbin.org/post', ['body' => $body]);
// Use the Utils::streamFor method to create a PSR-7 stream.
$body = Psr7\Utils::streamFor('hello!');
$r = $client->request('POST', 'http://httpbin.org/post', ['body' => $body]);
Uma maneira fácil de carregar dados JSON e definir o cabeçalho apropriado é usando a opção de pedido json
:
$r = $client->request('PUT', 'http://httpbin.org/put', [
'json' => ['foo' => 'bar']
]);
Além de especificar os dados em bruto de um pedido usando a opção de pedido body
, Guzzle fornece abstracções úteis sobre o envio de dados POST.
O envio de application/x-www-form-urlencoded
POST requests requer que se especifiquem os campos POST como um array na form_params
request options.
$response = $client->request('POST', 'http://httpbin.org/post', [
'form_params' => [
'field_name' => 'abc',
'other_field' => '123',
'nested_field' => [
'nested' => 'hello'
]
]
]);
Pode enviar ficheiros juntamente com um formulário (multipart/form-data
pedidos POST),
usando a opção de pedido multipart
. multipart
aceita um array de
arrays associativos, onde cada array associativo contém as seguintes chaves:
Psr\Http\Message\StreamInterface
para stream
o conteúdo de um fluxo PSR-7.use GuzzleHttp\Psr7;
$response = $client->request('POST', 'http://httpbin.org/post', [
'multipart' => [
[
'name' => 'field_name',
'contents' => 'abc'
],
[
'name' => 'file_name',
'contents' => Psr7\Utils::tryFopen('/path/to/file', 'r')
],
[
'name' => 'other_file',
'contents' => 'hello',
'filename' => 'filename.txt',
'headers' => [
'X-Foo' => 'this is an extra header to include'
]
]
]
]);
Guzzle pode manter uma sessão de cookie para si se instruído usando o
cookies
opção de pedido. Ao enviar um pedido, a opção cookies
opção
deve ser definido para uma instância de GuzzleHttp\Cookie\CookieJarInterface
.
// Use a specific cookie jar
$jar = new \GuzzleHttp\Cookie\CookieJar;
$r = $client->request('GET', 'http://httpbin.org/cookies', [
'cookies' => $jar
]);
Pode definir cookies
para true
num construtor cliente se quiser utilizar um frasco de cookies partilhado para todos os pedidos.
// Use a shared client cookie jar
$client = new \GuzzleHttp\Client(['cookies' => true]);
$r = $client->request('GET', 'http://httpbin.org/cookies');
Existem diferentes implementações para a GuzzleHttp\Cookie\CookieJarInterface
:
GuzzleHttp\Cookie\CookieJar
class stores cookies as an array.GuzzleHttp\Cookie\FileCookieJar
class persiste os cookies não-sessão
utilizando um ficheiro com o formato JSON.GuzzleHttp\Cookie\SessionCookieJar
class persiste nos cookies
sessão de cliente.Pode colocar manualmente cookies num frasco de cookies com o construtor nomeado fromArray(array $cookies, $domain)
.
$jar = \GuzzleHttp\Cookie\CookieJar::fromArray(
[
'some_cookie' => 'foo',
'other_cookie' => 'barbaz1234'
],
'example.org'
);
Pode obter um cookie pelo seu nome com o método getCookieByName($name)
que retorna um método GuzzleHttp\Cookie\SetCookie
instance.
$cookie = $jar->getCookieByName('some_cookie');
$cookie->getValue(); // 'foo'
$cookie->getDomain(); // 'example.org'
$cookie->getExpires(); // expiration date as a Unix timestamp
Os biscoitos também podem ser obtidos numa matriz graças ao método toArray().
A interface GuzzleHttp\Cookie\CookieJarInterface
estende
Traversable
para que possa ser iterada num laço frontal.
O Guzzle seguirá automaticamente os redireccionamentos, a não ser que o diga para não o fazer. Pode personalizar o comportamento do redireccionamento usando a opção de pedido allow_redirects
.
true
para permitir redireccionamentos normais com um número máximo de 5
redirecciona. Esta é a configuração por defeito.false
para desactivar o redireccionamento.$response = $client->request('GET', 'http://github.com');
echo $response->getStatusCode();
// 200
O exemplo seguinte mostra que os redireccionamentos podem ser desactivados.
$response = $client->request('GET', 'http://github.com', [
'allow_redirects' => false
]);
echo $response->getStatusCode();
// 301
Vista
A seguinte vista em árvore descreve como as Excepções Guzzle dependem uma da outra.
. \RuntimeException
└── TransferException (implements GuzzleException)
├── ConnectException (implements NetworkExceptionInterface)
└── RequestException
├── BadResponseException
│ ├── ServerException
│ └── ClientException
└── TooManyRedirectsException
Guzzle lança excepções para erros que ocorrem durante uma transferência.
A GuzzleHttp\Exception\ConnectException
exception is thrown in the
caso de um erro de rede. Esta excepção estende-se de
GuzzleHttp\Exception\TransferException
.
A GuzzleHttp\Exception\ClientException
é atirado para 400
erros de nível se a opção de pedido http_errors
for definida como verdadeira. Isto
excepção estende-se de GuzzleHttp\Exception\BadResponseException
e
GuzzleHttp\Exception\BadResponseException
estende-se de
GuzzleHttp\Exception\RequestException
.
use GuzzleHttp\Psr7;
use GuzzleHttp\Psr7; use GuzzleHttp\Psr7; use GuzzleHttp\Psr7
tente {{
$client->request('GET', 'https://github.com/_abc_123_404');
} catch (ClientException $e) {
echo Psr7\Message::toString($e->getRequest()));
echo Psr7\Message::toString($e->getResponse()));
}
A GuzzleHttp\Exception\ServerException
é atirado para nível 500
erros se a opção de pedido http_errors
for definida como verdadeira. Isto
excepção estende-se de GuzzleHttp\Exception\BadResponseException
.
A GuzzleHttp\Exception\TooManyRedirectsException
é atirado quando também
muitos redireccionamentos são seguidos. Esta excepção estende-se de GuzzleHttp\Exception\RequestException
.
Todas as excepções acima referidas estendem-se de GuzzleHttp\Exception\TransferException
.
Guzzle expõe algumas variáveis de ambiente que podem ser usadas para personalizar o comportamento da biblioteca.
GUZZLE_CURL_SELECT_TIMEOUT
curl_multi_select()
. Alguns sistemas
têm problemas com a implementação de PHP curl_multi_select()
onde
chamar esta função resulta sempre em esperar pela duração máxima de
o tempo limite.HTTP_PROXY
Define o procurador a utilizar ao enviar pedidos usando o protocolo "http".
Nota: como a variável HTTP_PROXY pode conter entradas arbitrárias de utilizadores em alguns ambientes (CGI), a variável só é utilizada no SAPI CLI. Ver https://httpoxy.org para mais informações.HTTPS_PROXY
NO_PROXY
Guzzle pode utilizar definições ini PHP na configuração de clientes.
openssl.cafile