README

使用构造函数映射JSON数据到对象的库

内容

• 安装
• 用法
• 支持的类型
• 检查器
  • 注意
  • 类型属性
  • 属性 @var 注解
  • 构造函数类型参数
  • 构造函数 @param 注解
  • 缓存
• 自定义
  • 类型映射
  • 检查器
• 基于

安装

composer require nstwf/json-mapper

用法

$factory = new \Nstwf\JsonMapper\JsonMapper\JsonMapperFactory();
$jsonMapper = $factory->create();

$data = (object)[
    "id"      => "123e4567-e89b-12d3-a456-426614174000",
    "roles"   => [1, 3, 7],
    "profile" => [
        "name" => "Alex",
        "age"  => 19,
    ]
];

$jsonMapper->mapObject($data, User::class);

支持的类型

• 标量类型（int, float, bool, string, array, mixed）
• 枚举
• 类
• 标量类型、枚举和类的数组
• 可为空类型

检查器

在此处描述所有支持的检查器。如果您不使用其中描述的一些功能，则可以自定义它们以优化

注意

• 要声明任何类型的数组（特别是对于类和枚举） - 使用phpDoc
• 如果phpDoc中的类不包含命名空间 - 尝试从use语句中发现命名空间（如果存在）
• 构造函数参数必须使用与属性相同的名称
• 联合类型通过与数据类型的相等比较来选择
  • 对于标量类型：如果没有描述的类型适合 - 值将转换为第一个类型
• 联合类型从左到右声明。
  • 请注意：如果与联合一起使用，具有后备类型的枚举可以映射为标量类型值。首选类型应放在前面

类型属性

$inspector = (new \Nstwf\JsonMapper\Inspector\InspectorBuilder())
                ->withTypesProperties()
                ->build();

class Example {
    private int $scalar;
    private int|string $union;
    private ?int $nullable;
    private User $class;
}

属性 @var 注解

$inspector = (new \Nstwf\JsonMapper\Inspector\InspectorBuilder())
                ->withPropertyAnnotations()
                ->build();

use App\Models\User;

class Example {
    /** @var int */
    private $scalar;
    /** @var int|string */
    private $union;
    /** @var int[] */
    private $array;
    /** @var int|null */
    private $nullable;
    /** @var User */
    private $class;
    /** @var \App\Models\Role */
    private $classWithNamespace;
}

构造函数类型参数

$inspector = (new \Nstwf\JsonMapper\Inspector\InspectorBuilder())
                ->withConstructorParameters()
                ->build();

class Example {
    public function __construct(
        int $scalar,
        int|string $union,
        ?int $nullable,
        User $class
    ) {
       $this->scalar = $scalar;
       /** more */
    }
}

构造函数 @param 注解

$inspector = (new \Nstwf\JsonMapper\Inspector\InspectorBuilder())
                ->withConstructorAnnotations()
                ->build();

use App\Models\User;

class Example {

    /**
    * @param int                $scalar
    * @param int|string         $union
    * @param int[]              $array
    * @param int|null           $nullable
    * @param User               $class
    * @param \App\Models\Role   $classWithNamespace
     */
    public function __construct(/*parameters*/) {}
}

属性 CustomName 属性

$inspector = (new \Nstwf\JsonMapper\Inspector\InspectorBuilder())
                ->withCustomNameAttribute()
                ->build();

class Example {
    #[\Nstwf\JsonMapper\Attribute\CustomName('custom_name')]
    private $property;
}

缓存

所有检查器都可以接收缓存。检查器的默认缓存为数组。您可以使用自己的实现，使用：Psr\SimpleCache\CacheInterface

$inspectorBuilder = new \Nstwf\JsonMapper\Inspector\InspectorBuilder();

$inspector = $inspectorBuilder
               ->withCache($redisCache)
               ->withTypesProperties()
               ->withPropertyAnnotations()
               ->build();

自定义

使用本地构建器自定义您的JSON映射器以满足您的需求

// Customize inspectors
$inspectorBuilder = new \Nstwf\JsonMapper\Inspector\InspectorBuilder();
$inspector = $inspectorBuilder
               ->withTypesProperties()
               ->withPropertyAnnotations()
               ->build();
                 
// Add own types to registry
$registry = new \Nstwf\JsonMapper\Registry\ClassFactoryRegistry();
$registry->add(Uuid::class, fn(string $value) => new Uuid($value));

// Use object mapper builder
$propertyMapperBuilder = new \Nstwf\JsonMapper\Property\Mapper\PropertyMapperBuilder();
$propertyMapper = $propertyMapperBuilder
                    ->withClassFactoryRegistry($registry)
                    ->build();
                    
$objectMapperBuilder = new \Nstwf\JsonMapper\Object\Mapper\ObjectMapperBuilder();
$objectMapper = $objectMapperBuilder
                    ->withPropertyMapper($propertyMapper)
                    ->build();

// Create JsonMapper
$factory = new \Nstwf\JsonMapper\JsonMapper\JsonMapperFactory();

$jsonMapper = $factory->create($inspector, $objectMapper);

自定义类型映射

您可以自定义某些类的映射。例如：_json中包含字符串形式的uuid，但在对象中将其定义为Uuid类_。只需添加具有自定义映射的类

{
  "id": "123e4567-e89b-12d3-a456-426614174000"
}

class User {
    private Uuid $id;
}

$registry = new \Nstwf\JsonMapper\Registry\ClassFactoryRegistry();

$registry->add(
    Uuid::class, fn(string $value) => new Uuid($value)
);

自定义检查器

您可以使用构建器指定类型发现。所有可用的检查器在此处定义。

// Example: if you do not use constructors
$builder = new \Nstwf\JsonMapper\Inspector\InspectorBuilder();
$builder->withTypesProperties()
        ->withPropertyAnnotations()
        ->build();

基于

• https://github.com/cweiske/jsonmapper
• https://github.com/JsonMapper/JsonMapper