Quickstart¶

Denne side indeholder en hurtig introduktion til Guzzle og indledende eksempler. Hvis du ikke allerede har installeret Guzzle, kan du gå over til Installation side.

Indsendelse af en anmodning¶

Du kan sende anmodninger med Guzzle ved hjælp af et GuzzleHttp\ClientInterface objekt.

Oprettelse af en klient¶

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,
]);

Klienter er uforanderlige i Guzzle, hvilket betyder, at du ikke kan ændre de standardindstillinger, der anvendes af en klient, efter at den er oprettet.

Klientkonstruktøren accepterer et associerende array af indstillinger:

base_uri

(string|UriInterface) Basis-URI for den klient, der er slået sammen til relativ URI'er. Kan være en streng eller en instans af UriInterface. Når en relativ URI leveres til en klient, vil klienten kombinere basis-URI'en med den relative URI ved hjælp af de regler, der er beskrevet i RFC 3986, afsnit 5.2.

// Opret en klient med en basis-URI
$client = new GuzzleHttp\Client(['base_uri' => 'https://foo.com/api/']);
// Send en anmodning til https://foo.com/api/test
$response = $client->request('GET', 'test');
// Send en anmodning til https://foo.com/root
$response = $client->request('GET', '/root');

Har du ikke lyst til at læse RFC 3986? Her er nogle hurtige eksempler på, hvordan en base_uri opløses med en anden URI.

>

