README

基于 League/Fractal 库的定制数据转换器。

查看 Fractal 文档：http://fractal.thephpleague.com/

Laravel 5.x/6.x

安装 saritasa/transformers 包

$ composer require saritasa/transformers

如果你使用 Laravel 5.4 或更早版本，或者 5.5+ 版本且禁用了包发现，请将 TransformersServiceProvider 服务提供者在 config/app.php 中添加

'providers' => array(
    // ...
    Saritasa\Transformers\TransformersServiceProvider::class,
)

这对于本地化正确工作来说是必需的。

可用的转换器

IDataTransformer

接口，用于从 League/Fractal 库中解除依赖。确保在此库中的每个转换器实现都具有此接口。

示例:

class AnotherTransformerWrapper implements IDataTransformer
{
    public function __construct(IDataTransformer $nestedTransformer) { ... }
}

BaseTransformer

当你只需要通过 Dingo/Api 方法将模型转换为 JSON 响应，并且没有特定的格式要求时，你可以直接使用 BaseTransformer。它调用 Arrayable->toArray() 方法。因此，Eloquent 模型结果将仅包含由 $visible 描述的字段，而不是 $hidden。 此外，还将 $dates 中枚举的字段转换为 ISO8061 格式。

示例:

class User extends \Illuminate\Database\Eloquent\Model {
    // "full_name" is a property calculated from first_name and last_name
    protected $visible = ['full_name', 'created_at'];
    protected $hidden = ['email', 'password'];
    protected $dates = ['created_at', 'updated_at', 'birthday'];
}

class UserController extends BaseApiController {
    public function myProfile(): \Dingo\Api\Http\Response {
        $user = $this->user(); // Returns Eloquent model
        return $this->response->item($user, new BaseTransformer);
        // Output will be JSON
        // { "full_name": "Ivan Ivanov", "created_at": "2017-04-12T23:20:50.52Z" }
    }
}

$user = User::find($userId);

ObjectFieldsTransformer

将输出请求的字段到结果中，无论它们在 Eloquent 模型中描述为 $hidden 还是 $visible

示例:

class User extends \Illuminate\Database\Eloquent\Model {
    // "full_name" is a property calculated from first_name and last_name
    protected $visible = ['full_name', 'created_at'];
    protected $hidden = ['email', 'password'];
    protected $dates = ['created_at', 'updated_at', 'birthday'];
}

class UserController extends BaseApiController {
    public function myProfile(): \Dingo\Api\Http\Response {
        $user = $this->user(); // Returns Eloquent model
        $profileTransformer = new ObjectFieldsTransformer('first_name', 'last_name', 'email', 'birthday');
        return $this->response->item($user, $profileTransformer);
        // Output will be JSON
        // { "first_name": "Ivan", "last_name": "Ivanov", "email": "ivanov@mail.ru", "birthday": "1985-04-12T00:00:00.00Z" }
    }
}

$user = User::find($userId);

CombineTransformer

按参数顺序应用多个转换器；

示例:

class UserProfileTransformer extends CombineTransformer
{
    public function __construct()
    {
        parent::__construct(
            new PreloadUserAvatarTransformer(),
            new PreloadUserSettingsTransformer()
        );
    }
}

LimitFieldsTransformer

结果将首先应用 ->toArray() 方法（该方法尊重 Eloquent 的 $visible 和 $hidden 字段），然后限制输出到选定的字段。这样，即使列出，隐藏字段也不会出现在输出中。

示例:

class User extends \Illuminate\Database\Eloquent\Model {
    protected $visible = ['full_name', 'created_at'];
    protected $hidden = ['email', 'password'];
    protected $dates = ['created_at', 'updated_at', 'birthday'];
}

class UserController extends BaseApiController {
    public function myProfile(): \Dingo\Api\Http\Response {
        $user = $this->user(); // Returns Eloquent model
        $publicProfileTransformer = new LimitFieldsTransformer('full_name', 'birthday');
        return $this->response->item($user, new BaseTransformer);
        // Output will be JSON
        // { "full_name": "Ivan Ivanov" }
    }
}

$user = User::find($userId);

异常

TransformException

当实现 IDataTransformer 的类遇到无法转换的数据时应该抛出。

示例:

function transform(Arrayable $data) {
    if (!$data->author) {
        new TransformException($this, "Author may not be empty");
    }
    // ...
}

TransformTypeMismatchException

如果转换器期望模型为特定类型，但获取了另一个类，则应该抛出。

class UserTransformer extends BaseTransformer {
    public function transform(Arrayable $model) {
        if (!$model instanceof User) {
            throw new TransformTypeMismatchException($this, User::class, get_class($model));
        }

        return transformUser($model);
    }

    private function transformUser(User $user) {
        ... // Handle strong-typed model
    }
}

实用类

DtoModel

允许你在使用 Fractal 进行集合转换时使用纯 DTO 模型，而不是 Eloquent。

贡献

创建分支，检出它
本地开发如常。 代码必须遵循 PSR-1，PSR-2 - 运行 PHP_CodeSniffer 以确保代码遵循风格指南
使用单元测试添加功能覆盖 并运行 PHPUnit 以确保所有测试通过
更新 README.md 以描述新或更改的功能
将更改描述添加到 CHANGES.md 文件。使用语义化版本控制约定来确定下一个版本号。
准备好后，创建拉取请求

创建快捷方式

如果你安装了 GNU Make，你可以使用以下快捷方式

make cs（而不是php vendor/bin/phpcs）- 使用PHP_CodeSniffer运行静态代码分析，检查代码风格
make csfix（而不是php vendor/bin/phpcbf）- 自动修复代码风格违规（例如PSR-2代码格式违规），尽可能使用PHP_CodeSniffer
make test（而不是php vendor/bin/phpunit）- 使用PHPUnit运行测试
make install - 替代composer install
make all或无参数直接make - 依次调用上述的安装、cs、test任务 - 项目将被组装，通过linter检查并使用单个命令进行测试

saritasa / transformers

维护者

详情