Pikakäynnistys

Tällä sivulla on pikaesittely Guzzlesta ja esimerkkejä. Jos et ole vielä asentanut Guzzlea, siirry Asennus sivulle.

Pyynnön tekeminen

Voit lähettää pyyntöjä Guzzlella käyttämällä GuzzleHttp\ClientInterface -objektia.

Asiakkaan luominen

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

Asiakkaat ovat muuttumattomia Guzzlessa, mikä tarkoittaa, että et voi muuttaa asiakkaan käyttämiä oletusasetuksia sen luomisen jälkeen.

Asiakkaan konstruktori hyväksyy assosiatiivisen joukon vaihtoehtoja:

base_uri

(string|UriInterface) Asiakkaan perus-URI, joka yhdistetään relatiiviseen URI:t. Voi olla merkkijono tai UriInterfacen instanssi. Kun suhteellinen URI annetaan asiakkaalle, asiakas yhdistää perus-URI:n ja suhteelliseen URI:hin käyttäen sääntöjä, jotka on kuvattu kohdassa RFC 3986, jakso 5.2.

// Luo asiakas perus-URI:n kanssa.
$client = new GuzzleHttp\Client(['base_uri' => 'https://foo.com/api/']);
// Lähetä pyyntö osoitteeseen https://foo.com/api/test
$response = $client->request('GET', 'test');
// Lähetä pyyntö osoitteeseen https://foo.com/root
$response = $client->request('GET', '/root');

Ei huvita lukea RFC 3986:aa? Tässä on muutamia nopeita esimerkkejä siitä, miten base_uri ratkaistaan toisella URI:lla.

base_uri URI Result
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
(kutsuttava) Funktio, joka siirtää HTTP-pyynnöt langan yli. funktiota kutsutaan Psr7\Http\Message\RequestInterface ja array siirtovaihtoehdoista, ja sen on palautettava GuzzleHttp\Promise\PromiseInterface, joka täytetään yhdellä Psr7\Http\Message\ResponseInterface onnistumisen yhteydessä.
...
(mixed) Kaikkia muita konstruktorille annettuja asetuksia käytetään oletusarvoisesti. pyyntöasetuksina jokaisessa asiakkaan luomassa pyynnössä.

Pyyntöjen lähettäminen

Asiakkaan taikamenetelmät helpottavat synkronisten pyyntöjen lähettämistä:

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

Voit luoda pyynnön ja lähettää sen sitten asiakkaan kanssa, kun olet valmis:

use GuzzleHttp\Psr7\Request;

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

Asiakasobjektit tarjoavat paljon joustavuutta siinä, miten pyyntöjä käsitellään. siirretään, mukaan lukien oletuspyyntövaihtoehdot, oletuskäsittelijän pinon väliohjelmisto joita kukin pyyntö käyttää, ja perus-URI, jonka avulla voit lähettää pyyntöjä. suhteellisen URI:n kanssa.

Saat lisätietoja asiakkaan väliohjelmistoista dokumentaation Handlers and Middleware -sivulta.

Asynkroniset pyynnöt

Voit lähettää asynkronisia pyyntöjä käyttämällä asiakkaan tarjoamia taikamenetelmiä:

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

Voit myös käyttää asiakkaan sendAsync() ja requestAsync() -menetelmiä:

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

Näiden menetelmien palauttama lupaus toteuttaa Promises/A+ spec, jonka tarjoaa Guzzle promises library. Tämä tarkoittaa että voit ketjuttaa then() kutsuja lupauksesta. Nämä then-kutsut ovat joko täytetään onnistuneella Psr\Http\Message\ResponseInterface tai hylätty poikkeustapauksella.

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

Samanaikaiset pyynnöt

Voit lähettää useita pyyntöjä samanaikaisesti lupausten ja asynkronisten pyyntöjen avulla.

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

Voit käyttää GuzzleHttp\Pool -objektia, kun sinulla on määrittelemätön määrä pyyntöjä, jotka haluat lähettää.

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

Tai käyttämällä sulkua, joka palauttaa lupauksen, kun allas kutsuu sulkua.

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

Vastausten käyttäminen

Edellisissä esimerkeissä haimme $response muuttujan tai olimme saimme vastauksen lupauksesta. Vastaus-olio toteuttaa PSR-7 response, Psr\Http\Message\ResponseInterface, ja se sisältää runsaasti hyödyllistä tietoa.

