README

遵循一些约定，显示任何实体的HAL表示变得非常简单。

HAL是HATEOAS约束的JSON表示格式，旨在在对象之间添加关系。

其完整规范可在以下地址找到：http://stateless.co/hal_specification.html

正在进行的工作使其框架无关，但实际上依赖于你使用symfony/http-foundation，这将在不久的将来更改为使用psr6（同时提供桥梁）。对于对象管理器，你可以自由选择你喜欢的，尽管目前只实现了doctrine orm。关系查找也很大程度上依赖于doctrine的ClassMetadata接口，我们可能需要对其进行抽象（你仍然可以使用你自己的实现）

使用方法

composer req bigz/halapi

Symfony包

https://github.com/BigZ/HalapiBundle

使用symfony的完整示例（你的API的好起点）

https://github.com/BigZ/promote-api

示例

use Halapi\AnnotationReader\AnnotationReaderInterface;
use Halapi\ObjectManager\ObjectManagerInterface;
use Halapi\UrlGenerator\UrlGeneratorInterface;
use Psr\Http\Message\ServerRequestInterface;

class EntityController()
{
    /**
     * You can provide your own implementations of those interfaces or use the provided ones.
     */
    public function __construct(
        UrlGeneratorInterface $router,
        AnnotationReaderInterface $annotationReader,
        ObjectManagerInterface $entityManager,
        PagerInterface $pager
    ) {
        $this->router = $router;
        $this->annotationReader = $annotationReader;
        $this->entityManager = $entityManager;
        $this->pager = $pager;
    }

    /**
     * Accessed by the /entities/{id} route
     */
    public function getHalFormattedEntity(ServerRequestInterface $request, Entity $entity)
    {
        $linksRelation = new LinksRelation(
            $this->annotationReader,
            $this->router,
            $this->entityManager,
        );
        $embeddedRelation = new EmbeddedRelation(
            $this->annotationReader,
            $request
        );

        $relationFactory = new RelationFactory([$linksRelation, $embeddedRelation]);
        $builder = new HALAPIBuilder($relationFactory);

        return $builder->gerSerializer()->serialize($entity);
    }

    /**
     * Accessed by the /entities
     */
    public function getHalFormattedCollection(ServerRequestInterface $request, $entityName)
    {
        $linksRelation = new LinksRelation(
            $this->router,
            $this->annotationReader,
            $this->entityManager,
            $request
        );
        $embeddedRelation = new EmbeddedRelation(
            $this->router,
            $this->annotationReader,
            $this->entityManager,
            $request
        );

        $relationFactory = new RelationFactory([$linksRelation, $embeddedRelation]);
        $builder = new HALAPIBuilder($relationFactory);

        $paginationFactory = new PaginationFactory(
            $this->router,
            $this->annotationReader,
            $this->entityManager,
            $this->pager
        );
        $paginatedRepresentation = $paginationFactory->getRepresentation($entityName);

        return $builder->gerSerializer()->serialize($paginatedRepresentation);
    }
}

资源

列表

分页

列表将为您提供分页的HAL格式化资源。

/entities?limit=2&page=2

过滤

您可以在特定字段上过滤结果。

/entities?filter[id]=5&filteroperator[id]=>

可用的运算符有>、<、>=、<=、=、!=默认运算符是=

排序

您可以根据任何属性对结果进行排序

/entities?sort=-created,title

实体

创建新实体

POST /entities

{ "entity": { "name": "eminem", "slug": "eminem", "bio": "来自底特律的说唱歌手", "labels": [1, 2] } }

将返回

{ "id": 2, "name": "eminem", "slug": "eminem", "bio": "来自底特律的说唱歌手", "_links": { "self": "/artists/2", "labels": [ "/labels/1", "/labels/2" ] } }

PUT & PATCH工作方式相同

嵌入

默认情况下，关系不会被嵌入。您可以通过指定需要嵌入的实体来更改此行为。/entities/1?embed[]=gigs&embed[]=labels

要允许关系被嵌入，您必须向实体的属性添加一个@Embeddable注解。

use Halapi\Annotation\Embeddable;

/**
* The Embeddable annoation below is here if you want a custom route for your entity.
* By default, the generator would you "get_'entity's" which is the default behaviour
* of FOSRestBundle.
* @Embeddable("fetch_artists")
*/
class Artist
{
    /**
     * @var int
     *
     * @Expose
     */
    private $id;

    /**
     * @var Labels[]
     *
     * @Embeddable
     */
    protected $labels;
}

生产就绪路线图

• (必须)提高覆盖率
• (必须)实现稀疏字段集
• (必须)实现深层资源包含
• (应该)支持IN过滤运算符
• (应该)使用propertyinfo组件重构
• (应该)使用doctrine/reflection而不是doctrine/common
• (应该)能够将任何其他HATEOAS格式序列化。与jms相比，这并不容易...