Where to read about Joomla 4 convention for class names

Question

In a few answers on JSE and looking at the Joomla 4 tutorial on building a new component, I have noticed that the convention for class names appears to have changed, dropping the <component_name> prefix and moving the file name to the prefix.

I have been searching for a few hours now looking for anything that explains the change and what the new convention to be used should be.

Where can I find more information?

Answer 1

Components in J4 use a service-based approach which, in theory, should allow any naming convention. Although for that you'd have to write your own factories.

But if you want to follow same conventions as Joomla core components, start by declaring a namespace in the component's manifest file. The namespace should be in this form:

[Vendor]\Component\[Component Name]

The Component part really shouldn't be needed but, apparently, there is at least one place in core libraries where it's expected for some reason.

The resulting manifest XML would be like this:

<namespace>Irata\Component\MyComponent</namespace>

Optionally, you could better organize your components by moving classes to a subdirectory. Core components use src directory but that's irrelevant. In the manifest you'd have to add a path attribute:

<namespace path="somedirectory">Irata\Component\MyComponent</namespace>

Namespaces declared in the manifest use PSR-4 autoloading. You can read about it here. This should answer most of questions about class/file structure. But there are some Joomla-specific things remaining.

From here, subnamespaces are created per application. Frontend classes are in Site subnamespace, backend classes are in Administrator subnamespace and API application (new in J4) classes are in Api subnamespace. So, for example, classes in administrator/components/com_mycomponent/ should have Irata\Component\MyComponent\Administrator namespace declaration.

When using core MVC factory, model, controller and table classes should be split into subnamespaces by type (Model, Controller and Table) and class names should be composed of item type (article, item or whatever) and class type. For example:

Irata\Component\MyComponent\Administrator\Controller\ItemController
Irata\Component\MyComponent\Administrator\Model\ItemModel
Irata\Component\MyComponent\Administrator\Table\ItemTable

The view is handled differently in that it adds item type as a subnamespace and classes consist of page format (e.g. Html or Feed) and class type (i.e. View):

Irata\Component\MyComponent\Administrator\View\Item\HtmlView
Irata\Component\MyComponent\Administrator\View\Item\FeedView

Form field and rule class name should consist of field/rule type and class type suffix. E.g. if you have a field with type="Dropdown", class name should be DropdownField. There is no limitation to what namespace to use but you have to register it using addfieldprefix or addruleprefix attribute. Also new in J4 are form filters which follow the same convention as fields and rules. Register them using addfilterprefix attribute.

Answer 2

Did you have a look at the Joomla code itself on Github too? https://github.com/joomla/joomla-cms/tree/4.0-dev

When I take a look at the php files in the tmpl directories of components and modules I see the following setup for classNames.

• modules => mod-modulenmame
• components => com-componentname

For instance com_contact. The className for a single contact can be found on line 27 of joomla-cms/components/com_contact/tmpl/contact/default.php

Press the line number and three dots appear. Select option "View git blame" and an overview appears on which commits caused the most recent change on that line. For line 27 it is commit https://github.com/joomla/joomla-cms/blame/ca4670a737a5954804363aee0657593cbff6e665/components/com_contact/tmpl/contact/default.php#L27 It has the following commit message:

[4,0] HTML class naming standard [frontend][com-contact] (#20770)

In this commit you can see the change of old to new classNames and how the new className is setup.

Does this help you to continue?

Answer 3

I managed to find this page in JDocs, while not looking for it, that looks like the closest thing to any sort of formal documentation although it is minimal.

https://docs.joomla.org/J4.x:Namespace_Conventions_In_Joomla

It is a start but it could do with a lot of more elaboration to put things in context as provided by @Sharky in his answer.