base_uri	URI	Resultat
	`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

(kan kaldes) Funktion, der overfører HTTP-forespørgsler over kablet. funktionen kaldes med en Psr7\Http\Message\RequestInterface og array af overførselsmuligheder, og skal returnere en GuzzleHttp\Promise\PromiseInterface, der er opfyldt med en Psr7\Http\Message\ResponseInterface ved succes.

...

(blandet) Alle andre indstillinger, der er overgivet til konstruktøren, anvendes som standard anmodningsindstillinger med hver anmodning, der oprettes af klienten.

Afsendelse af forespørgsler¶

Magiske metoder på klienten gør det nemt at sende synkrone anmodninger:

$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');

Du kan oprette en anmodning og derefter sende anmodningen med klienten, når du er klar:

use GuzzleHttp\Psr7\Request;

$request = new Request('PUT', 'http://httpbin.org/put');
$response = $client->send($request, ['timeout' => 2]);

Klientobjekter giver en stor fleksibilitet med hensyn til, hvordan anmodninger overføres, herunder standardforespørgselsindstillinger, standard håndtering af stak middleware der anvendes af hver anmodning, og en basis-URI, der gør det muligt at sende anmodninger med relative URI'er.

Du kan få mere at vide om klient-middleware på Handlers and Middleware siden i dokumentationen.

Async-anmodninger¶

Du kan sende asynkrone anmodninger ved hjælp af de magiske metoder, der leveres af en klient:

$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');

Du kan også bruge sendAsync() og requestAsync() metoderne for en klient:

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');

Det løfte, der returneres af disse metoder, implementerer Promises/A+ spec, som leveres af Guzzle promises library. Det betyder at du kan kæde then() kald fra løftet. Disse then-opkald er enten opfyldt med et vellykket Psr\Http\Message\ResponseInterface eller afvist med en undtagelse.

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();
    }
);

Samtidige anmodninger¶

Du kan sende flere anmodninger samtidig ved hjælp af løfter og asynkrone anmodninger.

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];

Du kan bruge GuzzleHttp\Pool objektet, når du har et ubestemt antal anmodninger, som du ønsker at sende.

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();

Eller du kan bruge en lukning, der returnerer et løfte, når puljen kalder lukningen.

$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));

Brug af svar¶

I de foregående eksempler hentede vi en $response variabel, eller vi var leveret et svar fra et løfte. Svarobjektet implementerer en PSR-7 respons, Psr\Http\Message\ResponseInterface, og indeholder masser af nyttige oplysninger.

Du kan få statuskoden og begrundelsen for svaret:

$code = $response->getStatusCode(); // 200
$reason = $response->getReasonPhrase(); // OK

Du kan hente overskrifter fra svaret:

// 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";
}

Kroppen af et svar kan hentes ved hjælp af getBody metoden. Body'en kan bruges som en streng, kastes til en streng eller bruges som et stream-lignende objekt.

$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();

Parametre for forespørgselsstreng¶

Du kan angive parametre for forespørgselsstrenge med en anmodning på flere måder.

Du kan angive parametre for forespørgselsstrenge i forespørgsels-URI'en:

$response = $client->request('GET', 'http://httpbin.org?foo=bar');

Du kan angive parametrene for forespørgselsstrengen ved hjælp af query request option som et array.

$client->request('GET', 'http://httpbin.org', [
    'query' => ['foo' => 'bar']
]);

Hvis du angiver indstillingen som et array, vil PHP's http_build_query funktion blive brugt til at formatere forespørgselsstrengen.

Og endelig kan du angive query request option som en streng.

$client->request('GET', 'http://httpbin.org', ['query' => 'foo=bar']);

Overførsel af data¶

Guzzle tilbyder flere metoder til at uploade data.

Du kan sende anmodninger, der indeholder en datastrøm, ved at sende en streng, ressource returneret fra fopen, eller en instans af en Psr\Http\Message\StreamInterface til body anmodningsindstillingen.

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]);

En nem måde at uploade JSON-data og indstille den relevante header på er ved at bruge json request option:

$r = $client->request('PUT', 'http://httpbin.org/put', [
    'json' => ['foo' => 'bar']
]);

POST/formularanmodninger¶

Ud over at angive de rå data i en anmodning ved hjælp af body anmodningsindstillingen, tilbyder Guzzle nyttige abstraktioner for at sende POST-data.

Sende formularfelter¶

Afsendelse af application/x-www-form-urlencoded POST-anmodninger kræver, at du angiver POST-felterne som et array i form_params anmodningsindstillingerne.

$response = $client->request('POST', 'http://httpbin.org/post', [
    'form_params' => [
        'field_name' => 'abc',
        'other_field' => '123',
        'nested_field' => [
            'nested' => 'hello'
        ]
    ]
]);

Afsendelse af formularfiler¶

Du kan sende filer sammen med en formular (multipart/form-data POST-forespørgsler), ved hjælp af multipart request option. multipart accepterer et array af associerende arrays, hvor hvert associerende array indeholder følgende nøgler:

name: (påkrævet, streng) nøgle tilknytning til formularfeltets navn.
indhold: (påkrævet, blandet) Angiv en streng til at sende indholdet af fil som en streng, angiv en fopen-ressource for at streame indholdet fra en PHP-stream, eller tilvejebringe en Psr\Http\Message\StreamInterface til at streame indholdet fra en PSR-7-stream.

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'
            ]
        ]
    ]
]);

Cookies¶

Guzzle kan opretholde en cookie-session for dig, hvis du får instrukser om det ved hjælp af cookies anmodningsindstilling. Når du sender en anmodning, skal cookies indstillingen cookies skal være indstillet til en instans af GuzzleHttp\Cookie\CookieJarInterface.

// Use a specific cookie jar
$jar = new \GuzzleHttp\Cookie\CookieJar;
$r = $client->request('GET', 'http://httpbin.org/cookies', [
    'cookies' => $jar
]);

Du kan indstille cookies til true i en klientkonstruktør, hvis du ønsker at bruge en fælles cookiekrukke for alle anmodninger.

// Use a shared client cookie jar
$client = new \GuzzleHttp\Client(['cookies' => true]);
$r = $client->request('GET', 'http://httpbin.org/cookies');

Der findes forskellige implementeringer for GuzzleHttp\Cookie\CookieJarInterface :

GuzzleHttp\Cookie\CookieJar klassen gemmer cookies som et array.
Klassen GuzzleHttp\Cookie\FileCookieJar bevarer ikke-sessionscookies ved hjælp af en JSON-formateret fil.
Klassen GuzzleHttp\Cookie\SessionCookieJar lagrer cookies i den klientsession.

Du kan manuelt indsætte cookies i en cookiekrukke med den navngivne konstruktør fromArray(array $cookies, $domain).

$jar = \GuzzleHttp\Cookie\CookieJar::fromArray(
    [
        'some_cookie' => 'foo',
        'other_cookie' => 'barbaz1234'
    ],
    'example.org'
);

Du kan hente en cookie ved hjælp af dens navn med getCookieByName($name) metoden, som returnerer en GuzzleHttp\Cookie\SetCookie instans.

$cookie = $jar->getCookieByName('some_cookie');

$cookie->getValue(); // 'foo'
$cookie->getDomain(); // 'example.org'
$cookie->getExpires(); // expiration date as a Unix timestamp

Cookies kan også hentes i et array takket være metoden toArray(). GuzzleHttp\Cookie\CookieJarInterface interface udvider Traversable, så den kan itereres i en foreach-loop.

Omdirigeringer¶

Guzzle vil automatisk følge omdirigeringer, medmindre du beder den om at lade være. Du kan tilpasse omdirigeringsadfærden ved hjælp af allow_redirects request option.

Sæt til true for at aktivere normale omdirigeringer med et maksimalt antal på 5 omdirigeringer. Dette er standardindstillingen.
Sæt til false for at deaktivere omdirigeringer.
Overfør et associeret array, der indeholder nøglen "max" for at angive den maksimale antal viderestillinger og eventuelt en "strict"-nøgleværdi for at angive om der skal anvendes strenge RFC-kompatible omdirigeringer (hvilket betyder, at POST anmodninger med POST-anmodninger i stedet for at gøre det, som de fleste browsere gør, hvilket er omdirigere POST-anmodninger med GET-anmodninger).

$response = $client->request('GET', 'http://github.com');
echo $response->getStatusCode();
// 200

Følgende eksempel viser, at omdirigeringer kan deaktiveres.

$response = $client->request('GET', 'http://github.com', [
    'allow_redirects' => false
]);
echo $response->getStatusCode();
// 301

Undtagelser¶

Trævisning

I følgende trædiagram beskrives det, hvordan Guzzle-undtagelserne afhænger af hinanden.

. \RuntimeException
└── TransferException (implements GuzzleException)
    ├── ConnectException (implements NetworkExceptionInterface)
    └── RequestException
        ├── BadResponseException
        │   ├── ServerException
        │   └── ClientException
        └── TooManyRedirectsException

Guzzle kaster undtagelser for fejl, der opstår under en overførsel.

En GuzzleHttp\Exception\ConnectException undtagelse er kastet i tilfælde af en netværksfejl. Denne undtagelse er en forlængelse af GuzzleHttp\Exception\TransferException.

En GuzzleHttp\Exception\ClientException kastes for 400 niveau fejl, hvis http_errors request option er sat til true. Denne undtagelse er en forlængelse af GuzzleHttp\Exception\BadResponseException og GuzzleHttp\Exception\BadResponseException. GuzzleHttp\Exception\BadResponseException udvider fra GuzzleHttp\Exception\RequestException.

use GuzzleHttp\Psr7;
use GuzzleHttp\Exception\ClientException;

try {
    $client->request('GET', 'https://github.com/_abc_123_404');
} catch (ClientException $e) {
    echo Psr7\Message::toString($e->getRequest());
    echo Psr7\Message::toString($e->getResponse()));
}

En GuzzleHttp\Exception\ServerException bliver kastet for 500 niveau fejl, hvis http_errors request option er sat til true. Denne undtagelse er en forlængelse af GuzzleHttp\Exception\BadResponseException.
En GuzzleHttp\Exception\TooManyRedirectsException bliver kastet, når for mange omdirigeringer følges. Denne undtagelse er en forlængelse af GuzzleHttp\Exception\RequestException.

Alle de ovennævnte undtagelser er en forlængelse af GuzzleHttp\Exception\TransferException.

Miljøvariabler¶

Guzzle indeholder nogle få miljøvariabler, som kan bruges til at tilpasse bibliotekets opførsel.

GUZZLE_CURL_SELECT_TIMEOUT

Styrer den varighed i sekunder, som en curl_multi_*-handler skal bruge, når valg på curl-håndtag ved hjælp af curl_multi_select(). Nogle systemer har problemer med PHP's implementering af curl_multi_select() hvor kald af denne funktion altid resulterer i, at man venter i den maksimale varighed af timeout.

HTTP_PROXY

Definerer den proxy, der skal bruges, når der sendes anmodninger via "http"-protokollen.

Bemærk: da HTTP_PROXY-variablen kan indeholde vilkårlige brugerinput i nogle (CGI) miljøer, bruges variablen kun i CLI SAPI. Se https://httpoxy.org for yderligere oplysninger.

HTTPS_PROXY

Definerer den proxy, der skal bruges, når der sendes anmodninger via "https"-protokollen.

NO_PROXY

Definerer URL'er, som der ikke skal bruges en proxy til. Se proxy for brug.

Relevante iniindstillinger¶

Guzzle kan bruge PHP ini indstillinger, når du konfigurerer klienter.

openssl.cafile: Angiver stien på disken til en CA-fil i PEM-format, der skal bruges ved afsendelse af anmodninger via "https". Se: https://wiki.php.net/rfc/tls-peer-verification#phpini_defaults

Indholdsfortegnelse