Addition: database version management. 

==========================================================
Summary
==========================================================

Sometimes we want to add or change something in the database underlying Aigaion.

In the ideal situation, an admin would copy a new release installation of Aigaion 
to the 'usual' location, and at the first access to Aigaion, the database structure 
would get automatically updated.

This file describes an implementation how to make sure that changing the database structure 
does not break down existing installations of Aigaion, nor does require heavy 
intervention in the database itself by an administrator. This is done in two parts. 
First the implementation of the mechanism is discussed. Next, a summary is given of
what should be done by those who want to change the database to effect improvements in 
Aigaion.

==========================================================
Implementation of a database version management mechanism.
==========================================================
A versioning mechanism needs two things: something to keep track of the version numbers of
both the database and the Aigaion version, and something to automatically update the database
should the two not match. 

How to keep track of the database version? Since doing this through the config.php file would 
(a) suggest that the versioning is somehow amenable to user intervention, which it is not, and 
(b) require write access to the files on the web server, which is not necessarly available, I 
keep track of the current version of the database in the database itself. This is 
done in a table called 'aigaiongeneral', which contains only one row of data. Database version 
is stored in the column 'version', and could be either a number or a free-text entry. 
Absence of the table signals the lowest possible version.

How to keep track of the Aigaion version, i.e. the version of the collection of PHP files? This 
is actually quite simple. A method 'checkDatabase()' is called upon login, just 
after connecting to the database, which checks if the database conforms to the current version.
If so, it returns true. If not, it tries to remedy the situation. If successfull, it still returns 
true. If not successfull in updating, it returns false. If checkDatabase() returns false, the 
Aigaion system should fail to load, with an appropriate error message.

The implementation of that method should look something like this:

function checkDatabase() {       
    if (!(adminLogin()))
        return false;
    //this call should obviously be adapted to the latest version
    if (!(checkDatabaseV0_7()))
        return false;    
    if (!(adminLogout()))
        return false;
    return true;    
    }
    

function checkDatabaseV0_7() {
  //check if version is already OK
  if (checkVersion("V0.7")) return true;
  //If not, first check if PREVIOUS version is OK
  if (!checkDatabaseV0_6()) return false;
  
  //if previous version OK: do the things necessary to update database to new version
      echo ("Updating version V0.7... "); //for debug
      
      [...]
      
      if (something went wrong during update)
      {
        dbError(mysql_error());
        return false;
      }

  //update version number in database
  if (!setVersion("V0.7"))  return false;    
    
  //successful: return true
  return true;   
  
}

==========================================================
HowTo: Extending the database definitions of Aigaion
==========================================================
Well, now that I look back, it seems obvious from the example above.
-Choose a new version number. 
-Update checkDatabase to check for new version, in schema/checkschema.php.  
-Fill in appropriate code for newest checkDatabaseVx_y. (checks for previous versions etc; 
 code for updating table, i.e. dropping and adding tables and columns)
-Make a note of the new database structure in _RECENTCHANGES.txt as well as
 in checkschema.php.
-TEST EVERYTHING THOUROUGHLY BEFORE COMMITTING
-IF POSSIBLE, ASK ANOTHER DEVELOPER TO REVIEW YOUR CHANGES, JUST TO BE ON THE SAFE SIDE...