PHPackages                             bigz/halapi - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. bigz/halapi

ActiveLibrary

bigz/halapi
===========

A PHP library to support implementing representations for HAL, REST over JSON web services

0.2.2(7y ago)22571MITPHPPHP >=5.6

Since Nov 26Pushed 7y ago1 watchersCompare

[ Source](https://github.com/BigZ/Halapi)[ Packagist](https://packagist.org/packages/bigz/halapi)[ RSS](/packages/bigz-halapi/feed)WikiDiscussions master Synced 2mo ago

READMEChangelog (4)Dependencies (10)Versions (6)Used By (1)

Hypertext Application Language for (REpresentational State Transfer) Application Programming Interfaces
-------------------------------------------------------------------------------------------------------

[](#hypertext-application-language-for-representational-state-transfer-application-programming-interfaces)

[![Build Status](https://camo.githubusercontent.com/3ddfa8f04008d72424c91dc8bbc1c58c9a0c115ad945071d54d37ea32f07f066/68747470733a2f2f7472617669732d63692e6f72672f4269675a2f48616c6170692e7376673f6272616e63683d6d6173746572)](http://travis-ci.org/BigZ/Halapi)[![Test Coverage](https://camo.githubusercontent.com/06b9bee5d386efb60640c91cd8cb6062c897d15d6b5968152e50196c1eedd645/68747470733a2f2f636f6465636c696d6174652e636f6d2f6769746875622f4269675a2f48616c6170692f6261646765732f636f7665726167652e737667)](https://codeclimate.com/github/BigZ/Halapi/coverage)[![SensioLabsInsight](https://camo.githubusercontent.com/fa0286b48e4565cd45d8d0b615ea1ec65df73810984ff48df619d2458348bb84/68747470733a2f2f696e73696768742e73656e73696f6c6162732e636f6d2f70726f6a656374732f32343065663531662d363632352d346337392d396261322d3538643466636236336661352f6d696e692e706e67)](https://insight.sensiolabs.com/projects/240ef51f-6625-4c79-9ba2-58d4fcb63fa5)[![Scrutinizer Quality Score](https://camo.githubusercontent.com/d89145e4cda73b7db945cde2ee8117b3b79fedb53bc4544821380022ca7ca5ff/68747470733a2f2f7363727574696e697a65722d63692e636f6d2f672f4269675a2f48616c6170692f6261646765732f7175616c6974792d73636f72652e706e673f733d34356235613832356639396465346432396339386235313033663539653036303133396366333534)](https://scrutinizer-ci.com/g/BigZ/Halapi/)[![Code Climate](https://camo.githubusercontent.com/d563cc641c390252912074b661124f3d9888fc5f2dc414ffd32e382fdd45c408/68747470733a2f2f636f6465636c696d6174652e636f6d2f6769746875622f4269675a2f48616c6170692f6261646765732f6770612e737667)](https://codeclimate.com/github/BigZ/Halapi)

Given some conventions, displaying the HAL representation of any entity becomes very easy.

HAL is a json presentation format of the HATEOAS constraint, which is meant to add relations between objects.

It's whole specification is available here [http://stateless.co/hal\_specification.html](http://stateless.co/hal_specification.html)

The work is in progress to make it framework agnostic but actually relies on you using symfony/http-foundation, which will change in a close future to use psr6 (while providing a bridge) For the object manager, you are free to choose the one you like, although only doctrine orm has been implemented at the mement. Relation findings relies also a lot on doctrine's ClassMetadata interface, that we should maybe abstract (you can still use your own implementaion)

Usage
=====

[](#usage)

`composer req bigz/halapi`

Symfony bundle
--------------

[](#symfony-bundle)

Full fledged example using symfony (a good starting point for your api)
-----------------------------------------------------------------------

[](#full-fledged-example-using-symfony-a-good-starting-point-for-your-api)

Example
=======

[](#example)

```
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);
    }
}

```

Resources
---------

[](#resources)

### List

[](#list)

#### Pagination

[](#pagination)

A list will give you a paginated ressource, HAL formatted.

`/entities?limit=2&page=2`

#### Filtering

[](#filtering)

You can filter out results on specific fields.

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

Available operators are `>`, `=`, `