Greita pradžia

Šiame puslapyje pateikiama trumpa įžanga į "Guzzle" ir įvadiniai pavyzdžiai. Jei dar neįdiegėte "Guzzle", eikite į Įdiegimas puslapyje.

Užklausos pateikimas

Užklausas su "Guzzle" galite siųsti naudodami GuzzleHttp\ClientInterface objektą.

Kliento kūrimas

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

"Guzzle" programoje klientai yra nekeičiami, o tai reiškia, kad negalite keisti numatytųjų nustatymų, naudojamų sukūrus klientą.

Kliento konstruktorius priima asocijuotą parinkčių masyvą:

base_uri

(string|UriInterface) Kliento bazinis URI, kuris sujungiamas į santykinį URI. Tai gali būti eilutė arba UriInterface egzempliorius. Kai santykinis URI klientui pateikiamas bazinis URI, klientas sujungia bazinį URI su santykiniu URI pagal taisykles, aprašytas RFC 3986, 5.2 skyriuje

// Sukurkite klientą su baziniu URI
$client = new GuzzleHttp\Client(307847298983429311951'base_uri' => 'https://foo.com/api/']);
// Siųskite užklausą į https://foo.com/api/test
$response = $client->request('GET', 'test');
// Siųsti užklausą į https://foo.com/root
$response = $client->request('GET', '/root');

Nesinori skaityti RFC 3986? Štai keletas trumpų pavyzdžių, kaip base_uri išsprendžiamas su kitu URI.

base_uri URI Rezultatas
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
(atšaukiama) Funkcija, perduodanti HTTP užklausas per laidą. funkcija iškviečiama su Psr7\Http\Message\RequestInterface ir masyvu perdavimo parinkčių ir turi grąžinti GuzzleHttp\Promise\PromiseInterface, kuris įvykdomas su Psr7\Http\Message\ResponseInterface sėkmės atveju.
...
(mišrus) Visos kitos konstruktoriui perduotos parinktys naudojamos kaip numatytosios užklausos parinktys kiekvienoje kliento sukurtoje užklausoje.

Užklausų siuntimas

Kliento "Magic" metodais lengva siųsti sinchronines užklausas:

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

Galite sukurti užklausą ir, kai būsite pasiruošę, išsiųsti užklausą kartu su klientu:

use GuzzleHttp\Psr7\Request;

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

Kliento objektai suteikia daug lankstumo, kaip užklausos įskaitant numatytąsias užklausų parinktis, numatytąsias tvarkytojo kamino tarpines programas kurios naudojamos kiekvienai užklausai, ir bazinį URI, leidžiantį siųsti užklausas su santykiniais URI.

Daugiau informacijos apie kliento tarpinę programinę įrangą rasite dokumentacijos Handlers and Middleware puslapyje.

Asynciniai prašymai

Asinchronines užklausas galite siųsti naudodami kliento pateiktus stebuklinguosius metodus:

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

Taip pat galite naudoti kliento sendAsync() ir requestAsync() metodus:

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

Šiais metodais grąžinamas pažadas įgyvendina Promises/A+ specifikaciją, pateiktą Guzzle pažadų biblioteka. Tai reiškia, kad kad galite grandininiu būdu then() skambinti iš pažado. Šie then skambučiai yra įvykdomi, kai sėkmingai Psr\Http\Message\ResponseInterface arba atmetama su išimtimi.

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

Lygiagrečios užklausos

Naudodami pažadus ir asinchronines užklausas galite siųsti kelias užklausas vienu metu.

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

Objektą GuzzleHttp\Pool galite naudoti, kai norite siųsti neapibrėžtą kiekį užklausų.

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

Arba naudokite uždarymą, kuris grąžins pažadą, kai baseinas iškvies uždarymą.

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

Atsakymų naudojimas

Ankstesniuose pavyzdžiuose gavome $response kintamąjį arba buvome gavome atsakymą iš pažado. Atsakymo objektas įgyvendina PSR-7 atsakymą, Psr\Http\Message\ResponseInterface, ir jame yra daug naudingos informacijos.

