PageConfig

Summary: Allow basic administrative configuration from a page
Version: 2008-06-01
Prerequisites:
Status: Alpha
Maintainer: Peter Bowers
Users: +1 (View / Edit)
Categories: Administration
Discussion: PageConfig-Talk?

Questions answered by this recipe

This section is optional; use it to indicate the types of questions (if any) this recipe is intended to answer.

  • How can I do basic configuration from a page rather than through config.php?
  • How can I give someone capability to change the skin or some configuration variable without giving them a machine account and FTP access?

Description

Allow basic configuration through markup on a page rather than through PHP code.

Installation

  • Download PageConfig.php and place it in your cookbook directory.
  • At the place in your config.php where you want these page-based configurations to occur place this line:

include('cookbook/PageConfig.php')

  • Set configuration variables as needed (especially $PCValidVars as the default setting restricts all set() directives for security purposes). Note that any configuration variables MUST be set PRIOR to including PageConfig.php.
    • $PCPages (default array("$SiteAdminGroup.PageConfig"))
      • This is an array of the pages which will be examined for configuration directives.
    • $PCValidVars (default array() -- this means NO values will be accepted for ANY variables -- the administrator must explicitly allow values to be set)
      • If you set $PCValidVars to true then it bypasses all security and allows setting of any global variables
      • If $PCValidVars is an array then the key must be the variable name (without the $ sign) and the value can be one of these:
        • If the value is true then that variable can be set to any value
$PCValidVars = true;  // allow all variable assignments
  • If the value is a string surrounded with slashes ("/^foo$/") then the variable can be set to any value which matches that regex
$PCValidVars['Skin'] = '/^(?:triad|gemini)$/';  // allow $Skin to be triad or gemini
  • If the value is an array of values then the variable can be set to any value contained in that array
$PCValidVars['Skin'] = array('triad','gemini');  // allow $Skin to be triad or gemini
  • $PCIncludeDir (default "$FarmDir/Cookbook")
    • This can be set to another directory or an array of directories. Files will be included with the include() directives only if they are found in these directories.
    • The PHP scripts which can be included via PageConfig can be strictly limited by creating a directory which contains only those acceptable scripts and setting this configuration variable to that location. If a script is not found in these directorires then it will not be allowed to be included.
      • Creating a directory "$FarmDir/Cookbook/PageConfig" and placing links to acceptable scripts in that directory pointing back to the cookbook directory is probably the preferred way to administrate this setup.
  • if you want to give different configuration options/permissions under different conditions you can set the various configuration variables (below) before including PageConfig.php, for example:
if (preg_match("/^MyGroup\./", $pagename) {
   $PCPages = array('$SiteAdminGroup.MyGroupPageConfig', "$SiteAdminGroup.PageConfig");
   $PCValidVars['MyVar'] = array('value1', 'value2', 'value3');
   include('cookbook/PageConfig.php');
}
  • Create a page SiteAdmin.PageConfig with the configuration directives as documented below.

Note that if $PCPages[] is going to be set to something besides array("$SiteAdminGroup.PageConfig") it must be set prior to including PageConfig.php.

Note also that PageConfig.php can be included as many times as you want for different aspects of configuration. Just use include() instead of include_once() when including PageConfig.php.

Be aware that setting global variables and including PHP scripts is a security risk. Make sure the configuration page is appropriately locked down.

Notes

Create a page called SiteAdmin.PageConfig. It supports (:comment ...:) markup and (:if ...:)...(:else:)...(:ifend:) markup to provide conditionals and comments. In addition it provides these directives:

  • include_once(file.php) (or include(file.php) or require(file.php) or require_once(file.php))
    • This will accomplish include_once('cookbook/file.php') (or alternatives)
  • set(var, value) or set(var, "value with spaces")
    • This will set the global variable var to the value specified.
    • Array values can be specified like this: {@set(var[index], value)@]
      • Example: set(foo[abc], 'qdx')
      • Note the lack of quotes around the index portion, even if the index is a string - this is necessary in the syntax

These 2 directives (include() and set()) can appear on a line by themselves or can be combined with multiple directives on a single line separated by a comma or a semi-colon.

Example 1

Normally in config.php you might have had a section like this:

include_once('cookbook/foo.php');
if ($pagename == 'MyGroup.Xyz') {
   include_once('cookbook/bar.php');
   $Bar_Var = 23;
}

But you want your administrators to be able to control that section themselves without FTP access and without PHP coding. They would create a SiteAdmin.PageConfig page that looks like this:

include(foo.php)
(:if name 'MyGroup.Xyz':)
   include(bar.php)
   set(Bar_Var, 23)
(:ifend:)

Or, alternately:

include(foo.php)
(:if name 'MyGroup.Xyz':)include(bar.php), set(Bar_Var, 23)(:ifend:)

Release Notes

If the recipe has multiple releases, then release notes can be placed here. Note that it's often easier for people to work with "release dates" instead of "version numbers".

  • 2008-06-01 Fixed a minor bug with rule processing (found in code-reading - I don't think it had any real-life effect). Allowed (:linebreaks:) markup to make the page easier to view while browsing. Upgraded status to "alpha" as I've been using it for a couple weeks without issues.
  • 2008-05-18 Fixed so variable names of more than 1 character could be set -- OOPS! Fixed bug with setting variables with values surrounded by double-quotes.
  • 2008-05-11B Add include_once, require, require_once in addition to include. Add $PCIncludeDir config var. Add $PCValidVars config var.
  • 2008-05-11 Initial release

Outstanding Issues

  • Lots of little global variables are created in the running of this script - this needs to be cleaned up
  • Potential security risk of allowing people to set global variables and include PHP scripts once they have access to that page
  • This is not cleaned up at all -- I'm getting an idea on the table in a tangible form because I think there will be lots of ideas on what's good and what's not good to have in this kind of a tool.

Development Roadmap

  • Restrict which PHP files can be included via a configuration variable
  • Possible other directives to implement besides include() and set()?
  • Possibly extend conditions if additional conditions are needed in a configuration context?

See Also

Contributors

Comments

See discussion at PageConfig-Talk?

User notes +1: If you use, used or reviewed this recipe, you can add your name. These statistics appear in the Cookbook listings and will help newcomers browsing through the wiki.