Upgrade Moodle 3.9 → 5.2: padrões reais de quem migrou de verdade

1. Por que Moodle 5.2 LTS (e não 5.0 nem 5.1)

O Moodle HQ adota um modelo de release com versões intermediárias (5.0, 5.1) e versões LTS (Long Term Support) com janela de suporte estendida. Para qualquer projeto que precise estabilidade operacional, só faz sentido planejar upgrade para uma LTS.

Em 2026, a LTS recomendada é a 5.2. As versões 5.0 e 5.1 já receberam patches mas o ciclo de suporte termina antes — ir para elas significa fazer outro upgrade em 6 a 12 meses. Quem opera Moodle em produção sabe: upgrade não é coisa que se faz duas vezes seguidas se puder evitar.

Critérios objetivos para escolher uma LTS:

• Ciclo de suporte garantido — patches de segurança por pelo menos 24 meses após o release.
• Compatibilidade com plugins de terceiros — autores de plugins importantes (BigBlueButton, H5P, Edwiser, NextSheet) tipicamente prio­rizam compatibilidade com LTS, não com intermediárias.
• Documentação mantida — docs.moodle.org cobre LTS com detalhe maior.
• Estabilidade do schema — entre LTS o schema do banco muda pouco, o que facilita rollback se necessário.

Regra prática: se a versão de destino não é LTS, não é projeto sério de upgrade — é experimento. E experimentos não vão para produção sem rollback rápido.

2. Por que o upgrade é encadeado e não direto

Esta é a pergunta que mais ouvimos em projeto novo: "Posso ir direto de 3.9 para 5.2?". Não.

O instalador do Moodle valida a versão de origem antes de aplicar migrações de schema. O código de upgrade está organizado em upgrade.php distribuído por componente (core, mod, block, theme, etc.). Cada componente tem uma sequência de funções de upgrade indexadas por versão. Quando o instalador tenta saltar de uma LTS para outra não-adjacente, encontra um gap nas funções de upgrade — e simplesmente recusa rodar (em alguns casos roda parcialmente e corrompe o schema de forma silenciosa, o que é pior).

O caminho obrigatório de 3.9 para 5.2:

3.9 LTS → 4.1 LTS → 4.5 LTS → 5.0 → 5.2 LTS

Sim, 5.0 não é LTS. Mas é exigida como ponte porque o gap de 4.5 para 5.2 inclui mudanças de schema que precisam passar pelas migrações intermediárias do 5.0. Tentar pular 5.0 quebra tabelas relacionadas a competências, badges e cache.

Em cada etapa do encadeamento, o processo correto é:

1. Backup completo antes de aplicar o upgrade da etapa.
2. Verificar PHP mínimo da versão de destino (cada LTS tem suas exigências).
3. Atualizar plugins de terceiros para versão compatível com a LTS da etapa.
4. Rodar o upgrade via CLI (php admin/cli/upgrade.php --non-interactive) — nunca via web UI em produção.
5. Purge cache (php admin/cli/purge_caches.php).
6. Validar integridade — acesso a cursos, lançamento de notas, login admin, acessos com diferentes roles.
7. Snapshot do banco antes da próxima etapa.

Aqui está o erro que mata projetos: pular o snapshot intermediário. Se a etapa 4.1 → 4.5 introduz inconsistência detectada só na etapa 4.5 → 5.0, sem snapshot intermediário você não consegue isolar onde quebrou. Acaba refazendo do início.

3. Os 6 riscos críticos que aparecem em quase 100% dos casos

Em quase uma década atendendo upgrades reais de Moodle 3.x para versões mais novas, identificamos uma constância impressionante: seis problemas técnicos aparecem em quase todos os ambientes legados. Independente do setor, do tamanho, do orçamento ou da maturidade da equipe de TI do cliente.

A auditoria pré-upgrade é desenhada para detectar esses seis riscos antes de qualquer orçamento. Quando aparecem (e sempre aparecem), o escopo do upgrade muda — e cliente entende por que upgrade não é "rodar update". Mais sobre isso na página de auditoria de segurança.

4. Quatro tipologias reais de Moodle legado

Diferente de comparar caso a caso (cada cliente é único), faz mais sentido reconhecer arquétipos recorrentes. Em quase uma década de operação, 90% dos projetos cabem numa das quatro tipologias abaixo. Identificar a sua antes do escopo evita surpresas.

Tipo 01 · Educativo multi-tenant

