Arquitetura XOOPS

Este documento fornece uma visão geral abrangente da arquitetura do sistema XOOPS, explicando como os vários componentes funcionam juntos para criar um sistema de gerenciamento de conteúdo flexível e extensível.

Visão Geral

O XOOPS segue uma arquitetura modular que separa as preocupações em camadas distintas. O sistema é construído em torno de vários princípios principais:

Modularidade: A funcionalidade é organizada em módulos independentes e instaláveis
Extensibilidade: O sistema pode ser estendido sem modificar o código principal
Abstração: As camadas de banco de dados e apresentação são abstraídas da lógica de negócio
Segurança: Mecanismos de segurança integrados protegem contra vulnerabilidades comuns

Camadas do Sistema

graph TB
    subgraph Presentation["🎨 Camada de Apresentação"]
        Themes["Temas"]
        Templates["Templates Smarty"]
        Blocks["Blocos"]
    end

    subgraph Application["⚙️ Camada de Aplicação"]
        Modules["Módulos"]
        Preloads["Preloads"]
        Controllers["Controladores"]
        BlockHandlers["Manipuladores de Blocos"]
    end

    subgraph Domain["📦 Camada de Domínio"]
        XoopsObject["XoopsObject"]
        Handlers["Manipuladores de Objetos"]
        Criteria["Sistema de Critérios"]
    end

    subgraph Infrastructure["🔧 Camada de Infraestrutura"]
        Database["XoopsDatabase"]
        Cache["Sistema de Cache"]
        Session["Gerenciador de Sessão"]
        Security["Camada de Segurança"]
    end

    Presentation --> Application
    Application --> Domain
    Domain --> Infrastructure

    style Presentation fill:#e8f5e9,stroke:#388e3c
    style Application fill:#e3f2fd,stroke:#1976d2
    style Domain fill:#fff3e0,stroke:#f57c00
    style Infrastructure fill:#fce4ec,stroke:#c2185b

1. Camada de Apresentação

A camada de apresentação lida com a renderização da interface do usuário usando o mecanismo de templates Smarty.

Componentes Principais:

Temas: Estilo visual e layout
Templates Smarty: Renderização de conteúdo dinâmico
Blocos: Widgets de conteúdo reutilizáveis

2. Camada de Aplicação

A camada de aplicação contém a lógica de negócio, controladores e funcionalidade do módulo.

Componentes Principais:

Módulos: Pacotes de funcionalidade independentes
Manipuladores: Classes de manipulação de dados
Preloads: Ouvintes de eventos e ganchos

3. Camada de Domínio

A camada de domínio contém objetos de negócio principais e regras.

Componentes Principais:

XoopsObject: Classe base para todos os objetos de domínio
Manipuladores: Operações CRUD para objetos de domínio

4. Camada de Infraestrutura

A camada de infraestrutura fornece serviços principais como acesso a banco de dados e cache.

Ciclo de Vida da Requisição

Entender o ciclo de vida da requisição é crucial para o desenvolvimento eficaz do XOOPS.

Fluxo do Controlador de Página XOOPS 2.5.x

O XOOPS 2.5.x atual usa um padrão Page Controller onde cada arquivo PHP lida com sua própria requisição. As globais ($xoopsDB, $xoopsUser, $xoopsTpl, etc.) são inicializadas durante o bootstrap e disponíveis em toda a execução.

sequenceDiagram
    participant Browser
    participant Entry as modules/mymod/index.php
    participant Main as mainfile.php
    participant Kernel as XOOPS Kernel
    participant DB as $xoopsDB
    participant User as $xoopsUser
    participant Handler as MyObjectHandler
    participant Tpl as $xoopsTpl (Smarty)
    participant Theme

    Browser->>Entry: GET /modules/mymod/index.php

    rect rgb(240, 248, 255)
        Note over Entry,User: Fase de Bootstrap (mainfile.php)
        Entry->>Main: include mainfile.php
        Main->>Kernel: Inicializar Core
        Kernel->>DB: Criar XoopsDatabase (singleton)
        Kernel->>User: Carregar Sessão → $xoopsUser
        Kernel->>Tpl: Inicializar Smarty → $xoopsTpl
        Main-->>Entry: Globais Prontas
    end

    rect rgb(255, 250, 240)
        Note over Entry,Handler: Execução do Controlador de Página
        Entry->>Handler: xoops_getModuleHandler('myobject')
        Handler->>DB: consultar via Critérios
        DB-->>Handler: Conjunto de Resultados
        Handler-->>Entry: XoopsObject[]
    end

    rect rgb(240, 255, 240)
        Note over Entry,Theme: Fase de Renderização
        Entry->>Tpl: $xoopsTpl->assign('items', $objects)
        Entry->>Theme: include header.php
        Entry->>Tpl: $xoopsTpl->display('mymod_index.tpl')
        Entry->>Theme: include footer.php
        Theme-->>Browser: Página HTML Completa
    end

