PSR-17: Các HTTP Factory

Tài liệu này mô tả một tiêu chuẩn chung cho các factory tạo ra các đối tượng HTTP tuân thủ PSR-7.

PSR-7 không bao gồm một khuyến nghị về cách tạo các đối tượng HTTP, điều này dẫn đến khó khăn khi cần tạo các đối tượng HTTP mới trong các thành phần không gắn với việc thực hiện cụ thể PSR-7.

Các interface được phác thảo trong tài liệu này mô tả các phương thức mà các đối tượng PSR-7 có thể được khởi tạo.

Các interface sau đây CÓ THỂ được thực hiện cùng nhau trong một class đơn lẻ hoặc trong các class riêng biệt.

RequestFactoryInterface

Có khả năng tạo ra các yêu cầu từ client.

namespace PsrHttpMessage;

use PsrHttpMessageRequestInterface;
use PsrHttpMessageUriInterface;

interface RequestFactoryInterface
{
    /**
     * Create a new request.
     *
     * @param string $method The HTTP method associated with the request.
     * @param UriInterface|string $uri The URI associated with the request. 
     */
    public function createRequest(string $method, $uri): RequestInterface;
}

ResponseFactoryInterface

Có khả năng tạo ra các phản hồi.

namespace PsrHttpMessage;

use PsrHttpMessageResponseInterface;

interface ResponseFactoryInterface
{
    /**
     * Create a new response.
     *
     * @param int $code The HTTP status code. Defaults to 200.
     * @param string $reasonPhrase The reason phrase to associate with the status code
     *     in the generated response. If none is provided, implementations MAY use
     *     the defaults as suggested in the HTTP specification.
     */
    public function createResponse(int $code = 200, string $reasonPhrase = '): ResponseInterface;
}

ServerRequestFactoryInterface

Có khả năng tạo ra các yêu cầu từ server.

namespace PsrHttpMessage;

use PsrHttpMessageServerRequestInterface;
use PsrHttpMessageUriInterface;

interface ServerRequestFactoryInterface
{
    /**
     * Create a new server request.
     *
     * Note that server parameters are taken precisely as given - no parsing/processing
     * of the given values is performed. In particular, no attempt is made to
     * determine the HTTP method or URI, which must be provided explicitly.
     *
     * @param string $method The HTTP method associated with the request.
     * @param UriInterface|string $uri The URI associated with the request. 
     * @param array $serverParams An array of Server API (SAPI) parameters with
     *     which to seed the generated request instance.
     */
    public function createServerRequest(string $method, $uri, array $serverParams = []): ServerRequestInterface;
}

Có khả năng tạo ra các luồng cho yêu cầu và phản hồi.

namespace PsrHttpMessage;

use PsrHttpMessageStreamInterface;

interface StreamFactoryInterface
{
    /**
     * Create a new stream from a string.
     *
     * The stream SHOULD be created with a temporary resource.
     *
     * @param string $content String content with which to populate the stream.
     */
    public function createStream(string $content = '): StreamInterface;

    /**
     * Create a stream from an existing file.
     *
     * The file MUST be opened using the given mode, which may be any mode
     * supported by the `fopen` function.
     *
     * The `$filename` MAY be any string supported by `fopen()`.
     *
     * @param string $filename The filename or stream URI to use as basis of stream.
     * @param string $mode The mode with which to open the underlying filename/stream.
     *
     * @throws RuntimeException If the file cannot be opened.
     * @throws InvalidArgumentException If the mode is invalid.
     */
    public function createStreamFromFile(string $filename, string $mode = 'r'): StreamInterface;

    /**
     * Create a new stream from an existing resource.
     *
     * The stream MUST be readable and may be writable.
     *
     * @param resource $resource The PHP resource to use as the basis for the stream.
     */
    public function createStreamFromResource($resource): StreamInterface;
}

Triển khai interface này NÊN sử dụng luồng tạm thời khi tạo tài nguyên từ chuỗi. Phương pháp ĐƯỢC KHUYẾN NGHỊ để làm như vậy là:

$resource = fopen('php://temp', 'r+');

UploadedFileFactoryInterface

Có khả năng tạo luồng cho các tệp đã tải lên.

namespace PsrHttpMessage;

use PsrHttpMessageStreamInterface;
use PsrHttpMessageUploadedFileInterface;

interface UploadedFileFactoryInterface
{
    /**
     * Create a new uploaded file.
     *
     * If a size is not provided it will be determined by checking the size of
     * the stream.
     *
     * @link http://php.net/manual/features.file-upload.post-method.php
     * @link http://php.net/manual/features.file-upload.errors.php
     *
     * @param StreamInterface $stream The underlying stream representing the
     *     uploaded file content.
     * @param int $size The size of the file in bytes.
     * @param int $error The PHP file upload error.
     * @param string $clientFilename The filename as provided by the client, if any.
     * @param string $clientMediaType The media type as provided by the client, if any.
     *
     * @throws InvalidArgumentException If the file resource is not readable.
     */
    public function createUploadedFile(
        StreamInterface $stream,
        int $size = null,
        int $error = UPLOAD_ERR_OK,
        string $clientFilename = null,
        string $clientMediaType = null
    ): UploadedFileInterface;
}

UriFactoryInterface

Có khả năng tạo URI cho các yêu cầu từ máy khách và máy chủ.

namespace PsrHttpMessage;

use PsrHttpMessageUriInterface;

interface UriFactoryInterface
{
    /**
     * Create a new URI.
     *
     * @param string $uri The URI to parse.
     *
     * @throws InvalidArgumentException If the given URI cannot be parsed.
     */
    public function createUri(string $uri = ') : UriInterface;
}