glFusion Wiki

Site Tools


glfusion:development:api:installer:start

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

glfusion:development:api:installer:start [2011/11/30 10:27]
glfusion:development:api:installer:start [2016/07/16 19:40] (current)
Line 1: Line 1:
 +====== 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:
 +<code php>
 +$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'​),​
 +);
 +</​code>​
 +
 +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.|
 +