This content may be out-of-date

This book was written circa 2022, when Joomla 4 was still a new thing. It has not been updated for Joomla 5 and beyond, and it's no longer being worked on. You can usually find more up-to-date information in the official Joomla! Manual.

Directory structure
Prev Chapter 2. Components Next

Directory structure

The directory structure of a typical Joomla 4 MVC component is as follows, assuming it's called com_example and has the namespace prefix \Acme\Component\Example. Directories are suffixed with /. Please note that capitalisation matters (directory and file names are case-sensitive).

  • administrator/components/com_example/ The component's backend directory

    • forms/ Optional. List view forms and search tools forms (formerly in models/forms)

      • items.xml An example form for the Items list view.

      • filter_items.xml An example search tools form for the Items list view.

      • item.xml An example form for the Item edit view.

      • …

    • language/ Not required but you should always somehow provide language files with your extension. The language files of your component (typically installed in administrator/languages/en-GB)

      • en-GB/ The English (Great Britain) language files. That's the default Joomla language.

        • com_example.ini The main language file for your component's views. Note that there is no longer an en-GB. prefix; it's implied by the directory the language file is in.

        • com_example.sys.ini The language file used by Joomla to display backend menu items, permissions, the component's Options page, core categories used by your component, select menu item types in the menu manager, and render each menu item type's configuration parameters.

    • layouts/ Optional. Any Joomla Layouts you want to ship with your extension for use in its backend.

    • services/ Required. Here lives the Service Provider of your component.

      • provider.php The service provider file.

    • sql/ Optional, unless your extension makes changes to database structure or content.

      • updates/ Required. Your component's schema (database) files applied on each update.

        • mysql/ Optional. Indicates updates for sites running on the MySQL database.

          • 1.0.0-20220815-0000.sql A database update file. You should name them version-date-time.sql. The version part is mandatory.

      • install.mysql.utf8.sql The SQL executed on your component's first installation. Update files are not executed in this case.

      • uninstall.mysql.utf8.sql The SQL executed on your component's uninstallation. Remove any tables or database data you created.

    • src/ Required. The root of your extension's PHP files and the root of the PSR-4 \Acme\Component\Example\Administrator namespace prefix.

      • Controller/ Required. Your component's controllers

        • ItemsController.php An example controller for a ListView

        • ItemController.php An example controller for an AdminView

        • …

      • Dispatcher/ Optional. Holds your custom component dispatcher.

        • Dispatcher.php Your custom component dispatcher.

      • Extension/ Optional. Holds your custom extension class.

        • ExampleExtension.php Your custom extension class.

      • Field/ Optional. Custom form fields. Use them in your XML forms using the attribute addfieldprefix="Acme\Component\Example\Administrator\Field".

      • Model/ Required. Your component's Models.

        • ItemsModel.php An example model for the Items list view.

        • ItemModel.php An example model for the Item view. Handles editing and adding records.

        • …

      • Provider/ Optional. Custom service providers.

        • RouterFactory.php Example of a RouterFactory provider, if you need a frontend SEF URL router.

      • Router/ Optional. The recommended place to put your custom RouterFactory, if you need a frontend SEF URL router.

      • Service/ Optional. Custom services.

        • Html/ Optional. Where your custom HTML services (which are made available through Joomla's HTMLHelper) live.

          • Example.php An example HTML service.

      • Table/ Required. Your Table classes.

        • ItemTable.php An example table class for the items of this component (which should ideally live in the #__example_items table if you want to follow Joomla best practices).

      • View/ Required. Your view classes. All subdirectories must be in Uppercasefirst format and match the controller's name before the Controller word.

        • Items/ The directory for the Items list view.

          • HtmlView.php The HTML view class for rendering this backend view.

        • Item/ The directory for the Item add/edit view.

          • HtmlView.php The HTML view class for rendering this backend view.

    • tmpl/ Required. The view templates for your backend views.

      [Important]Important

      All the sub-directories are in all lowercase. This is VERY important!

      Be careful if you are developing on Windows or macOS (which use case-insensitive filesystems). You might accidentally use MixedCase or Uppercasefirst folder names. While this will work fine on Windows and macOS it will fail on the Linux servers most sites run on. That's because Linux primarily uses case-sensitive filesystems.

      • items/

        • default.php The view template for the Items view.

      • item/

        • edit.php The view template for the Item view.

    • access.xml The component's permissions configuration file

    • config.xml The component;s Options page form file

    • example.xml The component's XML manifest

  • components/com_example/ The component's frontend directory

    • forms/ Optional. Any forms for frontend views (formerly in models/forms).

    • language/ Not required but you should always somehow provide language files with your extension. The language files of your component (typically installed in languages/en-GB)

      • en-GB/ The English (Great Britain) language files. That's the default Joomla language.

        • com_example.ini The main language file for your component's frontend views.

    • layouts/ Optional. Any Joomla Layouts you want to ship with your extension for use in its frontend.

    • src/ Required. The root of your extension's PHP files and the root of the PSR-4 \Acme\Component\Example\Site namespace prefix.

      • Controller/ Required. Your component's controllers

      • Dispatcher/ Optional. Holds your custom component dispatcher for the frontend only.

        • Dispatcher.php Your custom component frontend dispatcher.

      • Model/ Required. Your component's Models.

        • ItemsModel.php An example model for the Items list view.

        • ItemModel.php An example model for the Item view. Handles editing and adding records.

        • …

      • Service/ Optional. Custom services.

        • Category.php Optional. Your site's category service.

        • Router.php Optional. Your site's SEF router.

      • View/ Required. Your frontend view classes. All subdirectories must be in Uppercasefirst format and match the controller's name before the Controller word.

    • tmpl/ Required. The view templates for your backend views. All the sub-directories are in all lowercase.

  • api/components/com_example/ Optional. Your Joomla API application integration. Just having this directory is not enough, you will also need a published plugin for your application in the webservices folder.

    • src/ Required. The root of your extension's PHP files and the root of the PSR-4 \Acme\Component\Example\Api namespace prefix.

      • Controller/ Required. Your component's controllers

      • View/ Required. Your API view classes. All subdirectories must be in Uppercasefirst format and match the controller's name before the Controller word. Note that these views DO NOT use view template files; they return JSON data directly.

  • media/com_example/ Optional. Your component's static assets.

    • css/ Optional. Custom CSS files for your component.

    • js/ Optional. Custom JavaScript files for your component.

    • joomla.asset.json The WebAssetManager configuration file for your static assets.

Prev Up Next
Dispatching the component Home Service provider

Tags

Joomla! how-to opinion developers Linux PHP security Obsolete review macOS Windows Mandriva