Helpers¶
The helper class is where a module does its work. It gathers whatever data the
layout needs, exposes it as properties, and requires the layout. By convention
it lives in helper.php beside the entry file and is named Helper, and it
extends Hubzero\Module\Module.
It exists for a reason that has nothing to do with tidiness. The loader
includes the entry file once per instance, so anything declared at that
file's top level is declared twice the second time the module appears on a
page. Putting the class behind a require_once in a separate file is what
makes a module safe to place more than once. See
Controllers.
The base class¶
Hubzero\Module\Module extends Hubzero\Base\Obj and mixes in two traits,
AssetAware and Escapable. It is small enough to hold in your head:
| Member | What it is |
|---|---|
$params |
Hubzero\Config\Registry of the instance's parameters. |
$module |
The #__modules row for this instance. |
__construct($params, $module) |
Stores both. Takes them positionally, in that order. |
display() |
Requires the layout named by the layout parameter, defaulting to default. |
getLayoutPath($layout = 'default') |
Resolves a layout name to a file path, honouring template overrides. |
getCacheContent() |
Returns cached output for this instance, generating it by calling run() if the cache is cold. |
css(), js(), img() |
From AssetAware. See Assets. |
escape($var), setEscape($spec) |
From Escapable. Escapes a value for output; htmlspecialchars by default. |
Because it extends Obj, the class also carries the error bag: setError(),
getError(), getErrors().
The smallest one that works¶
The whole of mod_upcoming_bookings/helper.php:
Properties set on $this before the require are visible to the layout,
because the layout is included in the method's scope. There is no separate
view object and no assign() step.
Components\Bookings\Models\Reservation needs no require: the class loader
maps Components\ namespaces to component directories on its own. Several
shipped modules still write include_once Component::path('com_groups') . DS .
'models' . DS . 'recent.php'; before naming the class. That is the older
convention, from before the class loader covered extension namespaces; it is
harmless but do not copy it. See
Autoloading.
Warning
use User; is not optional. Inside
namespace Modules\UpcomingBookings an unqualified User resolves to
Modules\UpcomingBookings\User, which does not exist, and the call is a
fatal error — a white page, or an exception trace naming a class you never
wrote. Import every facade the file names: App, Lang, Request,
Route, User, Component, Plugin, Date. See
Facades.
Warning
A module is rendered inside somebody else's page, so an
uncaught exception in display() takes the whole page with it — not just
the block. Nothing wraps the include in a try. A model call that can throw
because the component is missing, or a table that does not exist yet, breaks
every page the module is placed on.
Choosing a layout¶
display() on the base class requires the layout named by the layout
parameter. If you override display(), you choose the layout yourself.
mod_mygroups switches on a parameter:
Parameters¶
$this->params is a Registry built from the instance's params column, so
every field declared in the manifest's <config> block is readable by name,
with a fallback for the case where an administrator never saved the form:
Parameters are what let one module serve two placements. mod_upcoming_bookings
declares limit and instrument_id, so the same code renders "your next five
bookings, anywhere" in the sidebar and "your next booking on the confocal" on
the instrument's own page, without a second module.
Warning
Always pass the default to get(). The default attribute in
the manifest is applied by the form, not by the Registry, so an instance
saved before you added the field has no value for it and
$this->params->get('limit') returns null. That is not an error anywhere
down the stack: limit(null) becomes limit(0), and the query builder
emits LIMIT 18446744073709551615. Your five-item sidebar block quietly
becomes every row in the table.
Caching¶
Cache a module when the query behind it is expensive and its output is the
same for everybody. getCacheContent() gives an opt-in output cache keyed on
the instance id. It returns an empty string — meaning "no cached content, do
the work" — unless a cache store is configured, the instance's cache
parameter is on, cache_time is non-zero, and the application is not in debug
mode. On a miss it buffers a call to run(), appends an HTML comment
recording when the copy was made, stores it, and returns it.
That contract splits the class in two: run() produces the output, and
display() decides whether to reuse a stored copy. mod_findresources is the
pattern in full:
Note
A module that calls getCacheContent() must define run().
The base class does not: getCacheContent() calls $this->run(), and a
module without one fatals the first time the cache misses.
Warning
The cache key is modules.{id} and nothing else. It does not
vary by user, view level, or menu item. Cache a per-user module and the
first visitor's output is served to everyone else — mod_upcoming_bookings
would show one researcher's reservations to the whole hub. That is a data
leak, not a rendering bug, and nothing in the framework stops you: the
cache parameter is on the instance, so an administrator can switch it on
for a module you never intended to cache. Do not declare cache and
cache_time fields in the manifest of a module whose output is per-user.
mod_findresources lists popular tags and caches; mod_mygroups is
per-user and does not.
cache_time is stored in seconds by the Module Manager but the cache store
takes minutes, so getCacheContent() divides values above 120 by 60 and
passes smaller values through unchanged. A cache_time of 900 caches for
fifteen minutes; a cache_time of 30 caches for thirty minutes, not thirty
seconds.
More than one class¶
Nothing limits a module to one class. Put additional classes in their own
files under the module directory and require_once them from helper.php,
keeping them in the module's namespace so they cannot collide with another
extension's.
require_once them by path, not by name. The class loader resolves
Modules\… by collapsing the namespace segment to one word, so a class in
mod_upcoming_bookings is looked for under mod_upcomingbookings and never
found — see Structure and
Autoloading.
Before you add the second class, ask whether it belongs in the component. A
"does this reservation clash" method is the Reservation model's, and putting
it in the module hides it from the administrator screens that need the same
rule.
Rewritten and checked against 2.4-main @ 91d03d0a23 on 2026-09-10.