[pLog-svn] r1520 - plog/trunk/class/config
oscar at devel.plogworld.net
oscar at devel.plogworld.net
Tue Mar 15 23:56:10 GMT 2005
Author: oscar
Date: 2005-03-15 23:56:09 +0000 (Tue, 15 Mar 2005)
New Revision: 1520
Modified:
plog/trunk/class/config/config.class.php
plog/trunk/class/config/configabstractstorage.class.php
plog/trunk/class/config/configdbstorage.class.php
plog/trunk/class/config/configfilestorage.class.php
plog/trunk/class/config/properties.class.php
Log:
more documentation stuff
Modified: plog/trunk/class/config/config.class.php
===================================================================
--- plog/trunk/class/config/config.class.php 2005-03-15 23:27:43 UTC (rev 1519)
+++ plog/trunk/class/config/config.class.php 2005-03-15 23:56:09 UTC (rev 1520)
@@ -1,10 +1,28 @@
<?php
- /**
- * @package config
- */
+ /**
+ * \defgroup Config
+ *
+ * The Config package is the central place where all configuration settings are stored in pLog.
+ *
+ * It works based on the Config::getConfig() method, which is a singleton method that will return a
+ * class that extends the "interface" (never mind that those things don't exist in PHP4)
+ * ConfigAbstractStorage. Classes implementing this interface take care of storing, retrieving and updating
+ * configuration parameters from a certain backend. At the moment, only a file-based backend and a database-based
+ * backend are supported, and there are no plans to implement any more backends since these have proven
+ * enough for the needs of pLog.
+ *
+ * The default backend is the database, implemented by the class ConfigDbStorage, while the file-storage backend
+ * is implemented by the ConfigFileStorageBackend. If needed, it is possible to directly create an instance of
+ * any of the storage backends but it is advisable to use Config::getConfig()
+ *
+ * There is more information about which methods are available from classes implementing a storage backend in the
+ * documentation of the ConfigAbstractStorage class, and examples of use of this module in the documentation of the
+ * Config class.
+ *
+ * Please also see this wiki page: http://wiki.plogworld.net/index.php/PLog_1.0/Global_Configuration_API
+ */
-
include_once( PLOG_CLASS_PATH."class/object/object.class.php" );
/**
@@ -13,19 +31,38 @@
define( "DEFAULT_STORAGE_BACKEND", "db" );
/**
- * Extends the Properties class so that our own configuration file is automatically loaded.
- * The configuration file is under config/config.properties.php
- *
- * It is recommented to use this function as a singleton rather than as an object.
- * @see Config
+ * \ingroup Config
+ *
+ * This class is the main entry point to the Config module. It provides a static method that will return
+ * a reference to the right config storage class.
+ *
+ * Example of usage for retrieving a particular key:
+ * <pre>
+ * $config =& Config::getConfig();
+ * $config->getValue( "my_config_value", $defaultValue );
+ * </pre>
+ *
+ * Example of saving some data back to the storage backend (we don't care which one it is):
+ * <pre>
+ * $config =& Config::getConfig();
+ * $config->setValue( "my_new_key", $newValue );
+ * ...
+ * $config->save();
+ * </pre>
+ *
+ * @see ConfigAbstractStorage
+ * @see ConfigDbStorage
+ * @see ConfigFileStorage
* @see getConfig
*/
- class Config extends Object {
+ class Config extends Object
+ {
/**
- * Makes sure that there is <b>only one</b> instance of this class for everybody.
- * It is not bad to call the constructor but using the getConfig we will
- * save some work.
+ * Makes sure that there is <b>only one</b> instance of this class for everybody, instead of creating
+ * a new instance every time we need to load some configuration. This will save some resources
+ * if we keep in mind that for example the database backend will load the entire table into memory
+ * every time a new instance is created.
*
* @param storage One of the storage methods implemented. Available ones are
* "db" and "file", but any other can be implemented.
@@ -36,7 +73,7 @@
* this method before.
* @see ConfigDbStorage
* @see ConfigFileStorage
- * @static
+ * @static
*/
function &getConfig( $storage = DEFAULT_STORAGE_BACKEND, $params = null )
{
Modified: plog/trunk/class/config/configabstractstorage.class.php
===================================================================
--- plog/trunk/class/config/configabstractstorage.class.php 2005-03-15 23:27:43 UTC (rev 1519)
+++ plog/trunk/class/config/configabstractstorage.class.php 2005-03-15 23:56:09 UTC (rev 1520)
@@ -1,10 +1,5 @@
<?php
- /**
- * @package config
- */
-
-
include_once( PLOG_CLASS_PATH."class/object/object.class.php" );
define( "TYPE_INTEGER", 1 );
@@ -15,10 +10,16 @@
define( "TYPE_FLOAT", 6 );
/**
+ * \ingroup Config
+ *
* Interface class that defines the methods that should be implemented
* by child classes wishing to implement a configuratino settings storage backend.
+ *
+ * This class cannot be instantiated directly, and an attempt to call any of its methods
+ * will end our script.
*/
- class ConfigAbstractStorage extends Object {
+ class ConfigAbstractStorage extends Object
+ {
function ConfigAbstractStorage( $params = null )
{
@@ -27,14 +28,14 @@
/**
* Returns a constant determining the type of the value passed as parameter. The constants
- * are:<ul>
- * <li>TYPE_INTEGER = 1</li>
- * <li>TYPE_BOOLEAN = 2</li>
- * <li>TYPE_STRING = 3</li>
- * <li>TYPE_OBJECT = 4</li>
- * <li>TYPE_ARRAY = 5</li>
- * <li>TYPE_FLOAT = 6</li>
- * </ul>
+ * are:
+ * - TYPE_INTEGER = 1
+ * - TYPE_BOOLEAN = 2
+ * - TYPE_STRING = 3
+ * - TYPE_OBJECT = 4
+ * - TYPE_ARRAY = 5
+ * - TYPE_FLOAT = 6
+ *
*
* @param value The value from which we'd like to know its type
* @return Returns one of the above.
@@ -61,54 +62,110 @@
return $type;
}
+ /**
+ * Given a key, gets its value from the storage backend.
+ *
+ * @param key The key that we're looking for
+ * @param defaultValue Optional, if the key does not exist we can provide a second parameter that
+ * will be returned as the default value
+ * @return The value assigned to the key or $defaultValue if there was no such key found
+ */
function getValue( $key, $defaultValue = null )
{
throw( new Exception( "ConfigAbstractStorage::getValue: This method must be implemented by child classes." ));
die();
}
+ /**
+ * Sets a value in the storage area. It is up to the storage backend implementation to either
+ * save the data right away after calling this method or whether it is needed to call
+ * ConfigAbstractStorage::save() in order to do so.
+ *
+ * @param key The key that we'd like to save
+ * @param value The value that should be assigned to this key
+ * @return True if successful or false otherwise
+ */
function setValue( $key, $value )
{
throw( new Exception( "ConfigAbstractStorage::setValue: This method must be implemented by child classes." ));
die();
}
+ /**
+ * Returns all the configuration parameters as an associative array
+ *
+ * @return An associative array
+ */
function getAsArray()
{
throw( new Exception( "ConfigAbstractStorage::getAsArray: This method must be implemented by child classes." ));
die();
}
+ /**
+ * triggers a reload of all the settings from the backend.
+ *
+ * @return True if successful or false otherwise
+ */
function reload()
{
throw( new Exception( "ConfigAbstractStorage::reload: This method must be implemented by child classes." ));
die();
}
+ /**
+ * returns the name of the configuration file where data is being saved. If the backend does not
+ * use a configuration file, the result of this method is an empty string
+ *
+ * @return name of the config file, or empty if not used
+ */
function getConfigFileName()
{
throw( new Exception( "ConfigAbstractStorage::getConfigFileName: This method must be implemented by child classes." ));
die();
}
+ /**
+ * Returns an associative array with all the keys that are in the storage backend
+ *
+ * @return An associative array, or an empty array if there are no keys
+ */
function getKeys()
{
throw( new Exception( "ConfigAbstractStorage::getKeys: This method must be implemented by child classes." ));
die();
}
+ /**
+ * Returns an array including only the values that are availalbe in the storage backend
+ *
+ * @return An array with only the values, or an empty array if there are no values.
+ */
function getValues()
{
throw( new Exception( "ConfigAbstractStorage::getValues: This method must be implemented by child classes." ));
die();
}
+ /**
+ * saves only one value to the configuration backend. This should save the value right away
+ * without the need to call ConfigAbstractStorage::save() afterwards
+ *
+ * @param key The name of the key that we'd like to save
+ * @param value The value of the key that we'd like to save
+ * @return true if successful or false otherwise
+ */
function saveValue( $key, $value )
{
throw( new Exception( "ConfigAbstractStorage::saveValue: This method must be implemented by child classes." ));
die();
}
+ /**
+ * saves all the keys and their values to disk
+ *
+ * @return true if successful or false otherwise
+ */
function save()
{
throw( new Exception( "ConfigAbstractStorage::saveValue: This method must be implemented by child classes." ));
Modified: plog/trunk/class/config/configdbstorage.class.php
===================================================================
--- plog/trunk/class/config/configdbstorage.class.php 2005-03-15 23:27:43 UTC (rev 1519)
+++ plog/trunk/class/config/configdbstorage.class.php 2005-03-15 23:56:09 UTC (rev 1520)
@@ -1,32 +1,30 @@
<?php
- /**
- * @package config
- */
-
-
include_once( PLOG_CLASS_PATH."class/object/object.class.php" );
include_once( PLOG_CLASS_PATH."class/config/configfilestorage.class.php" );
include_once( PLOG_CLASS_PATH."class/database/db.class.php" );
/**
+ * \ingroup Config
+ *
* Storage backend that stores/retrieves the data from the plog_config
- * table.<br/>
- * The structore of the table is as follows:<ul>
- * <li>id: setting identifier</li>
- * <li>config_key: Name of the setting. Can't be empty</li>
- * <li>config_value: Value assigned to the key</li>
- * <li>value_type: This field can take several values and gives the class
- * a hint regardign the type of the value:<ul>
- * <li>1: integer. The config_value field represents is value.</li>
- * <li>2: boolean. It is saved as 1 == true and 0 == false.</li>
- * <li>3: string. It is saved as is.</li>
- * <li>4: object. The object is saved in a seralized way.</li>
- * <li>5: array. The arrays are also saved serialized. This is transparently
+ * table.
+ * The structore of the table is as follows:
+ *
+ * - id: setting identifier
+ * - config_key: Name of the setting. Can't be empty
+ * - config_value: Value assigned to the key
+ * - value_type: This field can take several values and gives the class
+ * a hint regardign the type of the value:
+ * -- 1: integer. The config_value field represents is value.
+ * -- 2: boolean. It is saved as 1 == true and 0 == false.
+ * -- 3: string. It is saved as is.
+ * -- 4: object. The object is saved in a seralized way.
+ * -- 5: array. The arrays are also saved serialized. This is transparently
* done inside the save() and saveValue() methods, and therefore the user
- * does not have to worry about doing it.</li>
- * <li>6: float. It is saved as is.</li>
- * </ul>
+ * does not have to worry about doing it.
+ * -- 6: float. It is saved as is.
+ *
* Type detection is provided via the built-in mechanisms that PHP offers.
* </ul>
*/
@@ -164,6 +162,9 @@
return false;
}
+ /**
+ * @private
+ */
function _updateValue( $key, $value )
{
// if the key exists, we have to update it
@@ -198,6 +199,9 @@
return false;
}
+ /**
+ * @private
+ */
function _insertValue( $key, $value )
{
$type = $this->_getType( $value );
Modified: plog/trunk/class/config/configfilestorage.class.php
===================================================================
--- plog/trunk/class/config/configfilestorage.class.php 2005-03-15 23:27:43 UTC (rev 1519)
+++ plog/trunk/class/config/configfilestorage.class.php 2005-03-15 23:56:09 UTC (rev 1520)
@@ -1,10 +1,5 @@
<?php
- /**
- * @package config
- */
-
-
include_once( PLOG_CLASS_PATH."class/file/file.class.php" );
include_once( PLOG_CLASS_PATH."class/config/properties.class.php" );
include_once( PLOG_CLASS_PATH."class/config/configabstractstorage.class.php" );
@@ -14,10 +9,17 @@
}
/**
- * Extends the Properties class so that our own configuration file is automatically loaded.
- * The configuration file is under config/config.properties.php
+ * \ingroup Config
+ *
+ * Implements a file-based configuration backend. The data in the file has to be arranged
+ * in a php array called $config, in the same way the file config/config.properties.php is arranged.
+ *
+ * The backend will use the array keys as its own keys and the values as its own values, and will take
+ * care of serializing and unserializing data as needed (so that we can for example save Objects and
+ * Arrays to the config file)
*/
- class ConfigFileStorage extends ConfigAbstractStorage {
+ class ConfigFileStorage extends ConfigAbstractStorage
+ {
var $_configFile;
var $_props;
@@ -249,7 +251,7 @@
*
* @return The name of the folder used for temporary storage
*/
- function getTempFolder()
+ function getTempFolder()
{
return $this->getValue( "temp_folder" );
}
Modified: plog/trunk/class/config/properties.class.php
===================================================================
--- plog/trunk/class/config/properties.class.php 2005-03-15 23:27:43 UTC (rev 1519)
+++ plog/trunk/class/config/properties.class.php 2005-03-15 23:56:09 UTC (rev 1520)
@@ -1,13 +1,11 @@
<?php
- /**
- * @package config
- */
-
include_once( PLOG_CLASS_PATH."class/object/object.class.php" );
/**
- * Class inspired by the java class Properties
+ * \ingroup Config
+ *
+ * Class inspired by the java class Properties.
*/
class Properties extends Object
{
More information about the pLog-svn
mailing list