ajtarragona/censat-client

Client d'accés a la API Rest de l'aplicació CENSAT

Maintainers

Details

github.com/ajtarragona/censat-client

Source

Issues

Installs: 581

Dependents: 0

Suggesters: 0

Security: 0

Stars: 0

Watchers: 0

Forks: 0

Open Issues: 0

v2.1.19 2024-03-15 11:45 UTC

Requires

MIT 96f92d3da7bf7b885a4c186dfd1e9334d8f76949

  • Txomin Medrano Martorell <tmedrano.woop@tarragona.cat>

laravellaravel5

This package is auto-updated.

Last update: 2024-04-15 12:03:06 UTC

README

Client d'accés a la API Rest de l'aplicació CENSAT de l'Ajuntament de Tarragona

Table of Contents generated with DocToc

Instalació

composer require ajtarragona/censat-client:"@dev"

Configuració

Pots configurar el paquet a través de l'arxiu .env de l'aplicació. Aquests son els parámetres disponibles :

Per a l'accés via API

CENSAT_DEBUG
CENSAT_API_URL // no incloure la versio a la URL
CENSAT_API_VERSION
CENSAT_API_USER
CENSAT_API_PASSWORD
CENSAT_API_TOKEN

Si definim un token, es farà servir aquest per totes les peticions. Si no, se'n crearà un de nou per cada petició a partir de l'usuari i password. És recomanable doncs definir un token ja que es faran la meitat de crides. Censat genera tokens amb una expiració d'un any a través del mètode Login de la seva Api.

Per a l'accés via Base de Dades

CENSAT_DB_HOST
CENSAT_DB_PORT
CENSAT_DB_DATABASE
CENSAT_DB_USERNAME
CENSAT_DB_PASSWORD

Alternativament, pots publicar l'arxiu de configuració del paquet amb la comanda:

php artisan vendor:publish --tag=ajtarragona-censat-config

Això copiarà esl arxiu a censat-api.php i censat-database.php a la carpeta config.

Via API

Un cop configurat, el paquet està a punt per fer-se servir. Ho pots fer de les següents maneres:

A través d'una Facade:

use Censat;
...
public  function  test(){
    $censos=Censat::censuses();
    ...
}

Per Laravel < 5.6, cal registrar l'alias de la Facade a l'arxiu config/app.php :

'aliases'  =>  [
    ...
    'Censat'  =>  Ajtarragona\Censat\Facades\Censat::class
]

Vía Injecció de dependències: Als teus controlladors, helpers, model:

use Ajtarragona\Censat\Models\CensatClient;
...

public  function  test(CensatClient  $censat){
    $censos=$censat->censuses();
    ...
}

Vía funció helper:

...
public  function  test(){
    $censos=censat()->censuses();
    ...
}

Funcions

Definició de censos i entitats

censuses()

Returns all censuses. Objects of class Census

census($short_name)

Returns a census given its name.

censusEntities($short_name)

Returns a census entities given the census name. Objects of class Entity

entities()

Returns all entities.

entity($short_name)

Returns an entity given its name.

entityFields($short_name)

Returns an entity fields given the entity name. Objects of class Field

entityField($entity_name, $field_name)

Returns a single entity field given the entity name and the field name.

entityGridFields($short_name, $grid_name)

Returns the fields of an entity grid, given the entity name and the grid name.

Accedint a les instàncies (Crear, modificar i consultar)

instances($census_name, $entity_name, $options=[])

Returns all instances in a given census and entity. Objects of class Instance

Options:
  • fields : comma separated field names that will be returned. See fields section for more info.
  • parsevalues : true will return all object and array values as strings.
  • separator : is parsevalues is set to true, multiple fields will be returned as a comma separated string. With this options you can set a diferent separator character/s.
  • exclude : comma separated field names that will NOT be returned.
  • sort : name of the field to sort by.
  • direction : sort direction (asc or desc).
  • paginate : true to paginate (default false).
  • page : page number.
  • pagesize : page size (default 10).

