PHPackages                             power-vending/laravel-api-query-builder - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [API Development](/categories/api)
4. /
5. power-vending/laravel-api-query-builder

ActiveLibrary[API Development](/categories/api)

power-vending/laravel-api-query-builder
=======================================

Laravel API query builder - forked and customized from nealarec/laravel-json-query-builder

0.0.6(3w ago)1176MITPHP ^8.0

Since May 13Compare

[ Source](https://github.com/power-vending/laravel-api-query-builder)[ Packagist](https://packagist.org/packages/power-vending/laravel-api-query-builder)[ RSS](/packages/power-vending-laravel-api-query-builder/feed)WikiDiscussions Synced 3w ago

READMEChangelog (2)Dependencies (12)Versions (8)Used By (0)

Laravel JSON Query Builder
==========================

[](#laravel-json-query-builder)

Índice
------

[](#índice)

1. [O que é este pacote](#o-que-%C3%A9-este-pacote)
2. [Como funciona](#como-funciona)
3. [Requisitos do sistema](#requisitos-do-sistema)
4. [Instalação](#instala%C3%A7%C3%A3o)
5. [Configuração inicial](#configura%C3%A7%C3%A3o-inicial)
6. [Rota de schema](#rota-de-schema)
7. [Operadores de busca](#operadores-de-busca)
8. [Uso básico](#uso-b%C3%A1sico)
9. [Parâmetros disponíveis](#par%C3%A2metros-dispon%C3%ADveis)
10. [Trabalhando com relacionamentos](#trabalhando-com-relacionamentos)
11. [Exemplos práticos completos](#exemplos-pr%C3%A1ticos-completos)
12. [Customizações avançadas](#customiza%C3%A7%C3%B5es-avan%C3%A7adas)
13. [Erros retornados pela API](#erros-retornados-pela-api)
14. [Solução de problemas](#solu%C3%A7%C3%A3o-de-problemas)
15. [Testes](#testes)
16. [Créditos e licença](#cr%C3%A9ditos-e-licen%C3%A7a)

---

O que é este pacote
-------------------

[](#o-que-é-este-pacote)

Este pacote Laravel permite que você construa consultas (queries) dinâmicas no banco de dados usando parâmetros JSON através de requisições HTTP. Em vez de criar manualmente cada filtro, ordenação e paginação em seus controllers, este pacote processa automaticamente os parâmetros enviados pelo frontend.

### Para que serve

[](#para-que-serve)

Imagine que você tem uma API REST que retorna uma lista de produtos. Sem este pacote, você precisaria criar código para cada tipo de filtro possível:

```
// Sem o pacote - você precisa tratar cada caso manualmente
if ($request->has('name')) {
    $query->where('name', 'like', '%' . $request->name . '%');
}
if ($request->has('min_price')) {
    $query->where('price', '>=', $request->min_price);
}
if ($request->has('category')) {
    $query->where('category_id', $request->category);
}
```

Com este pacote, o frontend envia um JSON estruturado e tudo é processado automaticamente:

```
// Com o pacote - uma linha resolve tudo
return Product::query()->requestPaginate();
```

### Origem

[](#origem)

Este pacote foi originalmente desenvolvido por Neal Arec (nealarec/laravel-api-query-builder) e foi internalizado pela Power Vending para permitir customizações específicas e manutenção independente nos projetos internos da empresa.

---

Como funciona
-------------

[](#como-funciona)

O pacote funciona interpretando parâmetros JSON enviados via query string (GET) ou body (POST) de requisições HTTP e transformando-os em queries Eloquent do Laravel.

### Fluxo de funcionamento

[](#fluxo-de-funcionamento)

1. O frontend faz uma requisição HTTP com parâmetros JSON
2. O pacote intercepta esses parâmetros
3. Valida e processa cada parâmetro (filtros, ordenação, paginação, etc)
4. Constrói a query Eloquent correspondente
5. Retorna os dados de acordo com as especificações

### Exemplo visual

[](#exemplo-visual)

```
Frontend envia:
GET /api/products?search={"name":"LIKE:Notebook","price":"GT:1000"}&order_by={"price":"asc"}

Pacote transforma em:
SELECT * FROM products
WHERE name LIKE '%Notebook%'
  AND price > 1000
ORDER BY price ASC

Retorna:
{
  "data": [...],
  "current_page": 1,
  "total": 42
}

```

---

Requisitos do sistema
---------------------

[](#requisitos-do-sistema)

Para usar este pacote, você precisa ter as seguintes versões instaladas:

### PHP

[](#php)

- Versão 8.0 ou superior
- Extensões necessárias: PDO, Mbstring

### Laravel

[](#laravel)

O pacote é compatível com múltiplas versões do Laravel:

- Laravel 8.x
- Laravel 9.x
- Laravel 10.x
- Laravel 11.x
- Laravel 12.x

### Doctrine DBAL

[](#doctrine-dbal)

- Versão 3.0 ou superior
- Versão 4.0 também suportada

O Doctrine DBAL é necessário para algumas operações de análise de schema do banco de dados.

### Composer

[](#composer)

Necessário para gerenciar as dependências do PHP.

---

Instalação
----------

[](#instalação)

### Instalação via Composer

[](#instalação-via-composer)

Instale o pacote usando o Composer:

```
composer require power-vending/api-query-builder
```

O pacote será instalado automaticamente e o Laravel irá registrar o service provider.

---

Configuração inicial
--------------------

[](#configuração-inicial)

### Passo 1: Publicar arquivos de configuração

[](#passo-1-publicar-arquivos-de-configuração)

Publique o arquivo de configuração do pacote para o seu projeto:

```
php artisan vendor:publish --tag=api-query-builder-config
```

Este comando irá criar o arquivo `config/api-query-builder.php` no diretório de configurações do seu projeto.

### Passo 2: Entender o arquivo de configuração

[](#passo-2-entender-o-arquivo-de-configuração)

Abra o arquivo `config/api-query-builder.php`. Você verá algo parecido com:

```
return [
    // Operadores de busca disponíveis
    'operators' => [
        // Lista de classes de operadores
    ],

    // Colunas que nunca podem ser acessadas via query
    'global_forbidden_columns' => [
        'password',
        'remember_token',
    ],

    // Outras configurações...
];
```

### Passo 3: Adicionar a trait ao Model

[](#passo-3-adicionar-a-trait-ao-model)

Para que um Model aceite os parâmetros do pacote, adicione a trait `ApiQueryBuilder`:

```