Structure¶
A component is a directory named com_{componentname}, split first by client
and then by role. This page shows the layout of a real one, explains how class
names map onto it, and follows a request from the URL to the controller.
Almost nothing here is configurable, and that is the point: put a file in the place the convention names and it is found, with no registration anywhere. Put it a directory to one side and nothing reports it — the class simply does not exist, and the first line that mentions it is a fatal.
The layout¶
Everything below is from core/components/com_kb, with a few files elided:
config/, migrations/, and models/ sit above the client directories
because all three clients use them. Everything else belongs to exactly one
client. A component may also carry a helpers/ directory at the top level for
helpers shared between clients, and a tests/ directory.
com_bookings is the same shape with two clients and no API:
Namespaces and the class loader¶
Every component class lives under the Components namespace, and the segment
after it is the studly-cased component name without the com_ prefix:
Hubzero\Base\ClassLoader,
registered in core/bootstrap/app.php, resolves those names. It drops the
Components\ prefix, lowercases the component name and prefixes it with
com_, and joins the rest with directory separators:
Both the studly-cased and the wholly lowercased path are tried, against
PATH_APP first and then PATH_CORE. This is the one place the naming
convention bends: files and directories may be lowercase even when the class
name is not. Practically every component in the tree uses the lowercase
form, and so should yours; the mixed-case path is a fallback, not a choice
worth making.
Note
Whichever root holds the extension owns it. If
app/components/com_kb/ exists, no class is ever loaded from
core/components/com_kb/ — not even one the app copy does not define. This
is why a partial copy of a core component is a broken copy: the loader finds
the app directory, stops looking, and every class you did not copy is
missing.
Because classes autoload, require_once on a component class is redundant.
Several shipped components still do it — com_kb's entry points among them —
which is harmless but is inherited practice, not the current one. Leave it out
of new code.
The name is load-bearing¶
SiteController's constructor derives the component from the class
namespace, not from the directory or the request: it explodes the class name
and takes the second segment. Components\Bookings\Site\Controllers\Instruments
gives $this->_name = 'bookings' and $this->_option = 'com_bookings'.
Get the namespace segment and the directory out of step — a class declared
namespace Components\Booking\... inside com_bookings/ — and nothing throws.
The controller quietly reports itself as com_booking: it loads that
component's parameters (empty), looks for com_booking's language file
(missing, so every string renders as its own key), and Route::url() builds
URLs into a component that is not there.
The entry point¶
The URL carries the component in option:
With search engine friendly URLs on, the first path segment names the component instead, and the rest is handed to the component's router:
Either way the application ends at Component::render('com_bookings') in
Hubzero\Component\Loader.
That method defines PATH_COMPONENT (the client directory,
com_bookings/site or com_bookings/admin), plus PATH_COMPONENT_SITE and
PATH_COMPONENT_ADMINISTRATOR, loads the component's language files, and then
looks for something to run, in this order:
- a
Components\{Name}\{Client}\Bootstrapclass, whosestart()method is called; PATH_COMPONENT/{componentname}.php, which is simplyrequired;- a directory
PATH_COMPONENT/assets/react/{componentname}, run as a React application; - failing all of those, a
Hubzero\Component\DefaultSiteControlleris synthesised for the requested controller.
Every component in the tree today uses the second form, and it is the one to
write. Here is the whole of com_kb's site entry point:
That is the minimum: a namespace, a controller, execute(). (The two
require_once lines above it in the file are the inherited habit noted above;
the class loader covers both.) The administrator entry point does more,
because the administrator needs an authorisation gate and a sub-menu:
Three things are worth copying from it. The core.manage check is what keeps
non-managers out of the whole client — no controller sees the request without
it, and leaving it out means every logged-in user can reach the administrator
screens by typing the URL. Submenu::addEntry() builds the row of links under
the toolbar. And the controller name comes from the request, with a fallback,
so index.php?option=com_bookings&controller=reservations reaches
Components\Bookings\Admin\Controllers\Reservations.
Note
Entry point files are namespaced, so the facades they call must be
imported or fully qualified. com_kb's administrator entry point writes
\User::authorise() and \Route::url() with a leading backslash for
exactly this reason; see
Facades. The file parses
either way — the fatal arrives only when the line runs.
Do not close the PHP tag in a file that contains only PHP. A stray newline
after ?> becomes output, and output before the document is assembled breaks
redirects and headers.
What the directory alone gets you¶
Placing the directory on disk is enough to make a component run. When
Component::load() finds no row in #__extensions it builds a default record
with enabled set to 1, so the component executes.
What a missing row costs you is everything stored against it: the component
does not appear in the administrator's list of components,
Component::params() returns an empty registry, and there is no asset row for
its permissions. A migration creates that row, and that is
the step to do before anything else.
Rewritten and checked against 2.4-main @ 348f0057c2 on 2026-09-10.