Ātrākais sākums

Šajā lapā ir sniegts īss ievads par Guzzle un ievadpiemēri. Ja vēl neesat instalējis Guzzle, dodieties uz Instalēšana lapā.

Pieprasījuma iesniegšana

Ar Guzzle var nosūtīt pieprasījumus, izmantojot GuzzleHttp\ClientInterface objektu.

Klienta izveide

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 programmā klienti ir nemainīgi, un tas nozīmē, ka pēc klienta izveides nevar mainīt klienta izmantotās noklusējuma vērtības.

Klienta konstruktors pieņem asociatīvu iespēju masīvu:

base_uri

(string|UriInterface) Klienta bāzes URI, kas tiek apvienots ar relatīvo URI. Var būt virkne vai UriInterface instance. Ja relatīvais URI tiek sniegts klientam, klients apvienos bāzes URI ar URI relatīvo URI, izmantojot noteikumus, kas aprakstīti RFC 3986, 5.2. iedaļa

// Izveido klientu ar bāzes URI
$client = new GuzzleHttp\Client(307847298983429311951'base_uri' => 'https://foo.com/api/']);
// Nosūtīt pieprasījumu uz https://foo.com/api/test
$response = $client->request('GET', 'test');
// Nosūtīt pieprasījumu uz https://foo.com/root
$response = $client->request('GET', '/root');

Negribas lasīt RFC 3986? Šeit ir daži īsi piemēri, kā base_uri tiek atrisināts ar citu URI.

base_uri URI Rezultāts 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
(izsaucama) Funkcija, kas pārsūta HTTP pieprasījumus pa vadu. funkcija tiek izsaukta ar Psr7\Http\Message\RequestInterface un masīva pārsūtīšanas opciju masīva, un tam jāatgriež GuzzzzleHttp\Promise\PromiseInterface, kas tiek izpildīts ar Psr7\Http\Message\ResponseInterface veiksmes gadījumā.
...
(jaukts) Visas pārējās konstruktoram nodotās opcijas tiek izmantotas kā noklusējuma opcijas. pieprasījuma opcijas katrā klienta izveidotajā pieprasījumā.

Pieprasījumu nosūtīšana

Klienta burvju metodes atvieglo sinhrono pieprasījumu nosūtīšanu:

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

Varat izveidot pieprasījumu un pēc tam, kad esat gatavs, nosūtīt pieprasījumu kopā ar klientu:

use GuzzleHttp\Psr7\Request;

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

Klientu objekti nodrošina lielu elastību attiecībā uz to, kā pieprasījums tiek tostarp noklusējuma pieprasījuma opcijas, noklusējuma apstrādātāja paketes starpprogrammatūru. kas tiek izmantoti katram pieprasījumam, un bāzes URI, kas ļauj sūtīt pieprasījumus. ar relatīviem URI.

Vairāk par klienta starpprogrammatūru var uzzināt dokumentācijas Handlers and Middleware lapā.

Async pieprasījumi

Jūs varat sūtīt asinhronus pieprasījumus, izmantojot klienta nodrošinātās burvju metodes:

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

Varat izmantot arī klienta sendAsync() un requestAsync() metodes:

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

Šo metožu atgrieztais solījums implementē Promises/A+ spec, ko nodrošina Guzzle solījumu bibliotēka. Tas nozīmē, ka ka no solījuma var ķēdīt then() izsaukumus. Šie tad izsaukumi ir vai nu tiek izpildīti ar veiksmīgu Psr\Http\Message\ResponseInterface vai noraidīts ar izņēmumu.

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

Vienlaicīgi pieprasījumi

Varat sūtīt vairākus pieprasījumus vienlaicīgi, izmantojot solījumus un asinhronos pieprasījumus.

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

Objektu GuzzleHttp\Pool var izmantot, ja vēlaties nosūtīt nenoteiktu pieprasījumu skaitu.

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

Vai izmantojot slēgšanu, kas atgriež solījumu, tiklīdz baseins izsauc slēgšanu.

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

Atbilžu izmantošana

Iepriekšējos piemēros mēs ieguvām $response mainīgo vai mēs bijām saņēmām atbildi no solījuma. Atbildes objekts īsteno PSR-7 atbildi, Psr\Http\Message\ResponseInterface, un tajā ir daudz noderīgu informāciju.

