Skip to content
Tutorials Center
My learning

Topics

Lesson 30 of 37 ยท Development and Security

Component Structure and MVC

Understand how a modern Joomla component is built: folder layout, namespaces, service provider, dispatcher, controller, model, view and layout, with a runnable PHP stand-in.

Sooner or later a site needs something Joomla and the directory cannot supply: a booking form tied to your own tables, a staff directory with special rules, an import tool. That is the moment to write your own component, and understanding its structure also helps you read, debug and safely customize third-party components.

Joomla 4 and 5 use a modern architecture: PSR-4 namespaces, a dependency-injection container and a clean MVC (Model, View, Controller) split. Joomla cannot run on this site, so the Joomla code below is read-only, and the TryIt blocks are small plain-PHP stand-ins that show the same flow. You need basic PHP; if it is new to you, see the PHP tutorial first.

How a request reaches a component

A front-end URL such as /index.php?option=com_hello&view=hello is routed like this:

flowchart LR
    R["Request option=com_hello"] --> D["Dispatcher"]
    D --> C["Controller (task)"]
    C --> M["Model (data)"]
    C --> V["View (HtmlView)"]
    M --> V
    V --> T["Layout tmpl/hello/default.php"]
    T --> O["HTML output in the template"]

Dispatcher, controller, model, view, layout.

  • The option parameter names the component (com_hello).
  • The dispatcher loads the right controller, based on the task (for example hello.save) or the default view.
  • The controller handles the request: it validates input, calls the model, then picks a view.
  • The model talks to the database and contains business rules.
  • The view (HtmlView) collects data from the model and passes it to a layout, a PHP template file that prints HTML.

The component's HTML is placed in the main area of the template, and Joomla wraps it with modules in positions (see Cassiopeia and Template Styles).

Folder layout (Joomla 4 and later)

A component has an administrator part and a site part. An abbreviated structure for com_hello:

TEXT
com_hello/
  hello.xml                       <- manifest (type, namespace, files, menus)
  administrator/
    services/provider.php         <- service provider for the admin side
    src/Controller/DisplayController.php
    src/View/Hello/HtmlView.php
    tmpl/hello/default.php
    sql/install.mysql.utf8.sql
  site/
    services/provider.php
    src/Controller/DisplayController.php
    src/Model/HelloModel.php
    src/View/Hello/HtmlView.php
    tmpl/hello/default.php
    forms/ language/ ...
  language/en-GB/com_hello.ini

The manifest declares the namespace, so Joomla can autoload classes by name:

XML
<extension type="component" method="upgrade">
    <name>com_hello</name>
    <version>1.0.0</version>
    <namespace path="src">Example\Component\Hello</namespace>
    <files folder="site">
        <folder>services</folder>
        <folder>src</folder>
        <folder>tmpl</folder>
    </files>
    <administration>
        <menu>COM_HELLO</menu>
        <files folder="administrator">
            <folder>services</folder>
            <folder>src</folder>
            <folder>tmpl</folder>
        </files>
    </administration>
</extension>

Classes then live in Example\Component\Hello\Site\... (front end) and Example\Component\Hello\Administrator\... (back end), for instance Example\Component\Hello\Site\Controller\DisplayController.

The service provider

services/provider.php registers the pieces the component needs in Joomla's container. Joomla 4 and 5 components follow this pattern:

PHP
<?php
\defined('_JEXEC') or die;

use Joomla\CMS\Dispatcher\ComponentDispatcherFactoryInterface;
use Joomla\CMS\Extension\ComponentInterface;
use Joomla\CMS\Extension\Service\Provider\ComponentDispatcherFactory;
use Joomla\CMS\Extension\Service\Provider\MVCFactory;
use Joomla\CMS\MVC\Factory\MVCFactoryInterface;
use Joomla\CMS\Extension\MVCComponent;
use Joomla\DI\Container;
use Joomla\DI\ServiceProviderInterface;

