2017 © Pedro Peláez
 

library php-rest-router

A framework for building REST API structures

image

hq9000/php-rest-router

A framework for building REST API structures

  • Wednesday, January 24, 2018
  • by hq9000
  • Repository
  • 0 Watchers
  • 0 Stars
  • 49 Installations
  • PHP
  • 0 Dependents
  • 0 Suggesters
  • 0 Forks
  • 1 Open issues
  • 9 Versions
  • 20 % Grown

The README.md

PHP REST router

A simple opinionated PHP framework for building API structures., (*1)

Motivation

In one of the proprietary projects I was working on, we needed to have a huge and complex REST api surface. Due to its dynamic nature and deep branching, it was considered suboptimal to go the normal "method per action" way., (*2)

What was needed is to be able to define a certain meta-structure and have the endpoints be just as a reflection of it., (*3)

Main concepts

The main concepts of the framework are the ones of: - a structure (a tree of nodes) - node traversing, (*4)

Structure (a tree of nodes)

A Structure is represented by hq9000\PhpRestRouter\Structure class., (*5)

image, (*6)

Structure is a unidirectional, acyclic graph of Nodes., (*7)

Each node, except the root one, has exactly one input node., (*8)

note: the arrows on the diagram above rather show the direction of the traversing, and not the direction of association., (*9)

Also, every node has associated: - path processor - something that is responsible for gathering a piece of information relevant to this node - path trigger - something that will make node traversing choose this node instead of its sibling. - if a node is the only output of its upstream node, the trigger can be omitted, (*10)

Node traversing

The useful thing a structure makes possible is ability to traverse it., (*11)

Traversing is done by calling its public function trace($path, &$dataAccumulator), where: - path is a string representing an API endpoint - dataAccumulator is a passed-by-reference array that will be used by path processors to put information extracted from the path at each visited node., (*12)

The ultimate goal of traversing is to come up with two things: - the final node - the fully populated accumulator array, (*13)

the user of the framework may want to associate certain logic with these bits of information, but this is intentionally left out of scope of the framework., (*14)

Usage Example

This chapter gives a bit of human-readable explanation to complement reading the source code of CommonTest.php., (*15)

In that test, we pretend that the useful thing nodes can do is to hold certain tags. For that, we extend the Node class by DomainNode:, (*16)

/*
 * Here in test we use a simple subclass of a Node modeling some "Domain" class doing 
 * something actually useful. This one can hold some "tag", in reality,
 * it might, for instance, be able to handle a web request etc.
 */
class DomainNode extends Node
{

    /**
     * @var
     */
    private $tag;

    public function getTag()
    {
        return $this->tag;
    }

    public function setTag($tag)
    {
        $this->tag = $tag;
        return $this;
    }
}

The structure of these nodes is shown on the simplified diagram below:, (*17)

image, (*18)

The test itself performs the "tracings" and checks their results, for example that class2/123123 results in the $idNode found as the final one and the data array appropriatelly populated with, (*19)

{
  "class": "class2",
  "id": 123123
}

The Versions

24/01 2018

dev-master

9999999-dev

A framework for building REST API structures

  Sources   Download

The Requires

  • php ^5.5

 

The Development Requires

24/01 2018

1.0.7

1.0.7.0

A framework for building REST API structures

  Sources   Download

The Requires

  • php ^5.5

 

The Development Requires

13/09 2017

1.0.6

1.0.6.0

A framework for building REST API structures

  Sources   Download

The Requires

  • php ^5.5

 

11/09 2017

1.0.5

1.0.5.0

A framework for building REST API structures

  Sources   Download

The Requires

  • php ^5.5

 

11/09 2017

1.0.3

1.0.3.0

A framework for building REST API structures

  Sources   Download

The Requires

  • php ^5.5

 

11/09 2017

1.0.4

1.0.4.0

A framework for building REST API structures

  Sources   Download

The Requires

  • php ^5.5

 

08/09 2017

1.0.1

1.0.1.0

A framework for building REST API structures

  Sources   Download

The Requires

  • php ^5.5

 

08/09 2017

1.0.2

1.0.2.0

A framework for building REST API structures

  Sources   Download

The Requires

  • php ^5.5

 

08/09 2017

1.0.0

1.0.0.0

A framework for building REST API structures

  Sources   Download

The Requires

  • php ^5.3.3 || ^7.0