elyerr/api-response

为基于Laravel框架的API提供额外功能

维护者

详细信息

gitlab.com/elyerr/api-response

源代码

问题

安装: 307

依赖关系: 1

建议者: 0

安全性: 0

星级: 0

分支: 0

v1.0.10 2024-06-11 13:18 UTC

Requires

Requires (Dev)

AGPL-3.0-only f10cb3a8a4ff34e0e3e824b7b9d476d0fb3ba051

  • Elvis Yerel Roman Concha <yerel9212.woop@yahoo.es>

This package is auto-updated.

Last update: 2024-09-11 18:48:44 UTC

README

Laravel框架下的API扩展，包括过滤、搜索、排序、分页数据，并返回JSON格式

安装稳定版

composer require elyerr/api-response

安装开发版

composer require elyerr/api-response dev-main

安装必需的

php artisan api-response:install

JsonResponser功能

默认添加到GlobalController中，因此如果您想使用它，可以继承该控制器或在每个控制器中调用trait，您可以根据喜好选择。有关HTTP状态代码的更多代码信息，请参阅此处 HTTP response status codes，默认返回代码是200

功能和用法描述

  • message(mensaje, codigo)；以JSON格式返回信息
  • 用法示例
    return $this->message('respuesta correcta')
return $this->message('recurso creado', 201)
  • data(colleccion, codigo)；以JSON格式返回集合

  • 用法示例

    return $this->data([
[id => 1, name => 'test 1'],
[id => 2, name => 'test 2']
], 200);

  • showOne(Objecto, $transformador, codigo)；以JSON格式返回对象，使用一个transformador参数，您可以点击链接了解有关laravel fractal的更多信息

  • 用法示例
  • 无transformador示例
    $user = User::find(1);

return $this->showOne($user) return $this->showOne($user, 201)

- Usando transformador: puedes leer mas abajo la sección de configuración de transformador

$user = User::find(2); return $this->showOne($user, $user->transformer) return $this->showOne($user, $user->transformer, 201)

- `showAll(colleccion, transformador, codigo)`
esta funcion permite mostrar datos de una colleccion en formato Json, esta tiene la funcionalidad de ordenar datos, paginarlos, transformarlos.
- para ordenarlos se deben pasar los parametros por url 
- order_by : recibe el nombre del campo a ordena
- order_type : recibes dos datos `desc` y `asc`, este parámetro viene siendo no obligatorios
- la paginacion se realiza de forma automática tiene valor por defecto pero también se le pueden cambiar por los que se requiera, esta valor al igual que el anterior se pasan como parámetros.
- per_page : por defecto es 15
- formas de uso sin transformador

$users = User::all(); return $this->showAll($users)

- forma de uso con transformador **Ver la sección acerca de los tranformadores**

$users = User::all(); return $this->showAll($users, UserTransformer::class, 200)

// 使用模型中的公共属性

return $this->showAll($users, $users->first()->transformer, 200)

- incorporar la funcion de busqueda en el metodo `showAll()` sin transformador

// 模型中必须存在公共属性 public $table = "users" $params = $this->filter($user->table)

// 使用参数进行搜索 $data = $this->search($user->table, $params)

// 搜索指定的用户，并获取其信息，当是一个微服务时效率更高 $data = $this->search($user->table, $params, 'user_id', '$value_user_id')

// 无参数搜索 $data = $this->search($user->table)

return $this->showAll($data)



- usando transformadores

// 模型中必须存在公共属性 public $table = "users" // 模型中必须存在transformer属性。 请参阅transformers部分 $params = $this->filter_transform($user->transformer) $data = $this->search($user->table, $params) return $this->showAll($data, $user->transformer)

- `collumns_name_table(tabla)`
obtiene todas las claves de la tabla 
- formas de uso

$nombres = $this->collumns_name_table($user->table)

- `paginate(collecccion, perPage=15)`
pagina una colleccion por defecto su valor es 15 pero puede ser cambiado por el que desee
- formas de uso

$users = User::all();

data = $this->paginate($users, 100)


- `filter_transform($transformer)`
Como parametro recibe una clase Trasnformadora, devulve todos los campos una tabla transformada o enmascarada.
- formas de uso

$params = $this->filter_transform($user->transformer);


- `filter(tabla)`, igual que la anterior pero usa el nombre de la tabla
- formas de uso

$params = $this->filter($user->table)


- `search(tabla, parametros)`, esta función realiza una búsqueda usando el operador LIKE y solo acepta como parámetros los campos de la tabla del modelo que se este empleando, esta se suele usar junto con las dos funciones anteriores permitiendo enmascarar las busquedas o simplemente mostrado los campos como esta en la base de datos
- Formas de uso

// 可以这样 $params = $this->filter_transform($user->transformer); // 或者这样 $params = $this->filter($user->table)

// 可以带参数使用 $data = $this->search($user->table, $params)

// 或者不带参数使用 $data = $this->search($user->table)


- `orderBy($colleccion)`
esta función viene integrada en la función principal `showAll`, y los parámetros, se le pasan por url, puedes ver la sección de `showAll` para entender su funcionamiento

## Funcionalidad de Timestamps
este trait puede ser impementado en un modelo para que no use transformaderes para formatear la fecha de las fechas en el formato `AÑO-MES-DIA H:I`   por ejemplo `2023-12-01 15:30`

## Funcionalidad  de Asset

- `passwordTempGenerate(len)`; genera una cadena aleatoria, por defecto es de 15
  - formas de uso
    ```
     $this->passwordTempGenerate(20);
    ```
