Linio Input
Linio Input is yet another component of the Linio Framework. It aims to abstract HTTP request input handling, allowing a seamless integration with your domain model. The component is responsible for:
- Parsing request body contents
- Validating input data
- Hydrating input data into objects
Install
The recommended way to install Linio Input is through composer.
{
"require": {
"linio/input": "dev-master"
}
}
Tests
To run the test suite, you need install the dependencies via composer, then run PHPUnit.
$ composer install
$ phpunit
Usage
The library is very easy to use: first, you have to create your input handler class. The input handlers are responsible for specifying which data you're expecting to receive from requests. Let's create one:
<?php
namespace Linio\Api\Handler;
use Linio\Component\Input\InputHandler;
class RegistrationHandler extends InputHandler
{
public function define()
{
$this->add('referrer', 'string');
$this->add('registration_date', 'datetime');
$user = $this->add('user', 'Linio\Model\User');
$user->add('name', 'string');
$user->add('email', 'string');
$user->add('age', 'integer');
}
}
Now, in your controller, you just need to bind data to the handler:
<?php
namespace Linio\Api\Controller;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;
class RegistrationController
{
public function registerAction(Request $request): Response
{
$input = new RegistrationHandler();
$input->bind($request->request->all());
if (!$input->isValid()) {
return new Response($input->getErrorsAsString());
}
$data = $input->getData();
$data['referrer']; // string
$data['registration_date']; // \DateTime
$data['user']; // Linio\Model\User
return new Response(['message' => 'Valid!']);
}
}
Type Handler
When you are defining the fields for your input handler, there are a few types available: string, int, bool, datetime, etc. Those are predefined types provided by the library, but you can also create your own. This magic is handled by Linio\Component\Input\TypeHandler. The TypeHandler allows you to add new types, which are extensions of the BaseNode class.
<?php
class GuidNode extends BaseNode
{
public function __construct()
{
$this->addConstraint(new Linio\Component\Input\Constraint\GuidValue());
}
}
$typeHandler = new Linio\Component\Input\TypeHandler();
$typeHandler->addType('guid', GuidNode::class);
$input = new RegistrationHandler();
$input->setTypeHandler($typeHandler);
In this example, we have created a new guid type, which has a built-in constraint to validate contents. You can use custom types to do all sorts of things: add predefined constraint chains, transformers, instantiators and also customize how values are generated.
Constraints
Linio Input allows you to apply constraints to your fields. This can be done by providing a third argument for the add() method in your input handlers:
<?php
use Linio\Component\Input\Constraint\Pattern;
class RegistrationHandler extends InputHandler
{
public function define()
{
$this->add('referrer', 'string', ['required' => true]);
$this->add('registration_date', 'datetime');
$user = $this->add('user', 'Linio\Model\User');
$user->add('name', 'string');
$user->add('email', 'string', ['constraints' => [new Pattern('/^\S+@\S+\.\S+$/')]]);
$user->add('age', 'integer');
}
}
The library includes several constraints by default:
- Enum
- GuidValue
- NotNull
- Pattern
- StringSize
Transformers
Linio Input allows you to create data transformers, responsible for converting simple input data, like timestamps and unique IDs, into something meaningful, like a datetime object or the full entity (by performing a query).
<?php
namespace Linio\Api\Handler\Transformer;
use Doctrine\Common\Persistence\ObjectRepository;
use Linio\Component\Input\Transformer\TransformerInterface;
class IdTransformer implements TransformerInterface
{
/**
* @var ObjectRepository
*/
protected $repository;
public function transform($value)
{
try {
$entity = $this->repository->find($value);
} catch (\Exception $e) {
return null;
}
return $entity;
}
public function setRepository(ObjectRepository $repository)
{
$this->repository = $repository;
}
}
Data transformers can be added on a per-field basis during the definition of your input handler:
<?php
use Linio\Api\Handler\Transformer\IdTransformer;
class RegistrationHandler extends InputHandler
{
/**
* @var IdTransformer
*/
protected $idTransformer;
public function define()
{
$this->add('store_id', 'string', ['transformer' => $this->idTransformer]);
}
public function setIdTransformer(IdTransformer $idTransformer)
{
$this->idTransformer = $idTransformer;
}
}
Instantiators
Linio Input allows you to use different object instantiators on a per-field basis. This can be done by providing a third argument for the add() method in your input handlers:
<?php
use Linio\Component\Input\Instantiator\ConstructInstantiator;
use Linio\Component\Input\Instantiator\ReflectionInstantiator;
class RegistrationHandler extends InputHandler
{
public function define()
{
$this->add('foobar', 'My\Foo\Class', ['instantiator' => new ConstructInstantiator()]);
$this->add('barfoo', 'My\Bar\Class', ['instantiator' => new ReflectionInstantiator()]);
}
}
The library includes several instantiators by default:
- ConstructInstantiator
- PropertyInstantiator
- SetInstantiator
- ReflectionInstantiator
By default, the SetInstantiator is used by Object and Collection nodes.
InputHandlers
Linio Input supports portable, reusable InputHandlers via nesting. This is accomplished by including the handler to the options parameter when adding fields.
Suppose your application deals with mailing addresses:
<?php
class OrderHandler extends InputHandler
{
public function define()
{
$address = $this->add('shipping_address', Address::class);
$address->add('street', 'string');
$address->add('city', 'string');
$address->add('state', 'string');
$address->add('zip_code', 'integer');
}
}
Rather than duplicating this everywhere you need to handle an address, you can extract the address into its own InputHandler and re-use it throughout your application.
<?php
class AddressHandler extends InputHandler
{
public function define()
{
$address->add('street', 'string');
$address->add('city', 'string');
$address->add('state', 'string');
$address->add('zip_code', 'integer');
}
}
class OrderHandler extends InputHander
{
public function define()
{
$this->add('shipping_address', Address::Class, ['handler' => new AddressHandler()]);
}
}
class RegistrationHandler extends InputHander
{
public function define()
{
$this->add('home_address', Address::Class, ['handler' => new AddressHandler()]);
}
}
1 Mar 8, 2022
85 Apr 26, 2022
13 Apr 23, 2022
89 Nov 28, 2022
246 Jan 5, 2023
1.7k Dec 27, 2022
43 Sep 28, 2022
1 Oct 25, 2021
1.5k Dec 30, 2022
39 Oct 11, 2022
2 Sep 21, 2021
80 Dec 9, 2022
370 Dec 30, 2022
223 Jun 16, 2022
398 Nov 25, 2022
0 Jan 15, 2022
2 Mar 18, 2022
153 Jan 2, 2023