Modos de Integração

O MIDDAG oferece tres modos de integração. Escolha o modo proporcional a complexidade da sua necessidade.

Comparacao

Modo	Quando usar	Complexidade	Lifecycle
Extension	Modulo completo com DI, controllers, rotas	Alta	register / boot / compile
Hooks API	Reagir a eventos ou transformar dados	Baixa	boot only
Hooks File	Registrar callbacks sem plugin Moodle	Minima	Nenhum (auto-discovered)

Fluxo de decisão

graph TD
    START["Preciso integrar com o MIDDAG"] --> Q1{"Preciso de persistência,
controllers ou DI?"}
    Q1 -->|Sim| EXT["Extension"]
    Q1 -->|Não| Q2{"Preciso reagir
a eventos apenas?"}
    Q2 -->|Sim| Q3{"Tenho um
plugin Moodle?"}
    Q3 -->|Sim| HOOKS["Hooks API"]
    Q3 -->|Não| FILE["Hooks File"]
    Q2 -->|Não| Q4{"Preciso transformar
um valor?"}
    Q4 -->|Sim| Q3
    Q4 -->|Não| EXT

---

Extension

Uma extension é um módulo com lifecycle completo, registrado via hook Moodle.

1. Declarar a extension no lib.php do seu plugin

// local/meuplugin/lib.php

function local_meuplugin_extend_local_middag_extensions(array $definitions): array
{
    $definitions[] = [
        'class'    => \local_meuplugin\extensions\catalogo\catalogo_extension::class,
        'slug'     => 'catalogo',
        'group'    => 'integrations',
        'priority' => 50,
        'hidden'   => false,
        'requires' => [],
    ];

    return $definitions;
}

2. Criar a classe da extension

// local/meuplugin/classes/extensions/catalogo/catalogo_extension.php

namespace local_meuplugin\extensions\catalogo;

use local_middag\base\extension;
use Symfony\Component\DependencyInjection\ContainerBuilder;

final class catalogo_extension extends extension
{
    public const EXTENSION_IDNUMBER = 'catalogo';
    public const GROUP = 'integrations';
    public const PRIORITY = 50;
    public const REQUIRES = [];

    public function register(ContainerBuilder $container): void
    {
        // Registrar services no container de DI.
    }

    public function boot(): void
    {
        // Registrar hooks, listeners, controllers.
    }
}

O que a extension recebe

• Lifecycle completo (register / boot / compile).
• Container de DI para injeção e resolução de services.
• Auto-discovery de controllers (rotas via #[Route]).
• Gerenciamento via painel de extensions (ativar/desativar).
• Isolamento de falhas: se a extension falhar no boot, as demais continuam.

---

Hooks API

Permite reagir a eventos ou transformar dados do MIDDAG a partir de um plugin Moodle existente, sem criar extension.

Registrar uma action (side effect)

use local_middag\facade\hook_manager;

hook_manager::add_action('middag/item/created', function (object $item): void {
    // Reagir ao fato.
    mtrace('Item criado: ' . $item->get_id());
}, priority: 10);

Registrar um filter (transformacao)

use local_middag\facade\hook_manager;

hook_manager::add_filter('middag/item/title_display', function (string $title): string {
    return strtoupper($title);
}, priority: 20);

Actions vs Filters

Tipo	Operacao	Retorno
Action (add_action / do_action)	Executa side effect	Nenhum
Filter (add_filter / apply_filters)	Transforma um valor	Valor modificado

Hooks públicos seguem o padrão middag/{contexto}/{entidade}_{ação}.

---

Hooks File

A forma mais leve. Um arquivo PHP avulso, sem plugin Moodle.

Caminhos de auto-discovery

Prioridade	Caminho	Cenario
1	$CFG->dirroot . '/local/middag_hooks.php'	Padrao
2	$CFG->dataroot . '/middag_hooks.php'	Filesystem compartilhado
3	$CFG->dirroot . '/theme/{tema_ativo}/middag_hooks.php'	Hooks no tema

Exemplo minimo

<?php
// MOODLE/local/middag_hooks.php

defined('MOODLE_INTERNAL') || die();

use local_middag\facade\hook_manager;

hook_manager::add_action('middag/item/created', function (object $item): void {
    // Logica customizada.
});

hook_manager::add_filter('middag/item/title_display', function (string $title): string {
    return mb_strtoupper($title);
});

O framework válida existência, cacheia caminhos e suspende automaticamente hookfiles que gerem exception durante o carregamento.