Galite gauti būsenos kodą ir atsakymo priežasties frazę:

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

Iš atsakymo galite gauti antraštes:

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

Atsakymo kūną galima gauti naudojant getBody metodą. Kūnas gali būti naudojamas kaip eilutė, paverčiamas eilute arba naudojamas kaip į srautą panašus objektas.

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

Užklausos eilutės parametrai

Užklausos eilutės parametrus kartu su užklausa galite pateikti keliais būdais.

Užklausos eilutės parametrus galite nustatyti užklausos URI:

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

Užklausos eilutės parametrus galite nurodyti naudodami query užklausos parinktį kaip masyvą.

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

Pateikus parinktį kaip masyvą, užklausos eilutei suformatuoti bus naudojama PHP http_build_query funkcija.

Galiausiai galite pateikti query užklausos parinktį kaip eilutę.

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

Duomenų įkėlimas

"Guzzle" pateikia kelis duomenų įkėlimo būdus.

Užklausas, kuriose yra duomenų srautas, galite siųsti perduodami eilutę, iš fopen grąžintą išteklių arba Psr\Http\Message\StreamInterface prie body užklausos parinkties.

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

Lengvas būdas įkelti JSON duomenis ir nustatyti atitinkamą antraštę - naudoti json užklausos parinktį:

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

POST/formos užklausos

"Guzzle" ne tik nurodo neapdorotus užklausos duomenis naudodamas body užklausos parinktį, bet ir pateikia naudingas POST duomenų siuntimo abstrakcijas.

Formos laukų siuntimas

Siunčiant application/x-www-form-urlencoded POST užklausas reikia nurodyti POST laukus kaip masyvą form_params užklausos parinktyse.

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

Formos failų siuntimas

Failus galite siųsti kartu su forma (multipart/form-data POST užklausos), naudodami multipart užklausos parinktį. multipart priima masyvą asocijuotųjų masyvų, kur kiekvieną asocijuotąjį masyvą sudaro šie raktai:

  • name: (privaloma, eilutė) raktas, atitinkantis formos lauko pavadinimą.
  • turinys: (privaloma, mišrus) Pateikite eilutę, kuria siunčiamas turinys failą kaip eilutę, pateikite fopen išteklių, kad turinys būtų siunčiamas iš PHP srauto, arba pateikite Psr\Http\Message\StreamInterface srautui perduoti turinį iš PSR-7 srauto.
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'
            ]
        ]
    ]
]);

Slapukai

"Guzzle" gali išlaikyti slapukų seansą, jei nurodėte naudoti cookies užklausos parinktį. Siunčiant užklausą, cookies parinktis turi būti nustatyta kaip GuzzleHttp\Cookie\CookieJarInterface egzempliorius.

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

Galite nustatyti cookies į true kliento konstruktoriuje, jei norite naudoti bendrą slapukų indą visoms užklausoms.

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

Egzistuoja skirtingos GuzzleHttp\Cookie\CookieJarInterface realizacijos:

  • GuzzleHttp\Cookie\CookieJar klasė saugo slapukus kaip masyvą.
  • GuzzleHttp\Cookie\FileCookieJar klasė išsaugo ne sesijos slapukus. naudojant JSON formato failą.
  • GuzzleHttp\Cookie\SessionCookieJar klasė išsaugo slapukus kliento sesijoje.

Galite rankiniu būdu nustatyti slapukus į slapukų indą naudodami pavadintą konstruktorių fromArray(array $cookies, $domain).

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

Galite gauti slapuką pagal jo pavadinimą naudodami getCookieByName($name) metodą, kuris grąžina GuzzleHttp\Cookie\SetCookie instanciją.

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

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

Slapukus taip pat galima gauti į masyvą naudojant toArray() metodą. GuzzleHttp\Cookie\CookieJarInterface sąsaja išplečia Traversable, todėl ją galima naršyti foreach cikle.

Peradresavimai