Saat vastauksen tilakoodin ja syylausekkeen:

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

Voit hakea otsikot vastauksesta:

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

Vastauksen runko voidaan hakea getBody-menetelmällä. Runkoa voidaan käyttää merkkijonona, muuntaa merkkijonoksi tai käyttää stream-tyyppisenä objektina.

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

Kyselymerkkijonon parametrit

Voit antaa kyselyn merkkijonoparametreja pyynnön mukana usealla eri tavalla.

Voit määrittää kyselyn merkkijonoparametrit pyynnön URI:ssä:

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

Voit määrittää kyselyn merkkijonoparametrit query pyyntövaihtoehdon avulla.

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

Vaihtoehdon antaminen joukkona käyttää PHP:n http_build_query -funktiota kyselymerkkijonon muotoilemiseen.

Lopuksi voit antaa query -pyyntövaihtoehdon merkkijonona.

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

Tietojen lataaminen

Guzzle tarjoaa useita menetelmiä tietojen lataamiseen.

Voit lähettää pyyntöjä, jotka sisältävät tietovirran, välittämällä merkkijonon, fopen-ohjelmasta palautettu resurssi tai instanssi parametrista Psr\Http\Message\StreamInterface body pyyntövaihtoehtoon.

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

Helppo tapa ladata JSON-tietoja ja asettaa sopiva otsikko on käyttää json pyyntövaihtoehtoa:

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

POST/Lomakepyynnöt

Sen lisäksi, että pyynnön raakadatan voi määrittää body -vaihtoehdon avulla, Guzzle tarjoaa hyödyllisiä abstraktioita POST-tietojen lähettämiseen.

Lomakekenttien lähettäminen

application/x-www-form-urlencoded POST-pyyntöjen lähettäminen edellyttää, että määrittelet POST-kentät joukkona form_params pyyntöasetuksissa.

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

Lomaketiedostojen lähettäminen

Voit lähettää tiedostoja lomakkeen mukana (multipart/form-data POST-pyynnöt), käyttämällä multipart -pyyntövaihtoehtoa. multipart hyväksyy seuraavat asetukset. assosiatiivisia matriiseja, joissa kussakin assosiatiivisessa matriisissa on seuraavat avaimet:

  • name: (pakollinen, merkkijono) avain, joka vastaa lomakekentän nimeä.
  • sisältö: (pakollinen, mixed) Anna merkkijono, jolla lähetät sisällön tiedosto merkkijonona, anna fopen-resurssi tiedoston sisällön lähettämiseksi suoratoistona tiedostosta PHP-virrasta, tai tarjoa Psr\Http\Message\StreamInterface, jolla voidaan suoratoistaa sisältö sisällön PSR-7-virrasta.
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'
            ]
        ]
    ]
]);

Evästeet

Guzzle voi ylläpitää evästeistuntoa puolestasi, jos se on ohjeistettu käyttämällä komentoa cookies pyyntövaihtoehto. Kun lähetät pyynnön, cookies -vaihtoehto on cookies on asetettava GuzzleHttp\Cookie\CookieJarInterface:n instanssiksi.

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

Voit asettaa cookies arvoksi true asiakkaan konstruktorissa, jos haluat käyttää jaettua evästeiden purkkia kaikille pyynnöille.

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

GuzzleHttp\Cookie\CookieJarInterface :

  • Luokka GuzzleHttp\Cookie\CookieJar tallentaa evästeet matriisina.
  • Luokka GuzzleHttp\Cookie\FileCookieJar säilyttää muut kuin istunnon evästeet. käyttämällä JSON-muotoista tiedostoa.
  • Luokka GuzzleHttp\Cookie\SessionCookieJar pitää evästeet tallessa asiakkaan istuntoon.

Voit asettaa evästeet manuaalisesti evästepurkkiin nimetyllä konstruktorilla fromArray(array $cookies, $domain).

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

Voit hakea evästeen sen nimen perusteella getCookieByName($name)(/span) metodilla, joka palauttaa GuzzleHttp\Cookie\SetCookie.

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

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

Evästeet voidaan myös noutaa joukkoon toArray()-menetelmän avulla. GuzzleHttp\Cookie\CookieJarInterface rajapinta laajentaa Traversable, joten sitä voidaan iteroida foreach-silmukassa.

Uudelleenohjaukset

