Classificação da API¶

Grupos de classificacao¶

Grupo	Nome	Localizacao	Garantia
A	Publico estavel	`facade/`, contracts `@api`, tipos promovidos e diretorios explicitamente publicos	Politica de evolução e deprecacao SemVer
B	Extensao controlada	`base/`	Heranca estavel, protege contra reorganizacao interna
C	Interno	Implementacao sem `@api` e fora das excecoes publicas declaradas	Pode mudar sem aviso

Regra de consumo: use somente Grupo A e Grupo B. Grupo C é interno e pode ser refatorado a qualquer momento.

Como identificar o grupo¶

Indicador	Grupo
Anotacao `@api` na classe ou interface	A
Reside em `classes/base/`	B
Reside em `classes/facade/`	A (por diretorio)
Reside em `moodle/entity/` ou `moodle/dto/`	A (por diretorio)
Reside em diretorio explicitamente promovido no inventario	A
Tudo o mais fora dessas regras	C

Esta pagina resume a politica de consumo para integradores. O inventario normativo completo e as excecoes promovidas vivem no vault operacional e sao refletidos aqui sem redefinir a regra.

Promocao de grupo¶

Para promover um tipo de C para A:

Consumidor real existente
Semantica estavel comprovada
Aprovacao do tech lead

Nem todo tipo publico do Grupo A nasce de @api em framework/contract/. Alguns tipos sao publicos por diretorio ou por promocao declarada no inventario mantido pela equipe.

Deprecacao¶

Formato obrigatório:

/**
 * @deprecated since 5.2 Use \local_middag\framework\contract\new_interface instead.
 *             Will be removed in 6.0.0.
 */

Enforcement¶

PHPStan rule NoInternalImportsFromExtensionsRule bloqueia imports de tipos @internal por extensions em tempo de analise estatica.

Quando @api e @internal coexistem na mesma classe, @api prevalece.

Inventario de tipos @api¶

O inventario abaixo e um resumo para consumo externo. Em caso de duvida sobre excecoes, promocoes ou cobertura completa, prevalece o inventario mantido no vault interno e seus documentos de referencia.

Contract (cross-cutting)¶

Tipo	Uso
`command_bus_interface`	Type-hint para injeção do command bus
`command_interface`	Base para commands customizados
`controller_interface`	Contrato base de controller
`dashboard_widget_interface`	Contrato para widgets de dashboard
`form_request_interface`	Contrato de validação de input
`import_repository_interface`	Repositorios de importacao
`privacy_repository_interface`	Compliance de privacy
`repository_interface`	Contrato base de repositorio
`transaction_manager_interface`	Gestao transacional
`validator_interface`	Validação customizada

Contract Attributes¶

Tipo	Uso
`item_type`	Declarar tipos de item em extensions
`schedule`	Declarar agendamentos em scheduled services
`no_hook`	Suprimir do_action() automatico em signals internos
`on`	Registrar listeners de signal via auto-discovery em métodos
`trusted_output`	Desabilitar sanitização automatica em handlers de shortcode

Contract Core¶

Tipo	Uso
`block_interface`	Contrato para blocos
`extension_interface`	Contrato base de extension
`facade_interface`	Contrato de facade (geração via CLI)
`middag_interface`	Contrato raiz do framework

Exception¶

Tipo	HTTP	Uso
`middag_exception`	500	Catch generico do framework
`middag_domain_exception`	400	Regra de negocio violada
`middag_validation_exception`	422	Input inválido
`middag_not_found_exception`	404	Recurso nao encontrado
`middag_infrastructure_exception`	500	Falha de infra
`middag_persistence_exception`	500	Falha de persistência
`middag_authorization_exception`	403	Sem permissao

Service (cross-cutting)¶

Tipo	Uso
`adhoc_service_interface`	Agendamento de tarefas adhoc
`auth_service_interface`	Autenticação e sessão
`authentication_interface`	Contrato de autenticação
`authorizer_interface`	Verificação de capabilities
`capability_interface`	Contrato de capability
`dispatcher_interface`	Despacho de signals
`extension_service_interface`	Gestao de extensions
`http_client_interface`	Cliente HTTP para integracoes
`license_manager_interface`	Gestao de licencas
`license_service_interface`	Servico de licenciamento
`message_service_interface`	Envio de mensagens Moodle
`scheduled_service_interface`	Servicos agendados
`shortcode_manager_interface`	Gestao de shortcodes
`shortcodes_service_interface`	Servico de shortcodes
`user_service_interface`	Operações sobre usuários
`webhook_service_interface`	Gestao de webhooks

Domain: item/¶

