nilportugues/api-transformer

提供API转换核心功能的基库。

3.1.1 2017-04-07 14:32 UTC

README

Build Status Scrutinizer Code Quality SensioLabsInsight Latest Stable Version Total Downloads License Donate

用途

此库提供了API转换的核心功能,并且是许多其他包的基库。

它本身完全不可用。请查看以下使用此库的项目。

被使用于

以下转换器当前使用此库作为基础

安装

使用Composer安装包

$ composer require nilportugues/api-transformer

工作原理

必须使用Mapper类来加载,因为它期望一个包含定义结构的数组或实现ApiMapping的类名。

有两种方式将库集成到PHP框架中,以增加灵活性。

虽然我不建议有两种映射风格,但在同一个配置文件中同时使用它们是完全可能的。加载所有映射的Mapper类会对两者进行内部转换,因此客户端无需担心。

使用方法

use NilPortugues\Api\Mapping\Mapper;
use NilPortugues\AcmeProject\Infrastructure\Api\Mappings\PostApiMapping;

$arrayConfig = include 'mappings.php';
$classConfig = [
	PostApiMapping::class,
];

$mappings = array_merge($classConfig, $arrayConfig);

//Now $mapper can be passed to a Transformer.
$mapper = new Mapper($mappings);

创建映射文件

实现ApiMapping(推荐方法)

要创建映射,您可以实现以下接口

  • ApiMapping:将数据转换为纯JSON以供API消费或JSend API格式。
  • JsonApiMapping将数据转换为JSONAPI 1.0标准。
  • HalMapping将数据转换为HAL+JSON和HAL+XML API标准。

如预期的那样,您可能需要实现多个接口以支持多种API格式。

<?php

namespace NilPortugues\AcmeProject\Infrastructure\Api\Mappings;

use NilPortugues\AcmeProject\Blog\Domain\Post;
use NilPortugues\Api\Mappings\HalMapping;
use NilPortugues\Api\Mappings\JsonApiMapping;

class PostApiMapping implements JsonApiMapping, HalMapping
{
    /**
     * {@inheritdoc}
     */
    public function getClass() : string
    {
        return Post::class;
    }

    /**
     * {@inheritdoc}
     */
    public function getAlias() : string
    {
        return 'Posting'; //If none is used 'Post' will be used instead.
    }

    /**
     * {@inheritdoc}
     */
    public function getAliasedProperties() : array
    {
        return [
            'title' => 'headline',
            'content' => 'body',
        ];
    }

    /**
     * {@inheritdoc}
     */
    public function getHideProperties() : array
    {
        return [
           'comments',
       ];
    }

    /**
     * {@inheritdoc}
     */
    public function getIdProperties() : array
    {
        return [
            'postId',
        ];
    }

    /**
     * {@inheritdoc}
     */
    public function getUrls() : array
    {
        return [
          // Mandatory
          'self' => 'http://example.com/posts/{postId}',
          // Optional
          'comments' => 'http://example.com/posts/{postId}/comments',
        ];
    }

    /**
     * Returns an array of curies.
     *
     * @return array
     */
    public function getCuries() : array
    {
        return [
            'name' => 'example',
            'href' => 'http://example.com/docs/rels/{rel}',
        ];
    }

    /**
     * {@inheritdoc}
     */
    public function getRelationships() : array
    {
        return [
            'author' => [
                'related' => 'http://example.com/posts/{postId}/author',
                'self' => 'http://example.com/posts/{postId}/relationships/author',
            ],
        ];
    }
}

使用数组进行映射

// mappings.php

return  [
  [
      'class' => Post::class,
      'alias' => 'Posting', //If none is used 'Post' will be used instead.
      'aliased_properties' => [
          'title' => 'headline',
          'content' => 'body',
      ],
      'hide_properties' => [
		  'comments',
      ],
      'id_properties' => [
          'postId',
      ],
      'urls' => [
          // Mandatory
          'self' => 'http://example.com/posts/{postId}',
          // Optional
          'comments' => 'http://example.com/posts/{postId}/comments',
      ],
      // (Optional) Used by HAL+JSON / HAL+XML
      'curies' => [
          'name' => 'example',
          'href' => 'http://example.com/docs/rels/{rel}',
      ],
      // (Optional) Used by JSONAPI
      'relationships' => [
          'author' => [
            'related' => 'http://example.com/posts/{postId}/author',
            'self' => 'http://example.com/posts/{postId}/relationships/author',
          ],
      ]
  ],
];

质量

要在命令行运行PHPUnit测试,请转到测试目录并运行phpunit。

此库试图遵循PSR-1PSR-2PSR-4PSR-7

如果您发现任何符合性的疏忽,请通过Pull Request发送补丁。

贡献

对包的贡献总是受欢迎的!

支持

使用以下方式之一与我联系

作者

许可

代码库在MIT许可下授权。