> ## Documentation Index
> Fetch the complete documentation index at: https://docs-fw.madbuilder.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# 08. Carregamento estático de coleções

O carregamento estático de coleções é uma ferramenta poderosa oferecida pelo Adianti Framework. Com ela é possível definir as colunas selecionadas, filtrar o carregamento de objetos e ainda paginar os resultados.

## 8.1. Como definir as colunas de uma consulta no banco de dados?

É possível chamar uma função estática chamada `select()` em uma Active Record para definir as colunas que serão carregadas no comando SQL gerado pelo framework. A função `select()` recebe como parâmetro uma ou mais “strings” que serão usadas para selecionar as colunas.

E para que o Adianti Framework carregue os dados, é necessário chamar a função `load()`.

Exemplos funcionais seriam: carregar apenas nomes diferentes da tabela de funcionários e carregar nome e idade dos funcionários:

```php theme={null}
    try
    {
        TTransaction::open('exemplos');

        $funcionarios_nomes = Funcionario::select('distinct nome')->load();

        $funcionarios_nomes_idades = Funcionario::select('nome', 'idade')->load();

        TTransaction::close();
    }
    catch (Exception $e)
    {
        TTransaction::rollback();
        new TMessage('error', $e->getMessage());
    }
```

O primeiro comando SQL gerado foi:

```sql theme={null}
    SELECT 
        distinct nome 
    FROM 
        funcionario
```

O segundo comando SQL gerado foi:

```sql theme={null}
    SELECT 
        nome, idade 
    FROM funcionario
```

## 8.2. Como adicionar filtros no carregamento estático?

Da mesma maneira que a função `select()` existe para definir as colunas a serem selecionadas, existe a função `where()`, para criar filtros de carregamento de coleções. O uso mais simples da função `where()` usa três parâmetros:

```php theme={null}
    Model::where($variavel, $operador, $valor);
```

Para carregar os registros depois de adicionar o filtro, é necessário chamar a função `load()`.

No exemplo abaixo, foi feito o carregamento apenas de funcionários acima de 18 anos:

```php theme={null}
    try
    {
        TTransaction::open('exemplos');

        $funcionarios_nomes = Funcionario::where('idade', '>', 18)->load();

        TTransaction::close();
    }
    catch (Exception $e)
    {
        TTransaction::rollback();
        new TMessage('error', $e->getMessage());
    }
```

O comando SQL gerado foi:

```sql theme={null}
    SELECT 
        nome, sobrenome, dt_nascimento, funcao_id, cidade_id, endereco, cep, id 
    FROM 
        funcionario 
    WHERE 
        (idade > 18)
```

## 8.3. Como adicionar mais de um filtro?

Ao usar o carregamento estático de coleções, é possível adicionar N filtros. Para isso, basta chamar mais vezes a função `where()`. Veja o exemplo a seguir, em que serão carregados todos os funcionários que:

1. Tenham mais de 18 anos;
2. O nome comece com a letra A;
3. Tenham o CEP igual a 95900-000.

O código-fonte:

```php theme={null}
    try
    {
        TTransaction::open('exemplos');

        $funcionarios_nomes = Funcionario::where('idade', '>', 18)
                                         ->where('nome', 'like', 'A%')
                                         ->where('cep', '=', '95900000')
                                         ->load();


        TTransaction::close();
    }
    catch (Exception $e)
    {
        TTransaction::rollback();
        new TMessage('error', $e->getMessage());
    }
```

O comando SQL gerado foi:

```sql theme={null}
    SELECT 
        nome,
        sobrenome,
        dt_nascimento,
        funcao_id,
        cidade_id,
        endereco,
        cep,
        id
    FROM 
        funcionario
    WHERE 
        (idade > 18
        AND nome like 'A%' 
        AND cep = '95900000')
```

> Atenção: sempre que mais de um filtro `where` for usado, somente o primeiro deve ser chamado com os caracteres `::`. Os seguintes devem ser chamados com os caracteres `->`.

## 8.4. Como definir colunas e filtros em um carregamento?

É possível combinar as funções `select()` e `where()` para carregar apenas as informações desejadas seguindo as regras da aplicação. Para isso, basta empilhar as funções da mesma maneira que quando é usado mais que um filtro.

No exemplo abaixo, serão carregados apenas os nomes dos funcionários abaixo de 18 anos cujo nome começa com a letra A:

```php theme={null}
    try
    {
        TTransaction::open('exemplos');

        $funcionarios_nomes = Funcionario::select('nome')
                                         ->where('nome', 'like', 'A%')
                                         ->where('idade', '<', 18)
                                         ->load();


        TTransaction::close();
    }
    catch (Exception $e)
    {
        TTransaction::rollback();
        new TMessage('error', $e->getMessage());
}
```

O comando SQL gerado foi:

```sql theme={null}
    SELECT 
        nome 
    FROM 
        funcionario 
    WHERE 
        (nome like 'A%' AND idade < 18)
```

## 8.5. Como carregar os registros paginados?

Ainda no carregamento estático, é possível definir algumas propriedades, como ordenação, quantidade e paginação dos registros.

No exemplo abaixo, iremos carregar todos os funcionários com 25 anos de idade ou mais ordenados em ordem decrescente pelo ID pegando 10 registros após pular 20 (paginação).

```php theme={null}
    try
    {
        TTransaction::open('exemplos');

        $funcionarios = Funcionario::select('id, nome')
                                   ->where('idade', '>=', 25)
                                   ->orderBy('id', 'desc')
                                   ->take(10)
                                   ->skip(20)
                                   ->load();

        TTransaction::close();
    }
    catch (Exception $e)
    {
        TTransaction::rollback();
        new TMessage('error', $e->getMessage());
    }
```

O comando SQL gerado foi:

```php theme={null}
    SELECT 
        id, nome 
    FROM 
        funcionario 
    WHERE 
        (idade >= 25) 
    ORDER BY id desc 
    LIMIT 10 
    OFFSET 20
```

## 8.6. Como usar o operador OU em carregamentos estáticos?

Nos exemplos anteriores, todos os critérios de filtros eram adicionados com o operador `E (and)`, pois esse é o comportamento padrão do carregamento estático.

Mas o que fazer quando o desenvolvedor deseja utilizar outro critério?

Para alterar o comportamento padrão do carregamento estático de coleções, precisaremos alterar o quarto parâmetro da função `where()`. Quando não definido, esse parâmetro recebe o valor do operador `E`. O exemplo abaixo mostra como definir o operador `OU`.

```php theme={null}
    try
    {
        TTransaction::open('exemplos');

        $funcionarios = Funcionario::select('nome')
                                   ->where('idade', '>', 25, TExpression::OR_OPERATOR)
                                   ->where('idade', '=', 22, TExpression::OR_OPERATOR)
                                   ->load();

        TTransaction::close();
    }
    catch (Exception $e)
    {
        TTransaction::rollback();
        new TMessage('error', $e->getMessage());
    }
```

O comando SQL gerado foi:

```sql theme={null}
    SELECT 
        nome 
    FROM 
        funcionario 
    WHERE 
        (idade > 25 OR idade = 22)
```