Tipo	Uso
`item_interface`	Contrato do entity item
`item_dto_interface`	Contrato do DTO de item
`item_repository_interface`	Repositorio de items
`item_query_service_interface`	Busca de items
`item_service_interface`	Servico de items
`item_signal`	Signal de lifecycle de item
`item_validator_service_interface`	Validação de items

Domain: item_revision/¶

Tipo	Uso
`item_revision_interface`	Contrato do entity item_revision
`item_revision_repository_interface`	Repositorio de revisoes
`item_revision_service_interface`	Servico de revisoes

Domain: audit/¶

Tipo	Uso
`audit_diff_dto`	DTO de diff de auditoria
`audit_diff_interface`	Contrato de diff
`audit_diff_service_interface`	Servico de diff
`audit_log_dto`	DTO de log de auditoria
`audit_log_repository_interface`	Repositorio de logs de auditoria
`audit_service_interface`	Servico de auditoria
`audit_snapshot_dto`	DTO de snapshot
`audit_snapshot_interface`	Contrato de snapshot
`audit_snapshot_service_interface`	Servico de snapshots

Domain: job/¶

Tipo	Uso
`job`	Entity de job assíncrono
`job_attempt`	Entity de tentativa de job
`job_attempt_dto`	DTO de tentativa
`job_attempt_interface`	Contrato de tentativa
`job_attempt_service_interface`	Servico de tentativas
`job_dto`	DTO de job
`job_interface`	Contrato de job
`job_service_interface`	Servico de jobs
`job_signal`	Signal de lifecycle de job

Domain: activity_feed/¶

Tipo	Uso
`activity_feed`	Entity de activity feed
`activity_feed_dto`	DTO de activity feed
`activity_feed_service_interface`	Servico de feed
`activity_feed_trackable_interface`	Entities que participam do feed

Facade (por diretorio)¶

Todas as classes em classes/facade/ são Grupo A. Geradas via CLI.

use local_middag\facade\item_facade;

$items = item_facade::search('product', ['active' => true]);

Kernel¶

Tipo	Uso
`abstract_extension`	Base para extensions no kernel
`global_scope_manager_interface`	Gestao de global scopes
`hook_manager_interface`	Gestao de hooks

Infrastructure¶

Tipo	Uso
`global_scope_interface`	Criar global scopes
`operator`	Enum de operadores do query engine
`query_builder`	Construcao de queries
`result`	Value object de resultado de busca

Moodle Boundary: contract/¶

Tipo	Uso
`activity_feed_renderer_interface`	Rendering de activity feed
`activity_trackable_interface`	Entities rastreaveis
`backup_steps_provider_interface`	Backup/restore
`file_area_handler_interface`	Gestao de file areas
`privacy_provider_interface`	GDPR/privacy compliance
`translator_interface`	Traducao
`view_adapter_interface`	Adaptacao de views

Moodle Boundary: definition/¶

Tipo	Uso
`cache`	Declaração de cache stores
`capability`	Declaração de capabilities
`check`	Declaração de environment checks
`definition_interface`	Contrato base de definition
`event_definition`	Declaração de Moodle events customizados
`file_area`	Declaração de file areas
`hook`	Declaração de hooks
`message`	Declaração de message types
`service`	Declaração de external services

Moodle Boundary: enum/¶

Tipo	Uso
`cache_mode`	Modos de cache (APPLICATION, SESSION, REQUEST)
`capability_risk`	Riscos de capability
`capability_type`	Tipos de capability (read, write)
`check_type`	Tipos de environment check
`context_level`	Context levels Moodle
`event_edulevel`	Education levels para Moodle events
`message_permission`	Permissoes de mensagem

Moodle Boundary: settings/¶

Todos os 24 tipos em moodle/settings/ com @api são Grupo A. settings_resolver é @internal.

Tipos @api (completo)	Uso
`autocomplete`, `checkbox`, `colourpicker`, `description`, `directory`, `duration`, `encrypted_password`, `executable`, `filepath`, `heading`, `htmleditor`, `iplist`, `link`, `multicheckbox`, `multiselect`, `page`, `password`, `portlist`, `select`, `setting`, `setting_type`, `storedfile`, `text`, `textarea`, `time`	Declaração tipada de settings

Moodle Boundary: dto/ e entity/¶

Todas as entities em moodle/entity/ são Grupo A por diretório.

DTOs em moodle/dto/ com @api explícito são Grupo A. DTOs de infraestrutura interna de tasks são @internal e não fazem parte da API pública.

Tipo (Grupo A)	Uso
`calendar_event_dto`	Evento de calendário para extensions
`notification_dto`	Notificação Moodle para extensions

Shared (promovidos)¶

Tipo	Uso
`dto_interface`	Contrato base de DTO
`async_dispatch_dto`	DTO para despacho assíncrono
`extension_group`	Enum de grupos de extension
`widget_interface`	Contrato de widget