Http

Summary

Http is a library for creating HTTP components (Controller, Middleware, Header, Status) for chevere/router. It is compatible with the following PHP-FIG PSR:

• PSR-7: HTTP message interfaces
• PSR-17: HTTP Factories
• PSR-18: HTTP Client

Read Chevere Http at Rodolfo's blog for a compressive introduction to this package.

Installing

Http is available through Packagist and the repository source is at chevere/http.

composer require chevere/http

Controller

The Controller in Http is a special Controller meant to be used in the context of HTTP requests. It extends Action by adding request parameters (query string, body, files) and attributes for statuses and headers.

use Chevere\Http\Controller;

class UsersPostController extends Controller
{
    // ...
}

Accept Headers

Define accepted parameters for headers using the acceptHeaders method.

use Chevere\Parameter\Interfaces\ArrayStringParameterInterface;
use function Chevere\Parameter\arrayString;
use function Chevere\Parameter\parameters;
use function Chevere\Parameter\string;

public static function acceptHeaders(): ArrayStringParameterInterface
{
    return arrayString(
        ...['Webhook-Id' => string()],
    );
}

Accept Query

Define accepted parameters for query string using the acceptQuery method.

use Chevere\Parameter\Interfaces\ArrayStringParameterInterface;
use function Chevere\Parameter\arrayString;
use function Chevere\Parameter\parameters;
use function Chevere\Parameter\string;

public static function acceptQuery(): ArrayStringParameterInterface
{
    return arrayString(
        foo: string('/^[a-z]+$/'),
    );
}

Accept Body

Define accepted parameters for body using the acceptBody method.

use Chevere\Parameter\Interfaces\ArrayParameterInterface;
use function Chevere\Parameter\arrayp;
use function Chevere\Parameter\parameters;
use function Chevere\Parameter\string;

public static function acceptBody(): ArrayParameterInterface
{
    return arrayp(
        bar: string('/^[1-9]+$/'),
    );
}

Accept Files

Define accepted parameters for FILES using the acceptFiles method.

use Chevere\Parameter\Interfaces\ArrayParameterInterface;
use function Chevere\Parameter\arrayp;
use function Chevere\Parameter\file;

public static function acceptFiles(): ArrayParameterInterface
{
    return arrayp(
        myFile: file(),
    );
}

With Server Request

Use method withServerRequest to inject a PSR-7 ServerRequest instance. This will assert the request against the defined accept* methods.

use Psr\Http\Message\ServerRequestInterface;

$controller = $controller
    ->withServerRequest($request);

Headers

Use method headers to read headers parameters.

$headers = $controller->headers();
$header = $headers->required('Webhook-Id');

Query

Use method query to read query parameters.

$query = $controller->query();
$foo = $query->required('foo');

Body

Use method bodyParsed to read the body parameters parsed.

$parsed = $controller->bodyParsed();
$bar = $parsed->required('bar')->int();

Use method bodyStream to return the body stream.

$stream = $controller->bodyStream();

Use method body to return the body casted.

$cast = $controller->body();

Files

Use method files to read the files parameters.

$files = $controller->files();

Middleware

Define PSR Middleware collections using middlewares function.

use function Chevere\Http\middlewares;

$middlewares = middlewares(
    MiddlewareOne::class,
    MiddlewareTwo::class
);

Middleware priority goes from top to bottom, first in first out (FIFO).

Middleware with Arguments

Use MiddlewareNameWithArgumentsTrait to define Middleware with arguments:

use Chevere\Http\Interfaces\MiddlewareNameInterface;
use Chevere\Http\Traits\MiddlewareNameWithArgumentsTrait;
use Nyholm\Psr7\Factory\Psr17Factory;
use Psr\Http\Message\ResponseInterface;
use Psr\Http\Message\ServerRequestInterface;
use Psr\Http\Server\MiddlewareInterface;

class AllowListMiddleware implements MiddlewareInterface
{
    use MiddlewareNameWithArgumentsTrait;

    private string $allowList;

    public function setUp(string $allowList): void
    {
        $this->allowList = $allowList;
    }

    public static function with(string $allowList): MiddlewareNameInterface
    {
        return static::middlewareName(...get_defined_vars());
    }

    public function process(
        ServerRequestInterface $request,
        RequestHandlerInterface $handler,
    ): ResponseInterface {
        if ($this->allowList === '') {
            return $handler->handle($request);
        }
        $remoteAddress = $request->getServerParams()['REMOTE_ADDR'] ?? '';
        if ($remoteAddress === '') {
            return (new Psr17Factory())
                ->createResponse(
                    400,
                    'Unable to determine client IP address'
                );
        }
        if (! isIpAllowed($remoteAddress, $this->allowList)) {
            return (new Psr17Factory())
                ->createResponse(
                    403,
                    'Access denied from your IP address'
                );
        }

        return $handler->handle($request);
    }
}

This allows to pass MiddlewareName with constructor arguments (as in when defining routes):

$middlewareName = AllowListMiddleware::with('192.168.1.1');

Attributes

Use attributes to add context for Controller and Middleware.

Request

Request metadata can be defined using the Request attribute. It supports to define multiple Header arguments.

use Chevere\Http\Attributes\Request;
use Chevere\Http\Header;
use Chevere\Http\Controller;

#[Request(
    new Header('Accept', 'application/json'),
    new Header('Connection', 'keep-alive')
)]
class ResourceGetController extends Controller

Use function getRequest to read the Request attribute.

use function Chevere\Http\getRequest;

getRequest(ResourceGetController::class);

Response

Response metadata can be defined using the Response attribute. It supports to define Status and multiple Header arguments.

use Chevere\Http\Attributes\Response;
use Chevere\Http\Header;
use Chevere\Http\Controller;

#[Response(
    new Status(200),
    new Header('Content-Disposition', 'attachment'),
    new Header('Content-Type', 'application/json')
)]
class ResourceGetController extends Controller

Use function getResponse to read the Response attribute.

use function Chevere\Http\getResponse;

getResponse(ResourceGetController::class);

Documentation

Documentation is available at chevere.org.

License

Copyright Rodolfo Berrios A.

Chevere is licensed under the Apache License, Version 2.0. See LICENSE for the full license text.

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.