Common implementations for HTTP protocol.

4.0.2 2024-12-19 14:53 UTC

This package is auto-updated.

Last update: 2024-12-24 12:42:57 UTC


README

License

Overview

Common implementations for HTTP protocol. The library exposes concrete implementations that follow the PSR standards, specifically designed to operate with PSR-7 and PSR-15, providing solutions for building HTTP responses, requests, and other HTTP-related components.

Installation

composer require tiny-blocks/http

How to use

The library exposes interfaces like Headers and concrete implementations like Response, ContentType, and others, which facilitate construction.

Using the status code

The library exposes a concrete implementation through the Code enum. You can retrieve the status codes, their corresponding messages, and check for various status code ranges using the methods provided.

  • Get message: Returns the HTTP status message associated with the enum's code.

    use TinyBlocks\Http\Code;
    
    Code::OK->value;                        # 200
    Code::OK->message();                    # OK
    Code::IM_A_TEAPOT->message();           # I'm a teapot
    Code::INTERNAL_SERVER_ERROR->message(); # Internal Server Error
  • Check if the code is valid: Determines if the given code is a valid HTTP status code represented by the enum.

    use TinyBlocks\Http\Code;
    
    Code::isValidCode(code: 200); # true
    Code::isValidCode(code: 999); # false
  • Check if the code is an error: Determines if the given code is in the error range (4xx or 5xx).

    use TinyBlocks\Http\Code;
    
    Code::isErrorCode(code: 500); # true
    Code::isErrorCode(code: 200); # false
  • Check if the code is a success: Determines if the given code is in the success range (2xx).

    use TinyBlocks\Http\Code;
    
    Code::isSuccessCode(code: 500); # false
    Code::isSuccessCode(code: 200); # true

Creating a response

The library provides an easy and flexible way to create HTTP responses, allowing you to specify the status code, headers, and body. You can use the Response class to generate responses, and the result will always be a ResponseInterface from the PSR, ensuring compatibility with any framework that adheres to the PSR-7 standard.

  • Creating a response with a body: To create an HTTP response, you can pass any type of data as the body. Optionally, you can also specify one or more headers. If no headers are provided, the response will default to application/json content type.

    use TinyBlocks\Http\Response;
      
    Response::ok(body: ['message' => 'Resource created successfully.']);
  • Creating a response with a body and custom headers: You can also add custom headers to the response. For instance, if you want to specify a custom content type or any other header, you can pass the headers as additional arguments.

    use TinyBlocks\Http\Response;
    use TinyBlocks\Http\ContentType;
    use TinyBlocks\Http\CacheControl;
    use TinyBlocks\Http\ResponseCacheDirectives;
      
    $body = 'This is a plain text response';
    
    $contentType = ContentType::textPlain();
    
    $cacheControl = CacheControl::fromResponseDirectives(
        maxAge: ResponseCacheDirectives::maxAge(maxAgeInWholeSeconds: 10000),
        staleIfError: ResponseCacheDirectives::staleIfError()
    );
    
    Response::ok($body, $contentType, $cacheControl)
        ->withHeader(name: 'X-ID', value: 100)
        ->withHeader(name: 'X-NAME', value: 'Xpto');

License

Http is licensed under MIT.

Contributing

Please follow the contributing guidelines to contribute to the project.