README

这是一个用于在 PHP 结构和结构化数据之间显示数据的组件库。

库的主要思想是提供“砖块”，可以根据任何情况进行构建以显示数据。

定义

• 输入数据 (input) —需要显示在 PHP 结构中的结构化数据。
• 输出数据 (output) —从 PHP 结构中获取的结构化数据。
• 数组 (array) —在库中，这个词只表示 关联数组。
• 集合 (collection) —索引（非关联）数组，包含同类型值。

基础

库的核心是 *Mapper 接口

Mapper

一个空的接口，所有转换器都实现它。

InputMapper

输入数据转换器。包含一个唯一的方法

public function input(mixed $source): mixed;

OutputMapper

输出数据转换器。包含一个唯一的方法

将输入数据 $source 显示为 PHP 结构并返回它。

public function output(mixed $source): mixed;

BidirectionalMapper

结合了 InputMapper 和 OutputMapper。

示例

待办事项

BidirectionalMapper

应用

将其他转换器获取的转换器应用于输入数据。

use DobroSite\Mapping;

$mapper = new Mapping\Apply(
  input: new Mapping\Callback(
    input: fn(mixed $source) => is_numeric($source) ? new Mapping\FloatType() : new Mapping\AsIs(),
    output: fn(mixed $source) => is_float($source) ? new Mapping\FloatType() : new Mapping\AsIs(),
  )
);

$mapper->input('123.45'); // 123.45
$mapper->input('foo'); // 'foo'

ArrayKeys

将指定的转换连续应用于关联数组的每个键。

use DobroSite\Mapping;

$mapper = new Mapping\ArrayKeys(
  new Mapping\Callback(
    input: strtolower(...),
    output: strtoupper(...),
  ),
);

$mapper->input(['FOO' => 'foo value', 'BAR' => 'bar value']);
// ['foo' => 'foo value', 'bar' => 'bar value']

$mapper->output(['foo' => 'foo value', 'bar' => 'bar value']);
// ['FOO' => 'foo value', 'BAR' => 'bar value']

ArrayKeysMap

根据映射表更改数组键的名称。

use DobroSite\Mapping;

$mapper = new Mapping\ArrayKeysMap([
  'FOO' => 'foo',
  'BAR' => 'bar',
]);

$mapper->input(['FOO' => 'foo value', 'BAR' => 'bar value']);
// ['foo' => 'foo value', 'bar' => 'bar value']

$mapper->output(['foo' => 'foo value', 'bar' => 'bar value']);
// ['FOO' => 'foo value', 'BAR' => 'bar value']

ArrayValues

将转换应用于关联数组中指定的值。

use DobroSite\Mapping;

$mapper = new Mapping\ArrayValues([
  'active' => new Mapping\BooleanType('yes', 'no'),
]);

$mapper->input(['active' => 'yes']); // ['active' => true]
$mapper->output(['active' => true]); // ['active' => 'yes']

AsIs

保留值不变。

use DobroSite\Mapping;

$mapper = new Mapping\AsIs();
$mapper->input('foo'); // 'foo'
$mapper->output('foo'); // 'foo'

BooleanType

将值转换为布尔类型。

use DobroSite\Mapping;

$mapper = new Mapping\BooleanType();
$mapper->input('true'); // true
$mapper->output(true); // 'true'

$mapper = new Mapping\BooleanType(true: 'да', false: 'нет');
$mapper->input('Нет'); // false
$mapper->output(false); // 'нет'

Callback

允许使用函数回调进行转换。

use DobroSite\Mapping;

$mapper = new Mapping\Callback(
  input: strtolower(...),
  output: strtoupper(...),
);

$mapper->input('FOO'); // 'foo'
$mapper->output('foo'); // 'FOO'

Chained

创建一个转换链，依次执行：在 input 中从第一个到最后一个，在 output 中相反。

use DobroSite\Mapping;

$mapper = new Mapping\Chained(
  $mapper1,
  $mapper2,
  // …
);

Collection

将指定的转换应用于集合的每个元素。

use DobroSite\Mapping;

$mapper = new Mapping\Collection(
  new Mapping\FloatType(),
);

$mapper->input(['123.45', '67.89']); // [123.45, 67.89]

Constant

返回一个常数值。

use DobroSite\Mapping;

$mapper = new Mapping\Constant(input: 'foo', output: 'bar');
$mapper->input(uniqid()); // 'foo'
$mapper->output(uniqid()); // 'bar'