Varat iegūt atbildes statusa kodu un iemesla frāzi:

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

No atbildes var iegūt galvenes:

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

Atbildes ķermeni var iegūt, izmantojot getBody metodi. Atbildes ķermeni var izmantot kā virkni, pārvērst virknē vai izmantot kā plūsmai līdzīgu objektu.

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

Vaicājuma virknes parametri

Pieprasījuma rindas parametrus pieprasījumam var norādīt vairākos veidos.

Pieprasījuma URI var iestatīt vaicājuma virknes parametrus:

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

Pieprasījuma virknes parametrus var norādīt, izmantojot query pieprasījuma opciju kā masīvu.

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

Sniedzot opciju kā masīvu, tiks izmantota PHP http_build_query funkcija, lai formatētu vaicājuma virkni.

Visbeidzot, varat norādīt query pieprasījuma iespēju kā virkni.

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

Datu augšupielāde

Guzzle nodrošina vairākas datu augšupielādes metodes.

Varat sūtīt pieprasījumus, kas satur datu plūsmu, nododot virkni, fopen, vai no fopen, vai instanci Psr\Http\Message\StreamInterface pieprasījuma opcijai 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]);

Vienkāršs veids, kā augšupielādēt JSON datus un iestatīt atbilstošu galveni, ir, izmantojot json pieprasījuma iespēju:

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

POST/Formu pieprasījumi

Papildus pieprasījuma neapstrādāto datu norādīšanai, izmantojot body pieprasījuma opciju, Guzzle nodrošina noderīgas abstrakcijas POST datu nosūtīšanai.

Formas lauku nosūtīšana

Sūtot application/x-www-form-urlencoded POST pieprasījumus, ir jānorāda POST lauki kā masīvs form_params pieprasījuma opcijās.

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

Veidlapu failu nosūtīšana

Kopā ar veidlapu var nosūtīt failus (multipart/form-data POST pieprasījumi), izmantojot multipart pieprasījuma opciju. multipart pieņem masīvu no asociatīvo masīvu, kur katrs asociatīvais masīvs satur šādas atslēgas:

  • name: (obligāts, virkne) atslēga, kas atveido formas lauka nosaukumu.
  • saturs: (obligāts, jaukts) Norādiet virkni, lai nosūtītu saturu. failu kā virkni, norādiet resursu fopen, lai saturu straumētu no PHP plūsmas, vai sniedziet Psr\Http\Message\StreamInterface, lai straumētu saturu no PSR-7 plūsmas.
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'
            ]
        ]
    ]
]);

Sīkfaili

Guzzle var saglabāt sīkfailu sesiju, ja tiek norādīts, izmantojot cookies pieprasījuma opciju. Nosūtot pieprasījumu, cookies opcija jābūt iestatītai uz GuzzleHttp\Cookie\CookieJarInterface gadījumu.

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

Jūs varat iestatīt sīkfailus uz true klienta konstruktorā, ja vēlaties izmantot koplietošanas sīkfailu burku visiem pieprasījumiem.

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

Pastāv dažādas GuzzleHttp\Cookie\CookieJarInterface implementācijas:

  • GuzzleHttp\Cookie\CookieJar klase saglabā sīkdatnes kā masīvu.
  • GuzzleHttp\Cookie\FileCookieJar klase saglabā sīkfailus, kas nav sesijas sīkfaili. izmantojot JSON formāta failu.
  • GuzzleHttp\Cookie\SessionCookieJar klase saglabā sīkfailus. klienta sesijā.

Jūs varat manuāli iestatīt sīkfailus sīkfailu burkā, izmantojot nosaukto konstruktoru fromArray(array $cookies, $domain).

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

Jūs varat iegūt sīkfailu pēc tā nosaukuma, izmantojot getCookieByName($name) metodi, kas atgriež GuzzleHttp\Cookie\SetCookie gadījumu.

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

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

Sīkfailus var arī iegūt masīvā, izmantojot toArray() metodi. GuzzleHttp\Cookie\CookieJarInterface saskarne paplašina Traversable, lai to varētu veikt foreach cilpā.

Pārvirzes

