Tornar um colaborador autónomo no código do Moodle

Não é um Moodle qualquer — é uma plataforma à escala

• Núcleo Moodle 5.1 + plugins próprios: local_uniutils, local_secretaria, block_uniblock, tema edutor.
• Integração com o sistema académico eSURA/SGR — matrículas, resultados, finanças e inscrições sincronizam automaticamente.

Do que é feito · e onde se programa

No Moodle, quase tudo é um plugin

Um núcleo pequeno e estável + centenas de plugins. A regra de ouro: nunca se altera o núcleo — estende-se através de plugins, hooks e APIs. Assim, cada atualização do Moodle não destrói o nosso trabalho.

Onde vive o código

# raiz do projeto
config.php          # BD, wwwroot, dataroot
public/             # ← WEBROOT (Apache aponta aqui)
  index.php
  lib/              # APIs do núcleo
  admin/  course/  user/ …
  mod/ block/ theme/ local/ # plugins
admin/cli/          # scripts CLI (fora do webroot)
moodledata/         # ficheiros, cache (fora do webroot)

Código · Base de dados · Ficheiros

• Configuração vive em config.php (ligação) e na tabela mdl_config / mdl_config_plugins (definições).
• Nunca se acede à BD diretamente do código — usa-se sempre a API $DB (Módulo 4).

O que acontece a cada page load

Estas variáveis globais — $CFG, $DB, $USER, $PAGE, $OUTPUT — estão disponíveis em qualquer página depois de incluir config.php.

O "kit de ferramentas" que vamos usar

O modelo de permissões

Moodle + sistema académico eSURA/SGR

• local_secretaria → portal do estudante (Resultados, Extrato, Dados Pessoais…).
• block_uniblock → atalhos para a Secretaria Online.
• theme_edutor → identidade visual e página de login.

"Frankenstyle": tipo_nome

local_uniutils   // tipo=local nome=uniutils
block_uniblock   // tipo=block nome=uniblock
theme_edutor

Os ficheiros que importam

local/exemplo/
├── version.php      # identidade (obrigatório)
├── lib.php           # callbacks por convenção
├── settings.php      # definições de admin
├── index.php         # uma página
├── lang/en/…        # strings (obrigatório)
├── db/access.php     # capacidades
├── db/install.xml    # tabelas (XMLDB)
├── db/services.php   # web services
├── db/tasks.php      # tarefas agendadas
└── classes/          # código com autoload

Sem isto, não há plugin

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

$plugin->component = 'local_exemplo';   // = à pasta. Frankenstyle.
$plugin->version   = 2026060200;        // AAAAMMDDXX — subir a cada mudança de BD
$plugin->requires  = 2024100700;        // versão mínima do Moodle
$plugin->maturity  = MATURITY_STABLE;
$plugin->release   = '1.0.0';

Login → contexto → permissão → output

require_once(__DIR__.'/../../config.php');

require_login();                              // 1) exige sessão
$context = context_system::instance();
require_capability('local/exemplo:view', $context);  // 2) permissão

$PAGE->set_url(new moodle_url('/local/exemplo/index.php'));
$PAGE->set_context($context);
$PAGE->set_title(get_string('pluginname','local_exemplo'));

$avisos = $DB->get_records('local_exemplo_aviso');   // 3) dados

echo $OUTPUT->header();
// … conteúdo …
echo $OUTPUT->footer();

O padrão do block_uniblock

class block_exemplo extends block_base {
  function init() { $this->title = get_string('pluginname','block_exemplo'); }
  function applicable_formats() { return ['all'=>true]; }

  function get_content() {           // ← a lógica do bloco
    if ($this->content !== null) return $this->content;
    $this->content = new stdClass();
    $this->content->text = html_writer::link(
        new moodle_url('/secretaria/resultados'),
        get_string('examinationsdetails','local_uniutils'));
    return $this->content;
  }
}

É exatamente assim que o bloco real gera os atalhos da Secretaria Online.

Como o eSURA "empurra" dados para o Moodle

$functions = [
 'local_exemplo_save' => [
  'classname'=>'local_exemplo\\external\\save',
  'methodname'=>'execute',
  'type'=>'write',
  'capabilities'=>'local/exemplo:manage',
 ],
];

