README

Agile router is a composer library designed to create APIs in PHP in a fast and efficient way. It is an agile and great router. The main ideas is to make the creation of apis:

Agile: You can create first apis concept very quickly and improve with time.
Easy: The idea is that the router make all the boring work of check parameters and the developer could start to work to fun parts of the project XD

How to start 🚀

Follow the next steps to start to working with this php router. If you found anything wrong or bad explained don't doubt to contact with us (correctly me... but us, sounds better 😅).

Prerequisites 📋

You will need to have installed php and composer in your computer.

Installation 🔧

You need to require the package to your project.

composer require agrandesr/agile-router

Next, you can use in your code. We encourage to use in the root file index.php. It is important to write under the autoload require.

<?php

require './vendor/autoload.php';

use Agrandesr\Router;

$router = new Router();

$router->run();

Finally, you need to create a routes.json file to start to create your API.

There is a easy example to test!

{
    "hi": {
        "GET": {
            "execute":[
                {
                    "type":"json",
                    "content":{
                        "showAll":false,
                        "body":{
                            "Obi-wan":"Hello there!",
                            "Grievous": "General Kenobi"
                        }
                    }
                }
            ]
        }
    }
}

With this you will have a operative endpoint "hi" with the content:

{
    "Obi-wan":"Hello there!",
    "Grievous": "General Kenobi"
}

You only need to up the server with php. For example:

php -S localhost:8000

Now you can start to use the router json file following the documentation. We recommend to read quickly all the documentation at least one time before start. Yes, yes, it is boring, but trust me it will be very usefull.

Documentation

The main elements of the library are used in the Router file. But they can be use in different ways.

Future I will try to make an easy video tutorial to make easy the first steps.

Routes file options

The most important part of the framework are the routes files. The file, named routes.json have to be in the root of the project with index.php (you can change that with an advanced configuration, but first easy mode). In this file you can create and run a first operative API in a few steps.

The structure of the file is first, the paths; second, the methods; third, the framework properties for this endpoint.

{
    "path":{
        "METHOD1":{
            "FrameworkProperty1":{},
            "FrameworkProperty2":{},
            "FrameworkProperty3":{}
        },
        "METHOD2":{},
        "METHOD3":{}
    }
}

The paths are defined by users and separated by the character "/". To indicate a dynamic route, that is to say that a slug of the route is variable, you should only enclose it in brackets ({}). For example:

section/{slug}/section/{slug}

The methods are the normal request methods:

GET
POST
UPDATE
PUT
DELETE
...

Checkers

The framework consists of some properties to validate the most common data of a request, such as the parameters in the request or the Body.

Below is an example of a request using the available checkers.

{
    "params":{
        "POST":{
            "req_headers":["x-header"],
            "req_parameters":["param"],
            "req_body":["id","data.name","data.surname"],
            "render":{
                "type":"json",
                "content":{
                    "header":"^x-header^",
                    "param":"?param?",
                    "showAll":false,
                    "body":{
                        "id":"$id$",
                        "data": {
                            "name":"$data.name$",
                            "surname":"$data.surname$"
                        }
                    }
                }
            }
        }
    }
}

How you can see you can check the body, header and request parameters in a easy way.

At the same time, you can use these values for the response indicated in content for renders of type JSON (it can also be used with renders of type SQL).

For specific checker documentation:

Render method

The render method or property within the JSON is in charge of performing the final action and whose objective is to print the final result of the API. The idea is that the JSON method can be used mainly to prototype your API and that the frontend can start working with the API already deployed in production. Afterwards, you can calmly work replacing the JSON-type renderer with a CLASS-type renderer to make the code you need. Also, from JSON and CLASS you have SQL type. This is intended for rapidly prototyping APIs that interface to a database. You can find more information on each method below.

JSON render - Show a basic JSON default response.
CLASS render - Run the class that you decide and inside the class you can do what you want like vainilla php.
SQL render - Return the response of a query to a SQL database.

PHP Framework tools

Hi! The next tools are optionals. There were created to develop the framework and they are already downloaded. For this reason, could be a good idea to make a look. If the classes are good for you, cool! If you don't like... You can only ignore them or rewrite the code to delete... 😭

Some relevant information

Routes priority

It is very important to know that the JSON path is from top to bottom. So if you write two possible routes, the first one will always be executed. It is very important to keep that in mind. For example, for the call:

localhost/test/slug/test

With the Routes file (simplified):

{
    "test/{id}/test":{"...":"..."},
    "test/slug/test":{"...":"..."},
    "{id}/{value}/test":{"...":"..."}
}

Always will be enter to the configuration of the first route in your json file.

Aditional information

Versioning: 📌

For all available versions, see the tags in this repository.

Authors ✒️

A.Grandes.R - Main worker - AGrandesR

You can also look at the list of all [contributors] (https://github.com/your/project/contributors) who have participated in this project.

License 📄

This project is under the License MIT - read the file LICENSE.md for more details.

Thanks to: 🎁

Villanuevand for his incredible template for documentation 😊
Alberto Ramirez for his inspiration in the magic world of PHP.

agrandesr / agile-router

Maintainers

Details