OG Framework
OG Framework Documentação
Voltar para Documentação

Ferramentas

CLI System

O CLI (Command Line Interface) do OfficeGest é uma ferramenta de linha de comandos para executar tarefas de desenvolvimento, manutenção e gestão do ERP sem interface web.

Para Que Serve?

Se já usaste o Artisan do Laravel, o conceito é exactamente o mesmo. O CLI é uma forma de interagir com o framework através do terminal, sem precisar de um browser. É especialmente útil para tarefas que não fazem sentido ter uma interface visual, ou que precisam de ser automatizadas.

Alguns exemplos do que podes fazer:

  • Gerar código: Em vez de criar ficheiros manualmente, o CLI gera controllers, actions, DTOs, migrations, etc., já com a estrutura correcta.
  • Limpar caches: Quando fazes deploy ou mudas configurações, precisas de limpar vários caches. Um comando faz tudo.
  • Processar dados em batch: Importar milhares de registos, sincronizar com sistemas externos, enviar emails em massa — tudo via CLI.
  • Automatização: Os comandos podem ser executados via cron ou pipelines de CI/CD.

Quick Start

O executável está na raiz do projecto e chama-se og. Vamos ver os comandos mais comuns.

Listar Todos os Comandos

Se não sabes que comandos existem, este é o primeiro passo. Mostra todos os comandos disponíveis, agrupados por categoria. 

./og list

Obter Ajuda sobre um Comando

Cada comando tem documentação integrada. Mostra os argumentos esperados, opções disponíveis, e exemplos de uso. 

./og help make:controller

Comandos Mais Usados

# Limpar cache (usa isto sempre que mudares config)
./og cache:clear

# Gerar um controller novo
./og make:controller MeuController --module=MeuModulo

# Ver todas as rotas definidas
./og route:list

# Executar migrations pendentes
./og migrate

Contexto Multi-Tenant

O OfficeGest é multi-tenant — cada cliente tem a sua própria base de dados. Quando executas comandos via web, o sistema sabe qual é o tenant pelo domínio do pedido. No CLI, não há domínio, por isso tens de especificar manualmente.

Especificar Tenant

Para comandos que precisam de aceder à base de dados de um tenant específico, usa a variável HTTP_HOST. 

# Executar migration no tenant "demo"
HTTP_HOST=demo.officegest.com ./og migrate

# Limpar cache do tenant "clienteX"
HTTP_HOST=clientex.officegest.com ./og cache:clear

Geradores de Código

Os comandos make:* são os mais usados no dia-a-dia de desenvolvimento. Geram ficheiros com a estrutura correcta, nos directórios certos, seguindo as convenções do framework.

Comandos Disponíveis

Comando Descrição
make:module Nome Cria um módulo completo (estrutura de pastas, ServiceProvider, etc.)
make:controller Nome Cria um controller no módulo especificado
make:action Nome Cria uma action (lógica de negócio isolada)
make:dto Nome Cria um Data Transfer Object
make:request Nome Cria um Form Request (validação)
make:migration Nome Cria uma migration de base de dados
make:command Nome Cria um novo comando CLI

Criar Comandos Personalizados

Por vezes precisas de um comando específico para o teu módulo — por exemplo, para importar dados de um sistema externo, ou para correr tarefas de manutenção. É fácil criar os teus próprios comandos.

1. Gerar o Ficheiro Base

./og make:command ImportarClientes --module=MeuModulo

# Cria: Modules/MeuModulo/Commands/ImportarClientesCommand.php

2. Definir a Assinatura

A assinatura define o nome do comando, os argumentos que aceita, e as opções disponíveis. Tudo numa única string. 

protected ?string $signature = 'clientes:importar {ficheiro} {--dry-run} {--format=csv}';

// {ficheiro} → argumento obrigatório
// {--dry-run} → flag booleana (presente ou não)
// {--format=csv} → opção com valor default

3. Implementar a Lógica

public function handle(): void
{
    $ficheiro = $this->argument('ficheiro');
    $isDryRun = $this->option('dry-run');
    $format = $this->option('format');

    $this->info("A importar de: {$ficheiro}");

    if ($isDryRun) {
        $this->warning('Modo DRY-RUN: nada será guardado');
    }

    // Processar ficheiro...
    $linhas = $this->parseFicheiro($ficheiro, $format);

    // Barra de progresso para feedback visual
    $bar = $this->progressBar(count($linhas));

    foreach ($linhas as $linha) {
        // Importar...
        $bar->advance();
    }

    $bar->finish();
    $this->newLine();
    $this->success('Importação concluída!');
}

Input e Output

A classe base Command fornece vários métodos para interagir com o utilizador e mostrar resultados de forma clara.

Mostrar Mensagens

Usa cores para distinguir tipos de mensagem. Isto torna a saída do comando muito mais legível. 

$this->info('Informação normal');          // Azul
$this->success('Tudo correu bem!');         // Verde
$this->warning('Atenção a este detalhe');   // Amarelo
$this->error('Algo correu mal!');           // Vermelho

// Organização visual
$this->title('Título Principal');
$this->section('Secção');
$this->newLine(2); // Duas linhas em branco

Pedir Input ao Utilizador

// Pergunta simples
$nome = $this->ask('Qual o teu nome?');

// Com valor default (enter aceita o default)
$email = $this->ask('Email?', 'sem-email@exemplo.com');

// Password (caracteres ocultos)
$password = $this->secret('Password:');

// Confirmação sim/não
if ($this->confirm('Tens a certeza que queres continuar?')) {
    // Confirmou
}

// Escolha de múltiplas opções
$formato = $this->choice('Formato de exportação?', ['csv', 'json', 'xml'], 'csv');

Mostrar Tabelas

Para dados tabulares, o método table() formata tudo automaticamente. 

$this->table(
    ['ID', 'Nome', 'Email'],
    [
        [1, 'João', 'joao@email.com'],
        [2, 'Maria', 'maria@email.com'],
    ]
);
Segurança Paginação