Mapping input catchers to entities
Input catchers can be mapped to any class. What is this good for? For instance, to easily create an entity instance based on an import (from XML, JSON, etc.).
As mentioned, input catchers can be mapped to the properties of any class. You simply need to satisfy these three conditions:
- The class must implement the Entity_InputCatcher_Interface interface.
- The class must use the Entity_InputCatcher_Trait trait.
- For properties whose values you wish to capture, an input catcher definition must be provided using the Entity_InputCatcher_Definition attribute. A list of prebuilt input catcher types and their attributes can be found here.
The class then exposes the catchInput( array|Data_Array $input ) method, which captures the input and populates the instance property values.
Let's look at an example:
namespace JetApplication;
use Jet\Data_DateTime;
use Jet\Entity_InputCatcher_Definition;
use Jet\Entity_InputCatcher_Interface;
use Jet\Entity_InputCatcher_Trait;
use Jet\InputCatcher;
class ExampleClass implements Entity_InputCatcher_Interface
{
use Entity_InputCatcher_Trait;
#[Entity_InputCatcher_Definition(
type: InputCatcher::TYPE_DATE_TIME
)]
protected ?Data_DateTime $date_and_time = null;
#[Entity_InputCatcher_Definition(
type: InputCatcher::TYPE_STRING
)]
protected string $secure_string = '';
}
$example_object = new ExampleClass();
$config_data = require 'some/config/file.php';
$example_object->catchInput( $config_data );
Let's also look at another extremely useful application. In practice, any entity is composed of a main entity and its sub-entities, and it is necessary to populate the entities as a whole. This is also supported; let's show an example:
namespace JetApplication;
use Jet\BaseObject;
use Jet\Entity_InputCatcher_Definition;
use Jet\Entity_InputCatcher_Interface;
use Jet\Entity_InputCatcher_Trait;
use Jet\InputCatcher;
class EntityExample extends BaseObject implements Entity_InputCatcher_Interface
{
use Entity_InputCatcher_Trait;
#[Entity_InputCatcher_Definition(
type: InputCatcher::TYPE_INT,
)]
protected int $int_value = 0;
/**
* @var array<EntityExample_Sub1>
*/
#[Entity_InputCatcher_Definition(
is_sub_input_catchers: true,
factory_method_name: 'catchInput_Factory_sub_entities'
)]
protected array $sub_entities = [];
/**
* @param array<string> $array_keys
* @return void
*/
protected function catchInput_Factory_sub_entities( array $array_keys ) : void
{
$this->sub_entities = [];
foreach($array_keys as $key) {
$this->sub_entities[$key] = new EntityExample_Sub1();
}
}
}
class EntityExample_Sub1 extends BaseObject implements Entity_InputCatcher_Interface
{
use Entity_InputCatcher_Trait;
#[Entity_InputCatcher_Definition(
type: InputCatcher::TYPE_INT,
)]
protected int $int_value = 0;
}
$input = [
'int_value' => '123456',
'sub_entities' => [
'1' => [
'int_value' => '123456',
],
'2' => [
'int_value' => '223456',
],
'3' => [
'int_value' => '323456',
],
'4' => [
'int_value' => '423456',
],
'5' => [
'int_value' => '523456',
],
]
];
$obj = new EntityExample();
$obj->catchInput( $input );