Skip to content

Controllers

Introduction

eQual allows to attach URIs to any kind of operation defined in controllers, which are regular PHP scripts.

Within a package, controllers are stored inside the actions, data & apps folders.

eQual follows the CQRS architectural pattern (Command-Query Responsibility Separation) :

FOLDER OPERATION
actions "DO" operations (POST, PUT, PATCH, DELETE) : Processing operations involving data manipulation (Commands).
data "GET" operations (GET) : data providers answering to request (Queries).
apps "SHOW" operations : output involving UI data generated by the back-end (mostly Apps).

About Controllers

  • Controllers are re-usable and can be interdependent.
  • Controllers can act as data funnels and dispatchers.

Announcement

  • description

    • what it does

    • expected parameters and related characteristics

    • constraints, default value, optional or mandatory; type; name; description

  • dependency injection services required by the script

  • response format : content-type and content-disposition (charset)

  • CORS : accept-origin (Access-Control-Allow-Origin)

description

Describes what the controller does.

params

Array containing values used by the controller, which may be required.

constants

List of strings, representing constant names, used by the system.

They are present globally inside the config/config.inc.php file, but also can be overwritten (with the namespace config) inside packages with a config.inc.php file.

Every overwritten constant is limited to the package it belongs to.

If they are used by a controller, they must be listed by it. If there is an error, displays Error 500.

Example :

'constants'     => ['AUTH_ACCESS_TOKEN_VALIDITY', 'AUTH_REFRESH_TOKEN_VALIDITY', 'AUTH_TOKEN_HTTPS']

The constants are checked by the announce() function inside eq.lib.php.

access

The access property allows to quickly define rights management: making sure the user performing a request has the required permissions.

PROPERTY DESCRIPTION
visibility The level of "visibility" of the ('public', 'protected' or 'private').
groups An array holding the list of groups the view is restricted to.

Examples : 

<?php
'access' => [
  'visibility'  => 'public'                 
   // anyone can access the controller (anonymous users)
]

<?php
'access' => [
  'visibility'  => 'protected',
  'users'       => [ROOT_USER_ID],           // list of granted users ids  
]

<?php
'access' => [
  'visibility'  => 'protected',
  'groups'      => ['sales.bookings.users'], // list of granted groups names
]

response

The response property provides info about the format of the returned data (if any).

It also allows to restrict the accepted origins of the requests (using CORS). At the moment the origin is unlimited, it is possible to create an array with the URL allowed to access the API.

<?php
'response' => [
  'content-type'    => 'application/json',
  'charset'         => 'utf-8',
  'accept-origin'   => '*'
],

providers

List of the different providers/services needed by the controller.

Example: 

<?php 
'providers'   => ['context', 'orm' , 'auth']     
 //'orm'= ObjectManager & 'auth'=AuthentificationManager

examples

The controller announcement allows the description of an examples property, in the form of an associative array intended for providing example calls.

This property is optional but valuable for frequently used controllers. When defined, by convention, it includes one example per call type. Each example corresponds to a key in the map: CLI, HTTP, and PHP.

Example: 

'examples' => [
    'CLI'   => './equal.run --get=contractika_sd_absences --id=16',
    'HTTP'  => '/?get=contractika_sd_absences&id=16',
    'PHP'   => "eQual::run('get', 'contractika_sd_absences', ['id' => 16]);"
],

CLI calls

When invoking controllers through CLI, parameters can be provided using long options notation : --arg=param (as handled by getopt_long()).

As the command will be interpreted by bash and that special chars might be involved in the parameters values, it might be necessary to encapsulate values within double quotes.

Example:

./equal.run --get=model_collect --entity=core\\User --domain="[id,>,100]" --limit=500 --fields="{id,points}"