Quickstart¶

Eine Anfrage stellen¶

Sie können mit Guzzle Anfragen über ein GuzzleHttp\ClientInterface Objekt senden.

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

Verwendung von Antworten¶

In den vorherigen Beispielen haben wir eine $response Variable abgerufen oder wir haben eine Antwort aus einem Versprechen erhalten. Das Antwortobjekt implementiert eine PSR-7 Antwort, Psr\Http\Message\ResponseInterface, und enthält eine Menge hilfreiche Informationen.

Sie können den Statuscode und die Begründung der Antwort abrufen:

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

Sie können Kopfzeilen aus der Antwort abrufen:

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

Der Body einer Antwort kann mit der Methode getBody abgerufen werden. Der Body kann als String verwendet, in einen String umgewandelt oder als streamähnliches Objekt verwendet werden.

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

Query String Parameter¶

Sie können Query-String-Parameter auf verschiedene Weise mit einer Anfrage übermitteln.

Sie können Abfrage-String-Parameter in der URI der Anfrage festlegen:

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

Sie können die Parameter der Abfragezeichenfolge mit der query Anfrageoption als Array angeben.

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

Wenn Sie die Option als Array angeben, wird die PHP-Funktion http_build_query zur Formatierung des Abfrage-Strings verwendet.

Und schließlich können Sie die query Anfrageoption als Zeichenfolge angeben.

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

Daten hochladen¶

Guzzle bietet mehrere Methoden zum Hochladen von Daten.

Sie können Anfragen senden, die einen Datenstrom enthalten, indem Sie einen String übergeben, Ressource, die von fopen zurückgegeben wird, oder eine Instanz eines Psr\Http\Message\StreamInterface an die body Anfrageoption übergeben.

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

Eine einfache Möglichkeit, JSON-Daten hochzuladen und die entsprechende Kopfzeile zu setzen, ist die Verwendung der json Anfrageoption:

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

Cookies¶

Guzzle kann eine Cookie-Sitzung für Sie aufrechterhalten, wenn Sie mit der cookies Anfrageoption angewiesen wird. Wenn Sie eine Anfrage senden, muss die Option cookies auf eine Instanz von GuzzleHttp\Cookie\CookieJarInterface gesetzt werden.

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

Sie können cookies in einem Client-Konstruktor auf true setzen, wenn Sie ein gemeinsames Cookie-Gefäß für alle Anfragen verwenden möchten.

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

Für das GuzzleHttp\Cookie\CookieJarInterface existieren verschiedene Implementierungen:

• Die Klasse GuzzleHttp\Cookie\CookieJar speichert Cookies als Array.
• Die Klasse GuzzleHttp\Cookie\FileCookieJar bewahrt Nicht-Session-Cookies unter Verwendung einer JSON-formatierten Datei.
• Die Klasse GuzzleHttp\Cookie\SessionCookieJar bewahrt Cookies in der Client-Sitzung.

Sie können Cookies mit dem benannten Konstruktor fromArray(array $cookies, $domain) manuell in eine Cookie-Dose setzen.

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

Mit der Methode getCookieByName($name), die eine GuzzleHttp\Cookie\SetCookie Instanz zurückgibt, können Sie ein Cookie anhand seines Namens abrufen.

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

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

Die Cookies können dank der Methode toArray() auch in ein Array geholt werden. Die GuzzleHttp\Cookie\CookieJarInterface Schnittstelle erweitert Traversable, so dass sie in einer foreach-Schleife durchlaufen werden kann.

Weiterleitungen¶

Guzzle folgt automatisch Weiterleitungen, es sei denn, Sie weisen es an, dies nicht zu tun. Sie können das Weiterleitungsverhalten mit der allow_redirects Anfrageoption anpassen.

• Auf true gesetzt, um normale Weiterleitungen mit einer maximalen Anzahl von 5 Weiterleitungen. Dies ist die Standardeinstellung.
• Setzen Sie diesen Wert auf false, um Weiterleitungen zu deaktivieren.
• Übergeben Sie ein assoziatives Array mit dem 'max'-Schlüssel zur Angabe der maximalen Anzahl von Umleitungen und optional einen 'strict'-Schlüsselwert, um anzugeben ob strikte RFC-konforme Umleitungen verwendet werden sollen oder nicht (d.h. Umleitung von POST Anfragen mit POST-Anfragen umzuleiten im Gegensatz zu dem, was die meisten Browser tun, nämlich POST-Anfragen mit GET-Anfragen umleiten).

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

Das folgende Beispiel zeigt, dass Umleitungen deaktiviert werden können.

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

Ausnahmen¶

Baumansicht

Die folgende Strukturansicht beschreibt, wie die Guzzle-Ausnahmen voneinander abhängen.

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

Guzzle löst bei Fehlern, die während einer Übertragung auftreten, Ausnahmen aus.

• Eine GuzzleHttp\Exception\ConnectException Ausnahme wird bei einem Fall eines Netzwerkfehlers ausgelöst. Diese Ausnahme ist eine Erweiterung von GuzzleHttp\Exception\TransferException.

• Eine GuzzleHttp\Exception\ClientException wird bei 400 Level Fehlern ausgelöst, wenn die http_errors Anfrageoption auf true gesetzt ist. Diese Ausnahme erweitert sich von GuzzleHttp\Exception\BadResponseException und GuzzleHttp\Exception\BadResponseException extends from 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());
  }
  

• Eine GuzzleHttp\Exception\ServerException wird bei Fehlern der Stufe 500 ausgelöst Fehler ausgelöst, wenn die Anfrageoption http_errors auf true gesetzt ist. Diese Ausnahme ist eine Erweiterung von GuzzleHttp\Exception\BadResponseException.

• Eine GuzzleHttp\Exception\TooManyRedirectsException wird ausgelöst, wenn zu viele viele Weiterleitungen verfolgt werden. Diese Ausnahme ist eine Erweiterung von GuzzleHttp\Exception\RequestException.

Alle oben genannten Ausnahmen stammen von GuzzleHttp\Exception\TransferException ab.

Umgebungsvariablen¶

Guzzle stellt einige Umgebungsvariablen zur Verfügung, mit denen das Verhalten der Bibliothek angepasst werden kann.

GUZZLE_CURL_SELECT_TIMEOUT

Steuert die Dauer in Sekunden, die ein curl_multi_* Handler verwendet, wenn bei der Auswahl von Curl-Handles mit curl_multi_select(). Einige Systeme haben Probleme mit PHPs Implementierung von curl_multi_select(), wo der Aufruf dieser Funktion immer dazu führt, dass die maximale Dauer des der Zeitüberschreitung.

HTTP_PROXY

Legt den Proxy fest, der beim Senden von Anfragen über das "http"-Protokoll verwendet werden soll.

Hinweis: Da die HTTP_PROXY-Variable in einigen (CGI-)Umgebungen beliebige Benutzereingaben enthalten kann, wird die Variable nur im CLI SAPI verwendet. Siehe https://httpoxy.org für weitere Informationen.

HTTPS_PROXY

Legt den Proxy fest, der beim Senden von Anfragen über das "https"-Protokoll verwendet wird.

NO_PROXY

Definiert URLs, für die ein Proxy nicht verwendet werden soll. Zur Verwendung siehe proxy.