Ugrás a tartalomhoz

Fetch-átvitel

Megtekintés Markdownként Szerkesztés itt: GitHub Dokumentáció itt: 5b53f69

Az alapértelmezett fetch() a Phasis-ben a PHP ext-curl megoldásán fut: CURLOPT_FOLLOWLOCATION=false (a specifikáció szerinti átirányítási ciklus a Phasis oldalán fut), miközben a CURLOPT_PROGRESSFUNCTION ellenőrzi a AbortSignal-t. A legtöbb beágyazásnál ez megfelelő.

Minden más esetben — például proxyk, egyéni DNS, a gazdaalkalmazás meglévő HTTP kliense, hálózati homokozó vagy tesztbeli szimulálás esetén — az átviteli mód cserélhető.

A felület

PHP
public function setFetchTransport(callable $transport): void

A hívható elem a következőket kapja:

PHP
function (array $request, ?\Phasis\Value\JsObject $signal): array

A $request asszociatív tömb:

Kulcs Típus Megjegyzések
method string Már nagybetűs (GET, POST, …)
url string A URL feldolgozása és az átirányítási lánc után feloldott abszolút URL
headers list<list<string>> [name, value] párok; kis- és nagybetűzés a specifikáció szerinti normalizálással; a többször előforduló értékek külön párok (például Set-Cookie)
body string Nyers bájtok. Törzs nélküli metódusoknál üres karakterlánc.
redirect string "follow" / "error" / "manual" (az átviteli módnak NEM szabad követnie őket — az átirányítási ciklus a Phasis-ben fut)
timeout int Valós idejű keret milliszekundumban. A 0 azt jelenti: nincs korlát.
credentials string "omit" / "same-origin" / "include" — tájékoztató jellegű; a cookie-k bekötése külön, a setCookieJar() segítségével történik.

A $signal értéke null, ha a kéréshez nem tartozott jel; ellenkező esetben olyan JsObject, amely elérhetővé teszi az aborted és az reason értékét. Hosszú átvitelek közben rendszeresen ellenőrizze.

A visszatérési érték formája:

PHP
return [
    'status'     => 200,                          // int
    'statusText' => 'OK',                         // string
    'headers'    => [['content-type', 'text/plain'], ['x-custom', '1']],
    'body'       => '...response bytes...',       // string
];

Ha az átviteli mód kivételt dob, a Phasis elkapja és lefordítja:

  • Egy Phasis\BuiltIn\Fetch\TransportException a $e->kind === "aborted" értékkel → a fetch AbortError DOMException-mal utasítja el a kérést.
  • A kind === "timeout" → TypeError, az üzenettel együtt.
  • A kind === "network-error" (alapértelmezés) → TypeError.
  • Minden más esetben → TypeError a kivétel üzenetével.

Kidolgozott példák

Guzzle

PHP
use GuzzleHttp\Client;
use GuzzleHttp\Exception\GuzzleException;

$client = new Client(['allow_redirects' => false]);

$engine->setFetchTransport(function (array $req, $signal) use ($client) {
    try {
        $r = $client->request($req['method'], $req['url'], [
            'headers'     => collect($req['headers'])->groupBy(0)->map->pluck(1)->all(),
            'body'        => $req['body'],
            'timeout'     => max(1, $req['timeout'] / 1000.0),
            'http_errors' => false,
        ]);
    } catch (GuzzleException $e) {
        throw new \Phasis\BuiltIn\Fetch\TransportException($e->getMessage(), 'network-error');
    }
    $headers = [];
    foreach ($r->getHeaders() as $name => $values) {
        foreach ($values as $v) {
            $headers[] = [$name, $v];
        }
    }
    return [
        'status'     => $r->getStatusCode(),
        'statusText' => $r->getReasonPhrase(),
        'headers'    => $headers,
        'body'       => (string) $r->getBody(),
    ];
});

Symfony HttpClient

PHP
use Symfony\Component\HttpClient\HttpClient;

$client = HttpClient::create(['max_redirects' => 0]);