"Guzzle" automatiškai seka nukreipimus, nebent nurodysite to nedaryti. Peradresavimo elgseną galite pritaikyti naudodami allow_redirects užklausos parinktį.

  • Nustatykite į true, kad įjungtumėte įprastus nukreipimus, kurių maksimalus skaičius yra 5. peradresavimų. Tai numatytasis nustatymas.
  • Nustatykite į false, kad išjungtumėte nukreipimus.
  • Perduokite asocijuotą masyvą, kuriame yra raktas "max", nurodantis didžiausią skaičių ir pasirinktinai pateikti rakto "strict" reikšmę, kad būtų nurodyta ar naudoti griežtus RFC reikalavimus atitinkančius nukreipimus (t. y. nukreipti POST užklausas su POST užklausomis, o ne taip, kaip daro dauguma naršyklių, t. y. POST užklausas nukreipia GET užklausomis).
$response = $client->request('GET', 'http://github.com');
echo $response->getStatusCode();
// 200

Toliau pateiktame pavyzdyje parodyta, kad nukreipimus galima išjungti.

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

Išimtys

Medžio vaizdas

Toliau pateiktame medžio vaizde aprašyta, kaip "Guzzle" išimtys priklauso viena nuo kitos.

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

"Guzzle" išmeta išimtis dėl perdavimo metu įvykusių klaidų.

  • Išimtis GuzzleHttp\Exception\ConnectException išmetama į tinklo klaidos atveju. Ši išimtis išplečiama iš GuzzleHttp\Exception\TransferException.

  • Išmetama GuzzleHttp\Exception\ClientException dėl 400 lygio klaidos, jei http_errors užklausos parinktis nustatyta į true. Šis išimtis išplečiama iš GuzzleHttp\Exception\BadResponseException ir GuzzleHttp\Exception\BadResponseException išplečia iš GuzzleHttp\Exception\RequestException.

    naudoti GuzzleHttp\Psr7;
    use GuzzleHttp\ClientException\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());
    }
    
  • Išmetama GuzzleHttp\Exception\ServerException dėl 500 lygio klaidos, jei http_errors užklausos parinktyje nustatyta reikšmė true. Šis Išimtis išplečiama iš GuzzleHttp\Exception\BadResponseException.

  • GuzzleHttp\Exception\TooManyRedirectsException išmetama, kai per daug per daug nukreipimų. Ši išimtis išplečiama iš GuzzleHttp\Exception\RequestException.

Visos pirmiau minėtos išimtys išplečiamos iš GuzzleHttp\Exception\TransferException.

Aplinkos kintamieji

"Guzzle" pateikia kelis aplinkos kintamuosius, kuriuos galima naudoti bibliotekos elgsenai pritaikyti.

GUZZLE_CURL_SELECT_TIMEOUT
Nustato trukmę sekundėmis, kurią curl_multi_* tvarkyklė naudos, kai pasirenkant curl tvarkykles naudojant curl_multi_select(). Kai kurios sistemos turi problemų su PHP curl_multi_select() įgyvendinimu, kai skambinant šiai funkcijai, visada laukiama maksimalios trukmės laiko limitą.
HTTP_PROXY

Apibrėžia tarpinį serverį, kuris bus naudojamas siunčiant užklausas naudojant "http" protokolą.

Pastaba: kadangi kai kuriose (CGI) aplinkose HTTP_PROXY kintamajame gali būti savavališka naudotojo įvestis, šis kintamasis naudojamas tik CLI SAPI. Daugiau informacijos rasite https://httpoxy.org.

HTTPS_PROXY
Apibrėžia tarpinį serverį, kuris bus naudojamas siunčiant užklausas naudojant "https" protokolą.
NO_PROXY
Apibrėžia URL adresus, kuriems neturėtų būti naudojamas tarpinis serveris. Apie naudojimą žr. proxy.

Atitinkami ini nustatymai

Konfigūruojant klientus "Guzzle" gali naudoti PHP ini nustatymus.

openssl.cafile
Nurodomas kelias diske iki CA failo PEM formatu, kuris bus naudojamas siunčiant užklausas per "https". Žr: https://wiki.php.net/rfc/tls-peer-verification#phpini_defaults