README

Visão Geral

O LazyAPI é um package Laravel que facilita a criação de APIs CRUD (Create, Read, Update, Delete) de forma rápida e padronizada. Ele fornece uma estrutura base que automatiza operações comuns de API, incluindo filtragem avançada, paginação, ordenação e exportação para Excel.

Estrutura do Package

Arquivos Principais

LazyApiRoutes.php - Gerador de rotas CRUD básicas
LazyApiControllerTrait.php - Trait com métodos padrão para controllers
LazyApiService.php - Camada de serviço com lógica de negócio
LazyApiRepository.php - Camada de acesso a dados
LazyApiHttp.php - Respostas HTTP padronizadas
LazyApiFile.php - Utilitários para manipulação de arquivos
Excel.php - Exportação de dados para CSV
LazyApiServiceProvider.php - Service Provider do package

Como Usar

1. Configuração de Rotas

use maurienejunior\lazyapi\LazyApiRoutes;

// No arquivo de rotas (api.php ou web.php)
LazyApiRoutes::basicApiWithPrefix('users', UserController::class);

Esta linha criará automaticamente as seguintes rotas:

GET /users - Listar todos os usuários
GET /users/{id} - Buscar usuário por ID
POST /users - Criar novo usuário
POST /users/update - Atualizar usuário (método POST)
PUT /users - Atualizar usuário (método PUT)
DELETE /users/{id} - Deletar usuário

2. Controller

use maurienejunior\lazyapi\LazyApiControllerTrait;

class UserController extends Controller
{
    use LazyApiControllerTrait;
    
    public function __construct(UserService $service)
    {
        parent::__construct($service);
    }
}

3. Service

use maurienejunior\lazyapi\LazyApiService;

class UserService extends LazyApiService
{
    public function __construct(UserRepository $repository)
    {
        parent::__construct($repository);
    }
    
    // Métodos de validação e hooks personalizados
    public function validate($item)
    {
        // Implementar validações customizadas
        return null; // ou retornar mensagem de erro
    }
    
    public function modifyItensBeforeSave($item)
    {
        // Modificar dados antes de salvar
        return $item;
    }
    
    public function afterSave($obj, $item)
    {
        // Ações após salvar
    }
}

4. Repository

use maurienejunior\lazyapi\LazyApiRepository;
use App\Models\User;

class UserRepository extends LazyApiRepository
{
    protected $model = User::class;
    protected $primaryKey = 'id';
    protected $paginate = true;
    
    protected $fieldsToSearch = [
        ['field' => 'name', 'size' => 50],
        ['field' => 'email', 'size' => 100]
    ];
    
    protected $fieldsToExport = [
        'id' => 'ID',
        'name' => 'Nome',
        'email' => 'E-mail',
        'created_at' => 'Data de Criação'
    ];
    
    protected $relationships = ['profile', 'posts'];
}

Funcionalidades Avançadas

Filtragem de Dados

O LazyAPI suporta filtragem avançada através de parâmetros de query:

Operadores Básicos

GET /users?name=ilike|João
GET /users?age=>|18
GET /users?created_at=between|2023-01-01|2023-12-31
GET /users?status=whereIn|active,pending

Operadores Suportados

= - Igual
> - Maior que
< - Menor que
>= - Maior ou igual
<= - Menor ou igual
<> - Diferente
ilike - Busca parcial (case insensitive)
between - Entre valores
whereIn - Dentro de uma lista

Filtragem por Relacionamentos

GET /users?profile|name=ilike|João
GET /posts?user|email=ilike|@gmail.com

Busca Geral

GET /users?search=João

Filtros OR

GET /users?name||email=ilike|João

Ordenação

GET /users?orderByAsc=name
GET /users?orderByDesc=created_at
GET /users?orderByAsc=profile|name  // Ordenar por relacionamento

Paginação

GET /users?paginate=true&registerByPage=20

Seleção de Campos

GET /users?select=id,name,email

Relacionamentos

GET /users?withThisRelationships=profile,posts
GET /users?withoutThisRelationships=posts

Limitação de Resultados

GET /users?limit=10

Contagem

GET /users?count=true

Exportação para Excel

GET /users/excel

Respostas HTTP Padronizadas

O LazyApiHttp fornece respostas consistentes:

200 OK - Operação bem-sucedida
201 Created - Recurso criado
403 Forbidden - Erro de validação
404 Not Found - Recurso não encontrado
500 Internal Server Error - Erro interno

Formato das Respostas

// Sucesso
{
    "data": {...},
    "status": 200
}

// Erro
{
    "message": "Mensagem de erro",
    "devMsg": "Detalhes técnicos (apenas em desenvolvimento)"
}

Hooks Disponíveis

O LazyApiService oferece vários hooks para customização:

validate($item) - Validação antes de salvar/atualizar
modifyItensBeforeSave($item) - Modificar dados antes de salvar
modifyItensBeforeUpdate($item) - Modificar dados antes de atualizar
afterSave($obj, $item) - Ações após salvar
afterUpdate($obj, $item) - Ações após atualizar
beforeUpdate($item) - Ações antes de atualizar
beforeDelete($id) - Ações antes de deletar
modifyBeforeExport($data) - Modificar dados antes de exportar
modifyData($data) - Modificar query antes de executar

Instalação

Registre o ServiceProvider no config/app.php:

'providers' => [
    // ...
    maurienejunior\lazyapi\LazyApiServiceProvider::class,
],

Exemplo Completo

Model

class User extends Model
{
    protected $fillable = ['name', 'email', 'password'];
    
    public function profile()
    {
        return $this->hasOne(Profile::class);
    }
}

Repository

class UserRepository extends LazyApiRepository
{
    protected $model = User::class;
    protected $fieldsToSearch = [
        ['field' => 'name', 'size' => 100],
        ['field' => 'email', 'size' => 100]
    ];
    protected $fieldsToExport = [
        'id' => 'ID',
        'name' => 'Nome',
        'email' => 'E-mail'
    ];
}

Service

class UserService extends LazyApiService
{
    public function validate($item)
    {
        if (empty($item['name'])) {
            return 'Nome é obrigatório';
        }
        return null;
    }
}

Controller

class UserController extends Controller
{
    use LazyApiControllerTrait;
    
    public function __construct(UserService $service)
    {
        parent::__construct($service);
    }
}

Rotas

LazyApiRoutes::basicApiWithPrefix('users', UserController::class);

Com essa configuração, você terá uma API completa para gerenciar usuários com todas as funcionalidades do LazyAPI.

Vantagens

Rapidez no desenvolvimento - Reduz drasticamente o tempo de criação de APIs CRUD
Padronização - Mantém consistência entre diferentes endpoints
Flexibilidade - Permite customização através de hooks
Filtragem avançada - Sistema robusto de filtros e busca
Exportação - Funcionalidade built-in para exportar dados
Manutenibilidade - Código organizado em camadas bem definidas

Considerações

O package é específico para Laravel
Requer conhecimento básico de padrões Repository e Service
Ideal para APIs que seguem padrões CRUD convencionais
Pode necessitar customização para casos de uso muito específicos

maurienejunior / lazy-api

Maintainers

Details