- `generateUniqueCode($id, $includeDate, $includeLetters, $numLetters)`; genera un codigo unico.
  - formas de uso
    ```
    this->generateUniqueCode()
    this->generateUniqueCode(11001, true, true, 10)
    
    ```
- `is_diferent($old_value, $new_value, $update_is_null)`, verifica si una cadena de texto ha cambiado
  - `old_value` : valor a verificar o valor antiguo
  - `new_value` : valor nuevo que va a reemplazar el anterior
  - `update_is_null`:  por defecto es `false`, si se cambia a true, verificara si asi sea nulo el valor
  - formas de uso
    ```
    $this->is_diferent('valor_antiguo', 'valor nuevo'); //true
    $this->is_diferent('valor_antiguo', ''); //false
    $this->is_diferent('valor_antiguo', '', true); //true

    ```
- `format_date(string)`, Esta funcion se debe usar sobre datos de tipo time con su forma base en UTC, cuado se use esta funcion se debe pasar una cabecera del lado del cliente `X-LOCALTIME` con el localtime en el siguiente formato por ejemplo `"America/Denver" ` lo cual retornara un valor de la hora actual para dicho usuario en el siguiente formato `Y-m-d H:i:s`; si no se le pasa la cabecera retornará el tiempo en formato UTC
  - si esta usando js lo puedes pasar por la cabecera de la siguiente forma en las peticiones, esto capturará de forma automatica la zona del usuario para otro lenguaje puedes revisar su documentacion oficial.
    ```
    "X-LOCALTIME": Intl.DateTimeFormat().resolvedOptions().timeZone
    ```
  - forma de uso
    ```
    $this->format_date($user->created_at) 
    ```
- `verify_time_is_betweem(inicio, final)`, verifica si la fecha actual esta en un rango de fechas
  - Formas de uso
    ``` 
    $this->verify_time_is_betweem('2022-12-13', '2023-11-22')
    $this->verify_time_is_betweem('2022-12-13 12:15', '2023-12-22 23:45')
    ```
- `changeIndex(index)`, nomalmente se usa para transformar parametros del request en los transformadores, el middleware `transform.request:transformador`  debe ser agregado para los metodos store y update en el controlador en uso o bueno en las cunciones para crear o actualizar recursos
  - Formas de uso
    ```
    //formas de aplicacion del trasnformador en el controlador
    public function __construct(User $user){
        $this->middleware('transform.request:' . $user->transformer)
    }

    //ejemplo reglas en el request
    public function rules()
    { 
        return [
            'user' => ['required', 'array'],
            'user.*.name' => ['required','exists:table,id'],
            'user.*.last_name' => ['required','integer'],
        ];
    }

    //estas funcion debe ser implementada en el transformador
    public static function transformRequest($index)
    {   
        //forma de uso
        $index = Asset::changeIndex($index);

        $attribute = [
            'user' => 'user',
            'user.*.nombre' => 'user.*.name',
            'user.*.apellido' => 'user.*.last_name',
        ];
         
        return isset($attribute[$index]) ? $attribute[$index] : null;
    }

    public static function transformResponse($index)
    {
        $index = Asset::changeIndex($index);

        $attribute = [
            'user' => 'user',
            'user.*.name' => 'user.*.nombre',
            'user.*.last_name' => 'user.*.apellido',
        ];

        return isset($attribute[$index]) ? $attribute[$index] : null;
    }
    ```

- `addString($file, $index, $value, $replace = 0, $repeat = false)`, agrega un texto a un archivo en php.
  - `file`, ruta del archivo
  - `index`, posicion de la linea en el archivo don ira el texto,
  - `value`, valor que se agregara al archivo
  - `repacle`, 1 para remplazar y 0 para no remplazar
  - `repeat`, true para agregar la linea en caso exista, y false para no agregarla si ya existe,

  - formas de uso
    ```
    $file = 'ruta';

    //
    $this->addString($file, 12, "nuevo texto", 1, false)
    ```

- `fileToArray(file)`, convierte cada linea de un archivo en array
  - formas de uso
    ```
    $file = 'ruta';
    $this->fileToArray($file);
    ```
- `array_count_dimension(array)`; cuenta las dimenciones de un array
  - formas de uso
    ```
    $array = [
        [
            [
                'id' => 1,
                'name' => 'tess'
            ]
        ]
    ]
    $this->array_count_dimension($array) //3
    ```

## Uso de los Transformadores
para crear un transformador debe usarse el comando `php artisan make:transformer UserTransformer`, puedes revisar la [documentacion oficial](https://github.com/spatie/laravel-fractal).

- Esquema de los transformadores, todas esta funciones son requeridas en todos los que se implementen
    ```
    public function transform($role)
        {
            return [
                'id' => $role->id,
                'role' => $role->name,
                'descripcion' => $role->description,
            ];
        }

        public static function transformRequest($index)
        {
            $attribute = [
                'role' => 'name',
                'descripcion' => 'description',
            ];

            return isset($attribute[$index]) ? $attribute[$index] : null;
        }

        public static function transformResponse($index)
        {
            $attribute = [
                'name' => 'role',
                'description' => 'descripcion',
            ];

            return isset($attribute[$index]) ? $attribute[$index] : null;
        }

        public static function getOriginalAttributes($index)
        {
            $attributes = [
                'id' => 'id',
                'nombre' => 'name',
                'descripcion' => 'description',
            ];

            return isset($attributes[$index]) ? $attributes[$index] : null;
        }

    ```

- Aplicacion en la clase

    ```

    class User extends Auth
    {
        
        public $table = "users";


        public $transformer = UserTransformer::class;

    }   


    ```
- Aplicacion en el controlador

    ```
    public function __construct(User $user){
        $this->middleware('transform.request:' . $user->transformer)
    }

    ```