return new class () implements ServiceProviderInterface {
    public function register(Container $container): void
    {
        $container->registerServiceProvider(new MVCFactory('\\Example\\Component\\Hello'));
        $container->registerServiceProvider(new ComponentDispatcherFactory('\\Example\\Component\\Hello'));
        $container->set(ComponentInterface::class, function (Container $container) {
            $component = new MVCComponent($container->get(ComponentDispatcherFactoryInterface::class));
            $component->setMVCFactory($container->get(MVCFactoryInterface::class));
            return $component;
        });
    }
};

It looks verbose, but you copy it once per component and change the namespace. After that the framework finds controllers, models and views by naming convention.

Controller, model, view, layout

PHP
// src/Controller/DisplayController.php
namespace Example\Component\Hello\Site\Controller;

use Joomla\CMS\MVC\Controller\BaseController;

class DisplayController extends BaseController
{
    protected $default_view = 'hello';
}
PHP
// src/Model/HelloModel.php
namespace Example\Component\Hello\Site\Model;

use Joomla\CMS\MVC\Model\BaseDatabaseModel;

class HelloModel extends BaseDatabaseModel
{
    public function getMessage(): string
    {
        return 'Hello from the model';
    }
}
PHP
// src/View/Hello/HtmlView.php
namespace Example\Component\Hello\Site\View\Hello;

use Joomla\CMS\MVC\View\HtmlView as BaseHtmlView;

class HtmlView extends BaseHtmlView
{
    protected $message;

    public function display($tpl = null)
    {
        $this->message = $this->getModel()->getMessage();
        parent::display($tpl);
    }
}
PHP
<?php
// tmpl/hello/default.php
\defined('_JEXEC') or die;
?>
<h1><?php echo $this->escape($this->message); ?></h1>

Note $this->escape() in the layout: always escape values you print, as explained in Security Hardening and Updates. Because the layout lives in tmpl, a site owner can override it from the template (see Template Overrides and Child Templates).

A runnable stand-in

This plain-PHP program is not Joomla: it reproduces the flow (parse request, dispatch, controller, model, view, layout, escape) so you can see how the parts talk. Edit the URLs at the bottom.

PHP A tiny MVC dispatcher

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with fgets(STDIN)), it gets the next line from this box.

The third call shows why escaping matters: the markup in the name appears as text, not as a script.

Where the data goes: tasks and forms

Pages that change data use a task: task=hello.save means controller HelloController, method save. A secure task always checks a form token ($this->checkToken(); in a controller; HTMLHelper::_('form.token') in the form) and permissions ($this->app->getIdentity()->authorise('core.create', 'com_hello')). These protect against cross-site request forgery and unauthorized edits.

PHP Task routing and the token check

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with fgets(STDIN)), it gets the next line from this box.

Development setup tips

  • Develop locally with a throwaway Joomla site and Git, and set Debug System and Error Reporting: Maximum on the development copy only.
  • Package the component as a ZIP with the manifest at its root, then install it through System > Install > Extensions.
  • Use the Database page to confirm tables created by sql/install.mysql.utf8.sql.
  • Keep language strings in .ini files and call Text::_('COM_HELLO_TITLE').

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. In MVC, which part talks to the database?

    The model holds data access and business rules; the view and layout only present.
  2. 2. What does the namespace element in the manifest enable?

    It maps the namespace to the src folder so classes load by PSR-4 naming.
  3. 3. What does task=hello.save select?

    The part before the dot is the controller, the part after is the method.
  4. 4. Which call protects a printed value from carrying markup?

    escape() converts special characters to entities so values render as text.

Summary

  • A request names a component with option; the dispatcher, controller, model, view and layout do the rest.
  • Modern components use PSR-4 namespaces declared in the manifest and a services/provider.php.
  • Site and administrator parts have their own controllers, views and templates.
  • Always escape output, check form tokens and test permissions in tasks.
  • Layouts in tmpl can be overridden by templates.

Next: Plugins and Events