Correção de charset no Moodle

O Moodle é um LMS de código aberto amplamente utilizado por instituições e educadores para ambientes virtuais de ensino. O nome vem de Modular Object-Oriented Dynamic Learning Environment.

Um ponto crítico do Moodle é a codificação do banco de dados. Problemas de charset podem causar:

• textos com caracteres inválidos;
• arquivos exibidos com codificação incorreta;
• falhas em chamadas Ajax por inconsistência de strings.

Mesmo com debug habilitado, muitas vezes a causa real só aparece no error_log do servidor. Se o problema estiver ligado a charset/collation, o fluxo abaixo resolve na maioria dos casos.

Backup do sistema e banco de dados

Antes de qualquer alteração, faça backup.

Exemplo com cópia para testes:

• original: banco_01
• cópia: banco_01_fix

Esse processo pode ser executado em shell enjaulado, sem root.

Verificando o charset atual

mysql -e "USE banco_01_fix; SHOW VARIABLES WHERE Variable_name LIKE 'character_set_%' OR Variable_name LIKE 'collation%';"

Resultado comum:

utf8mb4_general_ci

Alterando o charset

O Moodle recomenda utf8mb4_unicode_ci.

Edite config.php na raiz do Moodle e aponte temporariamente para o banco de teste:

$CFG->dbname = 'banco_01_fix'; // original era banco_01

Converta para a collation recomendada:

php admin/cli/mysql_collation.php --collation=utf8mb4_unicode_ci

Aviso: em bancos grandes, o processo pode demorar.

Defina a collation no config.php:

$CFG->dboptions = array(
  'dbcollation' => 'utf8mb4_unicode_ci',
);

Forçando MySQL para UTF-8 (opcional)

Aviso: execute apenas em último caso.

Edite /etc/mysql/my.cnf:

[client]
default-character-set = utf8mb4

[mysqld]
character_set_server = utf8mb4
collation_server = utf8mb4_unicode_ci
skip-character-set-client-handshake

Depois, repare e otimize bancos:

mysqlcheck -u root -p --auto-repair --optimize --all-databases

Observações importantes

• O diretório moodledata deve ser gravável.
• Ele é definido no config.php.
• Em alguns ambientes, permissões amplas são usadas para compatibilidade, mas

isso aumenta risco de segurança.

• A recomendação oficial é manter moodledata fora da public_html.
• Em alguns painéis (como Hestia), isso pode exigir adaptação de arquitetura.
• Valide permissões e ownership de forma consistente com seu stack web/PHP.

Este post está licenciado sob CC BY-NC.