# dto

**Repository Path**: Reusify/dto

## Basic Information

- **Project Name**: dto
- **Description**: php dto
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-09-05
- **Last Updated**: 2025-10-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Reusify DTO

**Reusify DTO** 是一个轻量级 PHP DTO（Data Transfer Object）库，旨在简化数据对象的封装与复用。
它可以将数组或对象快速映射到 DTO，并支持字段映射、递归转数组、JSON 序列化等功能，减少重复写类、函数和 setter 的工作。

---

## 安装

通过 Composer 安装：

```bash
composer require reusify/dto
```

PHP 版本要求 >= 7.4。

---

## 特性

- 批量赋值（支持数组和对象）
- 字段映射（支持 `$map` 映射 DTO 属性）
- 支持私有/保护属性赋值
- 可递归转换为数组
- JSON 序列化支持
- 支持 `ArrayAccess`、`IteratorAggregate`、`Countable`
- 类型属性未初始化安全处理

---

## 使用示例

### 创建 DTO

```php
<?php

require_once "../vendor/autoload.php";

use Reusify\Dto\BaseDto;

class UserDto extends BaseDto
{
    public int $id;
    public string $name;
    public string $email;
    public string $password;
}

$userDto = new UserDto([
    'id' => 1,
]);

echo $userDto;
// 输出: {"id":1}

var_dump($userDto->toArray());
// 输出: ['id' => 1]

var_dump($userDto->toJson());
// 输出: {"id":1}
```

---

### 批量赋值和字段映射

```php
$userDto = new UserDto([
    'id' => 1,
    'name' => 'test',
    'email' => 'email',
    'password' => 'password',
]);

class AdminDto extends BaseDto
{
    public int $id;
    public string $name;
    public string $email;
    public string $password;
}

// 普通复制
$adminDto = new AdminDto($userDto);
echo $adminDto;
// 输出: {"id":1,"name":"test","email":"email","password":"password"}

// 使用字段映射，将 UserDto 的 name 赋值到 AdminDto 的 email
$userDto2 = new UserDto([
    'id' => 1,
    'name' => 'test',
    'email' => 'email',
]);

$adminDto1 = new AdminDto($userDto2, ['name' => 'email']);
echo $adminDto1;
// 输出: {"id":1,"name":"test","email":"test","password":""}
```

---

### fill 方法规则

`BaseDto::fill($data, $map)` 支持两种方式：

1. **直接同名赋值**

```php
$data = ['id' => 1, 'name' => 'Tom'];
$dto->fill($data);
// DTO 属性 id 和 name 会被赋值
```

2. **字段映射**

```php
$map = ['dtoPropertyName' => 'dataKey'];
$dto->fill($data, $map);
// DTO 属性 dtoPropertyName 会被赋值为 $data['dataKey']
```

- 支持 `$data` 为数组或对象（包括 `IteratorAggregate`）
- `$map` 的赋值优先级高于同名字段
- 会抛出 `LogicException` 如果 `$data` 缺少映射的 key

---

### 转数组和 JSON

```php
$array = $dto->toArray(); // 递归 DTO 转数组
$json = $dto->toJson();   // JSON 字符串
```

- 支持嵌套 DTO 对象
- 数组中的对象也会递归转换

---

### 支持接口

- `ArrayAccess`：可像数组访问 DTO 属性，但默认只读
  ```php
  $dto['id']; // 访问
  $dto['id'] = 123; // 抛异常
  ```
- `IteratorAggregate`：可遍历 DTO
  ```php
  foreach ($dto as $key => $value) {
      echo "$key => $value\n";
  }
  ```
- `Countable`：可获取 DTO 属性数量
  ```php
  count($dto);
  ```

---

### 示例：数组列提取

```php
$array = [];
$array[] = $userDto;
$array[] = $userDto;

$r = array_column($array, 'id');
var_dump($r); // 输出: [1, 1]
```

---

### 注意事项

- PHP 7.4+ 类型属性未初始化时会被安全跳过
- DTO 构造函数默认调用 `fill($data, $map)`，可传入初始值和映射
- Map 的 key 会覆盖原同名字段

---

### 总结

`Reusify DTO` 旨在让 PHP 开发者减少重复封装对象、函数和方法的工作，尤其适合在业务层频繁处理 DTO、API 响应或数据库映射场景。