Escola ou instituto com matriz + N subdomínios regionais ou de filiais, todos no mesmo core Moodle 3.x. Tipicamente 3 a 12 subdomínios. Cada subdomínio tem admin local mas ninguém atualiza o core. Volume de dataroot na faixa de 20-80 GB. Cron parado há anos. Plugins de relatórios descontinuados. Padrões de uso heterogêneos entre filiais (uma usa pesado, outra mal entra). Projeto típico: 3 a 9 semanas, encadeado, com janela de manutenção fora do calendário letivo.

Tipo 02 · Corporativo H5P-heavy

Empresa cujo departamento de T&D investiu em conteúdo interativo com mod_hvp. Centenas de atividades H5P (interactive video, course presentation, question sets), milhares de attempts acumulados, notas e progresso entram no histórico oficial de colaboradores. Não podem perder dados — é compliance interna. Não tinham plano para a deprecação do mod_hvp. Projeto típico: 2 a 5 semanas, sempre bundled com migração H5P (mod_hvp → mod_h5pactivity) preservando 95% dos dados.

Tipo 03 · Governo / setor público

Município, universidade pública ou órgão. Infraestrutura própria, restrições de licitação ou de processo de compra, integração SSO obrigatória (LDAP corporativo, SAML institucional, Gov.br), compliance LGPD pesada documentada, equipe interna de TI envolvida em cada decisão. Janela de manutenção restrita a horário não letivo ou fora do expediente público. Sign-off escrito de cada etapa exigido. Projeto típico: 6 a 12 semanas, mais lento porque governance é mais lento.

Tipo 04 · PME com tema customizado

Escola pequena, instituto privado ou empresa de cursos com investimento pesado em branding via tema customizado. Pode ser um tema premium pago (MB2NL/New Learning, Klass, Lambda, Edumy) ou um child theme custom sobre Boost. O tema não é compatível com 5.2 out-of-the-box. Cliente não aceita perder identidade visual. Solução: revisar templates Mustache + SCSS adaptando ao Bootstrap 5 da nova versão. Projeto típico: 2 a 4 semanas, geralmente com tema entregue antes do upgrade do core (staging serve para validar o visual).

Tipologias mistas existem — escola privada com tema custom + H5P em produção é Tipo 01 + Tipo 02 + Tipo 04 ao mesmo tempo. Universidade com migração H5P + SSO é Tipo 02 + Tipo 03. A auditoria inicial mapeia qual mix você tem e ajusta cronograma.

5. Como o PHP 8.4 mudou as regras

PHP 8.4 (lançado em novembro de 2024) trouxe melhorias significativas que o Moodle 5.2 aproveita: property hooks, asymmetric visibility, chained method calls without parentheses, e melhorias de performance em arrays grandes e foreach sobre coleções grandes.

Mas mais importante para projetos de upgrade são as quebras silenciosas:

• Implicit nullable types deprecated — parâmetros com default null agora exigem ?type explícito. Plugins que não fizeram isso geram warning em produção e podem quebrar em PHP 8.5+.
• strlen(), substr(), strpos() sobre não-string — antes coerciava, agora gera TypeError. Código antigo de extensões de relatório quebra.
• Curl options renomeados — alguns plugins de integração com APIs externas usavam constantes deprecated.
• MySQL 8 strict mode — combinado com PHP 8.4 + Moodle 5.2, queries com agregados sem GROUP BY explícito quebram. Plugins de relatórios antigos sofrem aqui.

Implicação prática: cada plugin de terceiros precisa ser testado individualmente em staging. Não dá para confiar em "a versão do plugin diz suportar Moodle 5.2" — testamos sempre. Quando um plugin crítico não é compatível, três decisões possíveis: aguardar update do autor, fazer fork e ajustar, ou substituir por equivalente.

6. Erros que vemos em upgrades auto-conduzidos

Antes de chegar para a gente, alguns clientes tentaram (ou sua equipe interna tentou) o upgrade sozinhos. Os padrões de erro são tão repetidos que viraram quase folclore:

Erro 1 · Pular o snapshot intermediário

Já mencionado: rodar 3.9 → 4.1 → 4.5 → 5.0 → 5.2 sem snapshot do banco entre cada etapa. Quando algo quebra na última etapa, não dá para isolar onde apareceu. Refaz tudo. Custo: dias perdidos.

Erro 2 · Atualizar PHP só depois do upgrade do Moodle

