Documentation: scripts/run_once.php

scripts/run_once.php - Run one time only scripts

This scripts helps to finalize complex software updates, such as:

update of the database schema (e.g., apply complex UPDATE queries to populate new fields of the SQL database)
change files that are not PHP scripts (e.g., change cascading style sheets of reference skins)
download of binary files (e.g., get a copy of the Flash viewer for Freemind maps)

How to write a script to be ran once?

Such script is really simple to write, since the only requirement for software developer is to display information to the surfer through 'echo' commands. This is because the regular rendering engine (updated via the $context variable) is not available during the execution of multiple scripts.

Except for the bare display interface, a script that is ran once benefits from the full power of YACS (database access, localization, ...).

Exemple of a script to perform some database update:

<?php
// feed-back
echo 'Change anchors in files...
'."\n";

// split membership components
$query = "UPDATE ".SQL::table_name('files')
            ." SET anchor_type = SUBSTRING_INDEX(anchor, ':', 1)"
            .", anchor_id = SUBSTRING_INDEX(anchor, ':', -1)";
if($count = SQL::query($query, TRUE))
    echo $count.' records have been updated.
'."\n";

?>

How to run scripts only once?

All you have to do it to upload these scripts into the directory scripts/run_once, and to launch the scripts/run_once.php script.

The script will locate every script into scripts/run_once and include each of them. Also, to avoid further execution, each executed script is renamed by appending the extension '.done'.

How to run scripts during software updates?

If some reference scripts are put into the scripts/run_once directory, they will be transferred and installed at the target server as other scripts.

For example, if you have to change the database through some software upgrade, and if this update has to be performed only once, you will:

prepare the software upgrade as usual, assuming that scripts may use an updated database
prepare an additional script to change the database itself, for example: my_database_update.php
put this additional script into scripts/run_once[/script]



During the software upgrade, scripts/update.php will transfer every new script,
including [code]my_database_update.php

, to the staging repository. Also, control/scan.php and control/setup.php are launched as usual to ensure that the database schema is correct. Then scripts/run_once.php will launch my_database_update.php, to actually finalize the database change.

Note that if there is no script to run in scripts/run_once.php, and if we are in the middle of an update (because switch.off exists), then the surfer is silently redirected to control/index.php.

While the run-once approach is powerful and should suffice for most needs, you may have to complement it in very specific cases. People interested into weird software will take a look at scripts/update_trailer.php.

What happens on first installation?

The YACS archive that contains reference scripts is used jointly on first installation and on upgrades. However, scripts to be ran once are useful only for upgrades. Therefore, on first installation (i.e., when the switch file is absent), the extension '.done' is appended to every script in the directory scripts/run_once without actual execution of them.

This script is a reference file of this system.

Licence: GNU Lesser General Public License

Auteurs:

Bernard Paques bernard.paques@bigfoot.com

send_body() - Dynamically generate the page

function send_body()

Voir aussi:

skins/index.php