Dev Wiki | Johnny Salazar Reidel

Orientações para desenvolvimento de extensões Joomla no projeto Guideway LMS

Detalhes
Escrito por Johnny Salazar Reidel
Categoria: Conteúdo de apoio programa TIC

Este documento serve como um guia para o desenvolvimento de novas funcionalidades para a extensão SP LMS em um ambiente Joomla 5. O objetivo é equilibrar a manutenção de uma extensão legada com a adoção das práticas modernas de desenvolvimento do Joomla.

Como recurso complementar, a gravação da nossa aula introdutória sobre este tópico realizada em 27/10/25 está disponível no link a seguir: https://www.youtube.com/watch?v=tcomtN0ol-M

 

1. O que é o Joomla?

O Joomla! é um Sistema de Gerenciamento de Conteúdo (CMS - Content Management System) de código aberto, escrito em PHP. Ele é usado para criar, publicar e gerenciar conteúdo em websites, blogs, intranets e aplicações web complexas. Sua força reside na flexibilidade e extensibilidade.

 

2. A Evolução do Código: Do Joomla 3 ao 6

É crucial entender a mudança de paradigma que ocorreu no Joomla:

  • Joomla 3 -> Joomla 4 (A Grande Mudança): Esta não foi uma simples atualização, mas uma refatoração profunda. O Joomla 4 modernizou todo o "core", introduzindo:

    • Namespaces*: A mudança mais significativa, alinhando o Joomla com as práticas modernas do PHP (PSR-4).

    • Nova Arquitetura MVC*: Mais limpa e organizada.

    • Injeção de Dependência e Serviços*: Para um código mais desacoplado.

    • Web Asset Manager*: Para gerenciamento moderno de CSS/JS.

    • Bootstrap 5*: Atualização da interface do usuário.

    • APIs de Webservices integradas.

  • Joomla 4, 5 e 6 (Evolução Rápida): Após a grande mudança do Joomla 4, a plataforma adotou um ciclo de lançamento mais rápido (versionamento semântico). As versões 5 e 6 não são uma quebra como foi a passagem do 3 para o 4. Elas são evolutivas. O Joomla 5 é o Joomla 4 refinado, e o Joomla 6 é o Joomla 5 refinado, garantindo uma base de código moderna e maior facilidade na atualização.

* O que são Namespaces? São uma forma de agrupar classes, funções e constantes relacionadas, evitando conflitos de nomes no código. É como ter "pastas" virtuais para o seu código PHP.

* O que é MVC? MVC (Model-View-Controller) é um padrão de arquitetura de software que separa a aplicação em três componentes principais: Model (Modelo: lida com os dados e a lógica de negócios), View (Visão: é a interface do usuário, o que é exibido) e Controller (Controlador: recebe as entradas do usuário e coordena entre o Model e a View).

* O que é Injeção de Dependência e Serviços? É um padrão de design onde os componentes de um software recebem suas dependências (outros objetos de que precisam) de fora, em vez de criá-los internamente. Isso torna o código mais flexível, testável e desacoplado.

* O que é o Web Asset Manager? É o sistema moderno do Joomla (a partir do J4) para gerenciar o carregamento de arquivos JavaScript (JS) e CSS. Ele permite controlar dependências (ex: carregar o jQuery antes de um script que o utilize) e garante que os arquivos sejam carregados de forma otimizada.

* O que é Bootstrap 5? É um popular framework de front-end (HTML, CSS e JS) para construir interfaces de usuário responsivas (que se adaptam a desktops, tablets e celulares). O Joomla 4+ o utiliza como base para o design do back-end e do template padrão (Cassiopeia).

  • O que é Autoloading (PSR-4)? É um padrão que permite ao PHP carregar classes automaticamente quando elas são necessárias, em vez de exigir que você inclua manualmente todos os arquivos PHP no início do script. O padrão PSR-4 define uma regra de como o "Namespace" de uma classe deve corresponder à estrutura de pastas do sistema de arquivos (ex: a classe MeuProjeto\Http\Request seria procurada no arquivo src/Http/Request.php).

 

3. Principais Tipos de Extensões

É importante entender que o Joomla já vem com um conjunto de extensões "nativas" (ou "core"), como o com_content (Artigos) e o com_users (Usuários). O poder do Joomla está na capacidade de desenvolver novas extensões (como o com_splms) que se integram ao sistema, ou instalar extensões de terceiros.