Guzzle seuraa automaattisesti uudelleenohjauksia, ellet kiellä sitä. Voit muokata uudelleenohjauskäyttäytymistä allow_redirects -valinnalla.

  • Aseta arvoksi true salliaksesi normaalit uudelleenohjaukset, joiden enimmäismäärä on 5. uudelleenohjauksia. Tämä on oletusasetus.
  • Aseta false, jos haluat poistaa uudelleenohjaukset käytöstä.
  • Syötä assosiatiivinen joukko, joka sisältää avaimen 'max', jolla määritetään suurin sallittu arvo. uudelleenohjausten määrä ja valinnaisesti 'strict'-avainarvo, jolla määritetään uudelleenohjausten määrä. käytetäänkö tiukkoja RFC-yhteensopivia uudelleenohjauksia (eli ohjataanko POST-postia pyynnöt POST-pyynnöillä vs. se, mitä useimmat selaimet tekevät, mikä on ohjaa POST-pyynnöt uudelleen GET-pyynnöillä).
$response = $client->request('GET', 'http://github.com');
echo $response->getStatusCode();
// 200

Seuraava esimerkki osoittaa, että uudelleenohjaukset voidaan poistaa käytöstä.

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

Poikkeukset

Puunäkymä

Seuraavassa puunäkymässä kuvataan, miten Guzzle-poikkeukset riippuvat toisistaan.

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

Guzzle heittää poikkeuksia siirron aikana ilmenevistä virheistä.

  • Poikkeus GuzzleHttp\Exception\ConnectException on heitetty verkkovirheen sattuessa. Tämä poikkeus on jatkoa GuzzleHttp\Exception\TransferException.

  • GuzzleHttp\Exception\ClientException heitetään, kun 400 tason virheistä, jos http_errors request option on true. Tämä poikkeus on jatkoa GuzzleHttp\Exception\BadResponseException ja GuzzleHttp\Exception\BadResponseException laajenee osoitteesta GuzzleHttp\Exception\RequestException.

    käytä 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());
    }
    
  • GuzzleHttp\Exception\ServerException heitetään 500 tason kohdalla. virheet, jos http_errors request option on true. Tämä poikkeus on jatkoa GuzzleHttp\Exception\BadResponseException:lle

  • GuzzleHttp\Exception\TooManyRedirectsException heitetään, kun liian monta monia uudelleenohjauksia noudatetaan. Tämä poikkeus on jatkoa GuzzleHttp\Exception\RequestException:lle.

Kaikki edellä mainitut poikkeukset jatkavat GuzzleHttp\Exception\TransferException.

Ympäristömuuttujat

Guzzle tarjoaa muutamia ympäristömuuttujia, joita voidaan käyttää kirjaston käyttäytymisen mukauttamiseen.

GUZZLE_CURL_SELECT_TIMEOUT
Määrittää sekunteina sen keston, jota curl_multi_*-käsittelijä käyttää, kun valittaessa curl-kahvoja käyttäen curl_multi_select(). Jotkut järjestelmät on ongelmia PHP:n curl_multi_select() toteutuksen kanssa, jossa tämän funktion kutsuminen johtaa aina siihen, että odotetaan maksimikeston verran aikakatkaisu.
HTTP_PROXY

Määrittää välityspalvelimen, jota käytetään lähetettäessä pyyntöjä http-protokollaa käyttäen.

Huomautus: koska HTTP_PROXY-muuttuja voi sisältää mielivaltaista käyttäjän syötettä joissakin (CGI) ympäristöissä, muuttujaa käytetään vain CLI SAPI:ssa. Katso https://httpoxy.org lisätietoja https://httpoxy.org.

HTTPS_PROXY
Määrittää välityspalvelimen, jota käytetään lähetettäessä pyyntöjä https-protokollaa käyttäen.
NO_PROXY
Määrittää URL-osoitteet, joihin välityspalvelinta ei tule käyttää. Katso proxy käytöstä.

Relevantit ini-asetukset

Guzzle voi käyttää PHP ini -asetuksia asiakkaiden konfiguroinnissa.

openssl.cafile
Määrittää levyllä olevan PEM-muotoisen CA-tiedoston polun, jota käytetään lähetettäessä pyyntöjä https:n kautta. Katso: https://wiki.php.net/rfc/tls-peer-verification#phpini_defaults https://wiki.php.net/rfc/tls-peer-verification#phpini_defaults