Documentation: versions/versions.php

Class Versions - The database abstraction layer for versions

Versions is the storage module that is aiming to implement version control and WiKi within YACS.

One version is a textual object used as a snapshot of an article, category, or section. Anchors are used to reference versioned item (i.e., 'article:123' or 'section:314'). Also, each version has a date of creation, and reference the surfer who generates it.

Basically, YACS maintains a stack of versions. New versions are pushed on the top of the stack. When necessary, an old version may be popped from the stack.

A version may be created on item change, like in the following example:

// save article content before change, and link it to last editor
Versions::save($article, 'article:123');

// update the article
Articles::put($new_content);

The list of versions related to one item may be retrieved as follows:

// retrieve the list of versions
Versions::list_for_anchor($anchor);

On revert back to a previous version, this version and most recent versions are suppressed from the database:

// restore a past version
Versions::restore($id);

It is also possible to prune one version, and remove older versions as well:

// clean oldies up to a given version
Versions::prune($id);

This script is a reference file of this system.

Licence: GNU Lesser General Public License

Auteurs:

Bernard Paques bernard.paques@bigfoot.com
Florent

delete_for_anchor() - Delete all versions for a given anchor

function delete_for_anchor($anchor)

$anchor - the anchor to check
returns an error message, if any

get() - Get one version by id

function &get($id)

$id - int the id of the version
returns the resulting $item array, with at least keys: 'id', 'anchor', 'content', etc.

Unserialize $item['content'] to actually retrieve version content.

get_url() - Get the url to view a version

function get_url($id, $action='view')

$id - int the id of the version to view
$action='view' - string the expected action ('view', 'restore', 'prune', ...)
returns an anchor to the viewing script

By default, a relative URL will be provided (e.g. 'versions/view.php?id=512'), which may be not processed correctly by search engines. If the parameter 'with_friendly_urls' has been set to 'Y' in the configuration panel, this function will return an URL parsable by search engines (e.g. 'versions/view.php/512').

Voir aussi:

control/configure.php

list_by_date() - List most recent versions

function &list_by_date($offset=0, $count=10, $variant='full')

$offset=0 - int the offset from the start of the list; usually, 0 or 1
$count=10 - int the number of items to display
$variant='full' - string the list variant, if any
returns NULL on error, else an ordered array with $url => ($prefix, $label, $suffix, $icon)

Actually list versions by date.

Voir aussi:

versions/index.php

list_by_date_for_anchor() - List most recent versions for one anchor

function &list_by_date_for_anchor($anchor, $offset=0, $count=10, $variant=NULL, $capability='?')

$anchor - string the target anchor
$offset=0 - int the offset from the start of the list; usually, 0 or 1
$count=10 - int the number of items to display
$variant=NULL - string the list variant, if any
$capability='?' - string to support editors
returns NULL on error, else an ordered array with $url => ($prefix, $label, $suffix, $icon)

Voir aussi:

versions/list.php

list_selected() - List selected versions

function &list_selected(&$result, $layout='compact', $capability='?')

&$result - resource result of database query
$layout='compact' - string 'full', etc or object, i.e., an instance of Layout_Interface
$capability='?' - string '?' or 'A', to support editors and to impersonate associates, where applicable
returns NULL on error, else an ordered array with $key => ($prefix, $label, $suffix, $type, $icon)

Accept following layouts:

'compact' - to build short lists in boxes and sidebars (this is the default)
'feeds' - an array of $url => array($time, $label, $author, $section, $icon, $introduction, $content, $trackback) for feeds and search

restore() - Restore an old version

function restore($id)

$id - int the id of the version to restore
returns TRUE on success, FALSE otherwise

This function returns the content of a previous version, and also purges the stack of previous versions.

This function also remember any error in $context['error']

save() - Remember a previous version a new version

function save($fields, $anchor)

$fields - array an array of fields
$anchor - string the anchor attached to this version
returns the id of the new version, or FALSE on error

On error this function adds a string to $context['error'].

Voir aussi:

versions/edit.php

setup() - Create tables for versions

function setup()

stat_for_anchor() - Get some statistics for one anchor

function &stat_for_anchor($anchor)

$anchor - the selected anchor (e.g., 'section:12')
returns the resulting ($count, $min_date, $max_date) array

Voir aussi:

sections/view.php