Existem cinco tipos principais de extensões que você pode construir:

  • Componentes (Components): Pense neles como a "aplicação principal" da página. Em uma URL do Joomla, é o componente que é chamado para renderizar a área de conteúdo central. Quando você lê um artigo (com_content) ou vê um curso no SP LMS (com_splms), é o componente que está no controle dessa visualização. Ele cuida da lógica de negócios, do acesso ao banco de dados (Model), das regras (Controller) e da geração do HTML principal (View). Cada página do Joomla carrega um componente principal por vez.

  • Módulos (Modules): São blocos de informação e funcionalidade que podem ser exibidos em múltiplos locais, não apenas ao redor do componente principal. Embora sejam comumente associados a posições pré-definidas no Template (ex: 'left', 'right', 'top', 'bottom'), eles também podem ser carregados de formas mais dinâmicas:

    • Dentro do Conteúdo: Em artigos, usando shortcodes do plugin "Content - Load Modules" (ex: { loadposition minhanovaposicao} ou { loadmoduleid 123}).

    • Em Extensões de Terceiros: Como dentro do SP Page Builder.

    • Diretamente no Código: Chamados via PHP de dentro de um componente ou outro módulo.

    Pense em: menus (mod_menu), o carrinho de compras (mod_splmscart), ou uma lista de "Cursos Populares" (mod_splmscourses). Novas posições de módulo podem ser criadas para esses carregamentos dinâmicos, e módulos podem ser carregados tanto pela posição quanto pelo ID. Vários módulos podem ser carregados na mesma página.

  • Plugins (Plugins): São extensões poderosas e "invisíveis" que rodam em resposta a gatilhos (eventos) específicos do sistema. Eles modificam o comportamento padrão do Joomla. Por exemplo, um plugin pode:

    • Interferir antes de um artigo ser salvo (evento onContentBeforeSave) para validar um campo extra.

    • Modificar o HTML de um artigo depois dele ser renderizado (evento onContentAfterDisplay) para adicionar botões de compartilhamento social.

    • Rodar após o login do usuário (evento onUserLogin, como o user_lmsprofile) para carregar dados extras do perfil do aluno.

  • Templates (Templates): Controlam todo o design visual e a estrutura de layout do site (front-end e back-end). É o template que define as "posições" onde os módulos podem ser publicados.

  • Bibliotecas (Libraries): Conjuntos de código reutilizados que podem ser usados por qualquer outra extensão.

 

4. Estrutura Legada (J3) vs. Moderna (J4+)

A diferença na estrutura de arquivos e classes é a principal barreira entre as versões:

Característica

Joomla 3 (Legado)

Joomla 4 / 5 / 6 (Moderno)

Namespaces

Não usa.

Obrigatório. (Ex: Joomla\CMS\Factory)

Nomes de Classes

Classes "J" globais (Ex: JFactory, JControllerLegacy).

Classes com namespace (Ex: Factory, BaseController).

Estrutura

Arquivos de entrada (splms.php) misturados com lógica.

Estrutura MVC clara, com autoloading (PSR-4)* e arquivos de serviço (services/provider.php).

Dependências

JFactory para tudo (JFactory::getDbo(), JFactory::getApplication()).

Injeção de dependência ou Factory com namespace (Factory::getDatabase(), Factory::getApplication()).

Assets (JS/CSS)

JHtml::_('script', ...)

Web Asset Manager ($wa = Factory::getApplication()->getDocument()->getWebAssetManager(); $wa->useScript('meu-script');)

Esta mudança de arquitetura reflete-se diretamente na estrutura de arquivos. A simulação abaixo mostra a diferença de organização para um componente (ex: com_mycomponent) no lado administrator.

Simulação de Estrutura Legada (Joomla 3) - Componente:

com_mycomponent/ (administrator)
├── mycomponent.php       (Arquivo de entrada principal)
├── controller.php          (Controlador principal)
├── controllers/
│   ├── item.php
│   └── list.php
├── models/
│   ├── item.php
│   └── list.php
├── tables/
│   └── item.php
├── views/
│   └── item/
│       ├── view.html.php (Classe da View)
│       └── tmpl/
│           ├── default.php (Layout/Template da View)
│           └── edit.php
└── mycomponent.xml         (Manifesto)

Simulação de Estrutura Moderna (Joomla 4/5/6) - Componente:

