Download the PHP package ajtarragona/censat-client without Composer

Censat Client for Laravel

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

Table of Contents generated with DocToc

• Instalació
• Configuració
• Via API
  • Funcions
  • Definició de censos i entitats
    • censuses()
    • census($short_name)
    • censusEntities($short_name)
    • entities()
    • entity($short_name)
    • entityFields($short_name)
    • entityField($entity_name, $field_name)
    • entityGridFields($short_name, $grid_name)
  • Accedint a les instàncies (Crear, modificar i consultar)
    • instances($census_name, $entity_name, $options=[])
    • search($census_name, $entity_name, $filters, $options=[])
    • instancesTree($census_name, $entity_name, $field_name, $options=[])
    • instance($census_name, $entity_name, $id, $options=[])
    • getInstanceField($census_name, $entity_name, $id, $field_name)
    • createInstance($census_name, $entity_name, $fields)
    • deleteInstance($census_name, $entity_name, $id, $hard=false)
    • updateInstance($census_name, $entity_name, $id, $fields)
    • updateInstanceField($census_name, $entity_name, $id, $field_name, $value)
    • clearInstanceField($census_name, $entity_name, $id, $field_name)
    • addInstanceFieldItem($census_name, $entity_name, $id, $field_name, $value)
    • removeInstanceFieldItem($census_name, $entity_name, $id, $field_name, $item_id)
  • Graelles (Grids)
    • getInstanceGridItems($census_name, $entity_name, $id, $grid_name)
    • getInstanceGridItem($census_name, $entity_name, $id, $grid_name, $grid_item_id)
    • addInstanceGridItem($census_name, $entity_name, $id, $grid_name, $values=[])
    • updateInstanceGridItem($census_name, $entity_name, $id, $grid_name, $grid_item_id, $values=[])
    • removeInstanceGridItem($census_name, $entity_name, $id, $grid_name, $grid_item_id)
  • Entitats relacionades
    • addInstanceRelatedItem($census_name, $entity_name, $id, $field_name, $item_id)
    • removeInstanceRelatedItem($census_name, $entity_name, $id, $field_name, $item_id)
  • Attachments (documents)
    • getAttachment($attachment_id)
    • getAttachmentContent($attachment_id)
    • downloadAttachment($attachment_id)
  • Trees Feature
    • getTrees($options=[])
    • getTree($tree_id, $options=[])
    • getTreeNodes($tree_id, $options=[])
    • getNode($tree_id, $node_id, $options=[])
    • getNodeChildren($tree_id, $node_id, $options=[])
    • getNodeParent($tree_id, $node_id, $options=[])
    • getNodeAncestors($tree_id, $node_id, $options=[])
    • getNodeDescendants($tree_id, $node_id, $options=[])
    • getNodeSiblings($tree_id, $node_id, $direction=null, $options=[])
  • Classes
  • Census
    • entity($entity_name)
    • entities()
  • Entity
    • fields()
    • field($short_name)
    • relatedEntity($short_name)
    • forCensus($census_name)
    • all($options=[])
    • get($id, $options=[])
    • search($filters, $options=[])
    • tree( $short_name, $options=[])
    • create( $options=[])
  • Field
    • settings()
    • options()
    • gridFields()
    • relatedEntity()
  • Instance
    • entity()
    • census()
    • update($fields)
    • get($field_name)
    • set($field_name, $value)
    • add($field_name, $value)
    • clear($field_name)
    • remove($field_name, $item_id)
    • delete()
    • destroy()
  • TreeNode
    • parent($options=[])
    • siblings($direction=null, $options=[])
    • descendants($options=[])
    • ancestors($options=[])
    • children($options=[])
• Vía Base de Dades (Eloquent )
  • Camps data
  • Integracions i Mapes
  • Relacions
  • Selects
  • Grids

Instalació

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

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

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

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:

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

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

Vía funció helper:

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:

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

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

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:

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

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

Options:

• See instances method

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).

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

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

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.

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.

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:

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.

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

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.

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

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.

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