Globais Principais em 2.5.x

Global	Tipo	Inicializado	Propósito
`$xoopsDB`	`XoopsDatabase`	Bootstrap	Conexão com banco de dados (singleton)
`$xoopsUser`	`XoopsUser\|null`	Carregamento de sessão	Usuário atualmente conectado
`$xoopsTpl`	`XoopsTpl`	Inicialização de template	Mecanismo de templates Smarty
`$xoopsModule`	`XoopsModule`	Carregamento de módulo	Contexto do módulo atual
`$xoopsConfig`	`array`	Carregamento de configuração	Configuração do sistema

1. Fase de Bootstrap

// mainfile.php é o ponto de entrada
include_once XOOPS_ROOT_PATH . '/mainfile.php';

// Inicialização do core
$xoops = Xoops::getInstance();
$xoops->boot();

Passos:

Carregar configuração (mainfile.php)
Inicializar autoloader
Configurar tratamento de erros
Estabelecer conexão com banco de dados
Carregar sessão do usuário
Inicializar mecanismo de templates Smarty

2. Fase de Roteamento

// Roteamento de requisição para módulo apropriado
$module = $GLOBALS['xoopsModule'];
$controller = $module->getController();
$controller->dispatch($request);

Passos:

Analisar URL da requisição
Identificar módulo alvo
Carregar configuração do módulo
Verificar permissões
Rotear para manipulador apropriado

3. Fase de Execução

// Execução do controlador
$data = $handler->getObjects($criteria);
$xoopsTpl->assign('items', $data);

Passos:

Executar lógica do controlador
Interagir com a camada de dados
Processar regras de negócio
Preparar dados da visualização

4. Fase de Renderização

// Renderização de template
include XOOPS_ROOT_PATH . '/header.php';
$xoopsTpl->display('db:module_template.tpl');
include XOOPS_ROOT_PATH . '/footer.php';

Passos:

Aplicar layout do tema
Renderizar template do módulo
Processar blocos
Gerar resposta

Componentes Principais

XoopsObject

A classe base para todos os objetos de dados no XOOPS.

<?php
class MyModuleItem extends XoopsObject
{
    public function __construct()
    {
        $this->initVar('id', XOBJ_DTYPE_INT, null, false);
        $this->initVar('title', XOBJ_DTYPE_TXTBOX, '', true, 255);
        $this->initVar('content', XOBJ_DTYPE_TXTAREA, '', false);
        $this->initVar('created', XOBJ_DTYPE_INT, time(), false);
    }
}

Métodos Principais:

initVar() - Definir propriedades do objeto
getVar() - Recuperar valores de propriedade
setVar() - Definir valores de propriedade
assignVars() - Atribuição em massa a partir de array

XoopsPersistableObjectHandler

Lida com operações CRUD para instâncias de XoopsObject.

<?php
class MyModuleItemHandler extends XoopsPersistableObjectHandler
{
    public function __construct(\XoopsDatabase $db)
    {
        parent::__construct($db, 'mymodule_items', 'MyModuleItem', 'id', 'title');
    }

    public function getActiveItems($limit = 10)
    {
        $criteria = new CriteriaCompo();
        $criteria->add(new Criteria('status', 1));
        $criteria->setSort('created');
        $criteria->setOrder('DESC');
        $criteria->setLimit($limit);

        return $this->getObjects($criteria);
    }
}

Métodos Principais:

create() - Criar nova instância de objeto
get() - Recuperar objeto por ID
insert() - Salvar objeto no banco de dados
delete() - Remover objeto do banco de dados
getObjects() - Recuperar múltiplos objetos
getCount() - Contar objetos correspondentes

Estrutura do Módulo

Cada módulo XOOPS segue uma estrutura de diretório padrão:

