Quickstart¶

Taotluse esitamine¶

Guzzle'iga saab päringuid saata, kasutades GuzzleHttp\ClientInterface objekti.

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

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

use GuzzleHttp\Psr7\Request;

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

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

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

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

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

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

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

Vastuste kasutamine¶

Eelmistes näidetes saime $response muutuja või olime me saime vastuse lubadusest. Vastuse objekt rakendab PSR-7 response, Psr\Http\Message\ResponseInterface, ja sisaldab palju kasulikku teavet.

Võite saada vastuse staatuskoodi ja põhjuse fraasi:

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

Vastusest saab välja võtta päiseid:

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

Vastuse keha saab kätte meetodiga getBody. Vastuse keha saab kasutada stringina, teisendada stringiks või kasutada voogulaadse 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();

Päringu stringi parameetrid¶

Päringusseadme parameetrid saab esitada päringuga koos päringuga mitmel viisil.

Saate määrata päringustringi parameetrid päringu URI-s:

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

Saate määrata päringustringi parameetrid, kasutades query päringuvõimalust massiivina.

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

Valiku esitamine massiivi kujul kasutab päringustringi vormindamiseks PHP http_build_query funktsiooni.

Ja lõpuks saate esitada query päringuvõimaluse stringina.

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

Andmete üleslaadimine¶

Guzzle pakub andmete üleslaadimiseks mitmeid meetodeid.

Saate saata päringuid, mis sisaldavad andmevoolu, edastades stringi, fopen tagastatud ressurssi või instantsi fopen või instantsi Psr\Http\Message\StreamInterface body päringuvariandile.

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

Lihtne viis JSON-andmete üleslaadimiseks ja sobiva päise määramiseks on kasutada json päringuvõimalust:

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

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

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

Küpsised¶

Guzzle võib säilitada teie jaoks küpsiste sessiooni, kui kasutate selleks juhiseid, kasutades funktsiooni cookies taotlusvalikut. Päringu saatmisel saab cookies valikuga cookies peab olema seatud GuzzleHttp\Cookie\CookieJarInterface eksemplariks.

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

Saate cookies määrata true kliendi konstruktoris, kui soovite kasutada kõigi päringute jaoks ühist küpsiste purki.

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

GuzzleHttp\Cookie\CookieJarInterface jaoks on olemas erinevad implementatsioonid:

• Klass GuzzleHttp\Cookie\CookieJar salvestab küpsiseid massiivi kujul.
• GuzzleHttp\Cookie\FileCookieJar klass säilitab mitte-sessiooniküpsised. kasutades JSON-formaadis faili.
• GuzzleHttp\Cookie\SessionCookieJar klass säilitab küpsised dokumendis. kliendi sessioonis.

Küpsiseid saab käsitsi küpsiste purki panna nimega konstruktoriga fromArray(array $cookies, $domain).

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

Küpsise saab kätte selle nime järgi meetodiga getCookieByName($name), mis tagastab GuzzleHttp\Cookie\SetCookie instantsi.

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

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

Küpsiseid saab ka massiivina kätte tänu meetodile toArray(). GuzzleHttp\Cookie\CookieJarInterface liides laiendab GuzzleHttp\Cookie\CookieJarInterface liidest. Traversable, nii et seda saab korrata foreach-tsüklis.

Ümbersuunamised¶

Guzzle järgib automaatselt ümbersuunamisi, kui te ei ütle talle, et ta seda ei tee. Te saate kohandada ümbersuunamise käitumist, kasutades allow_redirects taotluse valikut.

• Määra true, et võimaldada tavalisi ümbersuunamisi, mille maksimaalne arv on 5. ümbersuunamised. See on vaikimisi seade.
• Määrake false, et keelata ümbersuunamised.
• Anda üle assotsiatiivne massiivi, mis sisaldab võtit 'max', et määrata maksimaalset ümbersuunamiste arvu ja valikuliselt anda võtme 'strict' väärtus, et määrata ümberjuhatuste arv. kas kasutada range RFC-konformseid ümbersuunamisi või mitte (st ümbersuunata POSTi taotlusi POST päringutega vs. teha seda, mida enamik brausereid teeb, mis on POST-päringute ümbersuunamine GET-päringutega).

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

Järgmine näide näitab, et ümbersuunamisi saab keelata.

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

Erandid¶

Tree View

Järgmine puuvaade kirjeldab, kuidas Guzzle'i erandid üksteisest sõltuvad.

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

Guzzle viskab ülekande ajal tekkivate vigade korral erandeid.

• Erand GuzzleHttp\Exception\ConnectException on visatud erandis võrguühenduse vea korral. See erand laieneb GuzzleHttp\Exception\TransferException.

• A GuzzleHttp\Exception\ClientException is thrown for 400 taseme vead, kui http_errors taotluse valikuks on seatud true. See erand laieneb GuzzleHttp\Exception\BadResponseException ja GuzzleHttp\Exception\BadResponseException ja GuzzleHttp\Exception\BadResponseException laieneb aastast 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());
  }
  

• GuzzleHttp\Exception\ServerException visatakse 500 taseme korral. vead, kui http_errors taotluse valikuks on seatud true. See erand laieneb GuzzleHttp\Exception\BadResponseException

• GuzzleHttp\Exception\TooManyRedirectsException visatakse siis, kui liiga palju palju ümbersuunamisi järgitakse. See erand laieneb GuzzleHttp\Exception\RequestException

Kõik ülaltoodud erandid tulenevad GuzzleHttp\Exception\TransferException.

Keskkonnamuutujad¶

Guzzle avaldab mõned keskkonnamuutujad, mida saab kasutada raamatukogu käitumise kohandamiseks.

GUZZLE_CURL_SELECT_TIMEOUT

Kontrollib kestust sekundites, mida curl_multi_* käitleja kasutab, kui valides curl-käepidemeid, kasutades curl_multi_select(). Mõned süsteemid on probleeme PHP rakendusega curl_multi_select(), kus selle funktsiooni kutsumine toob alati kaasa ootamise maksimaalse kestusega timeouti.

HTTP_PROXY

Määratleb proxy, mida kasutatakse päringute saatmisel http-protokolli kasutades.

Märkus: kuna muutuja HTTP_PROXY võib mõnes (CGI) keskkonnas sisaldada suvalist kasutaja sisendit, kasutatakse seda muutujat ainult CLI SAPI-s. Lisateavet vt https://httpoxy.org.

HTTPS_PROXY

Määratleb proxy, mida kasutatakse päringute saatmisel https-protokolli kasutades.

NO_PROXY

Määratleb URL-aadressid, mille puhul ei tohiks kasutada proxy't. Vt proxy kasutamise kohta.