Γρήγορη εκκίνηση

Αυτή η σελίδα παρέχει μια γρήγορη εισαγωγή στο 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
(μπορεί να κληθεί) Συνάρτηση που μεταφέρει αιτήσεις HTTP μέσω καλωδίου. Το συνάρτηση καλείται με μια Psr7\Http\Message\RequestInterface και πίνακα των επιλογών μεταφοράς και πρέπει να επιστρέφει ένα GuzzleHttp\Promise\PromiseInterface που εκπληρώνεται με ένα Psr7\Http\Message\ResponseInterface σε περίπτωση επιτυχίας.
...
(mixed) Όλες οι άλλες επιλογές που περνούν στον κατασκευαστή χρησιμοποιούνται ως προεπιλεγμένες επιλογές αίτησης με κάθε αίτηση που δημιουργείται από τον πελάτη.

Αποστολή αιτημάτων

Οι μαγικές μέθοδοι στον πελάτη διευκολύνουν την αποστολή συγχρονισμένων αιτήσεων:

$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 της τεκμηρίωσης.

Async Requests

Μπορείτε να στείλετε ασύγχρονες αιτήσεις χρησιμοποιώντας τις μαγικές μεθόδους που παρέχονται από έναν πελάτη:

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

POST/Form Requests

Εκτός από τον προσδιορισμό των ακατέργαστων δεδομένων μιας αίτησης χρησιμοποιώντας την επιλογή 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 δέχεται έναν πίνακα από συσχετιζόμενων πινάκων, όπου κάθε συσχετιζόμενος πίνακας περιέχει τα ακόλουθα κλειδιά:

  • name: (υποχρεωτικό, αλφαριθμητικό) αντιστοίχιση κλειδιού με το όνομα του πεδίου της φόρμας.
  • περιεχόμενα: (Δώστε μια συμβολοσειρά για να στείλετε τα περιεχόμενα του αρχείου ως συμβολοσειρά, παρέχετε έναν πόρο fopen για τη ροή των περιεχομένων από ένα PHP stream, ή παρέχετε μια 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'
            ]
        ]
    ]
]);

Cookies

Το 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 για να απενεργοποιήσετε τις ανακατευθύνσεις.
  • Περάστε έναν συσχετιστικό πίνακα που περιέχει το κλειδί '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 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_* θα χρησιμοποιήσει όταν επιλογή σε χειριστήρια 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 για τη χρήση.

Σχετικές ρυθμίσεις ini

Το Guzzle μπορεί να χρησιμοποιήσει τις ρυθμίσεις PHP ini κατά τη διαμόρφωση των πελατών.

openssl.cafile
Καθορίζει τη διαδρομή στο δίσκο προς ένα αρχείο CA σε μορφή PEM που θα χρησιμοποιηθεί κατά την αποστολή αιτήσεις μέσω "https". Βλ: https://wiki.php.net/rfc/tls-peer-verification#phpini_defaults