ajtarragona/censat-client

CENSAT 应用程序的 Rest API 客户端

维护者

详细信息

github.com/ajtarragona/censat-client

源代码

问题

安装: 593

依赖项: 0

建议者: 0

安全: 0

星标: 0

关注者: 0

分支: 0

开放问题: 0

v2.1.21 2024-09-16 07:50 UTC

Requires

MIT 09bbf7555b83784cb74bc144bb2d466ba73a7fc6

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

laravellaravel5

This package is auto-updated.

Last update: 2024-09-16 07:51:07 UTC

README

CENSAT 应用程序的 Tarragona 市政 Rest API 客户端

目录 由 DocToc 生成

安装

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

配置

您可以通过应用程序的 .env 文件配置此包。以下是一些可用参数

通过 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

定义一个令牌后，将用于所有请求。如果没有定义，将根据每个请求的用户名和密码创建一个新的令牌。因为将有半数请求使用令牌，所以建议定义一个令牌。Censat通过其Api的Login方法生成一个有效期为一年的令牌。

通过数据库访问

CENSAT_DB_HOST
CENSAT_DB_PORT
CENSAT_DB_DATABASE
CENSAT_DB_USERNAME
CENSAT_DB_PASSWORD

或者，你可以使用以下命令发布包的配置文件：

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

这将把文件复制到censat-api.php和censat-database.php到config目录。

通过 API

配置完成后，包就准备好使用了。你可以以下方式使用它：

通过Facade

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

对于Laravel < 5.6，需要在config/app.php文件中注册Facade别名

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

依赖注入：在你的控制器、辅助器、模型中

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

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

通过helper函数

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

功能

定义普查和实体

censuses()

返回所有普查。类Census的对象

census($short_name)

返回给定名称的普查。

censusEntities($short_name)

返回给定名称的普查实体。类Entity的对象

entities()

返回所有实体。

entity($short_name)

返回给定名称的实体。

entityFields($short_name)

返回给定名称的实体字段。类Field的对象

entityField($entity_name, $field_name)

返回给定名称和字段名称的单个实体字段。

entityGridFields($short_name, $grid_name)

返回实体网格的字段，给定实体名称和网格名称。

访问实例（创建、修改和查询）

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

返回给定普查和实体的所有实例。类Instance的对象

选项
  • fields：要返回的字段名称，以逗号分隔。有关更多信息，请参阅fields部分。
  • parsevalues：如果设置为true，将返回所有对象和数组值作为字符串。
  • separator：如果parsevalues设置为true，多个字段将作为以逗号分隔的字符串返回。使用此选项，您可以设置不同的分隔符字符/。
  • exclude：要返回的字段名称，以逗号分隔。
  • sort：要排序的字段名称。
  • direction：排序方向（升序或降序）。
  • paginate：如果设置为true，则分页（默认为false）。
  • page：页码。
  • pagesize：页面大小（默认为10）。

字段

我们可以通过逗号分隔的字段名称列表指定我们希望返回哪些字段。

我们有别名basefields，它将返回基础字段（id，日期，版本...）

但是，我们还可以通过点符号导航数据模型。例如，如果我们想返回一个关联字段的id，我们可以这样做：

nom_camp_relacio.id

对于网格或多个字段（关系、集成、选择），我们有特殊的访问器

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

而且，所有的都可以连接在一起

nom_camp.0.nom_grid.1.camp_usuari.username

格式化器：在每个字段上，我们可以通过|字符应用格式化器。这些将应用于返回值。例如，我们可以让返回的文本值变成大写

nom_camp|upper

可以连接多个格式化器，它们将按顺序应用。

nom_camp|upper|lower

