glFusion Wiki

Site Tools


glfusion:development:api:installer:start

lib-install.php

(glFusion v1.1.0)

The lib-install library provides a convenient framework for installing a glFusion plugin. All the database and filesystem actions are handled by the library. Lib-install provides the following services and benefits over writing it yourself:

  • No SQL coding for most glFusion objects (groups, features, blocks, etc.)
  • Errors during install will rollback changes automatically saving the programmer from writing a lot of redundant code.
  • Uniform error messages for common problems.
  • Built-in sense of variables so when you create a group, adding a feature to it is easily handled. (Avoids code like str_replace('###group_id###', $group_id, $sql) in SQL.)
  • Extensible, you can add types of install objects to the installer by providing properly named hooks.

Library Concepts

Your plugin would contain a file containing an array of commands to issue to the installer. The array is a list of arrays containing control data for the install. The format of the array is very specific. What follows is a sample install array:

$pi_name         = 'tags';
$pi_display_name = 'Tags';
$pi_version      = '0.6beta';
$gl_version      = '1.1.2';
$pi_url          = 'http://www.glfusion.org/';
 
require_once "{$_CONF['path']}plugins/$pi_name/sql/{$_DB_dbms}_install.php";
 
 
$INSTALL_plugin['tags'] = Array(
    'installer' => Array('type' => 'installer', 'version' => '1', 'mode' => 'install'),
    'plugin' => Array('type' => 'plugin', 'name' => $pi_name,
          'ver' => $pi_version, 'gl_ver' => $gl_version,
          'url' => $pi_url, 'display' => $pi_display_name),
    Array('type' => 'table', 'table' => $_TABLES['tags'], 'sql' => $_SQL['tags']),
    Array('type' => 'table', 'table' => $_TABLES['tag_agg'], 'sql' => $_SQL['tag_agg']),
    Array('type' => 'table', 'table' => $_TABLES['tag_redir'], 'sql' => $_SQL['tag_redir']),
    Array('type' => 'group', 'group' => 'Tags Admin',
          'desc' => 'Moderators of the Tags Plugin',
          'variable' => 'admin_group_id', 'addroot' => true),
    Array('type' => 'group', 'group' => 'Tags Users',
          'desc' => 'Users who can enter tags',
          'variable' => 'user_group_id', 'addroot' => true),
    Array('type' => 'addgroup', 'parent_var' => 'user_group_id',
          'child_grp' => 'Logged-in Users'),
    Array('type' => 'feature', 'feature' => 'tags.moderate',
          'desc' => 'Ability to moderate tags',
          'variable' => 'admin_feature_id'),
    Array('type' => 'feature', 'feature' => 'tags.edit',
          'desc' => 'Ability to add/remove personal tags',
          'variable' => 'edit_feature_id'),
    Array('type' => 'mapping', 'group' => 'admin_group_id',
          'feature' => 'admin_feature_id',
          'log' => 'Adding tags.admin feature to the tags admin group'),
    Array('type' => 'mapping', 'group' => 'admin_group_id',
          'feature' => 'edit_feature_id',
          'log' => 'Adding tags.edit feature to the tags admin group'),
    Array('type' => 'block', 'name' => 'tagcloud', 'title' => 'Popular Tags',
          'phpblockfn' => 'phpblock_tagcloud', 'block_type' => 'phpblock',
          'group_id' => 'admin_group_id'),
);

There are two required entries. The first entry with the key named 'installer' is used to make sure the install array and library are compatible. The entry with the key 'plugin' must be of type 'plugin'. It is used to modify the plugins table. The rest of the entries do not need addressable indexes as they are accessed sequentially to install your plugin. This does mean that the order they are placed in the array is important. Mappings of groups to features require that the group and feature already exist, for example.

At a minimum, each array in the list must contain a map element with the key 'type'. This is used to determine what is being created by the installer. The library understand the following types: table, group, feature, mapping, block, feed, a ddgroup, sql, mkdir, and checkfile.

Array Entry Types

installer

This section tells the installer library about the structure.

key required description
version Yes Used to make sure the structure is compatible with the library. Currently the only valid value is '1'.
mode Yes Set to 'install' if the structure describes a new install or 'upgrade' if the structure describes an upgrade.

plugin

This section describes the plugin to be installed.

key required description
name Yes Name of the plugin, placed directly into the pi_name field of the plugins tables.
ver Yes Version of the plugin.
gl_ver Yes Required glFusion version.
url Yes Support URL of plugin.
display_name Yes Pretty name of the plugin used in log messages.

table

Create a database table.

key required description
type Yes Must be 'table'
name Yes The $_TABLES name of the table.
sql Yes The SQL used to create the table.

sql

Perform an SQL query.

key required description
type Yes Must be 'sql'
sql Yes SQL query string(s) to execute during installation. This is typically used to install default/example data. This argument can be a single query string, or an array of query strings. (new in 1.3.0)
rev No SQL query string(s) which reverse the step above (if necessary) should the overall installation fail. Note that this is not needed in all cases, as often tables that are created during installation are automatically dropped. This argument can be a single query string, or an array of query strings. (new in 1.3.0)
log No Describe SQL operation being performed.

group

Create a glFusion user group.

key required description
type Yes Must be 'group'
name Yes The group name.
desc Yes The group description.
variable No An identifier used by the installer for storing the grp_id of the newly created group.
addroot No If true (or not present), adds the Root group to the group.

feature

Create a glFusion access feature.

key required description
type Yes Must be 'feature'
name Yes The feature name.
desc Yes The feature description.
variable No An identifier used by the installer for storing the ft_id of the newly created feature.

mapping

Assigns a feature to a group.

key required description
type Yes Must be 'mapping'
group group or findgroup is required The name of an identifier found in the variable tag of a previously created group.
findgroup group or findgroup is required The name of a group in the database. Useful for mapping features onto groups such as 'Logged-in Users'.
feature Yes The name of an identifier found in the variable tag of previously created feature.
log No Describe the mapping in the error log using the text in this tag.

addgroup

Place a group inside another group.

key required description
type Yes Must be 'addgroup'
parent_var parent_var or parent_grp is required The name of an identifier found in the variable tag of a previously created group.
parent_grp parent_var or parent_grp is required The name of a group in the database.
child_var child_var or child_grp is required The name of an identifier found in the variable tag of a previously created group.
child_grp child_var or child_grp is required The name of a group in the database.

block

Create a side block.

key required description
type Yes Must be 'block'
All the column names in the block table name, block_type The block function pulls any listed tags found on the block table.
group_id No Assign group_id the value of the identified group.
variable No An identifier that will contain the bid of the created block.

mkdir

Create a directory in the filesystem.

key required description
type Yes Must be 'mkdir'
dirs Yes Full path of one or more directories to create. Any trailing slashes are ignored. This value can be a single path or an array of paths.
glfusion/development/api/installer/start.txt · Last modified: 2017/04/12 21:15 (external edit)

Page Tools