9. diel - Štandardy jazyka PHP - PSR-7 (Rozhranie HTTP správ a prúdov)

V predchádzajúcej lekcii, Štandardy jazyka PHP - PSR-7 (Všeobecná špecifikácie a prúdy) , sme sa začali venovať štandardu PSR-7, popísali si HTTP správy a prúdy (streamy).

V lekcii PSR-7 sme sa venovali HTTP správam a prúdom a dnes si ukážeme, ako by sme s nimi mali správne pracovať.

Psr \ Http \ Message \ MessageInterface

Pod pojmom HTTP správy všeobecne rozumieme požiadavku klienta na server a odpoveď servera klientovi. Toto rozhranie definuje metódy, ktoré sú spoločné obom typom správ.

Správy sú považované za immutable objekty. Všetky metódy, ktoré môžu zmeniť stav požiadaviek alebo otázok musia byť implementované tak, aby ponechali pôvodné znenie a vrátili novú inštanciu sa zmeneným stavom - NESMIE teda prepísať stav pôvodnej.

Tohto rozhrania sa tiež týkajú štandardmi RFC 7230 a RFC 7231.

<?php
namespace Psr\Http\Message;

interface MessageInterface
{
    public function getProtocolVersion();
     /**
      * @return string
      */

Vracia verziu HTTP protokolu ako reťazec.

Reťazec MUSÍ obsahovať len číslo verzie, napríklad "1.1" alebo "1.0".

public function withProtocolVersion($version);
 /**
  * @param string $version
  * @return static
  */

Vracia inštanciu sa zadanou verzií HTTP protokolu.

Reťazec MUSÍ obsahovať len číslo verzie.

Táto funkcia MUSÍ byť implementovaná tak, aby zachovala nezmeniteľnosť (immutability) správy a MUSÍ vracať inštanciu s novou verziou protokolu.

/**
 *     // Reprezentuje hlavičku jako řetězec
 *     foreach ($message->getHeaders() as $name => $values) {
 *         echo $name . ': ' . implode(', ', $values);
 *     }
 *
 *     // Iterativně zobrazíme hlavičky
 *     foreach ($message->getHeaders() as $name => $values) {
 *         foreach ($values as $value) {
 *             header(sprintf('%s: %s', $name, $value), false);
 *         }
 *     }
 * @return string[][]
 */
public function getHeaders();

Vracia hodnoty všetkých záhlaví, kde kľúče reprezentujú názvy hlavičiek a každá hodnota pole reťazcov spojených s hlavičkou.

Kým názvy hlavičiek nie sú case-sensitive, funkcia getHeaders() zachová pôvodný zápis.

Každý kľúč MUSÍ byť názvom nejaké hlavičky a každá hodnota MUSÍ byť pole reťazcov danej hlavičky.

public function hasHeader($name);
/**
 * @param string $name
 * @return bool
 */

Funkcia hasHeader() zistí, či sa zadaný header v správe vyskytuje. Argument je opäť case-insensitive. Vracia hodnotu true, ak aspoň nejaký header odpovedá argumentu; v opačnom prípade vráti hodnotu false.

public function getHeader($name);
/**
 * @param string $name
 * @return string[]
 */

Funkcia getHeader() získa hodnotu header. Názov zadávame opäť ako case-insensitive. Vracia pole (v podobe reťazca) pre zadaný názov header.

Ak sa header v správe nenachádza, funkcia MUSÍ vrátiť prázdne polia.

public function getHeaderLine($name);
/**
 * @param string $name
 * @return string
 */

Funkcia getHeaderLine() vracia všetky hodnoty (jedného) header oddelené čiarkou. Argument $name musí byť zadávaný ako case-insensitive.

Ale pozor! Nie všetky hlavičky môžu byť týmto spôsobom správne zlúčia (napr. Set-Cookie). V týchto prípadoch použime radšej metódu getHeader() a pri spájaní potom aj vlastné oddeľovač. Ak sa v správe hlavička nenachádza, funkcia MUSÍ vrátiť prázdny string.

public function withHeader($name, $value);
/**
 * @param string $name
 * @param string|string[] $value // Nová hodnota
 * @return static
 * @throws \InvalidArgumentException
 *    // Výjimka pro neplatné argumenty (ať už hodnoty nebo názvy hlaviček)
 */

Vracia inštanciu sa zadanou hodnotou nahrádzajúci konkrétne header. Aj keď sú názvy hlavičiek case-insensitive, veľkosť písmen bude touto funkciou zachovaná a môže byť vrátená pomocou getHeaders().

Funkcia MUSÍ byť implementovaná tak, aby zachovala nezmeniteľnosť správy a MUSÍ vrátiť inštanciu s novou / aktualizovanú hodnotou.

public function withAddedHeader($name, $value);
/*
 * @param string $name Case-insensitive název
 * @param string|string[] $value
 *    // Hodnota (hodnoty), které chceme přidat
 * @return static
 * @throws \InvalidArgumentException
 *    // Vyhodí výjimku pro neplatný název/hodnoty
 */

Funkcia withAddedHeader() vracia inštanciu určitej hlavičky, ku ktorej je pridaná ďalšia hodnota. Existujúce hodnoty budú zachované, nová bude pridaná. Ak header neexistoval, tak sa vytvorí.

Funkcia MUSÍ byť implementovaná tak, aby zachovala nezmeniteľnosť správy a MUSÍ vrátiť inštanciu s novou hodnotou / vytvorenú hlavičkou.

public function withoutHeader($name);
/*
 * @param string $name
 *   // Case-insensitive název hlavičky, kterou si přejeme odstranit
 * @return static
*/

Vracia inštanciu bez zadanej hlavičky. Rozpoznávanie názvov MUSÍ byť nezávislé od veľkosti písmen.

Funkcia MUSÍ byť implementovaná tak, aby zachovala nezmeniteľnosť správy a MUSÍ vrátiť inštanciu bez zadanej hlavičky.

public function getBody();
/*
 * @return StreamInterface
 */

Získa telo správy a vracia ho ako stream.

