A execução de scripts PHP via interface de linha de comando (CLI) é uma prática fundamental para automação de tarefas, processametno de filas e rotinas de manutenção (cron jobs). Para tornar esses scripts flexíveis, é essencial capturar e tratar argumentos passados pelo terminal. A função nativa getopt() é a ferramenta padrão do PHP para essa finalidade.

Fundamentos da função getopt()

A assinatura básica da função é:

getopt(string $short_options, array $long_options = [], int &$rest_index = null): array|false

O foco principal são as short_options, onde cada caractere define uma flag. Existem três níveis de parametrização:

• Caractere único: Define uma opção que não aceita valores (funciona como um booleano/flag).
• Caractere seguido de um dois-pontos (:): Indica que o parâmetro requer obrigatoriamente um valor.
• Caractere seguido de dois dois-pontos (::): Indica que o parâmetro aceita um valor opcional.

Implementação Prática de um Script de Automação

Abaixo, apresentamos um exemplo de script estruturado para processar tarefas específicas (como sincronização de dados) baseando-se em parâmetros de ação e tempo.

<?php

/**
 * Script CLI para processamento de tarefas agendadas.
 * Parâmetros:
 * -a: Nome da ação (obrigatório)
 * -p: Período/Timestamp (opcional)
 * -h: Ajuda
 */

$opcoes = getopt("a:p::h");

// Validação inicial
if (!$opcoes || isset($opcoes['h'])) {
    exibirManual();
    exit(1);
}

if (!isset($opcoes['a'])) {
    echo "Erro: O parâmetro de ação (-a) é obrigatório.\n";
    exit(1);
}

$acao = $opcoes['a'];
$periodoRaw = $opcoes['p'] ?? null;

// Tratamento de timestamps
$inicio = $fim = null;
if ($periodoRaw) {
    $segmentos = explode('-', $periodoRaw);
    $inicio = (int)$segmentos[0];
    
    if (count($segmentos) === 2) {
        $fim = (int)$segmentos[1];
    } else {
        $fim = time();
    }
}

// Roteamento de tarefas
switch ($acao) {
    case 'vendas':
        processarSincronizacaoVendas($inicio, $fim);
        break;
    case 'estoque':
        echo "Iniciando atualização de estoque...\n";
        // Lógica de estoque aqui
        break;
    default:
        echo "Ação desconhecida: $acao\n";
        break;
}

function processarSincronizacaoVendas($start, $end) {
    if (!$start) $start = strtotime("-24 hours");
    
    echo "Sincronizando vendas de " . date('Y-m-d H:i:s', $start) . " até " . date('Y-m-d H:i:s', $end) . "\n";
    
    // Simulação de processamento em lotes
    $passo = 3600; // 1 hora
    for ($atual = $start; $atual < $end; $atual += $passo) {
        $proximo = min($atual + $passo, $end);
        executarTarefaInterna($atual, $proximo);
    }
}

function executarTarefaInterna($ts1, $ts2) {
    // Lógica de negócio
}

function exibirManual() {
    $manual = <<<text ajuda.="" argumentos:="" da="" de="" do="" echo="" este="" estoque="" exibe="" guia="" intervalo="" nome="" ou="" php="" script.php="" script:="" tarefa="" text="" timestamp="" uso="" vendas=""></text>

Nuances e Comportamentos do getopt()

1. Atribuição de Valores Obrigatórios

Para opções definidas com um dois-pontos (ex: a:), o PHP aceita o valor de três formas:

php script.php -avendas
php script.php -a=vendas
php script.php -a vendas

2. Atribuição de Valores Opcionais

Para opções com dois dois-pontos (ex: p::), o PHP é mais restritivo. Não deve haver espaço entre o parâmetro e o valor se não for utilizado o sinal de igual:

# Correto
php script.php -p123456
php script.php -p=123456

# Incorreto (Resultará em 'false' para o parâmetro p)
php script.php -p 123456

3. Manipulação de Flags

Parâmetros simples (sem dois-pontos) retornam sempre bool(false) se estiverem presentes no comando. Sua existência no array retornado por getopt() indica que o usuário ativou aquela flag.

4. Múltiplas Ocorrências

Se um parâmetro for passado várias vezes no mesmo comando, o getopt() converterá o valor associado em um array contendo todas as entradas fornecidas:

# Comando
php script.php -a task1 -a task2

# Resultado no PHP
["a"] => ["task1", "task2"]