Gyorstalpaló¶

Ez az oldal egy gyors bevezetést nyújt a Guzzle-hez és bevezető példákat. Ha még nem telepítette a Guzzle-t, látogasson el a Telepítés oldalra. oldalra.

Kérelem benyújtása¶

A Guzzle segítségével egy GuzzleHttp\ClientInterface objektummal küldhetünk kéréseket.

Ügyfél létrehozása¶

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

A kliensek megváltoztathatatlanok a Guzzle-ben, ami azt jelenti, hogy az ügyfél által használt alapértelmezett beállításokat nem lehet megváltoztatni a létrehozása után.

Az ügyfélkonstruktor az opciók asszociatív tömbjét fogadja el:

base_uri

(string|UriInterface) Az ügyfél alap URI-je, amely a relatívba van beolvasztva. URI-kba. Lehet egy string vagy az UriInterface példánya. Amikor egy relatív URI kliensnek adunk meg, a kliens az alap URI-t kombinálja a relatív URI-vel a következő pontban leírt szabályok szerint RFC 3986, 5.2. szakasz.

// Létrehoz egy ügyfelet egy alap URI-vel.
$client = new GuzzleHttp\Client(['base_uri' => 'https://foo.com/api/']);
// Kérés küldése a https://foo.com/api/test címre.
$response = $client->request('GET', 'test');
// Kérés küldése a https://foo.com/root címre
$response = $client->request('GET', '/root');

Nincs kedve elolvasni az RFC 3986-ot? Íme néhány gyors példa arra, hogyan oldódik fel egy base_uri egy másik URI-val.

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

(hívható) A HTTP-kérelmeket vezeték útján továbbító függvény. A függvényt egy Psr7\Http\Message\RequestInterface és egy tömbös az átviteli opciókból, és vissza kell adnia egy GuzzleHttp\Promise\PromiseInterface, amely egy

-val teljesül.
Psr7\Http\Message\ResponseInterface

siker esetén.

...

(vegyes) A konstruktornak átadott összes többi opciót alapértelmezettként használjuk. kérési opciók minden, az ügyfél által létrehozott kérésnél.

Kérések küldése¶

Az ügyfél mágikus módszerei megkönnyítik a szinkron kérések küldését:

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

Létrehozhat egy kérést, majd elküldheti a kérést az ügyféllel együtt, amikor készen áll:

use GuzzleHttp\Psr7\Request;

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

Az ügyfélobjektumok nagyfokú rugalmasságot biztosítanak a kérések átvitelét, beleértve az alapértelmezett kérési opciókat, az alapértelmezett kezelő stack middleware-t amelyeket minden egyes kérés használ, és egy alap URI-t, amely lehetővé teszi a kérések küldését. relatív URI-kkal.

A kliens middleware-ről többet megtudhat a dokumentáció Handlers and Middleware oldalán.

Aszinkron kérések¶

Aszinkron kéréseket az ügyfél által biztosított mágikus módszerekkel küldhet:

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

Használhatja az ügyfél sendAsync() és requestAsync() módszereit is:

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

Az ezen metódusok által visszaadott ígéret megvalósítja a Promises/A+ specifikációt, amelyet a Guzzle ígéret könyvtár által biztosított Guzzle ígéret könyvtár. Ez azt jelenti, hogy hogy az ígéretből then() hívások láncolhatók. Ezek a then hívások a következők vagy egy sikeres Psr\Http\Message\ResponseInterface vagy egy sikeres -val teljesülnek. elutasítva egy kivétellel.

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

Egyidejű kérések¶

Az ígéretek és az aszinkron kérések segítségével több kérést is küldhetsz egyidejűleg.

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

A GuzzleHttp\Pool objektumot akkor használhatja, ha meghatározatlan számú kérést szeretne elküldeni.

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

Vagy egy olyan lezárás használata, amely visszaad egy ígéretet, amint a pool meghívja a lezárást.

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

Válaszok használata¶

