Αυτή η σελίδα παρέχει μια γρήγορη εισαγωγή στο Guzzle και εισαγωγικά παραδείγματα. Αν δεν έχετε ήδη εγκαταστήσει το Guzzle, μεταβείτε στη σελίδα Εγκατάσταση σελίδα.
Μπορείτε να στέλνετε αιτήσεις με το 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,
]);
Οι πελάτες είναι αμετάβλητοι στο Guzzle, πράγμα που σημαίνει ότι δεν μπορείτε να αλλάξετε τις προεπιλογές που χρησιμοποιούνται από έναν πελάτη μετά τη δημιουργία του.
Ο κατασκευαστής του πελάτη δέχεται έναν συσχετιστικό πίνακα επιλογών:
base_uri
(string|UriInterface) Βασικό URI του πελάτη που συγχωνεύεται σε σχετικό URIs. Μπορεί να είναι μια συμβολοσειρά ή μια περίπτωση του UriInterface. Όταν ένα σχετικό URI παρέχεται σε έναν πελάτη, ο πελάτης θα συνδυάσει το βασικό URI με το σχετικό URI χρησιμοποιώντας τους κανόνες που περιγράφονται στην ενότητα RFC 3986, ενότητα 5.2.
// Δημιουργία ενός πελάτη με ένα βασικό URI
$client = new GuzzleHttp\Client(['base_uri' => 'https://foo.com/api/']),
// Αποστολή αίτησης στο https://foo.com/api/test
$response = $client->request('GET', 'test'),
// Αποστολή αιτήματος στο https://foo.com/root
$response = $client->request('GET', '/root'),
Δεν έχετε όρεξη να διαβάσετε το RFC 3986; Εδώ είναι μερικά γρήγορα παραδείγματα για το πώς ένα base_uri
επιλύεται με ένα άλλο URI.
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
Psr7\Http\Message\RequestInterface
και πίνακα
των επιλογών μεταφοράς και πρέπει να επιστρέφει ένα
GuzzleHttp\Promise\PromiseInterface
που εκπληρώνεται με ένα
Psr7\Http\Message\ResponseInterface
σε περίπτωση επιτυχίας....
Οι μαγικές μέθοδοι στον πελάτη διευκολύνουν την αποστολή συγχρονισμένων αιτήσεων:
$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]);
Τα αντικείμενα-πελάτες παρέχουν μεγάλη ευελιξία στον τρόπο με τον οποίο οι αιτήσεις μεταφέρονται, συμπεριλαμβανομένων των προεπιλεγμένων επιλογών αίτησης, του προεπιλεγμένου ενδιάμεσου λογισμικού στοίβας χειριστών που χρησιμοποιούνται από κάθε αίτηση, και ένα βασικό URI που σας επιτρέπει να στέλνετε αιτήσεις με σχετικά URI.
Μπορείτε να μάθετε περισσότερα για το ενδιάμεσο λογισμικό πελάτη στη σελίδα Handlers and Middleware της τεκμηρίωσης.
Μπορείτε να στείλετε ασύγχρονες αιτήσεις χρησιμοποιώντας τις μαγικές μεθόδους που παρέχονται από έναν πελάτη:
$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');
Μπορείτε επίσης να χρησιμοποιήσετε τις μεθόδους sendAsync() και requestAsync() ενός πελάτη:
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');
Η υπόσχεση που επιστρέφεται από αυτές τις μεθόδους υλοποιεί την
Promises/A+ spec, που παρέχεται από την
Guzzle promises library. Αυτό σημαίνει
ότι μπορείτε να κάνετε αλυσιδωτές then()
κλήσεις από την υπόσχεση. Αυτές οι κλήσεις then είναι
είτε εκπληρώνονται με μια επιτυχή Psr\Http\Message\ResponseInterface
ή
απορρίπτεται με μια εξαίρεση.
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];
Μπορείτε να χρησιμοποιήσετε το αντικείμενο GuzzleHttp\Pool
όταν έχετε έναν απροσδιόριστο αριθμό αιτήσεων που θέλετε να στείλετε.
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();
Ή χρησιμοποιώντας ένα closure που θα επιστρέψει μια υπόσχεση μόλις η δεξαμενή καλέσει το closure.
$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
μεταβλητή ή ήμασταν
παραδώσαμε μια απάντηση από μια υπόσχεση. Το αντικείμενο response υλοποιεί ένα PSR-7
response, 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']
]);
Η παροχή της επιλογής ως πίνακα θα χρησιμοποιήσει τη συνάρτηση http_build_query
της PHP για τη μορφοποίηση της συμβολοσειράς ερωτήματος.
Και τέλος, μπορείτε να παρέχετε την 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']
]);
Εκτός από τον προσδιορισμό των ακατέργαστων δεδομένων μιας αίτησης χρησιμοποιώντας την επιλογή body
, το Guzzle παρέχει χρήσιμες αφαιρέσεις για την αποστολή δεδομένων POST.
Η αποστολή αιτήσεων application/x-www-form-urlencoded
POST απαιτεί να καθορίσετε τα πεδία POST ως πίνακα στις επιλογές αίτησης form_params
.
$response = $client->request('POST', 'http://httpbin.org/post', [
'form_params' => [
'field_name' => 'abc',
'other_field' => '123',
'nested_field' => [
'nested' => 'hello'
]
]
]);
Μπορείτε να στέλνετε αρχεία μαζί με μια φόρμα (multipart/form-data
αιτήσεις POST),
χρησιμοποιώντας την επιλογή αίτησης multipart
. multipart
δέχεται έναν πίνακα από
συσχετιζόμενων πινάκων, όπου κάθε συσχετιζόμενος πίνακας περιέχει τα ακόλουθα κλειδιά:
Psr\Http\Message\StreamInterface
για να μεταφέρει τα περιεχόμενα από μια ροή.
τα περιεχόμενα από μια ροή PSR-7.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 μπορεί να διατηρήσει μια περίοδο λειτουργίας cookie για εσάς, αν σας δοθεί εντολή χρησιμοποιώντας την εντολή
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
σε έναν κατασκευαστή πελάτη αν θέλετε να χρησιμοποιήσετε ένα κοινόχρηστο δοχείο cookies για όλες τις αιτήσεις.
// 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
αποθηκεύει τα cookies ως πίνακα.GuzzleHttp\Cookie\FileCookieJar
επιμένει στα cookies που δεν ανήκουν στην περίοδο συνεδρίασης.
χρησιμοποιώντας ένα διαμορφωμένο αρχείο JSON.GuzzleHttp\Cookie\SessionCookieJar
διατηρεί τα cookies στο αρχείο
συνεδρία του πελάτη.Μπορείτε να τοποθετήσετε χειροκίνητα cookies σε ένα cookie jar με τον ονομαστικό κατασκευαστή fromArray(array $cookies, $domain)
.
$jar = \GuzzleHttp\Cookie\CookieJar::fromArray(
[
'some_cookie' => 'foo',
'other_cookie' => 'barbaz1234'
],
'example.org'
);
Μπορείτε να λάβετε ένα cookie με βάση το όνομά του με τη μέθοδο 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
Τα cookies μπορούν επίσης να ανακτηθούν σε έναν πίνακα χάρη στη μέθοδο toArray().
Η διασύνδεση GuzzleHttp\Cookie\CookieJarInterface
επεκτείνει τη διασύνδεση
Traversable
ώστε να μπορεί να επαναληφθεί σε έναν βρόχο foreach.
Το Guzzle θα ακολουθεί αυτόματα τις ανακατευθύνσεις εκτός αν του πείτε να μην το κάνει. Μπορείτε να προσαρμόσετε τη συμπεριφορά ανακατεύθυνσης χρησιμοποιώντας την επιλογή αίτησης allow_redirects
.
true
για να ενεργοποιήσετε κανονικές ανακατευθύνσεις με μέγιστο αριθμό 5
ανακατευθύνσεων. Αυτή είναι η προεπιλεγμένη ρύθμιση.false
για να απενεργοποιήσετε τις ανακατευθύνσεις.$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
request option έχει οριστεί σε true. Αυτό το
εξαίρεση επεκτείνεται από την GuzzleHttp\Exception\BadResponseException
και
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()),
}
Μια GuzzleHttp\Exception\ServerException
πετάγεται για 500 επίπεδο
σφάλματα εάν η επιλογή http_errors
request option έχει οριστεί σε true. Αυτό το
εξαίρεση επεκτείνεται από την GuzzleHttp\Exception\BadResponseException
.
Μια GuzzleHttp\Exception\TooManyRedirectsException
πετιέται όταν πάρα πολλές
πολλές ανακατευθύνσεις ακολουθούνται. Αυτή η εξαίρεση επεκτείνεται από την GuzzleHttp\Exception\RequestException
.
Όλες οι παραπάνω εξαιρέσεις επεκτείνονται από την GuzzleHttp\Exception\TransferException
.
Το Guzzle διαθέτει μερικές μεταβλητές περιβάλλοντος που μπορούν να χρησιμοποιηθούν για την προσαρμογή της συμπεριφοράς της βιβλιοθήκης.
GUZZLE_CURL_SELECT_TIMEOUT
curl_multi_select()
. Ορισμένα συστήματα
έχουν προβλήματα με την υλοποίηση της PHP της curl_multi_select()
όπου
η κλήση αυτής της συνάρτησης οδηγεί πάντα σε αναμονή για τη μέγιστη διάρκεια του
του χρονικού ορίου.HTTP_PROXY
Καθορίζει τον διακομιστή μεσολάβησης που θα χρησιμοποιείται κατά την αποστολή αιτημάτων που χρησιμοποιούν το πρωτόκολλο "http"
Σημείωση: επειδή η μεταβλητή HTTP_PROXY μπορεί να περιέχει αυθαίρετη είσοδο χρήστη σε ορισμένα περιβάλλοντα (CGI), η μεταβλητή χρησιμοποιείται μόνο στο CLI SAPI. Δείτε https://httpoxy.org για περισσότερες πληροφορίες.
HTTPS_PROXY
NO_PROXY
Το Guzzle μπορεί να χρησιμοποιήσει τις ρυθμίσεις PHP ini κατά τη διαμόρφωση των πελατών.
openssl.cafile