community.aegirproject.org

Using contexts in your code

Updated by Steven Jones on 02/07/2011 - 21:44
AddedChangedDeleted

Getting the current context is really easy, just call the 'd' accessor:

<?php
$current_context = d();
?>
What the current context is will depend on the drush command that is running and the context that was passed into that drush command. For example if you ran a site verify task, then the caller would name a site context, and thus initially calls to d() would return the site context. The values of the context are accessible as simple properties of this object.

So, suppose a verify task it started for the main Aegir frontend, which has a context that is always called '@hostmaster' the drush command invocation would look like this:

drush @hostmaster provision-verify

Then the drush command for provision-verify could do this:

<?php
function drush_provision_verify() {
  $context = d();
  drush_print('Passed context of type: ' . d()->type);
}
?>
Which would print the type of the context passed to the verify command, in this case 'site'.

The d accessor is not to be feared! It is used all over the place in Aegir and if you're not sure what context your going to get then you can always print d()->name and you'll get the name of the context that you're dealing with.

Loading a named context

You can pass an optional argument to the d accessor of the name of the context that you want. So, if you feel compelled to access a property about the main Aegir frontend site anywhere you can do this:

<?php
$hostmaster_context = d('@hostmaster');
?>

Though most of the time you'll be dealing with the current context, and contexts that it references.

'Subcontexts'

Here's an example context:

<?php
$aliases['hostmaster'] = array (
  'context_type' => 'site',
  'platform' => '@platform_hostmaster',
  'server' => '@server_master',
  'db_server' => '@server_localhost',
  'uri' => 'aegir.example.com',
  'root' => '/var/aegir/hostmaster-0.4-beta2',
  'site_path' => '/var/aegir/hostmaster-0.4-beta2/sites/aegir.example.com',
  'site_enabled' => true,
  'language' => 'en',
  'client_email' => 'aegir@example.com',
  'aliases' =>
  array (
  ),
  'redirection' => false,
  'profile' => 'hostmaster',
);

Notice that some of the properties are the name of contexts, such as 'db_server' which has a value of '@server_localhost'.

Suppose now that I have some code that wants to get a property of the db_server associated with the @hostmaster context, I can simply to this:

<?php
$hostmaster_context = d('@hostmaster');
$db_server_context = $hostmaster_context->db_server;
// $db_server_context is now a fully populated context object, not the string '@server_localhost'
drush_print('DB server on port: . $db_server_context->db_port);
?>

The provisionContext object will return full context objects for properties that store the names of other contexts. The how and why of determining which to return as strings and which to return as a context object will be covered later. It is entirely possible to have the name of a context stored as a property in a context, that when accessed returns the string, rather than the context named in the string.