yiisoft/input-http

Maps data from PSR-7 HTTP request to PHP DTO representing user input.

dev-master 2024-02-11 21:19 UTC

This package is auto-updated.

Last update: 2024-02-22 08:37:34 UTC


README

68747470733a2f2f796969736f66742e6769746875622e696f2f646f63732f696d616765732f7969695f6c6f676f2e737667

Yii Input HTTP


Latest Stable Version Total Downloads Build status Code Coverage Mutation testing badge static analysis type-coverage psalm-level

The package provides Yii Hydrator attributes to get data from PSR-7 HTTP request and adds extra abilities to middlewares processed by Yii Middleware Dispatcher:

  • maps data from PSR-7 HTTP request to PHP DTO representing user input;
  • usage Yii Hydrator parameter attributes for resolve middleware parameters.

Requirements

  • PHP 8.0 or higher.

Installation

The package could be installed with composer:

composer require yiisoft/input-http

General usage

First of all, you need to store a request object into request provider. There are three ways to do it:

  1. Add \Yiisoft\Input\Http\Request\Catcher\RequestCatcherMiddleware to your application middleware stack.

  2. Add \Yiisoft\Input\Http\Request\Catcher\RequestCatcherParametersResolver to your middleware parameters resolver in Yiisoft\Middleware\Dispatcher\MiddlewareFactory. It is usually used as additional parameters resolver in composite parameters resolver. Example parameters resolver configuration for Yii DI container:

    use Yiisoft\Definitions\Reference;
    use Yiisoft\Input\Http\Request\Catcher\RequestCatcherParametersResolver;
    use Yiisoft\Middleware\Dispatcher\CompositeParametersResolver;
    use Yiisoft\Middleware\Dispatcher\ParametersResolverInterface;
    
    ParametersResolverInterface::class => [
        'class' => CompositeParametersResolver::class,
        '__construct()' => [
       gt     Reference::to(RequestCatcherParametersResolver::class),
            // ...
        ],
    ],
  3. Manually:

    /** 
     * @var \Yiisoft\Input\Http\Request\RequestProviderInterface $requestProvider
     * @var \Psr\Http\Message\ServerRequestInterface $request
     */
    $requestProvider->set($request);

To use the package, you need to create a DTO class and mark its properties with attributes:

use \Yiisoft\Input\Http\Attribute\Parameter\Query;
use \Yiisoft\Input\Http\Attribute\Parameter\Body;
use \Yiisoft\Input\Http\Attribute\Parameter\UploadedFiles;

final class EditPostInput
{
    public function __construct(
        #[Query]
        private string $id,
        #[Body]        
        private string $title,
        #[Body]        
        private string $content,
        #[UploadedFiles('uploads')]        
        private $uploads,
    )
    {
    
    }

    // getters
        
} 

Post id will be mapped from query parameter id, title and content will be mapped from request body and uploads will be mapped from request uploaded files.

Additionally, you can fill a property from request attribute using #[Request('attributeName')]. This is useful when middleware prior writes the value.

Instead of mapping each property, you can use the following:

use \Yiisoft\Input\Http\Attribute\Data\FromQuery;
use \Yiisoft\Input\Http\Attribute\Data\FromBody; 

#[FromQuery]
final class SearchInput
{
    public function __construct(
        private string $query,
        private string $category,
    ) {}
    
    // getters
}

#[FromBody]
final class CreateUserInput
{
    public function __construct(
        private string $username,
        private string $email,
    ) {}
    
    // getters
}

SearchInput will be mapped from query parameters, CreateUserInput will be mapped from parsed request body. Both will expect request parameters in request named same as DTO properties.

Documentation

License

The Yii Input HTTP is free software. It is released under the terms of the BSD License. Please see LICENSE for more information.

Maintained by Yii Software.

Support the project

Open Collective

Follow updates

Official website Twitter Telegram Facebook Slack