com_mycomponent/ (administrator)
├── tmpl/                     <-- (Layouts movidos para a raiz)
│   └── Item/
│       ├── default.php
│       └── edit.php
├── src/                      <-- (Todo o código PHP com Namespace)
│   ├── Controller/
│   │   ├── ItemController.php
│   │   └── ListController.php
│   ├── Extension/
│   │   └── MycomponentComponent.php (Ponto de Entrada / Dispatcher)
│   ├── Model/
│   │   ├── ItemModel.php
│   │   └── ListModel.php
│   ├── Table/
│   │   └── ItemTable.php
│   └── View/
│       └── Item/
│           └── HtmlView.php (Classe da View)
├── services/
│   └── provider.php      (Injeção de Dependência)
└── joomla.xml            (Manifesto, define Namespaces e PSR-4)

Simulação de Estrutura Legada (Joomla 3) - Módulo:

mod_mymodule/ (site)
├── mod_mymodule.php      (Arquivo de entrada principal, lógica)
├── helper.php            (Classe Helper, ex: ModMyModuleHelper)
├── tmpl/
│   └── default.php     (Layout/Template da View)
└── mod_mymodule.xml      (Manifesto)

Simulação de Estrutura Moderna (Joomla 4/5/6) - Módulo:

mod_mymodule/ (site)
├── tmpl/
│   └── default.php     (Layout/Template da View)
├── src/
│   ├── Helper/
│   │   └── MyModuleHelper.php (Classe Helper com Namespace)
│   └── Dispatcher/
│       └── Dispatcher.php   (Ponto de entrada moderno)
├── services/
│   └── provider.php      (Injeção de Dependência)
└── joomla.xml            (Manifesto, define Namespaces e PSR-4)

 

5. Cenário do Projeto: SP LMS no Joomla 5

Este é o nosso desafio central. Preste atenção nesta seção.

  • Ambiente: Joomla 5.

  • Extensão Principal: SP LMS.

  • Extensões Instaladas:

    • com_splms (Componente principal)

      • Caminho (Admin): administrator/components/com_splms

      • Caminho (Site): components/com_splms

    • mod_splmscart

      • Caminho (Site): modules/mod_splmscart

    • mod_splmscoursecategories

      • Caminho (Site): modules/mod_splmscoursecategories

    • mod_splmscoursesearch

      • Caminho (Site): modules/mod_splmscoursesearch

    • mod_splmscourses

      • Caminho (Site): modules/mod_splmscourses

    • mod_splmsperson

      • Caminho (Site): modules/mod_splmsperson

    • user_lmsprofile (Plugin)

      • Caminho: plugins/user/lmsprofile

 

O Desafio: Estrutura Legada

As extensões SP LMS foram construídas na arquitetura antiga do Joomla 3 (sem namespaces, classes J...). Elas só funcionam no Joomla 5 porque o Plugin de Compatibilidade (System - B/C) está ativo. Este plugin "traduz" as chamadas antigas para as novas, mas não é o ideal.

 

A Diretriz de Desenvolvimento

Não temos tempo para migrar toda a extensão SP LMS para a arquitetura moderna. No entanto, para garantir a evolução e a manutenibilidade do projeto, todo novo desenvolvimento deve seguir as práticas modernas.

  1. Código Novo = Código Moderno: Ao criar novos recursos dentro do com_splms, ou ao criar um novo módulo (ex: mod_meunovomodulo, caso precise criar novos módulos), você deve usar a structure do Joomla 5/6:

    • Use Namespaces para suas novas classes.

    • Use o Web Asset Manager para adicionar JS e CSS.

    • Use as classes Factory, Uri, Text, etc., com seus namespaces (Joomla\CMS\Factory).

    • Siga o tutorial de "Criação de Módulos" moderno (link abaixo), caso precise criar novos módulos.

  2. Evite Funções Legadas: No seu código novo, não use vistas legadas (ex: JFactory, JRequest, JHtml::_('script')). Seu código novo não deve depender do plugin de compatibilidade.

  3. Foco na Documentação Oficial: A orientação de não usar buscadores é vital. Buscadores frequentemente retornam tutoriais antigos (Joomla 1.5, 2.5, 3) que usarão código legado e prejudicarão seu aprendizado. A única fonte de verdade deve ser o portal oficial: https://manual.joomla.org/.

 

6. Links de Documentação (manual.joomla.org)

Use os links abaixo como referência primária para o desenvolvimento moderno no Joomla 4, 5 e 6.

 

Tutoriais Específicos

 

Conceitos Gerais (Modernos)

Categorias