README

Introdução

O FilterEasy é um pacote PHP que permite aplicar filtros em consultas de banco de dados de forma fácil e eficiente. Com ele, você pode criar consultas mais complexas e personalizadas, sem precisar escrever código SQL extenso.

Instalação

Instalação:

 composer require gsferro/filtereasy

Implementação:

Na Model adicione a trait do pacote:
```
Use FilterEasy;
```
O pacote se utiliza do padrão Mass Assignment do Laravel para tratar os filtros, mas somente os campos do array $fillable são considerados, com exceção dos relacionamentos, que é explicado logo abaixo.
Por default, todos os itens são tratados com a cláusula where.
Caso seja enviado um valor contendo um array, sera utilizado owhereIn.
- Para array, coloque no name um [], exemplo:
```
permission_id[]
```

Para verificações utilizando o operador like ou uma verificação que force um bool, é necessário inicializar os seguintes atributos, respectivamente:

/*
|---------------------------------------------------
| FilterEasy
|---------------------------------------------------
*/
private array $likeFilterFields = [
    // coloque os campos para like
];

private array $boolFilterFields = [
    // coloque os campos bool
];

Busca com Datas e Hora:
1. Para fazer verificação de periodos de data, usar os sufixo a seguir, não precisam ser usados juntos:
  1. :start
  2. :end
  - Exemplos:
  - Com o :start será implementado where('created_at', '>=', $value)
    
    created_at:start
  - Com o :end será implementado where('updated_at', '<=', $value)
    
    updated_at:end
2. Para implementar no formulário de filtro (ou se for utilizar diretamente no controller), basta colocar o attr: name="created_at:start" | name="updated_at:end"
3. Para implementar uma consulta como a do whereBetween, basta colocar o mesmo campo 2x, cada uma com um sufixo
  - Exemplo:
  deleted_at:start
  
  deleted_at:end
- O sql gerado será assim:
```
where (`created_at`) >= ? and (`created_at`) <= ?  
```
1. Obs: Até a v1.1 era utilizado whereDate, porém assim não é possivel enviar também a hora, caso o campo seja um datetime.
Para Relacionamento:
- Utilize a notação relationName:relationField o pacote incluirá o relacionamento na query.
- Esta notação não precisa estar no $fillable, mas o relationName precisa ser um relacionamento implementando na model.
  - Exemplo:
```
posts:title
relationName = posts
relationField = title
```
- Caso queira utilizar o like, coloque o relationName:relationField no $likeFilterFields:
```
private array  $likeFilterFields = [
    // demais campos
    "posts:title",
];
```

Caso use $guarded ou outros campos que não estão no $fillable:

Inicialize o atributo $otherFilterFields:

/*
|---------------------------------------------------
| FilterEasy
|---------------------------------------------------
*/
private array $otherFilterFields = [
// coloque outros campos que não esteja no fillable
];

Exemplo: id, uuid, created_at , updated_at, deleted_ate etc.

Caso queria fazer um alias ou precise com um unico paramentro pesquisar em várias colunas (muito comum em apis):

Inicialize o atributo $combinedFilterFields:

Exemplo:

/*
|---------------------------------------------------
| FilterEasy
|---------------------------------------------------
*/
private array $combinedFilterFields = [
 'client' => [
    'name' => 'like',
    'id' => '=',
    'age' => '>',
  ]
];

Nesse caso, ele verificara o valor enviado na posição client dentro do request e ira setar na query com o orWhere;

Ex: Caso tenha enviado um request assim: client=123, o sql gerado sera:

 select * from users where (name like '123%' or id = 123 or age > 123)

Para implementar uma consulta utilizando whereNull ou whereNotNull, no conceito de exists dados na tabela, basta inicializar o atributo $nullableFilterFields e passar o valor boolean, sendo true|1 para whereNotNull e false|0 para whereNull:

Inicialize o atributo $nullableFilterFields:

/*
|---------------------------------------------------
| FilterEasy
|---------------------------------------------------
*/
private array $nullableFilterFields = [
// coloque os campos que serão verificados se estão null
];

Exemplo: updated_at=1 e remember_token=false

select * from users where updated_at is not null and remember_token is null

Recursos Adicionais

Você não precisa sanitizar os dados antes de enviar, o pacote limpa os campos que vierem em branco ('') e null, mas aceita o 0 como um valor válido, pois pode ser usado como um operador boleano
Use o filterEasyRequest(), como scope, para pegar todos os dados do request sem precisar passá-los por parâmetro. Pois ele chamara o filterEasy pasando a facade request()->all() como parâmetro

Se você utilizar o pacote prettus/l5-repository ou qualquer outro para Repository, recomendo criar a classe FilterEasyCriteria já implementando o filterEasyRequest()

Implementando assim:

<?php

namespace App\Criteria;

use Prettus\Repository\Contracts\CriteriaInterface;
use Prettus\Repository\Contracts\RepositoryInterface;

class FilterEasyCriteria implements CriteriaInterface
{
    /**
     * Apply criteria in query repository
     *
     * @param  string  $model
     * @return mixed
     */
    public function apply($model, RepositoryInterface $repository)
    {
        return $model->filterEasyRequest();
    }
}

E para usar, bastando simplesmente:

 public function index(): View
 {
     // set filtereasy
     $this->repository->pushCriteria(new FilterEasyCriteria);

     return view('index', [
         'model' => $this->repository,
     ]);
 }

Solução de Problemas

Se você encontrar algum problema ao usar o FilterEasy, verifique se:

A consulta de banco de dados está correta.
Os filtros estão a ser aplicados corretamente.
A versão do pacote está atualizada.
Recursos Adicionais
Se você inicializou os atributos na model
Se você tiver um novo campo no model que não estiver listado
Se você tiver um relacionamento que não estiver implementado na model

Contribuição

Se você deseja contribuir com o FilterEasy, por favor, siga as seguintes etapas:

Faça um fork do repositório.
Crie uma branch para sua contribuição.
Faça as alterações necessárias.
Envie um pull request.

License

O FilterEasy é licenciado sob a licença MIT. Leia o arquivo LICENSE para mais informações.

gsferro / filtereasy

Maintainers

Details