gsferro / filtereasy
Forma easy e generica de fazer filtros na model
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
-
Para verificações utilizando o operador
like
ou uma verificação que force umbool
, é 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:
-
Para fazer verificação de periodos de data, usar os
sufixo
a seguir, não precisam ser usados juntos::start
:end
- Exemplos:
- Com o
:start
será implementadowhere('created_at', '>=', $value)
created_at:start
- Com o
:end
será implementadowhere('updated_at', '<=', $value)
updated_at:end
-
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"
-
Para implementar uma consulta como a do
whereBetween
, basta colocar o mesmo campo 2x, cada uma com umsufixo
- Exemplo:
deleted_at:start
deleted_at:end
- O sql gerado será assim:
where (`created_at`) >= ? and (`created_at`) <= ?
- Obs: Até a
v1.1
era utilizadowhereDate
, 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 orelationName
precisa ser um relacionamento implementando na model.- Exemplo:
posts:title relationName = posts relationField = title
- Exemplo:
- Caso queira utilizar o
like
, coloque orelationName:relationField
no$likeFilterFields
:private array $likeFilterFields = [ // demais campos "posts:title", ];
- Utilize a notação
-
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_at
e etc.
- Inicialize o atributo
-
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 dorequest
e ira setar na query com oorWhere
; - Ex: Caso tenha enviado um request assim:
client=123
, osql
gerado sera:select * from users where (name like '123%' or id = 123 or age > 123)
- Nesse caso, ele verificara o valor enviado na posição
- Inicialize o atributo
-
Para implementar uma consulta utilizando
whereNull
ouwhereNotNull
, no conceito deexists
dados na tabela, basta inicializar o atributo$nullableFilterFields
e passar o valorboolean
, sendotrue|1
parawhereNotNull
efalse|0
parawhereNull
:- Inicialize o atributo
$nullableFilterFields
:/* |--------------------------------------------------- | FilterEasy |--------------------------------------------------- */ private array $nullableFilterFields = [ // coloque os campos que serão verificados se estão null ];
- Exemplo:
updated_at=1
eremember_token=false
select * from users where updated_at is not null and remember_token is null
- Inicialize o atributo
Recursos Adicionais
- Você não precisa sanitizar os dados antes de enviar, o pacote limpa os campos que vierem em branco (
''
) enull
, mas aceita o0
como um valor válido, pois pode ser usado como um operadorboleano
- Use o
filterEasyRequest()
, comoscope
, para pegar todos os dados do request sem precisar passá-los por parâmetro. Pois ele chamara ofilterEasy
pasando a facaderequest()->all()
como parâmetro - Se você utilizar o pacote
prettus/l5-repository
ou qualquer outro paraRepository
, recomendo criar a classeFilterEasyCriteria
já implementando ofilterEasyRequest()
- 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.