Variáveis globais e configuração

O Gestor é procedural e compartilha estado por quatro arrays globais. Dentro de uma função, declare global $_GESTOR; (e $_CONFIG, $_BANCO) antes de usar.

Há também $_CRON (definido por cron.php antes do config.php, com SERVER_NAME e ROOT_PATH do domínio agendado) e o próprio $_ENV, com as chaves cruas do .env.

Como o .env é encontrado

1. ROOT_PATH é a pasta do Gestor: $_INDEX['sistemas-dir'] na web, a pasta do config.php no CLI e $_CRON['ROOT_PATH'] no cron.

2. O .env procurado é autenticacoes/<SERVER_NAME>/.env, carregado pelo Dotenv. No CLI, sem SERVER_NAME definido, usa localhost.

3. Se não existir, o config.php tenta cada pasta de autenticacoes/ em ordem alfabética e carrega a primeira que tiver .env.

4. Nenhuma encontrada: 503 com JSON Configuration file (.env) not found. Sem o Composer instalado (sem Dotenv): 500.

Os nomes de cookie recebem um sufixo por domínio (_ + os 8 primeiros caracteres, em maiúsculas, do MD5 do nome da pasta do domínio), por exemplo _C2FCID_05B11065. Assim, dois projetos no mesmo domínio-pai não trocam cookies. Um script de CLI que gera cookie para um site precisa rodar com o SERVER_NAME desse site.

$_BANCO

A conexão em si ($_BANCO['conexao']) é aberta sob demanda por banco.php.

$_CONFIG: mapa do .env

Leia $_CONFIG para configurações do sistema. Para chaves que também podem ser lidas por código fora do bootstrap web, os módulos do core usam a ordem $_CONFIG → $_ENV → getenv(): uma chave lida de um lugar só fica inerte, sem erro, onde aquele lugar não é preenchido.

$_GESTOR: estado da instalação (do config.php)

Um projeto pode acrescentar ou sobrescrever chaves em config-project.php (na raiz do Gestor), incluído no fim do config.php. É ali que vivem, por exemplo:

• project-css e project-javascript, com as variantes *-layouts-include e *-layouts-remove;

• project-page-tailwind-bundles;

• project-version.

$_GESTOR: estado da requisição

Acesso Controlado: gestor_get(), gestor_set(), gestor_has() e gestor_contexto()

A partir da req-229 (BATCH-238), como preparação arquitetural para a refatoração orientada a objetos da Linha 3.1, novos desenvolvimentos devem priorizar as funções de acesso controlado da camada GestorState em vez de manipular $_GESTOR de forma indiscriminada:

• gestor_get(string $chave, mixed $padrao = null): mixed: Leitura com fallback e suporte a notação pontuada (ex.: gestor_get('banco.conexao.host', 'localhost')).

• gestor_set(string $chave, mixed $valor): bool: Escrita segura com validação. Protege chaves críticas do Core contra mutação acidental.

• gestor_has(string $chave): bool: Verificação determinística de existência (suporta notação pontuada).

• gestor_contexto(string $escopo): array: Extração de fatias delimitadas de contexto (modulo, usuario, sistema, etc.).

Chaves protegidas do Core (Imutáveis após boot)

As seguintes chaves não podem ser sobrescritas acidentalmente via gestor_set():

• raiz-absoluta

• url-raiz

• linguagem-codigo

• versao-num

Tentativas de sobrescrita disparam alerta nos logs do sistema e retornam false.

100% de Retrocompatibilidade

O array $_GESTOR continua existindo como armazenamento subjacente. Códigos legados existentes que lêem ou escrevem em $_GESTOR['chave'] continuam funcionando sem qualquer alteração.

Veja também

• Ciclo de uma requisição: em que momento cada chave é preenchida.

• Instalação: como o .env nasce.

• Skills c2f-global-variables e c2f-environment-configuration.