Бърз старт¶

Подаване на заявка¶

Можете да изпращате заявки с Guzzle, като използвате обект GuzzleHttp\ClientInterface.

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

Използване на отговорите¶

В предишните примери извличахме променлива $response или бяхме получихме отговор от обещание. Обектът на отговора имплементира PSR-7 отговор, Psr\Http\Message\ResponseInterface, и съдържа много полезна информация.

Можете да получите кода на състоянието и фразата за причина на отговора:

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

Можете да извличате заглавия от отговора:

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

Тялото на отговора може да бъде извлечено чрез метода getBody. Тялото може да се използва като низ, да се превърне в низ или да се използва като обект, подобен на поток.

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

Параметри на низ от запитвания¶

Можете да предоставите параметри на заявката по няколко начина.

Можете да зададете параметри на низ от заявки в URI на заявката:

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

Можете да зададете параметрите на низа на заявката, като използвате опцията за заявка query като масив.

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

Предоставянето на опцията като масив ще използва функцията на PHP http_build_query за форматиране на заявката.

И накрая, можете да предоставите опцията за заявка query като низ.

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

Качване на данни¶

Guzzle предоставя няколко метода за качване на данни.

Можете да изпращате заявки, които съдържат поток от данни, като предавате низ, ресурс, върнат от fopen, или инстанция на Psr\Http\Message\StreamInterface към опцията 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]);

Лесен начин за качване на JSON данни и задаване на подходящ хедър е използването на опцията за заявка json:

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

Бисквитки¶

Guzzle може да поддържа сесия с бисквитки за вас, ако сте инструктирани с помощта на cookies опция за заявка. Когато изпращате заявка, опцията cookies трябва да бъде зададена като инстанция на GuzzleHttp\Cookie\CookieJarInterface.

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

Можете да зададете cookies на true в конструктора на клиента, ако искате да използвате общ буркан с бисквитки за всички заявки.

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

Съществуват различни имплементации за GuzzleHttp\Cookie\CookieJarInterface :

• Класът GuzzleHttp\Cookie\CookieJar съхранява бисквитките като масив.
• Класът GuzzleHttp\Cookie\FileCookieJar запазва бисквитките, които не са от сесията. с помощта на файл, форматиран в JSON.
• Класът GuzzleHttp\Cookie\SessionCookieJar запазва бисквитките в сесията на клиента.

Можете ръчно да зададете "бисквитки" в буркан за "бисквитки" с именувания конструктор fromArray(array $cookies, $domain).

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

Можете да получите бисквитка по нейното име с метода getCookieByName($name), който връща GuzzleHttp\Cookie\SetCookie инстанция.

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

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

Бисквитките могат да се извличат и в масив благодарение на метода toArray(). Интерфейсът GuzzleHttp\Cookie\CookieJarInterface разширява Traversable, така че може да бъде претърсван в цикъла foreach.

Пренасочвания¶

Guzzle автоматично ще следва пренасочвания, освен ако не му кажете да не го прави. Можете да персонализирате поведението на пренасочване, като използвате опцията за заявка allow_redirects.

• Задайте на true, за да разрешите нормални пренасочвания с максимален брой 5 пренасочвания. Това е настройката по подразбиране.
• Задайте false, за да деактивирате пренасочването.
• Подаване на асоциативен масив, съдържащ ключа 'max', за да се посочи максималната стойност на пренасочвания и по желание предоставя стойност на ключа 'strict', за да се определи дали да се използват стриктни пренасочвания в съответствие с RFC (което означава пренасочване на POST заявки с POST заявки срещу това, което правят повечето браузъри, а именно пренасочване на POST заявки с GET заявки).

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

Следващият пример показва, че пренасочването може да бъде деактивирано.

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

Изключения¶

Изглед на дърво

Следният дървовиден изглед описва как изключенията на Guzzle зависят едно от друго.

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

Guzzle хвърля изключения за грешки, които възникват по време на прехвърлянето.

• Изключение GuzzleHttp\Exception\ConnectException се хвърля в в случай на грешка в мрежата. Това изключение се разширява от GuzzleHttp\Exception\TransferException.

• Изхвърля се GuzzleHttp\Exception\ClientException за 400 ниво, ако опцията за заявка http_errors е настроена на true. Това изключение се разширява от GuzzleHttp\Exception\BadResponseException и GuzzleHttp\Exception\BadResponseException разширява от GuzzleHttp\Exception\RequestException.

  използвайте 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 за ниво 500 ако опцията за заявка http_errors е настроена на true. Тази опция изключение се разширява от GuzzleHttp\Exception\BadResponseException.

• Изключение GuzzleHttp\Exception\TooManyRedirectsException се хвърля, когато твърде много се следват твърде много пренасочвания. Това изключение се разширява от GuzzleHttp\Exception\RequestException.

Всички горепосочени изключения се разширяват от GuzzleHttp\Exception\TransferException.

Променливи на средата¶

Guzzle предлага няколко променливи на средата, които могат да се използват за персонализиране на поведението на библиотеката.

GUZZLE_CURL_SELECT_TIMEOUT

Контролира продължителността в секунди, която ще се използва от curl_multi_* манипулатора, когато при избиране на curl манипулатори с помощта на curl_multi_select(). Някои системи имат проблеми с имплементацията на PHP на curl_multi_select(), където извикването на тази функция винаги води до изчакване на максималната продължителност на времетраенето.

HTTP_PROXY

Определя прокси сървъра, който да се използва при изпращане на заявки чрез протокола "http".

Забележка: тъй като променливата HTTP_PROXY може да съдържа произволен потребителски вход в някои (CGI) среди, променливата се използва само в CLI SAPI. Вижте https://httpoxy.org за повече информация.

HTTPS_PROXY

Определя прокси сървъра, който да се използва при изпращане на заявки чрез протокола "https".

NO_PROXY

Дефинира URL адреси, за които не трябва да се използва прокси. Вижте proxy за употреба.