Documentation: scripts/index.php

scripts/index.php - Handling PHP scripts

While YACS is aiming to ease content publishing and sharing, we are thinking that the same objective should be targeted for the software itself.

More specifically, we have designed this module with the manipulation of numerous php script files in mind:

to derive on-line documentation from php comments
to list reference scripts that are shared on a server
to visualize differences between reference and running scripts
to suggest on software updates from a reference server

This module is based on several simple patterns:

the remote reference pattern is used to synchronize one server with one reference server
the local reference pattern is used to build the documentation and to publish shared scripts

Update your scripts from a remote reference repository

The remote reference pattern consists of scanning a remote server to build a set of staging files. After having setup the address of the reference server (through scripts/configure.php), the webmaster will have to activate the staging script (scripts/stage.php). The script will fetch the index of reference scripts (in footprints.php), and compare its content to the actual set of running scripts. For each running script having a diverging md5 signature, the script will cache the reference version into scripts/staging. As a result, at the end of the staging process:

all running scripts will have been compared to the reference scripts
for each non-matching file, a staging version will have been prepared

After the staging step the update itself can take place by launching scripts/update.php. First of all, this script displays the list of staging files, and offer the opportunity to read the new version or to list differences. The diff algorithm has been implemented into scripts/scripts.php for that purpose. To actually update the system, scripts/update.php rename old versions as '.bak', and move new versions from the staging directory to their final location.

Aside from the new scripts other updates will take place thanks to following steps:

scripts/update.php also switches the server off
control/scan.php will rebuild all hooks, to possibly take into account new hooks downloaded from the reference server
control/setup.php will check the database structure, and create it if necessary
scripts/run_once.php is launched, to possibly apply big changes to an existing database
control/index.php displays the control panel and gives the opportunity to switch the server on again.

Make a reference repository of your running scripts

The local reference pattern consists of building a safe repository of scripts and of related information page. Once one server has been setup correctly, maybe after some script modifications, skin updates, etc., the webmaster (actually, any associate) may wish to freeze this configuration as the reference one. By activating the building script (scripts/build.php), he (or she) will copy reference scripts to a safe place (scripts/reference). These scripts will be scanned for structured comments (see scripts/phpdoc.php) and the related documentation will be generated automatically. An index of reference scripts, including file names, dates and an md5 hash code, will be generated as well for further checking by other servers. As a result, at the end of the building process:

a complete set of reference scripts is saved in their 'sand box'
the documentation for these scripts is published
an inventory of these files is published (scripts/reference/footprints.php)

How to define that a script is to be included in the reference set? Simple: put the keyword &arobas;reference on a single line of the first php comment of the script.

How to use these mechanisms in your particular situation?

Despite the simplicity of these patterns, we are quite confindent that most webmasters will appreciate them over time. At least, they enable smooth updates of running scripts for most (minor) modifications. Moreover, these patterns will successfully frequent models of web deployments:

Standalone servers will benefit from the building script to at least generate and update a (tiny?) set

of useful pages to document the software. Note that these pages are fully indexed to enable free-text searches.

Servers connected to the Internet will have the opportunity to track YACS enhancements quite easily, simply by

checking from time to time one the public reference servers.

Groups of servers managed by a single webmasters may be linked to a single private reference server. It is likely

that various organizations will develop additional scripts on the YACS platform. They may use the remote reference pattern to distribute these scripts internally to slave servers.

This script is a reference file of this system.

Licence: GNU Lesser General Public License

Auteurs:

Bernard Paques bernard.paques@bigfoot.com