    public function withBody(StreamInterface $body);
    /*
     * Tělo:
     * @param StreamInterface $body
     * @return static
     *  V případě neplatného těla vyhodí výjimku:
     * @throws \InvalidArgumentException
     */
}

Vracia inštanciu s odovzdaným telom správy. Telo MUSÍ byť StreamInterface objekt.

Funkcia MUSÍ byť implementovaná tak, aby zachovala nezmeniteľnosť správy a MUSÍ vrátiť inštanciu, ktorá obsahuje nový stream s telom.

Psr\Http\Message\StreamInterface

Toto rozhranie opisuje dátový prúd a poskytuje wrapper pre najbežnejšie operácie, akou je potrebné serializácie celého prúdu do reťazca:

<?php
namespace Psr\Http\Message;

interface StreamInterface
{
    public function __toString();
    /**
     * @return string
     */

Funkcia __toString() prečíta všetky dáta z prúdu od začiatku do konca reťazca.

Funkcia sa MUSÍ pokúsiť o vyhľadanie začiatku prúdu predtým, než začne čítať dáta a musí čítať do tej doby, než dôjde na koniec.

Pozor, použitie tejto funkcie môže vyústiť v uloženie veľkého množstva dát do pamäte.

Funkcia NESMIE vyhodiť výnimku, pokiaľ vykonávame nejakú operáciu s reťazcami (pozri php.net manuál).

public function close();
/**
 *
 * @return void
 */

public function detach();
/**
 *
 * @return resource|null
 * Vrátí zdroj, pokud existuje, jinak null
 */

Funkcia close() uzavrie prúd a všetko s ním súvisiace. Druhá funkcia oddelí od prúdu akejkoľvek zdroja s ním súvisiace. Po zavolaní funkcie je prúd ďalej nepoužiteľný.

Ďalšie funkcie sú pomerne jednoduché:

public function getSize();
/**
 *
 * @return int|null
 *  Vrátí velikost v bytech, pokud je známa, jinak null
 */

public function tell();
/**
 *
 * @return int // Pozice
 * @throws \RuntimeException
 *  Vyhodí výjimku při výskytu chyby
 */

public function eof();
/**
 *
 * @return bool
 */

Funkcia getSize() získa veľkosť prúdu, ak je známa. Ďalšie funkcie tell() vracia aktuálnu pozíciu ukazovateľa čítania alebo zápisu a funkcie eof() vracia hodnotu true, ak sa nachádzame na konci prúdu.

public function isSeekable();
/**
 * @return bool
 */

Funkcia isSeekable() vracia hodnotu true alebo false podľa toho, či je prúd tzv. Seekable. Pojem seekable znamená, že môžeme sami definovať pozíciu kurzora v prúde, čiže prepísať či čítať akýkoľvek byte. Ak sa pokúsime "hľadať" mimo prúdu, respektíve za ním, dôjde k jeho predĺženiu, teda napr. Veľkosť súboru sa zväčší.

public function seek($offset, $whence = SEEK_SET);
/**
 * @param int $offset
 * @param int $whence
 * @throws \RuntimeException
 */

Funkcia seek() sa posunie na určenú pozíciu vo streamu. Parameter $whence určuje, ako bude vypočítaná pozícia kurzora na základe offsetu.

Validný hodnoty sú rovnaké ako pre známu vstavanú funkciu fseek():

• SEEK_SET: Pozícia je rovná offsetu (v bytoch)
• SEEK_CUR: Pozícia je rovná offsetu + aktuálnej pozície
• SEEK_END: Pozícia je koniec prúdu + offset

public function rewind();
/**
 * @throws \RuntimeException
 */

Funkcia rewind() presunie ukazovateľ na začiatok prúdu. Ak prúd nie je seekable, funkcia vyhodí výnimku, inak sa vykoná seek(0) (pozri funkcie vyššie seek() a PHP manuál).

public function isWritable();
    /**
     * Určí, jestli do proudu můžeme zapisovat
     *
     * @return bool
     */

    public function write($string);
    /**
     * Zapíše data do proudu
     *
     * @param string $string Řetězec, který chceme zapsat
     * @return int Počet zapsaných bytů
     * @throws \RuntimeException
     */

    public function isReadable();
    /**
     * Určí, jestli je proud čitelný
     *
     * @return bool
     */

    public function read($length);
    /**
     * Přečte data ze streamu
     *
     * @param int $length
     *    Přečte až $length bytů z objektu a vrátí je
     * @return string
     *    Vrátí data nebo prázdný řetězec
     * @throws \RuntimeException
     */

    public function getContents();
    /**
     * Vrátí zbývající obsah ve streamu
     *
     * @return string
     * @throws \RuntimeException
     * Pokud nelze stream přečíst, vyhodí výjimku
     */

    public function getMetadata($key = null);
    /**
     * @param string $key Specific // Metadata
     * @return array|mixed|null
     */
}

Funkcia getMetadata() získa metadáta z prúdu ako asociatívne pole alebo vráti špecifický kľúč. Tieto kľúče sú identické s tými, ktoré by vrátila funkcie stream_get_meta_data(). Funkcia vracia asociatívne pole, ak neposkytneme žiadny kľúč. Inak hodnotu priradenú kľúči alebo hodnotu null, ak kľúč nie je nájdený.

V ďalšej lekcii, Štandardy jazyka PHP - PSR-7 (Request target a URI) , sa budeme venovať ďalšej časti PSR-7, a to request line, URI a superglobálním premenným.