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.

Global configuration

The site settings live in app/config/, one PHP file per group, each returning a plain array:

// app/config/app.php
return array(
    'secret'        => '26a6751ffda14c...',
    'sitename'      => 'myhub',
    'debug'         => '0',
    'offset'        => 'America/New_York',
    'site_template' => 'hubzero',
);

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:

use Config;

$name   = Config::get('sitename');
$offset = Config::get('offset');
$limit  = Config::get('list_limit', 25);

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.

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:

use Component;

$params = Component::params('com_bookings');

$limit  = (int) $params->get('display_limit', 25);
$access = $params->get('access-view');

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:

class plgSystemExample extends \Hubzero\Plugin\Plugin
{
    public function onAfterRoute()
    {
        $timeout = $this->params->get('timeout', 30);
    }
}

From outside the plugin, ask the Plugin facade for them by group and name:

use Plugin;

$params = Plugin::params('authentication', 'facebook');

$appid  = $params->get('app_id');

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:

namespace Modules\Featured;

use Hubzero\Module\Module;

class Featured extends Module
{
    public function display()
    {
        $limit = $this->params->get('limit', 5);

        require $this->getLayoutPath();
    }
}

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

$params = Component::params('com_bookings');
$params->merge($menuParams);

if ($params->has('feed_email'))
{
    // ...
}

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:

$limit = (int) $params->get('limit', 25);

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.