以下是可用的格式化器：

  • upper：转换为大写

  • lower：转换为小写

  • serialize：序列化

  • csv(delimiter?;enclosure?)：转换为csv，如果返回的是数组（可选地，我们可以定义分隔符和用于括号文本的字符）

  • json：转换为json

  • array：如果原本是对象，则转换为数组

  • object：如果原本是数组，则转换为对象

  • matricula/format/string(format?)：这三个做的是一样的事情。显示字段返回的文本版本。

  • pad(num;char?;position?)：在数字前填充零（可以指定零的数量，可选地指定要添加的字符，如果不希望是零，以及位置：（0：左侧，1：右侧，2：两侧））

  • count：如果返回数组，则返回元素数量

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

在给定的普查和实体中搜索实例。

过滤器

必须是一个过滤器数组或过滤器组：过滤器必须是一个包含以下属性的键值数组

  • id：要过滤的字段名称
  • value：字段值
  • operation：逻辑操作（=，!=，<，>，<=，>=，contains，starts_with，ends_with，in，not in，isnull，isnotnull）(默认=)

过滤器组必须是一个包含以下属性的键值数组

  • concat：和/或
  • filters：过滤器或过滤器组的数组
[
    ["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"]
    ]]
]
选项
instancesTree($census_name, $entity_name, $field_name, $options=[])

根据普查名称、实体名称和建立实例父子层次结构的字段名称，返回整个实例树。

选项
  • parent_id：以该根实例开始树的ID（默认为null）
  • sort：要排序的字段名称。
  • direction：排序方向（升序或降序）。
  • filters：参见search方法
instance($census_name, $entity_name, $id, $options=[])

根据普查名称、实体名称和实例ID返回单个实例。

选项
  • fields：以逗号分隔的字段名称，将返回。别名"basefields"将返回id、版本和日期。
  • parsevalues：如果设置为true，将返回所有对象和数组值作为字符串。
  • exclude：要返回的字段名称，以逗号分隔。
getInstanceField($census_name, $entity_name, $id, $field_name)

根据普查、实体、实例ID和字段名称获取实例字段。

createInstance($census_name, $entity_name, $fields)

在给定的普查和实体中创建实例。返回创建的实例或异常。

  • 字段必须是一个键值数组，包含字段名称及其值。
  • 对于多值，如选择、关系、文档或表格，使用数组。
  • 选择和关系字段期望的是相关值的ID。
  • 文档类型字段期望一个包含'file-name'和'file-content'（二进制内容）的数组。
  • 集成字段（如LDAP用户和UOs）期望集成的主键（示例中的用户名和代码）。
    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)

根据普查、实体和实例ID删除实例。默认为软删除。可以通过将参数hard设置为true来强制进行硬删除。返回true或异常。

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

根据普查、实体和实例ID更新实例。字段必须是一个包含字段名称及其值的键值数组。返回更新的实例或异常。

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

更新实例的单个字段。返回更新的实例或异常。

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

清除（设置为null）实例字段。返回更新的实例或异常。

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

向实例字段添加项目，给定其值。对于多个字段（关系、选择、集成或表格）很有用。返回更新的实例或异常。

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

根据ID删除实例字段项目。对于多个字段（关系、选择、集成或表格）很有用。返回更新的实例或异常。

网格（Graelles）

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

返回实例网格的项目。

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

根据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)

根据ID删除实例网格项目。返回更新的实例或异常。

相关实体

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

向实例关系字段添加项目，给定其ID。返回更新的实例或异常。

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

从实例关系字段中删除项目，给定其ID。返回更新的实例或异常。

附件（文档）

getAttachment($attachment_id)

根据Censat ID返回附件信息。

getAttachmentContent($attachment_id)

根据Censat ID返回附件内容（以base64编码）。

downloadAttachment($attachment_id)

下载（通过响应流文件）根据Censat ID的附件。

树功能

getTrees($options=[])

返回所有树。

getTree($tree_id, $options=[])

通过其ID或short_name返回树。

getTreeNodes($tree_id, $options=[])

返回树的节点。

