5. Configurando o API Controller

​

Chave Primária ($primaryKey)

// Em: app/controller/MinhaController.php

class MinhaController extends ApiResourceController
{
    ...

    // Informando que a chave primária é 'codigo'
    protected $primaryKey = 'codigo'; 
}

​

Personalizando a Resposta JSON

​

Paginação ($perPage)

Observação: como já foi mencionado anteriormente, para exibir uma página específica, basta enviar o parâmetro page na URL. Ex.: http://localhost/api/exibir-registros?page=3.

// Em: app/controller/MinhaController.php

protected $perPage = 50; // Agora, a listagem retornará 50 itens por página

Nota: Internamente, o método addPagination() é chamado durante a listagem para ler o parâmetro page da URL e aplicar os limites (LIMIT, OFFSET) à consulta, utilizando o valor de $perPage.

​

Selecionando e Renomeando Campos

• $indexFields: Campos que aparecerão na rota de listagem.
• $showFields: Campos que aparecerão na rota de detalhe de um item.

// Em: app/controller/ApiPedidovendaController.php

class ApiPedidovendaController extends ApiResourceController
{
    ...

    // Campos para a rota de listagem (GET /api/pedido-venda)
    protected $indexFields = [
        'cliente_nome' => 'Cliente: {cliente->nome}',
        'valor_total' => 'Valor Total: {valor_total}'
    ];

    // Campos para a rota de detalhe (GET /api/pedido-venda/{id})
    protected $showFields = [
        'cliente_nome' => 'Cliente: {cliente->nome}',
        'valor_total' => 'Valor Total: {valor_total}'
    ];
}

​

Ocultando Campos ($hiddenFields)

// Oculta os campos de timestamp da resposta

protected $hiddenFields = ['created_at', 'updated_at', 'deleted_at'];

​

Habilitando Ordenação e Filtros

class ApiPedidovendaController extends ApiResourceController
{
    ...

    protected $sortable = ['valor_total'];
    protected $filterable = ['valor_total', 'dt_pedido'];
}

• Para Ordenar (sort):
  • GET /api/pedido-venda?sort=valor_total (ordem ascendente - padrão)
  • GET /api/pedido-venda?sort=valor_total&direction=desc (ordem decrescente)
• Para Filtrar (filter):
  • GET /api/pedido-venda?filters[valor_total][gte]=50000

Observação: caso o valor inserido não tenha sido definido como filterable, ele será ignorado.

​

Nota: Entendendo buildCriteria

​

Formatando Dados com Transformers

• $transformers: Array de [campo => função] para formatar os dados do modelo principal.

// Em: app/controller/ApiPedidovendaController.php

public function __construct()
{
    parent::__construct();

    // Adiciona um transformer
    $this->addTransformer('dt_pedido', function ($value, $object) {
        // O retorno dessa função é o valor que será incluído na resposta JSON
        if(!empty(trim($value)))
        {
            try
            {
                // Transforma a data para o formato brasileiro
                $date = new DateTime($value);
                return $date->format('d/m/Y');
            }
            catch (Exception $e)
            {
                return $value;
            }
        }
    });
}

​

Nota a respeito de: prepareItemForResponse

1. Verifica o contexto: Decide se usa as regras de $indexFields (para listagens) ou $showFields (para detalhes).
2. Seleciona os campos: Se as listas acima estiverem definidas, ele as usa para montar a resposta. Caso contrário, pega todos os campos do objeto.
3. Oculta campos: Remove os campos listados em $hiddenFields.
4. Aplica os transformers: Por último, aplica as funções de formatação definidas em $transformers aos campos correspondentes. Isso é feito através do método interno applyTransformers(), que itera sobre as funções e executa cada uma delas.

​

Validando Campos Obrigatórios

• $requiredFields: Um array no formato ['nome_do_campo' => 'Rótulo para Erro'].

• $requiredFieldsToCheck: Um array que permite validar um conjunto de campos personalizado, ignorando temporariamente a propriedade $requiredFields da classe.
• $errorPrefix: Uma string para adicionar um prefixo às mensagens de erro, útil para dar contexto (ex.: “Item #1: Campo obrigatório”).

// Em: app/controller/ApiPedidovendaController.php

class ApiPedidovendaController extends ApiResourceController
{
    ...

    protected $requiredFields = [
        'valor_total' => 'Valor Total',
        'dt_pedido' => 'Data do Pedido'
    ];
}

Observação: caso, no modelo de dados, um campo seja definido como obrigatório (NOT NULL), ele será validado automaticamente.

​

Ganchos (Hooks) para Personalização Avançada

​

1. beforeStore

// Em: app/controller/ApiPedidovendaController.php

class ApiPedidovendaController extends ApiResourceController
{
    ...

    public function beforeStore($object, $masterData)
    {
        if(!isset($masterData['dt_pedido'])) {
            $object->dt_pedido = date('Y-m-d');
        }
    }
}

• TRecord $object: o objeto do modelo principal, já preenchido com os dados da requisição, mas ainda sem ID (pois não foi salvo).
• array $masterData: o array de dados brutos do mestre, recebido na requisição.

​

2. afterStore

// Em: app/controller/ApiPedidovendaController.php

class ApiPedidovendaController extends ApiResourceController
{
    ...

    public function afterStore($object, $masterData)
    {
        // Disparar e-mail de confirmação (classe EmailService fictícia)
        try {
            $message = EmailService::enviarNotificacaoPedido($object);
        } catch (Exception $e) {
            error_log("Erro ao enviar notificação: " . $e->getMessage());
        }
    }
}

Observação: ambos beforeStore e afterStore recebem os mesmos parâmetros. Entretanto, por ocorrer após o salvamento do registro-mestre, afterStore recebe o ID do registro salvo em $object.

​

3. beforeStoreDetail

• TRecord $master: o objeto do registro mestre, já salvo.
• TRecord $detail: o objeto do modelo de detalhe, preenchido com os dados do item atual, mas ainda não salvo.
• array $detailData: o array de dados brutos do item de detalhe específico.

​

4. afterStoreDetail

Observação: ambos beforeStoreDetail e afterStoreDetail recebem os mesmos parâmetros. Entretanto, por ocorrer dentro do loop de salvamento dos detalhes, afterStoreDetail recebe o ID do registro salvo em $detail.

​

5. afterStoreDetails

// Em: app/controller/ApiPedidovendaController.php

class ApiPedidovendaController extends ApiResourceController
{
    ...

    public function afterStoreDetails($master, $storedDetails)
    {
        $total = 0;
        foreach ($storedDetails as $item) {
            // Supondo que o detalhe tenha 'quantidade' e 'valor'
            $subtotal = $item->quantidade * $item->valor;
            $total += $subtotal;
        }

        // Atualiza o valor_total no objeto mestre e salva novamente
        $master->valor_total = $total;
        $master->store();
    }
}

Observação: a requisição não informou o valor_total, apenas os valores dos produtos.

• TRecord $master: o objeto do registro mestre.
• array $storedDetails: um array contendo todos os objetos TRecord dos detalhes que acabaram de ser salvos.