Sequência correta: PHP 8.x compatível com a versão de destino antes de aplicar o upgrade. Quem inverte essa ordem quebra antes de começar — o instalador do Moodle valida a versão do PHP e recusa rodar.

Erro 3 · Usar a web UI em produção

O instalador via web UI tem timeout (30 segundos é o default da maioria das stacks). Upgrade de Moodle médio leva 5 a 20 minutos. A página dá timeout, conexão cai, e o cliente fica com upgrade pela metade. Sempre via CLI: php admin/cli/upgrade.php --non-interactive.

Erro 4 · Não desinstalar plugins descontinuados antes

Plugins descontinuados nem sempre rodam o próprio uninstall.php quando o upgrade do core já passou da versão que os suportava. Aí ficam tabelas órfãs, configurações zumbi, e até erros em telas de admin. Desinstalar limpamente antes do upgrade do core é regra.

Erro 5 · Confiar no backup do hosting sem testar

Backup automático do cPanel/Plesk é frequentemente parcial (só banco, ou só arquivos) ou em formato proprietário que não restaura em outro hosting. Antes do upgrade, fazer backup manual completo (mysqldump + tar do dataroot + tar do codebase) e restaurar em staging para validar.

Erro 6 · Não validar com usuários reais

Equipe técnica valida que "subiu, login funciona, cursos abrem". Mas o aluno reclama que a atividade H5P perdeu o progresso, o professor não consegue lançar nota porque o gradebook mudou layout, o RH não acha o relatório que sai todo mês. Validação tem que incluir casos de uso reais de cada role, com pessoas de cada perfil.

7. Checklist da auditoria pré-upgrade

Antes de orçar um upgrade, o que precisa ser respondido pelo cliente ou apurado por auditoria:

Sobre o ambiente atual:

• Versão exata do Moodle (número de build, não só "3.x")
• Versão do PHP, do MySQL/MariaDB, do servidor web
• Tamanho do banco e do dataroot
• Configuração de cache (file, Redis, Memcached, nenhum)
• Estado do cron (rodando, parado, há quanto tempo)
• Sistema operacional do servidor e provedor de hosting

Sobre conteúdo e uso:

• Número de cursos ativos + arquivados
• Número de usuários ativos no último ano
• Lista completa de plugins instalados (incluindo desativados)
• Uso de H5P (mod_hvp ou mod_h5pactivity)
• Tema atual (gratuito, premium pago, custom child theme)
• Customizações feitas no tema ou no core (sim/não — e quem fez)

Sobre integrações:

• SSO ativo? (LDAP, SAML, OAuth, Shibboleth)
• Integrações com ERP, CRM, sistema de matrícula
• Pagamento (PagSeguro, Stripe, manual)
• Webhooks externos
• BBB (BigBlueButton) ou outra videoconferência integrada

Sobre operação:

• Backup atual: quem faz, em que frequência, onde guarda, já foi restaurado?
• Janela de manutenção possível (24/7, fora do horário letivo, só de madrugada)
• Quem é o responsável técnico (cliente, fornecedor, ProgramaMoodle)?
• Compliance aplicável (LGPD, GDPR, CNPD, ISO)

Quando essas 24+ informações estão mapeadas, o orçamento é específico e realista em vez de chute. E o cronograma é defensável. É por isso que nunca damos orçamento de upgrade sem auditoria prévia.

8. Conclusão prática

Upgrade de Moodle não é "rodar update". É processo técnico encadeado com 6 riscos críticos quase universais, 4 tipologias de cenário, e quebras silenciosas do PHP 8.4 que afetam plugins de terceiros.

Para quem está pensando em fazer in-house: é possível, se a equipe interna tem PHP/MySQL/Linux sólido, está disposta a fazer staging clone, snapshot por etapa, testes com usuários reais e backup validado. Para quem não tem esse luxo de tempo e expertise, terceirizar com quem já fez dezenas vale o investimento — porque o custo de quebrar um Moodle em produção (perda de dados, downtime no semestre, conflito com cliente) é absurdamente maior que o custo do upgrade bem feito.

Se você está em Moodle 3.x ou 4.x antigo agora, em junho de 2026, vale uma decisão consciente: ou planeja o upgrade nos próximos 6 meses (antes da próxima auditoria, antes do próximo semestre, antes do próximo audit de compliance), ou aceita que a plataforma vai virar dívida técnica acelerada. Não tem terceira opção.