Az előző példákban egy $response változót hívtunk le, vagy egy $response változót. választ kaptunk egy ígéretből. A response objektum egy PSR-7 válasz, Psr\Http\Message\ResponseInterface, és sok-sok -ot tartalmaz. hasznos információt tartalmaz.

Megkaphatja a válasz állapotkódját és indoklását:

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

A válaszból lekérdezheti a fejléceket:

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

A válasz teste a getBody metódussal kérhető le. A testet stringként, stringgé alakítva vagy stream-szerű objektumként lehet használni.

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

A lekérdezési karakterlánc paraméterei¶

A lekérdezési karakterlánc paramétereit többféleképpen is megadhatja egy kéréssel együtt.

A lekérdezési karakterlánc paramétereit a kérés URI-jában állíthatja be:

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

A lekérdezési karakterlánc paramétereit a query kérési opcióval adhatja meg tömbként.

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

Ha az opciót tömbként adjuk meg, akkor a PHP http_build_query függvényét használjuk a lekérdezési karakterlánc formázására.

Végül pedig megadhatja a query kérési opciót stringként.

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

Adatok feltöltése¶

A Guzzle többféle módszert kínál az adatok feltöltésére.

Az adatfolyamot tartalmazó kéréseket egy karakterlánc átadásával küldheti el, fopen által visszaadott erőforrás, vagy egy példánya egy Psr\Http\Message\StreamInterface a body kérési opcióhoz.

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

A JSON-adatok feltöltésének és a megfelelő fejléc beállításának egyszerű módja a json kérési opció használata:

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

POST/űrlapkérelmek¶

A kérés nyers adatainak a body kérési opcióval történő megadása mellett a Guzzle hasznos absztrakciókat biztosít a POST-adatok küldéséhez.

Az űrlap mezőinek elküldése¶

A application/x-www-form-urlencoded POST-kérések küldése megköveteli, hogy a POST-mezőket a form_params kérési beállításokban tömbként adja meg.

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

Formanyomtatványok küldése¶

Az űrlapokkal együtt fájlokat is küldhetünk (multipart/form-data POST kérések), a multipart kérési opcióval. multipart elfogad egy tömbnyi asszociatív tömböket, ahol minden egyes asszociatív tömb a következő kulcsokat tartalmazza:

name: (kötelező, string) az űrlapmező nevéhez tartozó kulcs.
tartalom: (kötelező, vegyes) Adjon meg egy karakterláncot, amivel elküldi a fájl tartalmának stringként történő átviteléhez, fopen erőforrás megadása a tartalom streameléséhez egy PHP folyamból, vagy adjon meg egy Psr\Http\Message\StreamInterface adatfolyamot a tartalom átviteléhez. tartalmát egy PSR-7 folyamból.

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ütik¶

A Guzzle képes fenntartani egy cookie-munkamenetet az Ön számára, ha utasítást kap a cookies kérési opcióval. A kérés küldésekor a cookies opcióval a GuzzleHttp\Cookie\CookieJarInterface egy példányára kell beállítani.

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

A cookies értéket true beállíthatja egy ügyfélkonstruktorban, ha egy közös cookie-tárolót szeretne használni minden kéréshez.

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

Különböző implementációk léteznek a GuzzleHttp\Cookie\CookieJarInterface :

A GuzzleHttp\Cookie\CookieJar osztály a sütiket tömbként tárolja.
A GuzzleHttp\Cookie\FileCookieJar osztály a nem munkamenethez tartozó cookie-kat tárolja. egy JSON formátumú fájl segítségével.
A GuzzleHttp\Cookie\SessionCookieJar osztály a cookie-kat a cookie-kat a fájlban tárolja. kliens munkamenetben.

A cookie-kat manuálisan is beállíthatod a cookie-edénybe a fromArray(array $cookies, $domain) nevű konstruktorral.

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

Egy cookie-t a neve alapján a getCookieByName($name)(/span) módszerrel kaphatunk meg, amely egy GuzzleHttp\Cookie\SetCookie példányt ad vissza.

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

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