Constructor

使用类的构造函数将数组显示为对象。

详细信息请参阅下文“对象处理”。

在 Constructor 构造函数中将 $class 作为参数传递时，应传递类名或返回创建的对象类名的 Mapper 实例。

use App\Foo;
use DobroSite\Mapping;

$mapper = new Mapping\Constructor(Foo::class);
$instanceOfFoo = $mapper->input(['foo' => 'foo value']);

use App\Foo;
use App\Bar;
use DobroSite\Mapping;

$mapper = new Mapping\ObjectConstructor(
  Mapping\Callback(
    fn(array $properties) => array_key_exists('bar', $properties) ? Bar::class : Foo::class, 
  )
);

$instanceOfFoo = $mapper->input(['foo' => 'foo value']);
$instanceOfBar = $mapper->input(['bar' => 'bar value']);

EnumType

将枚举类型的值转换为其他类型。

use App\SomeEnum;
use DobroSite\Mapping;

$mapper = new Mapping\EnumType(SomeEnum::class);
$mapper->input('foo'); // SomeEnum::Foo
$mapper->output(SomeEnum::Foo); // 'foo' 

FloatType

将值转换为浮点数。

use DobroSite\Mapping;

$mapper = new Mapping\FloatType();
$mapper->input('1234.56'); // 1_234.56

$mapper = new Mapping\FloatType(
  new \NumberFormatter('ru_RU', \NumberFormatter::DEFAULT_STYLE)
);
$mapper->input('1 234,56'); // 1_234.56

Map

根据映射（关联数组）转换值。

use DobroSite\Mapping;

$mapper = new Mapping\Map(['foo' => 'bar']);
$mapper->input('foo'); // 'bar'
$mapper->output('bar'); // 'foo'

Nullable

修改器，允许其他转换器接受 null 值。

use DobroSite\Mapping;

$float = new Mapping\FloatType();
$nullable = new Mapping\Nullable($float);

$nullable->input('123'); // 123
$nullable->input(null); // NULL
$float->input(null); // → InvalidArgumentException

ObjectFactory

使用工厂将数组显示为对象。

详细信息请参阅下文“对象处理”。

在 ObjectFactory 构造函数中将 $factory 作为参数传递时，应传递创建所需对象的工厂。

use DobroSite\Mapping;

$mapper = new Mapping\ObjectFactory('\App\factory_function');
$mapper = new Mapping\ObjectFactory(factory_function(...));
$mapper = new Mapping\ObjectFactory([Factory::class, 'staticMethod']);
$mapper = new Mapping\ObjectFactory([$factory, 'method']);
$mapper = new Mapping\ClassType\CallableObjectFactory(
  fn(string $foo, string $bar) => new SomeClass($foo, $bar)
);

ObjectMapper

组合转换器，将 InputMapper 和 OutputMapper 结合起来，用于转换数组 ⇆ 对象。

在第一个参数 (input) 中应传递一个 InputMapper 实例，该实例从数组创建对象，例如，Constructor 或 ObjectFactory。

在第二个参数（output）中，您可以传递一个创建对象数组的OutputMapper实例。如果未指定此参数，将使用PublicProperties。

use DobroSite\Mapping;

$mapper = new Mapping\ObjectMapper(
  input: new Mapping\Constructor(Foo::class),
);

InputMapper

ArrayDefaults

允许为输入数组中缺失的键设置默认值。

use DobroSite\Mapping;

$mapper = new Mapping\ArrayDefaults([
  'bar' => 'bar value',
]);

$mapper->input(['foo' => 'foo value']);
// ['foo' => 'foo value', 'bar' => 'bar value']

OutputMapper

Merge

构造函数接收多个OutputMapper实例。调用output方法时，依次将获得的值传递给每个转换器，然后使用array_merge将它们返回的结果合并。

use DobroSite\Mapping;

$mapper = new Mapping\Merge(
 new Mapping\Constant(output: ['bar' => 'BAR']),
 new Mapping\Constant(output: ['baz' => 'BAZ']),
);

$mapper->output(['foo' => 'FOO']);
// ['foo' => 'FOO', 'bar' => 'BAR', 'baz' => 'BAZ']

PublicProperties

接收一个对象作为输入，返回其公共属性关联数组。用于ObjectMapper。

对象处理

待办事项