modules/mymodule/
├── class/                  # Classes PHP
│   ├── MyModuleItem.php
│   └── MyModuleItemHandler.php
├── include/                # Arquivos de inclusão
│   ├── common.php
│   └── functions.php
├── templates/              # Templates Smarty
│   ├── mymodule_index.tpl
│   └── mymodule_item.tpl
├── admin/                  # Área de administrador
│   ├── index.php
│   └── menu.php
├── language/               # Traduções
│   └── english/
│       ├── main.php
│       └── modinfo.php
├── sql/                    # Esquema de banco de dados
│   └── mysql.sql
├── xoops_version.php       # Informações do módulo
├── index.php               # Entrada do módulo
└── header.php              # Cabeçalho do módulo

Container de Injeção de Dependência

O desenvolvimento moderno do XOOPS pode aproveitar a injeção de dependência para melhor testabilidade.

Implementação Básica do Container

<?php
class XoopsDependencyContainer
{
    private array $services = [];

    public function register(string $name, callable $factory): void
    {
        $this->services[$name] = $factory;
    }

    public function resolve(string $name): mixed
    {
        if (!isset($this->services[$name])) {
            throw new \InvalidArgumentException("Service not found: $name");
        }

        $factory = $this->services[$name];

        if (is_callable($factory)) {
            return $factory($this);
        }

        return $factory;
    }

    public function has(string $name): bool
    {
        return isset($this->services[$name]);
    }
}

Container Compatível com PSR-11

<?php
namespace Xmf\Di;

use Psr\Container\ContainerInterface;

class BasicContainer implements ContainerInterface
{
    protected array $definitions = [];

    public function set(string $id, mixed $value): void
    {
        $this->definitions[$id] = $value;
    }

    public function get(string $id): mixed
    {
        if (!$this->has($id)) {
            throw new \InvalidArgumentException("Service not found: $id");
        }

        $entry = $this->definitions[$id];

        if (is_callable($entry)) {
            return $entry($this);
        }

        return $entry;
    }

    public function has(string $id): bool
    {
        return isset($this->definitions[$id]);
    }
}

Exemplo de Uso

<?php
// Registro de serviço
$container = new XoopsDependencyContainer();

$container->register('database', function () {
    return XoopsDatabaseFactory::getDatabaseConnection();
});

$container->register('userHandler', function ($c) {
    return new XoopsUserHandler($c->resolve('database'));
});

// Resolução de serviço
$userHandler = $container->resolve('userHandler');
$user = $userHandler->get($userId);

Pontos de Extensão

O XOOPS fornece vários mecanismos de extensão:

1. Preloads

Os preloads permitem que os módulos se conectem a eventos principais.

<?php
class MymoduleCorePreload extends XoopsPreloadItem
{
    public static function eventCoreHeaderEnd($args)
    {
        // Executar quando o processamento do cabeçalho termina
    }

    public static function eventCoreFooterStart($args)
    {
        // Executar quando o processamento do rodapé começa
    }
}

2. Plugins

Os plugins estendem funcionalidades específicas dentro dos módulos.

<?php
class MymoduleNotifyPlugin
{
    public function onItemCreate($item)
    {
        // Enviar notificação quando item é criado
    }
}

3. Filtros

Os filtros modificam dados conforme passam pelo sistema.

<?php
// Exemplo de filtro de conteúdo
$myts = MyTextSanitizer::getInstance();
$content = $myts->displayTarea($rawContent, 1, 1, 1);

Boas Práticas

Organização de Código

Use namespaces para novo código:

namespace XoopsModules\MyModule;

class Item extends \XoopsObject
{
    // Implementação
}

Siga autoload PSR-4:

{
    "autoload": {
        "psr-4": {
            "XoopsModules\\MyModule\\": "class/"
        }
    }
}

Separe responsabilidades:
- Lógica de domínio em class/
- Apresentação em templates/
- Controladores na raiz do módulo

Desempenho

Use cache para operações custosas
Carregue lazy recursos quando possível
Minimize consultas ao banco de dados usando lote de critérios
Otimize templates evitando lógica complexa

Segurança

Valide toda entrada usando Xmf\Request
Escape output em templates
Use prepared statements para consultas ao banco de dados
Verifique permissões antes de operações sensíveis

Documentação Relacionada

Design-Patterns - Padrões de design usados no XOOPS
Database Layer - Detalhes de abstração de banco de dados
Smarty Basics - Documentação do sistema de templates
Security Best Practices - Diretrizes de segurança

#xoops #arquitetura #core #design #system-design