title: Contratos: API Pública description: Zonas de consumo, estabilidade e política de evolução da API pública do framework.

API Pública¶

O local_middag estabiliza sua interface de consumo através de três zonas de consumo distintas. Esta classificação permite que o framework evolua e refatore seus componentes internos sem quebrar as extensões e plugins que dependem dele.

O que é¶

A API Pública do framework é o conjunto de classes, interfaces e hooks garantidos como estáveis para consumo externo. Ela funciona como um contrato de fidelidade entre o core e os desenvolvedores de extensions.

O framework utiliza três classificações para seus componentes: 1. API Pública Estável: Pontos fixos de entrada e contratos protegidos. 2. Camada de Extensão Controlada: Estruturas base para herança segura. 3. Interno por Padrão: O motor do framework, livre para mudanças profundas sem aviso prévio.

Por que existe¶

Sem uma distinção clara do que é "público" e o que é "detalhe de implementação": * Qualquer refatoração no core quebraria as dezenas de extensions existentes. * Desenvolvedores teriam medo de atualizar, temendo bugs imprevisíveis. * A superfície de contato seria imensa, tornando a manutenção do framework insustentável.

Ao definir zonas de consumo, o framework garante estabilidade onde ela é necessária (fronteira) e agilidade onde o código deve evoluir (núcleo).

As Três Zonas de Consumo¶

Zona	Aonde vive	Garantia de Estabilidade
API Pública Estável	`classes/facade/` e contracts com `@api`	Alta. Breaking changes exigem deprecation e migração.
Extensão Controlada	`classes/base/`	Média. Estável para herança seguindo o modelo do framework.
Interno por Padrão	`classes/framework/*` (exceto tipos `@api`)	Nenhuma. Pode mudar em qualquer release minor ou patch.

Decisões de design¶

Anotação como Verdade: A presença da anotação @api no DocBlock de uma classe ou interface é o sinal definitivo de sua publicidade. Se um componente está em framework/ mas não possui @api, ele é Interno.
Ciclo de Deprecation: Removimentos nunca são súbitos. Um componente marcado como @deprecated terá prazo mínimo de uma minor version ou 3 meses (o que for maior) antes de ser removido em uma major version.
Enforcement Automatizado: O framework fornece o script php cli/check_api_boundaries.php para validar se as extensions estão violando as fronteiras de consumo, acessando o que não deveriam.

O que não é¶

Não é Carta Branca: Ter acesso ao namespace do framework não significa que você deve instanciar qualquer classe dele. Respeite as Facades.
XMLDB Schema não é API: Os nomes de tabelas físicos e colunas no banco de dados são internos. Sempre utilize os Repositories para acessar dados.
Signals não promovidos não são API: Apenas Signals oficialmente documentados como públicos fazem parte do contrato estável.

Perspectiva para builders de extensions¶

Como desenvolvedor de extension: 1. Consuma Facades: Elas são o caminho preferencial para acesso estático simples. 2. Use Contracts @api: Quando sua extension precisar de Injeção de Dependência ou substituir um comportamento do framework. 3. Respeite o @internal: Se uma classe interna parece útil, peça a promoção dela para @api em vez de consumi-la diretamente. Consumir código interno garante que sua extension quebrará na próxima atualização.

Exemplo ilustrativo¶

Identificando o contrato de estabilidade no código:

/**
 * @api
 * Esta interface faz parte do contrato público estável.
 */
interface item_repository_interface { ... }

/**
 * @internal
 * Esta classe é detalhe técnico e pode mudar sem aviso.
 */
final class sql_item_hydrator { ... }

Se sua extension utiliza sql_item_hydrator, ela está fora do contrato de suporte do framework.