Fields:

Podem especificar quins camps volem que se'ns retornis amb una llista dels noms, separats per coma.

Tenim l'alias basefields que ens retornarà els camps base (id, dates, versio...)

Però a més, podem navegar pel model de dades mitjançant notació punt. Per exemple si volem que ens retorni l'id d'un camp de relació, podem fer:

nom_camp_relacio.id

En el cas de grids o camps múltiples (relacions, integracions, selects) tenim els accessors especials:

nom_grid.0 (o l'índex que vulguem)
nom_grid.first 
nob_grid.last

I la gràcia és que tot plegat es pot concatenar:

nom_camp.0.nom_grid.1.camp_usuari.username

Formatadors Sobre cada camp, podem aplicar formatadors separant-los amb el caràcter |. Aquests s'aplicaran al valor retornat. Per exemple podem fer que ens retorni un valor de text en majúscules:

nom_camp|upper

Es poden concaternar varios formatadors que s'aplicaran en ordre.

nom_camp|upper|lower

Aquests son els disponibles:

  • upper: passa a majúscules

  • lower: passa a minúscules

  • serialize: serialitza

  • csv(delimiter?;enclosure?): passa a csv, en cas que ens tornin arrays (opcionalment podem definir el caracter delimitador i les cometes per enbolcallar els texts)

  • json: passa a json

  • array: passa a rray si era un objecte

  • object: passa a objecte si era un array

  • matricula/format/string(format?): els 3 fan el mateix. Mostra una versió textual del camp retornat.

  • pad(num;char?;position?): afegeix zeros per l'equerra (podem passar el numero de zeros, i opcionalment el caracter a afegir, si no volem q sigui zero i la posicio: (0: esquerra, 1: dreta, 2:els dos costats) )

  • count: retorna el numero d'elements si es retorna un array

search($census_name, $entity_name, $filters, $options=[])

Search instances in a given census and entity.

Filters:

Must be an array of filters or filtergroups: A filter must be a key-value array with following attributes:

  • id : name of the field to filter
  • value : value of the field
  • operation : Logic Operation (=, !=, <, > , <=, >=, contains, starts_with, ends_with, in, not in, isnull, isnotnull) (default =)

A filtergroup must be a key-value array with following attributes:

  • concat : and / or
  • filters : array of filters or filtergroups
[
    ["id"=>  "name",  "value"=>"john",  "operation"=>"contains"],
    ["id"=>  "gender",  "value"=>"male"],  //default operation =
    ["id"=>  "age",  "value"=>18,  "operation"=>">"],
    ["id"=>  "active",  "operation"=>"isnotnull"],  //value not needed
    ["id"=>  "tags",  "operation"=>"in",  "value"=>[1,2,3]],
    ["concat"=>  "or",  "filters"=>[
        ["id"=>  "gender",  "value"=>"female"]
    ]]
]
Options:
instancesTree($census_name, $entity_name, $field_name, $options=[])

Returns the whole instances tree given a census name, an entity name and the field name that establishes the instances parenthood hyerarchy.

Options:
  • parent_id : id of the root instance to start the tree with (defaults to null)
  • sort : name of the field to sort by.
  • direction : sort direction (asc or desc).
  • filters : see search method
instance($census_name, $entity_name, $id, $options=[])

Returns a single instance given a census name, an entity name and the instance id.

Options:
  • fields : comma separated field names that will be returned. Alias "basefields" will return id, version and dates.
  • parsevalues : true will return all object and array values as strings.
  • exclude : comma separated field names that will NOT be returned.
getInstanceField($census_name, $entity_name, $id, $field_name)

Get an instance field given a census and entity, the instance id and the field name.

createInstance($census_name, $entity_name, $fields)

Create an instance in a given census and entity. Returns the created instance or an exception.

  • Fields must be a key-value array with the field names and its values.
  • For multiple values like selects, relations, documents or grids, use arrays.
  • Select and relation fields expect the ID of the related values.
  • Document-type fields expect and array with 'file-name' and 'file-content' (binary content)
  • Integration fields (like LDAP users and UOs) expect the PK of the integration (username and code in the examples).
    try{
        $instance= Censat::createInstance("census_name","entity_name",[
            "name" => "John",
            "surname" => "Smith",
            "age" => 25,
            "addresses_grid"=> [
                [
                    "street"=>"Fake street",
                    "number"=> 1
                ],
                [
                    "street"=>"Dumb street",
                    "number"=> 33
                    "floor" => 1
                ]
            ],
            "tags" => [1,2,4], //relation field
            'document_simple' => [
                "file-name"=>"doc_name.pdf",
                "file-content"=>$binary_content
            ],
            'document_multiple' => [
                [
                    "file-name"=>"doc_name1.pdf",
                    "file-content"=>$binary_content
                ],
                [
                    "file-name"=>"doc_name2.pdf",
                    "file-content"=>$binary_content
                ]
            ]
        ]);
    }catch(Exception $e){
        ...
    }
deleteInstance($census_name, $entity_name, $id, $hard=false)

Delete and instance given a census and entity and the instance id. By default it is a soft delete. Hard delete can be forced setting the parameter hardto true. Returns true or an Exception

updateInstance($census_name, $entity_name, $id, $fields)

Update an instance given a census and entity and the instance id. Fields must be a key-value array with the field names and its values. Returns the updated instance or an Exception.

updateInstanceField($census_name, $entity_name, $id, $field_name, $value)

Update an instance single field. Returns the updated instance or an Exception.

clearInstanceField($census_name, $entity_name, $id, $field_name)

Clears (sets to null) an instance field. Returns the updated instance or an Exception.

addInstanceFieldItem($census_name, $entity_name, $id, $field_name, $value)

Add an item to an instance field, given its value. It is useful for multiple fields (relations, selects, integrations or grids). Returns the updated instance or an Exception.

removeInstanceFieldItem($census_name, $entity_name, $id, $field_name, $item_id)

Removes an instance field item, given its id It is useful for multiple fields (relations, selects, integrations or grids). Returns the updated instance or an Exception.

Graelles (Grids)

getInstanceGridItems($census_name, $entity_name, $id, $grid_name)

Returns the items of an instance grid.

getInstanceGridItem($census_name, $entity_name, $id, $grid_name, $grid_item_id)

Returns an item of an instance grid, given its id.

addInstanceGridItem($census_name, $entity_name, $id, $grid_name, $values=[])

Add an item to an instance grid, given its value. Returns the updated instance an Exception.

updateInstanceGridItem($census_name, $entity_name, $id, $grid_name, $grid_item_id, $values=[])

Updates an instance grid item. Returns the updated instance an Exception.

removeInstanceGridItem($census_name, $entity_name, $id, $grid_name, $grid_item_id)

Removes an instance grid item, given its id. Returns the updated instance an Exception.

Entitats relacionades

addInstanceRelatedItem($census_name, $entity_name, $id, $field_name, $item_id)

Add an item to an instance relation field, given its id. Returns the updated instance an Exception.

removeInstanceRelatedItem($census_name, $entity_name, $id, $field_name, $item_id)

Remove an item from an instance relation field, given its id. Returns the updated instance an Exception.

Attachments (documents)

getAttachment($attachment_id)

Returns an attachment info given its Censat ID

getAttachmentContent($attachment_id)

Returns an attachment content (encoded in base64) given its Censat ID

downloadAttachment($attachment_id)

Downloads (streams the file through the response) an attachment given its Censat ID

Trees Feature

getTrees($options=[])

Retorna tots els arbres

getTree($tree_id, $options=[])

Retorna un arbre passant el seu ID o short_name

getTreeNodes($tree_id, $options=[])

Retorna els nodes d'un arbre

Options:
  • parent_id : Si s'especifica, retorna nodes a partir d'aquest node arrel.
  • with_instance : Retorna més dades de la instància d'aquest node.
  • hyerarchical : Retorna els nodes de forma jeràrquica (per defecte true).
  • depth : Nivell de profunditat (Si no s'especifica es retornen tots els nivells).
  • term : Paraula de cerca per filtrar els nodes (si s'especifica, es retornaran els nodes sense jerarquia).
  • instance_id : Retorna els nodes en que l'id d'instància sigui el passat.
  • entity_id : Retorna els nodes en que l'id de la entitat sigui el passat.
  • census_id : Retorna els nodes en que l'id del cens sigui el passat.
getNode($tree_id, $node_id, $options=[])

Retorna un node d'un arbre passant els seus IDs.

getNodeChildren($tree_id, $node_id, $options=[])

Retorna els fills d'un node

getNodeParent($tree_id, $node_id, $options=[])

Retorna el pare d'un node

getNodeAncestors($tree_id, $node_id, $options=[])

Retorna els ancestres d'un node

getNodeDescendants($tree_id, $node_id, $options=[])

Retorna els descendents d'un node

getNodeSiblings($tree_id, $node_id, $direction=null, $options=[])

Retorna els germans d'un node. Es pot especificar si volem només els següents (next) o anteriors (prev)

Classes

Els diferents mètodes de consulta retornen objectes de diferents classes. A través d'aquestes classes també podem fer crides a diferents mètodes.

Census

entity($entity_name)

Returns an entity in the census given its name

$entity=$census->entity('test')
entities()

Returns all the census entities

Entity

fields()

Returns all the entity fields

field($short_name)

Returns an entity field given its name

relatedEntity($short_name)

Returns the related entity given an entity-relation field name

forCensus($census_name)

Locates the entity in the given census. The following methods only work if this has been called previously

all($options=[])

Returns all the instances of the entity

$instances=$entity->forCensus("census_name")->all();
get($id, $options=[])

Returns an instance of the entity given its id. See instances method available options.

search($filters, $options=[])

Search instances in the entity. See search method for filter options.

tree( $short_name, $options=[])

Returns the whole instances tree in the entity given the field name that establishes the instances parenthood hyerarchy.

create( $options=[])

Creates an instance in the entity. See createInstance method

Field

settings()

Returns the field settings

options()

For select field types, returns the select options.

gridFields()

For grid field types, returns the grid fields.

relatedEntity()

For entity-relation field types, returns the related entity

Instance

entity()

Return the instance entity

census()

Return the instance census

update($fields)

Updates the instance given an array of fields. See createInstance method

get($field_name)

Gets the value of given field

set($field_name, $value)

Sets the value of given field

add($field_name, $value)

Adds a value to a given field. Useful for multiple fields and grids.

clear($field_name)

Clears (sets to null) the given field.

remove($field_name, $item_id)

Removes an item from a given field. Useful for multiple fields and grids.

delete()

Soft deletes the instance

destroy()

Destroys the instance

TreeNode

parent($options=[])

Retorna el no de pare

siblings($direction=null, $options=[])

Retorna els germams

descendants($options=[])

Retorna els descendents

ancestors($options=[])

Retorna els ancestres

children($options=[])

Retorna els fills directes

Vía Base de Dades (Eloquent )

Alternativament podem fer servir Eloquent per accedir als models del censat, sempre i quant tinguem accés a la base de dades.

Simplement cal definir els nostres models extenent el model base CensatEntityModel.

namespace App\Models;

use Ajtarragona\Censat\Models\Eloquent\CensatEntityModel;

class NomEntitat extends CensatEntityModel
{
    public $entity_name = 'nom_entitat';  // nom de la entitat
    public $census_id = 28; //id del cens (només necessari si la entitat està a més d'un cens)
    
}

Estem treballant amb models Eloquent, per la qual cosa tenim disponible tota la seva funcionalitat: QueryBuilder, Relacions, Scopes, Mutators, etc.

Documentació d'Eloquent

IMPORTANT! Per ara només és aconsellable fer servir aquest mètode per consulta. Realitzar modificacions (create, update, delete) directament podria donar generar inconsistència a les dades: no s'auditen els canvis, no s'actualitza caché...

Camps data

Si la nostra entitat té algun camp de tipus Data, podem indicar-ho aprofitant el mutator de Laravel $dates.

class Tramit extends CensatEntityModel
{
    ...
    protected $dates = [
        'data_inici',
        'data_final'
    ];
    ...

Integracions i Mapes

Els camps de tipus Integració o de tipus Mapa son objectes json internament, per la qual cosa ho podem indicar aprofitant el casting d'atributs de Laravel:

class Tramit extends CensatEntityModel
{
    ...
    protected $casts = [
        'unitat_organica' => 'object'
    ];
    ...

Relacions

Si una entitat té algun camp de Relació, ho podem indicar a partir dels atributs $simple_relations i $multiple_relations, indicant el nom del camp i el nom de la classe que modela la entitat relacionada.

class Tramit extends CensatEntityModel
{
 
    public $entity_name = 'tramit';
    
    
    protected $simple_relations = [
        'estruc_org' => '\App\Models\Tramits\UnitatOrganica'
    ];

    protected $multiple_relations = [
        'classificacio_tematica' => '\App\Models\Tramits\TematicaTramit',
        'classificacio_perfil' => '\App\Models\Tramits\Perfil'
    ];

    ...

Definint els camps de relació d'aquesta manera aquests automàticament esdevenen relacions Eloquent al model. Podem fer coses com aquestes, per exemple:

$tramit=Tramit::find(1);
$tramit->estruc_org; //aixo retorna una instància de \App\Models\Tramits\UnitatOrganica o null
$tramit->classificacio_tematica; //aixo retorna una col·lecció
$tramit->classificacio_tematica()->where('id','>',10)->orderBy('id') //aqui tenim el QueryBuilder

$tramits=Tramit::has('classificacio_tematica')->get() //retorna tramits amb alguna classsificació temàtica

Aquests exemples d'Eloquent son extensibles als camps Select i Grids que veurem tot seguit.

Selects

Si una entitat té algun camp de tipus Select, ho podem indicar a partir dels atributs $simple_selects i $multiple_selects, indicant el nom del camp i el nom de la classe que modela el select.

class Tramit extends CensatEntityModel
{
 
    public $entity_name = 'tramit';
    
    
    protected $simple_selects = [
        'tipus_instancia' => '\App\Models\Tramits\TipusSolicitud',
        'destinatari' => '\App\Models\Tramits\Destinatari'
    ];

          
    protected $multiple_selects = [
        'formes_tramitacio' => '\App\Models\Tramits\FormaTramitacio'
    ];

    ...

Aquesta classe del Select haurà d'extendre la classe CensatSelectModel, indicant el nom de la entitat i el nom del camp.

namespace App\Models\Tramits;
use Ajtarragona\Censat\Models\Eloquent\CensatSelectModel;

class TipusSolicitud extends CensatSelectModel
{
    public $entity_name="tramit";
    public $field_name="tipus_instancia";

}

Grids

Si una entitat té alguna graella, ho podem indicar a partir de l'atribut $grids, indicant el nom de la graella i el nom de la classe que la modela.

class Tramit extends CensatEntityModel
{
 
    public $entity_name = 'tramit';
    
    
    protected $grids = [
        'autors' => '\App\Models\Tramits\Autor'
    ];   
    
    ...

Aquesta classe del Grid haurà d'extendre la classe CensatGridModel, indicant el nom de la entitat i el nom de la graella.

namespace App\Models\Tramits;
use Ajtarragona\Censat\Models\Eloquent\CensatGridModel;

class Autor extends CensatGridModel
{
    public $entity_name ="tramit";
    public $grid_name ="autors";

   ...
}