A cookie-kat a toArray() metódusnak köszönhetően egy tömbbe is be lehet gyűjteni. A GuzzleHttp\Cookie\CookieJarInterface interfész kiterjeszti a -ot. Traversable, így egy foreach ciklusban iterálható.

Átirányítások¶

A Guzzle automatikusan követi az átirányításokat, hacsak nem mondja, hogy ne tegye. Az átirányítási viselkedést a allow_redirects kérési opcióval testre szabhatja.

Állítsa true értékre, hogy engedélyezze a normál átirányításokat, maximum 5 darabig. átirányítások. Ez az alapértelmezett beállítás.
Állítsa false értékre az átirányítások letiltásához.
Adjon át egy asszociatív tömböt, amely tartalmazza a 'max' kulcsot a maximális érték megadásához. átirányítások számát, és opcionálisan megadhat egy 'strict' kulcsértéket az átirányítások számának megadásához. hogy szigorú RFC-kompatibilis átirányításokat használjon-e vagy sem (azaz a POST átirányítás kéréseket POST kérésekkel, szemben azzal, amit a legtöbb böngésző tesz, ami a következő POST kérések átirányítása GET kérésekkel).

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

A következő példa azt mutatja, hogy az átirányítások letilthatók.

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

Kivételek¶

Fa nézet

A következő fa nézet leírja, hogy a Guzzle kivételek hogyan függenek egymástól.

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

A Guzzle kivételeket dob az átvitel során fellépő hibák esetén.

A GuzzleHttp\Exception\ConnectException kivétel dobott a -ban. hálózati hiba esetén. Ez a kivétel a GuzzleHttp\Exception\TransferException.

A GuzzleHttp\Exception\ClientException a 400 szintű hibák esetén, ha a http_errors kérési opció true-ra van állítva. Ez a kivétel a GuzzleHttp\Exception\BadResponseException és 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());
}

A GuzzleHttp\Exception\ServerException 500 szint esetén dobódik. hibákat, ha a http_errors kérési opció true-ra van állítva. Ez a kivétel a GuzzleHttp\Exception\BadResponseException
kiterjesztése.
A GuzzleHttp\Exception\TooManyRedirectsException akkor dobódik, amikor túl sok sok átirányítást követ. Ez a kivétel a GuzzleHttp\Exception\RequestException
kiterjesztése.

A fenti kivételek mindegyike a GuzzleHttp\Exception\TransferException kiterjesztése.

Környezeti változók¶

A Guzzle tartalmaz néhány környezeti változót, amelyekkel testreszabható a könyvtár viselkedése.

GUZZLE_CURL_SELECT_TIMEOUT

Azt az időtartamot szabályozza másodpercben, amelyet a curl_multi_* kezelő használ, amikor a a curl-kezelőket választja ki a curl_multi_select() használatával. Néhány rendszer problémák vannak a curl_multi_select() PHP implementációjával, amikor is ennek a függvénynek a meghívása mindig a maximális időtartamú várakozást eredményezi. timeout időtartamára.

HTTP_PROXY

Meghatározza a "http" protokollt használó kérések küldéséhez használandó proxy-t.

Megjegyzés: mivel a HTTP_PROXY változó néhány (CGI) környezetben tetszőleges felhasználói bevitelt tartalmazhat, a változót csak a CLI SAPI-ban használjuk. További információért lásd https://httpoxy.org https://httpoxy.org.

HTTPS_PROXY

Meghatározza a "https" protokollt használó kérések küldéséhez használandó proxy-t.

NO_PROXY

Meghatározza azokat az URL-címeket, amelyekhez nem szabad proxyt használni. A használatról lásd proxy.

Releváns ini beállítások¶

A Guzzle képes a PHP ini beállításokat használni az ügyfelek konfigurálásakor.

openssl.cafile: Megadja egy PEM formátumú hitelesítésszolgáltatói fájl lemezen található elérési útvonalát, amelyet a következő fájl küldéséhez kell használni "https"-en keresztüli kérések küldéséhez. Lásd: https://wiki.php.net/rfc/tls-peer-verification#phpini_defaults

Tartalomjegyzék