class save extends external_api {
 static function execute_parameters(){…}
 static function execute($dados){
   self::validate_context($ctx);
   require_capability(…);
   // gravar com $DB
 }
 static function execute_returns(){…}
}

Ativa-se em Admin ▸ Web services, cria-se um utilizador de serviço e um token — como a conta esura@unisced.edu.mz.

Do eSURA até à base de dados

Cada parâmetro é validado e a permissão verificada antes de tocar na base de dados.

Trabalho automático e reativo

namespace local_exemplo\task;
class export_task
   extends \core\task\scheduled_task {
 function execute() {
   mtrace('a exportar…');
 }
}

// db/events.php
$observers = [[
 'eventname'=>'\\mod_quiz\\event\\
    attempt_submitted',
 'callback'=>'\\local_exemplo\\
    observer::quiz_submitted',
]];

Falar com o eSURA/SGR a partir do código

// REST — cliente cURL do Moodle (respeita proxy/segurança)
$curl = new \curl();
$curl->setHeader('Authorization: Basic '.base64_encode("$user:$pass"));
$resposta = $curl->post('https://esura.…/service/...', $payload);

// SOAP — como o secretaria faz para os tickets (osTicket)
$client = new \SoapClient($wsdlurl);
$client->__soapCall('ostTicket.open', $dados);

Quatro peças trabalham juntas

Um tema personaliza qualquer uma destas peças — sem tocar no núcleo.

Um tema-filho do Boost

# theme/edutor/config.php
$THEME->name = 'edutor';
$THEME->parents = ['boost'];   # herda do Boost
$THEME->scss = fn($t)=>
   theme_edutor_get_main_scss_content($t);
$THEME->prescsscallback  = '…get_pre_scss';
$THEME->extrascsscallback = '…get_extra_scss';
$THEME->rendererfactory =
   'theme_overridden_renderer_factory';
$THEME->layouts = [ … ];

De .scss a CSS no browser

• Parciais em scss/theme/: _header.scss, _footer.scss, _courseformat.scss…
• Cache agressivo → depois de mexer em SCSS, purgar caches (ou themedesignermode em dev).

Sobrepor um template do núcleo

Copiar o template do componente para o tema, mantendo o caminho — o Moodle usa a versão do tema:

# o tema sobrepõe o formulário de login do núcleo:
theme/edutor/templates/core/loginform.mustache

# dentro: HTML + variáveis {{…}} e secções {{#…}}
{{#showloginform}}
  <form class="login-form" action="{{loginurl}}">
    <input name="username" …>
  </form>
{{/showloginform}}

Lógica de zero no template: só apresentação. Os dados vêm do renderer.

Lógica de apresentação & interatividade

namespace theme_edutor\output;
class core_renderer
   extends \core_renderer {
 function favicon() { … }
}

// amd/src/main.js
export const init = () => { … };

// no PHP:
$PAGE->requires->js_call_amd(
  'theme_edutor/main','init');

Tema-filho, não editar o edutor

/* SCSS personalizado (admin) */
.form-col.col-12 {
  display: none;   /* ← escondia user/pass */
}

As três regras inegociáveis

• i18n todo o texto via get_string() — nunca fixo no código.
• Lógica em classes/ com namespaces e autoload; lib.php só para callbacks.

Validar tudo · SQL com placeholders

// ENTRADA: limpar sempre com PARAM_*
$id = required_param('id', PARAM_INT);

// BD: NUNCA concatenar variáveis (injeção SQL)
$DB->get_records_sql(
  'SELECT * FROM {local_exemplo_aviso} WHERE titulo = ?',
  [$titulo]);                 // ✅ parâmetro seguro

// ❌ NUNCA: "... WHERE titulo = '$titulo'"

• Permissões sempre require_capability() — não confiar na navegação.
• Tabelas via {nometabela} (sem mdl_).

Proteger o utilizador e os dados

Código que se prova a si mesmo

Mesmo poucos testes nos pontos críticos (web services, cálculos) evitam regressões caras.

O fluxo de trabalho diário

$CFG->debug = (E_ALL | E_STRICT);
$CFG->debugdisplay = 1;

php admin/cli/upgrade.php
php admin/cli/purge_caches.php
php admin/cli/cron.php

O ciclo de trabalho diário

Editar é imediato (código montado no contentor) · purgar caches resolve 90% dos "não atualiza".

Da arquitetura à autonomia

Para continuar a aprender