<?php

/*
<fusedoc fuse="application.php" language="PHP" version="1.1">
	<responsibilities>
		I define Application variable handling functions.
		
		Include this file in your code with require_once().
		
		I create an array of application variables named _APPLICATION. Changes to this array will be persistent
		because of application_write_all() is registered as a shutdown function. This means that it will be called
		once the script shuts down.
		
		I store this array as a WDDX packet in a file.
		
		NOTE: This code probably needs some kind of file locking. At least, that's what I would do
			  when using Cold Fusion on a Windows box. As I am totally new to PHP and have never
			  coded for Unix/Linux platforms, I am not sure of the issues behind shared file storage.
		
		To identify the application, use application_start() and specify a UNIQUE application name
		and the physical location of the application data storage e.g.:
		
			application_start( "WEB_APP_NAME", "C:\\PHP\\APPLICATIONDATA\\" );
		
		application_start() deserializes the WDDX packet to the global _APPLICATION array.
		If the storage file does ot exist, it creates a new one.
		
		When created, the _APPLICATION array contains two strings:
		
			_APPLICATION["AppName"]
			_APPLICATION["AppDataLocation"]
		
		These two values are used by the other functions to serialize and deserialize the array to and
		from the data file.
		
		To register a value as an application variable use application_register(). This will also update
		the data file.
		
		Similarly to session functions, you can use application_unregister() to remove an application
		variable from the array. This will also update the data file.
		
		To remove all variables, use application_unset(). This will also update the data file.
		
		There is no need for a 'destroy' function. The application_unset() is enough to re-initialise the _APPLICATION array.
	</responsibilities>
	
	<properties>
		<history author="Martin Laine"
				 email="martin@doryphores.net"
				 date="15/01/2002"
				 type="Create"/>
		<history author="Martin Laine"
				 email="martin@doryphores.net"
				 date="20/01/2002"
				 type="Update">
			Added application_write_all to the set of functions and set it as a shutdown function.
			This now allows for the _APPLICATION array to be READ and WRITE enabled.
		</history>
	</properties>
	
	<io>
		<out>
			<array name="_APPLICATION">
				<string name="AppName" comments="Name of the application."/>
				<string name="AppDataLocation" comments="Physical path to the application data storage directory."/>
				<mixed name="*" comments="User-defined application variables."/>
			</array>
		</out>
	</io>
</fusedoc>
*/

// --------------------------------------------------------------
// Initialise _APPLICATION array if not set
// --------------------------------------------------------------

if( !isset( $_APPLICATION ) ) $_APPLICATION = array();


// --------------------------------------------------------------
// Use this function to update the data file
// --------------------------------------------------------------

function application_write_all() {
	global $_APPLICATION;
	$FileName = $_APPLICATION["AppDataLocation"] . "app_" . $_APPLICATION["AppName"] . ".dat";

	// Serialize the array and write it to the data file
	$fp = fopen( $FileName, "w" ) or die( "Unable to open the application data file" );
	fwrite( $fp, wddx_serialize_value( $_APPLICATION ) ) or die( "Unable to write to the application data file" );
	fclose( $fp );
}


// --------------------------------------------------------------
// Use this function to identify the application and deserialize the array
// --------------------------------------------------------------

function application_start( $AppName, $AppDataLocation ) {
	global $_APPLICATION;
	$FileName = $AppDataLocation . "app_" . $AppName . ".dat";

	// Check for the existence of the data file
	if( !file_exists( $FileName ) ) {
		// Write AppName and AppDataLocation to the _APPLICATION array
		$_APPLICATION["AppName"] = $AppName;
		$_APPLICATION["AppDataLocation"] = $AppDataLocation;

		// Write array to data file
		application_write_all();
	}
	else {
		// Get the WDDX packet from the data file and write to the _APPLICATION array
		$fp = fopen( $FileName, "r" ) or die( "Unable to open the application data file" );
		$_APPLICATION = wddx_deserialize( fread ( $fp, filesize ( $FileName ) ) );
		fclose( $fp );
	}
}


// --------------------------------------------------------------
// Use this function to register an application variable
// --------------------------------------------------------------

function application_register( $VarName ) {
	global $_APPLICATION;

	// Make sure we are not trying to modify AppName or AppDataLocation
	if( strcmp( $VarName, "AppName" ) == 0 OR strcmp( $VarName, "AppDataLocation" ) == 0 ) die( "Warning: Attempting to register " . $VarName );
	
	// Write the new value to the array
	$_APPLICATION[$VarName] = $GLOBALS[$VarName];
	
	// Write array to data file
	application_write_all();
}


// --------------------------------------------------------------
// Use this function to unregister an application variable
// --------------------------------------------------------------

function application_unregister( $VarName ) {
	global $_APPLICATION;
	
	// Make sure we are not trying to unregister AppName or AppDataLocation
	if( strcmp( $VarName, "AppName" ) == 0 OR strcmp( $VarName, "AppDataLocation" ) == 0 ) die( "Warning: Attempting to unregister " . $VarName );

	// Remove the variable from the array if it exists
	if( isset( $_APPLICATION[$VarName] ) ) unset( $GLOBALS["_APPLICATION"][$VarName] );

	// Write array to data file
	application_write_all();
}


// --------------------------------------------------------------
// Use this function to remove all application variables
// --------------------------------------------------------------

function application_unset() {
	global $_APPLICATION;

	// Remove all application variables except AppName and AppDataLocation
	foreach( array_keys( $_APPLICATION ) as $Index ) if( strcmp( $Index, "AppName" ) != 0 AND strcmp( $Index, "AppDataLocation" ) != 0 ) unset( $GLOBALS["_APPLICATION"][$Index] );

	// Write array to data file
	application_write_all();
}

register_shutdown_function( "application_write_all" );

?>