Config¶
Four kinds of configuration exist on a hub, and each is reached a different
way: the global settings, and the parameters belonging to a component, a
plugin, or a module. All four end up as a
Hubzero\Config\Registry
with the same get() on it.
Which one you want depends on who is meant to set the value:
| The value is | Where it belongs | How to read it |
|---|---|---|
| The same for the whole hub — the site name, the time zone, the mail server | Global configuration | Config::get('offset') |
| A setting for your component that an administrator changes once — how many bookings a page lists | The component's config/config.xml |
Component::params('com_bookings') |
| A setting for one instance of a plugin | The plugin's manifest | $this->params inside the plugin |
| A setting for one placement of a module on one page | The module instance | $this->params inside the module |
A value that a member sets is none of these. That is a user parameter —
User::getParam(), see users — or a column on one of your own
tables.
Warning
A parameter that is not declared in the extension's XML can
still be read, and comes back as your default. Nothing reports that the
field does not exist, so a typo in a parameter name looks exactly like an
administrator who has not set it yet. com_tags has three of these:
show_sizes, show_tag_count and show_tags_sort are read by its layout
and declared in no manifest, so the tag cloud takes its defaults on every
hub. Check the name against the XML when a setting appears to have no
effect.
Global configuration¶
The site settings live in app/config/, one PHP file per group, each
returning a plain array:
Hubzero\Base\Application builds a
Hubzero\Config\Repository
for the current client during boot — before any service provider runs,
because the providers read it — and binds it as config. Its file loader
globs every file in app/config/ and keys the result by filename. Read it
through the facade:
The repository flattens the groups on read. cache_handler lives in
app/config/cache.php and sitename in app/config/app.php, but both are
reached by their bare name — Config::get() scans the groups for the key
before falling back to dotted-path lookup. That is why nothing in the tree
writes Config::get('cache.cache_handler').
App::get('config') returns the same object, which also implements
ArrayAccess, Countable and IteratorAggregate, so $config['sitename']
and foreach work on it.
Note
Configuration is read-only from an extension's point of view.
set() exists on the registry, but it changes the in-memory copy for the
rest of this request and nothing else. The administrator's Global
Configuration screen is what writes the files back.
The configuration reference lists every option the tree declares.
Component configuration¶
A component's options come from its config/config.xml and are stored in
the #__extensions row. Read them through the Component facade:
Component::params($option, $strict = false) returns a Registry. Inside a
controller extending Hubzero\Component\SiteController or
AdminController the same object is already on $this->config, so use that
rather than calling the facade again.
A menu item can override component parameters for the page it points at. Where that matters, controllers merge the menu item's params over the component's; the merged result is what the view should read.
Plugin configuration¶
A plugin's own parameters are on $this->params, populated before any event
method runs:
From outside the plugin, ask the Plugin facade for them by group and
name:
Plugin::byType($type, $plugin = null) returns the plugin records
themselves — id, name, type, params — when you need more than the
parameters. Note the argument order: the group first (authentication,
content, cron), the individual plugin second.
Module configuration¶
A module's parameters are on $this->params in the module class, and are
the values an administrator entered on that module instance:
The same object is available inside the module's layout as $this->params,
because the layout is included from within the module object.
Reading a Registry¶
All four return the same class, so the same methods apply:
| Method | What it does |
|---|---|
get($path, $default = null) |
Read a value, dotted paths supported |
has($path) |
Whether the path is set |
set($path, $value) |
Set it, in memory |
def($key, $default = '') |
Set only if not already set |
merge($source, $recursive = false) |
Merge another registry or array over this one |
toArray() / toObject() |
Convert |
toString($format = 'json') |
Serialise; json, ini, xml, php, yaml |
A value read out of a Registry is whatever was stored — usually a string,
even for a number or a checkbox. Cast it where the type matters:
get('limit') returns "25", not 25. It behaves as a number in
arithmetic and in a query, so the fault only surfaces where the type is
checked: a strict === 25 is false, in_array($v, [1, 2], true) is false,
and a parameter typed int on a method signature raises a TypeError under
strict_types. Cast on the way out of the registry, once.
Rewritten and checked against 2.4-main @ 348f0057c2 on 2026-09-10.