[Sommaire] [Imprimer]

   1  <?php
   2  
   3      /**
   4       * \defgroup Config
   5       *
   6       * The Config package is the central place where all configuration settings are stored in pLog.
   7       *
   8       * It works based on the Config::getConfig() method, which is a singleton method that will return a
   9       * class that extends the "interface" (never mind that those things don't exist in PHP4) 
  10       * ConfigAbstractStorage. Classes implementing this interface take care of storing, retrieving and updating
  11       * configuration parameters from a certain backend. At the moment, only a file-based backend and a database-based
  12       * backend are supported, and there are no plans to implement any more backends since these have proven
  13       * enough for the needs of pLog.
  14       *
  15       * The default backend is the database, implemented by the class ConfigDbStorage, while the file-storage backend
  16       * is implemented by the ConfigFileStorageBackend. If needed, it is possible to directly create an instance of 
  17       * any of the storage backends but it is advisable to use Config::getConfig()
  18       * 
  19       * There is more information about which methods are available from classes implementing a storage backend in the
  20       * documentation of the ConfigAbstractStorage class, and examples of use of this module in the documentation of the
  21       * Config class.
  22       *
  23       * Please also see this wiki page: http://wiki.plogworld.net/index.php/PLog_1.0/Global_Configuration_API
  24       */
  25  
  26      
  27  
  28      /**
  29       * Set it to either "file" or "db"
  30       */
  31      define( "DEFAULT_STORAGE_BACKEND", "db" );
  32  
  33      /**
  34       * \ingroup Config
  35       * 
  36       * This class is the main entry point to the Config module. It provides a static method that will return
  37       * a reference to the right config storage class.
  38       *
  39       * Example of usage for retrieving a particular key:
  40       * <pre>
  41       *  $config =& Config::getConfig();
  42       *  $config->getValue( "my_config_value", $defaultValue );
  43       * </pre>
  44       *
  45       * Example of saving some data back to the storage backend (we don't care which one it is):
  46       * <pre>
  47       *  $config =& Config::getConfig();
  48       *  $config->setValue( "my_new_key", $newValue );
  49       *  ...
  50       *  $config->save();
  51       * </pre>
  52       *
  53       * @see ConfigAbstractStorage
  54       * @see ConfigDbStorage
  55       * @see ConfigFileStorage
  56       * @see getConfig
  57       */
  58      class Config  
  59      {
  60  
  61          /**
  62           * Makes sure that there is <b>only one</b> instance of this class for everybody, instead of creating
  63           * a new instance every time we need to load some configuration. This will save some resources
  64           * if we keep in mind that for example the database backend will load the entire table into memory
  65           * every time a new instance is created.
  66           *
  67           * @param storage One of the storage methods implemented. Available ones are
  68           * "db" and "file", but any other can be implemented.
  69           * @param params An array containing storage backend specific parameters. In the case
  70           * of the file-based storage it could be the name of the file to use (for example)
  71           * @return Returns an instance of the Config class, be it a new one if this is the first
  72           * time we were calling it or an already created one if somebody else called
  73           * this method before.
  74           * @see ConfigDbStorage
  75           * @see ConfigFileStorage
  76           * @static
  77           */
  78          function &getConfig( $storage = DEFAULT_STORAGE_BACKEND, $params = null )
  79          {
  80              static $configInstance;
  81  
  82              // mappings to the storage classes
  83              // more can be added any time
  84              $storageTypes = Array(
  85                  "file" => "ConfigFileStorage",
  86                  "db"   => "ConfigDbStorage"
  87              );
  88  
  89              // check if there was an instance of the Config class already created
  90              if( !isset($configInstance[$storage])) {
  91                  // now we have to instantiate the right storage class
  92                  if( $storage == "" || !array_key_exists( $storage, $storageTypes )) {
  93                      // there is no class to implement this storage method, so we quite
  94                      // because this is quite a severe error
  95                      throw(new Exception( "Config class Exception: no storage class found for storage parameter = ".$storage ));
  96                      die();
  97                  }
  98  
  99                  // if all went fine, get the name for that class
 100                  $className = $storageTypes[$storage];
 101                  lt_include( PLOG_CLASS_PATH.'class/config/'.strtolower($className).'.class.php' );
 102                  // and create an object
 103                  $configInstance[$storage] = new $className( $params );
 104              }
 105  
 106              // return the instance
 107              return $configInstance[$storage];
 108          }
 109      }
 110  ?>