选项
  • parent_id : 如果指定，则从该根节点返回节点。
  • with_instance : 返回该节点的实例的更多数据。
  • hyerarchical : 以层次结构返回节点（默认为true）。
  • depth : 深度级别（如果没有指定，则返回所有级别）。
  • term : 搜索词，用于过滤节点（如果指定，则返回无层次结构的节点）。
  • instance_id : 返回实例ID为指定值的节点。
  • entity_id : 返回实体ID为指定值的节点。
  • census_id : 返回普查ID为指定值的节点。
getNode($tree_id, $node_id, $options=[])

通过传递其ID返回树中的一个节点。

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=[])

返回一个节点的兄弟节点。可以指定是下一个（next）还是上一个（prev）。

类

不同的查询方法返回不同类的对象。通过这些类，我们也可以调用不同的方法。

普查

entity($entity_name)

根据其名称返回普查中的实体。

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

返回所有普查实体。

实体

fields()

返回所有实体字段。

field($short_name)

根据其名称返回实体字段。

relatedEntity($short_name)

根据实体-关系字段名称返回相关实体。

forCensus($census_name)

在给定的普查中定位实体。以下方法只有在之前调用过此方法后才会生效。

all($options=[])

返回实体的所有实例。

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

根据其实例ID返回实体实例。请参阅instances方法的可用选项。

search($filters, $options=[])

在实体中搜索实例。请参阅search方法以获取筛选选项。

tree( $short_name, $options=[])

根据建立实例亲缘关系层次结构的字段名称，返回实体中整个实例树。

create( $options=[])

在实体中创建实例。请参阅createInstance方法。

字段

settings()

返回字段设置。

options()

对于选择字段类型，返回选择选项。

gridFields()

对于网格字段类型，返回网格字段。

relatedEntity()

对于实体-关系字段类型，返回相关实体。

实例

entity()

返回实例实体。

census()

返回实例普查。

update($fields)

根据一组字段更新实例。请参阅createInstance方法。

get($field_name)

获取指定字段的值。

set($field_name, $value)

设置指定字段的值。

add($field_name, $value)

向指定字段添加值。对于多个字段和网格非常有用。

clear($field_name)

清除（设置为null）指定字段。

remove($field_name, $item_id)

从指定字段中删除项目。对于多个字段和网格非常有用。

delete()

软删除实例。

destroy()

销毁实例。

TreeNode

parent($options=[])

返回父节点编号。

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

返回兄弟节点。

descendants($options=[])

返回后代节点。

ancestors($options=[])

返回祖先节点。

children($options=[])

返回直接子节点。

通过数据库（Eloquent ）

作为备选，我们可以使用Eloquent来访问普查模型，前提是我们有数据库访问权限。

只需定义我们的模型扩展基本模型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)
    
}

我们正在使用Eloquent模型，因此我们可以使用其全部功能：QueryBuilder、关系、Scopes、Mutators等。

Eloquent文档

重要！目前建议仅使用此方法进行查询。直接执行修改（创建、更新、删除）可能会生成数据不一致：更改未经审计，缓存未更新...

数据字段

如果我们的实体有某种类型的数据字段，我们可以利用Laravel的$dates mutator来指出。

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

集成和地图

类型为集成或类型为地图的字段内部是json对象，因此我们可以利用Laravel的属性铸造来指出。

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

关系

如果一个实体有任何类型的关系字段，我们可以通过$simple_relations和$multiple_relations属性来指定，指明字段名称和表示相关实体的类的名称。

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'
    ];

    ...

以这种方式定义关系字段，它们将自动成为Eloquent模型中的关系。我们可以进行如下操作，例如

$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

以下Eloquent示例可以扩展到我们接下来将要看到的Select和Grid字段。

选择

如果一个实体有任何类型的Select字段，我们可以通过$simple_selects和$multiple_selects属性来指定，指明字段名称和表示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'
    ];

    ...

Select类必须扩展CensatSelectModel类，指明实体名称和字段名称。

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

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

}

网格

如果一个实体有任何类型的网格，我们可以通过$grids属性来指定，指明网格名称和表示网格的类的名称。

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

Grid类必须扩展CensatGridModel类，指明实体名称和网格名称。

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

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

   ...
}