Guzzle automātiski sekos novirzēm, ja vien nebūsiet licis to nedarīt. Jūs varat pielāgot novirzīšanas uzvedību, izmantojot allow_redirects pieprasījuma iespēju.

  • Iestatiet true, lai iespējotu parastos novirzienus ar maksimālo skaitu 5. novirzīšanu. Tas ir noklusējuma iestatījums.
  • Iestatiet false, lai atspējotu novirzīšanu.
  • Nodod asociatīvu masīvu, kas satur atslēgu 'max', lai norādītu maksimālo skaitu un pēc izvēles norāda atslēgas "strict" vērtību, lai norādītu vai izmantot stingrus RFC atbilstošus novirzienus (tas nozīmē, ka novirzīt POST pieprasījumus ar POST pieprasījumiem pretstatā tam, ko dara vairums pārlūkprogrammu, t.i. pāradresē POST pieprasījumus ar GET pieprasījumiem).
$response = $client->request('GET', 'http://github.com');
echo $response->getStatusCode();
// 200

Turpmākajā piemērā parādīts, ka novirzīšanu var atspējot.

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

Izņēmumi

Koku skats

Nākamajā koka attēlā ir aprakstīts, kā Guzzle izņēmumi ir atkarīgi viens no otra.

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

Guzzle izmet izņēmumus par kļūdām, kas rodas pārsūtīšanas laikā.

  • Izņēmums GuzzleHttp\Exception\ConnectException tiek izmests programmā. tīkla kļūdas gadījumā. Šis izņēmums ir paplašināts no GuzzleHttp\Exception\TransferException.

  • Tiek izmests GuzzleHttp\Exception\ClientException 400 līmeņa kļūdas, ja http_errors pieprasījuma opcija ir iestatīta uz true. Šis izņēmums ir paplašinājums no GuzzleHttp\Exception\BadResponseException un GuzzleHttp\Exception\BadResponseException paplašina no GuzzleHttp\Exception\RequestException.

    izmantot 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());
    }
    
  • Tiek izmests GuzzleHttp\Exception\ServerException pie 500 līmeņa. kļūdas, ja http_errors pieprasījuma opcija ir iestatīta uz true. Šis izņēmums ir paplašināts no GuzzleHttp\Exception\BadResponseException.

  • GuzzleHttp\Exception\TooManyRedirectsException tiek izmests, ja pārāk daudz tiek sekots pārāk daudziem novirzieniem. Šis izņēmums ir paplašinājums no GuzzleHttp\Exception\RequestException.

Visi iepriekš minētie izņēmumi ir paplašināti no GuzzleHttp\Exception\TransferException.

Vides mainīgie

Guzzle piedāvā dažus vides mainīgos, kurus var izmantot, lai pielāgotu bibliotēkas darbību.

GUZZLE_CURL_SELECT_TIMEOUT
Kontrolē ilgumu sekundēs, ko curl_multi_* apstrādātājs izmantos, kad izvēloties curl apstrādātājus, izmantojot curl_multi_select(). Dažas sistēmas ir problēmas ar PHP implementāciju curl_multi_select(), kur izsaucot šo funkciju, vienmēr jāgaida maksimālo ilgumu timeout.
HTTP_PROXY

Nosaka starpniekserveri, kas tiks izmantots, sūtot pieprasījumus, izmantojot "http" protokolu.

Piezīme: tā kā HTTP_PROXY mainīgais dažās (CGI) vidēs var saturēt patvaļīgu lietotāja ievadi, šis mainīgais tiek izmantots tikai CLI SAPI. Vairāk informācijas skatiet https://httpoxy.org.

HTTPS_PROXY
Nosaka starpniekserveri, kas jāizmanto, sūtot pieprasījumus, izmantojot "https" protokolu.
NO_PROXY
Definē URL, kuriem nedrīkst izmantot starpniekserveri. Lietošanu skatiet proxy.

Attiecīgie ini iestatījumi

Konfigurējot klientus, Guzzle var izmantot PHP ini iestatījumus.

openssl.cafile
Norāda ceļu uz CA datni PEM formātā, kas jāizmanto, nosūtot pieprasījumus, izmantojot "https". Sk: https://wiki.php.net/rfc/tls-peer-verification#phpini_defaults