$engine->setFetchTransport(function (array $req, $signal) use ($client) {
    $headers = [];
    foreach ($req['headers'] as [$name, $value]) {
        $headers[$name][] = $value;
    }
    $r = $client->request($req['method'], $req['url'], [
        'headers'      => $headers,
        'body'         => $req['body'],
        'timeout'      => $req['timeout'] / 1000.0,
        'max_redirects'=> 0,
    ]);
    return [
        'status'     => $r->getStatusCode(),
        'statusText' => '',
        'headers'    => collect($r->getHeaders(false))
            ->flatMap(fn ($values, $name) => array_map(fn ($v) => [$name, $v], $values))
            ->values()->all(),
        'body'       => $r->getContent(false),
    ];
});

Mindent tiltó mód

PHP
$engine->setFetchTransport(function () {
    throw new \Phasis\BuiltIn\Fetch\TransportException(
        'network access disabled in this sandbox',
        'network-error',
    );
});

Ezzel minden fetch() hívás TypeError hibával utasítódik el. Hasznos a felhasználó által megadott JS kód homokozóba zárásához.

Tesztbeli szimuláció

PHP
$canned = [
    'https://api.example.com/users' => ['status' => 200, 'body' => '{"users":[]}'],
    'https://api.example.com/404'   => ['status' => 404, 'body' => 'not found'],
];

$engine->setFetchTransport(function (array $req) use ($canned) {
    $r = $canned[$req['url']] ?? ['status' => 500, 'body' => 'no mock'];
    return [
        'status'     => $r['status'],
        'statusText' => $r['status'] === 200 ? 'OK' : 'ERR',
        'headers'    => [['content-type', 'application/json']],
        'body'       => $r['body'],
    ];
});

A házirend-hook

Az átviteli mód végrehajtja a kérést; a házirend-hook dönti el, hogy egyáltalán végrehajtható-e. Használja HTTPS-alapú szabályozáshoz, fejléc beszúrásához, URL átírásához, engedélyezési listákhoz vagy bérlőnként eltérő hitelesítő adatok kötéséhez.

PHP
public function setFetchPolicy(callable $hook): void

A hook aláírása: function (JsObject $request): ?JsObject. A null visszaadása változatlanul engedélyezi a kérést. A Request visszaadása átírja. A kivételdobás a fetch elutasítását eredményezi a dobott hibával.

PHP
$allowedHosts = ['api.example.com', 'cdn.example.com'];

$engine->setFetchPolicy(function ($req) use ($allowedHosts) {
    $url = parse_url($req->get('url')->value);
    if (!in_array($url['host'] ?? '', $allowedHosts, true)) {
        throw new \RuntimeException("host not allowed: " . ($url['host'] ?? ''));
    }
    // Inject internal-only auth header
    $req->get('headers')->call('set', 'X-Internal-Token', $secret);
    return null;
});

A házirend-hook az átviteli mód előtt fut — így még egy hibás vagy nem megbízható átviteli mód sem tudja megkerülni.

Az alapértelmezett viselkedés összefoglalása

Tényező Alapértelmezés
Átviteli mód CurlTransport (PHP ext-curl)
Átirányítások Követés legfeljebb 20 alkalommal a specifikáció szerint. A redirect: "manual" az átirányított Response választ adja vissza type: "opaqueredirect" értékkel.
Időkorlát 30 s valós idő, 10 s csatlakozás
TLS ellenőrzése CURLOPT_SSL_VERIFYPEER = true (nem kapcsolható ki — az átviteli mód cseréjével írható felül)
User-Agent A Phasis/0.1 csak akkor kerül be, ha még nincs beállítva
Cookie-k Nincs tárolva. Az engedélyezéshez használja a setCookieJar() elemet.
Házirend-hook Nincs. Minden kérés engedélyezett, kivéve, ha kifejezetten letiltják.
AbortSignal Az átvitel közben a curl előrehaladási visszahívásának ellenőrzésével érvényesül.

Lásd még