README

About
Installation
Configuration
Example of usage
How it works
Tests
Road map

About

Philarmony is a bundle made to help you create a modular REST API. From database to controllers and forms, without forgetting authorization and data validation, manage your API easily in minutes.

V.3.0 - What's new ?

Better performances, this is what can resume Philarmony V3. The core has been rewritten with

Installation

You can install using composer, assuming it is already installed globally :

composer require deozza/philarmony-core-bundle

Configuration

In order yo use Philarmony in your project, you need to configure it. First, create a philarmony.yaml file with the following structure :

deozza_philarmony:
    directory:
      entity: ~
      property: ~
      enumeration: ~

This will be used to locate the database schema files. By default they are created and stored in /var/Philarmony/.

Then, to use the embedded services, as the controllers and the repositories, of Philarmony, you need to enable them in your /config/services.yaml and in your config/routes/annotations.yaml :

services: 
    Deozza\PhilarmonyCoreBundle\Controller\:
      resource: '@DeozzaPhilarmonyCoreBundle/Controller'
      tags: ['controller.service_arguments']
      
    Deozza\PhilarmonyCoreBundle\Repository\:
      resource: '@DeozzaPhilarmonyCoreBundle/Repository'
      tags: ['doctrine.service_entity']

philarmony_controllers:
    resource: '@DeozzaPhilarmonyCoreBundle/Controller'
    type: annotation
    prefix: /

Finally, in order to use filters inside your query, add the following functions inside the doctrine.yaml configuration file :

doctrine:
    orm:
        dql:
            string_functions:
                JSON_EXTRACT: Scienta\DoctrineJsonFunctions\Query\AST\Functions\Mysql\JsonExtract
                JSON_UNQUOTE: Scienta\DoctrineJsonFunctions\Query\AST\Functions\Mysql\JsonUnquote

Example of usage

For this example, our API example will manage vacation rentals. Users are able to create rental offers, book vacations and communicate through an internal message service.

Therefore, the database would be constituted with 4 different entity kinds :

offer : contains all the infos about a rental offer
booking : contains all the info about a booking and the offer it is linked with
conversation: contains all the message of a conversation between 2 users
message : contains the content of the message and other informations about it

These entities are defined by default inside the entity.yaml configuration file, and their properties inside the property.yaml file.

Here is an example of a cUrl request with its body (in JSON) to create a new rental offer :

curl --header "Content-Type: application/json"
     --request POST
     --data '{"title": "Stunning appartment in Tokyo", "description": "Located in central Tokyo. 2 bedrooms, bathroom, wifi.", "price": 82, "place_category":"appartment"}'
     http://www.mysuper.app/api/entity/offer

As you can see, the kind of entity you post is specified in the url. This will allow Philarmony to adapt the comportment of the API following the logic you implemented in the yaml configuration files and via your business logic. Here is the JSON response you would expect from the previous request:

{
  "uuid": "00100000-0000-4000-a000-000000000000",
  "kind": "offer",
  "owner": "00100000-0000-4000-a000-000000000000",
  "date_of_Creation": "2019-01-01T12:00:00+02:00",
  "properties": {
    "title": "Stunning appartment in Tokyo",
    "description": "Located in central Tokyo. 2 bedrooms, bathroom, wifi.",
    "price": 82,
    "place_category": "appartment"
  }
}

Say that an offer can have multiple descriptions and you want to add another one, simply send a request like the following :

curl --header "Content-Type: application/json"
     --request POST
     --data '{"description": "Animals are allowed"}'
     http://www.mysuper.app/api/offer/00100000-0000-4000-a000-000000000000/description

Here will be the expected response :

{
  "uuid": "00100000-0000-4000-a000-000000000000",
  "kind": "offer",
  "owner": "00100000-0000-4000-a000-000000000000",
  "date_of_Creation": "2019-01-01T12:00:00+02:00",
  "properties": {
    "title": "Stunning appartment in Tokyo",
    "description": [
       "Located in central Tokyo. 2 bedrooms, bathroom, wifi.",
       "Animals are allowed"
       ],
    "price": 82,
    "house_category": "appartment"
    }
}

Responses

When you perform a request to Philarmony, it will always send a response containing a serialized JSON and one of the HTTP code listed above.

How it works

Database schema

Your database schema is fully designed by 3 yaml files.

Entity

An Entity is what could be view as a MySQL table, a main container of data. By default, it is defined by an owner (the User who created the entity), a kind, the date it was create and its properties.

Property

The property is what could be view as a MySQL column, the container of a specific data. By default, it is defined by a type, a unique paremeter and a required parameter.

Enumeration

The enumeration is a list of possible values handled by of property.

Validation state

Validation state is used in order to assert an entity is in good conditions to be used. Each state defines specific methods usable by specific users.

Authorization

To assure the right user is manipulating a resource, authorization is handled by the validation state. It determines which users are allowed to send the different requests.

Constraints

In order to pass from one state to the next, the entity and its data must be valid according to constraints.

Conflict rules

A conflict rules is a custom and advanced constraint that need to be developed and cannot be added to a configuration file.

Tests

A demo app has been developped and is visible here. Through the tests of this app, we ensure that every feature of Philarmony is tested and we garanty the stability of the bundle.

Road map

Database migration : for now, when you delete or update a property or an entity, you need to handle manually the migration. For a better experience, I am thinking about a kind of automatic solution

deozza / philarmony-core-bundle

Maintainers

Details