Author: Derick Rethans
Date: 2006-01-29 12:45:17 +0100 (Sun, 29 Jan 2006)
New Revision: 2082
Log:
- First bit of tutorial.
Modified:
packages/Configuration/trunk/docs/examples/settings.ini
packages/Configuration/trunk/docs/tutorial.txt
packages/Configuration/trunk/docs/tutorial_example_01.php
Modified: packages/Configuration/trunk/docs/examples/settings.ini
===================================================================
--- packages/Configuration/trunk/docs/examples/settings.ini 2006-01-29
11:45:00 UTC (rev 2081)
+++ packages/Configuration/trunk/docs/examples/settings.ini 2006-01-29
11:45:17 UTC (rev 2082)
@@ -9,3 +9,4 @@
# Storing passwords in INI files is not a good idea,
# is it?
password=42
+connection_retries=five
Modified: packages/Configuration/trunk/docs/tutorial.txt
===================================================================
--- packages/Configuration/trunk/docs/tutorial.txt 2006-01-29 11:45:00 UTC
(rev 2081)
+++ packages/Configuration/trunk/docs/tutorial.txt 2006-01-29 11:45:17 UTC
(rev 2082)
@@ -6,20 +6,93 @@
Introduction
============
+The Configuration component allows you to read settings. Those settings can
+come from any backend in theory, but currently there are only two backends
+implemented: ezcConfigurationIniReader for reading plain configuration files
and
+ezcConfigurationArrayReader for reading parsed configuration files in the form
of
+a PHP array. The latter is faster then the first one.
+The format for the plain configuration files can be found in the section
+`File Format`_.
+
Class overview
==============
-ezcTranslationManager
+ezcConfigurationManager
The main class of this component. It is responsible for calling the
- configured backends to read in translation data and return a translation
- context in the form of an ezcTranslation object.
+ configured backends to read in configuration data and return the settings to
+ the application. It implements the singleton pattern and this class can be
+ used in most situations where no special handling of configuration data is
+ required.
+ezcConfigurationIniReader and ezcConfigurationArrayReader
+ Both classes inherited from the ezcConfigurationFileReader and provide lower
+ level access to reading configuration files. They also provide a method for
+ validating configuration files.
+ezcConfigurationIniWriter and ezcConfigurationArrayWriter
+ Write configuration files in the format that ezcConfigurationIniReader and
+ ezcConfigurationArrayReader support.
+
+ezcConfiguration
+ Is the basic class to query and modify configuration settings. Objects of
+ this class are returned by ezcConfigurationFileReader::getConfig() and can be
+ stored into files through the ezcConfigurationFileWriter::setConfig() method.
+
+
+
Basic Usage
===========
+There are two basic ways to use this component. The first one is through the
+manager class ezcConfigurationManager. This is mostly suitable for the bulk of
+your application for retrieving configuration settings.
+The second way is through the individual reader and writer classes themselves.
+They provide you with more finegrained control over the settings.
+
+Using the Manager
+-----------------
+
+In this first example you see how configuration settings stored in the file
+"settings.ini" are accessed:
+
+.. include:: tutorial_example_01.php
+ :literal:
+
+In line 4 and 5 we retrieve an instance of the ezcConfigurationManager class
+and initialize the system with the init() method. The two arguments specify the
+reader to use (ezcConfigurationIniReader) and where to find the configuration
+information. The second argument is the location, and its meaning is dependent
+on the reader class.
+
+In line 7 we retrieve the setting "password" from the settings group "db" in
+the configuration named "settings". In the case of the
+ezcConfigurationIniReader and ezcConfigurationArrayReader the name of the
+configuration corresponds to a specific file on disk.
+
+Lines 10-11 and 13-14 show two different ways on how to receive a list of
+settings. The first method returns an associative array, while the second
+method returns an numerical indexed array which you can f.e. use with the
+list() construct.
+
+Instead of the ezcConfigurationManager::getSetting() method there is also a
+number of additional methods that return a setting. These alternative methods
+also check whether the type of the settings is correct. See f.e. the
+ezcConfigurationManager::fetchArraySetting() description.
+
+The ezcConfigurationManager::hasSetting() method can be used to find out
+whether a specific setting exists and the
+ezcConfigurationManager::hasSettings() methods verifies if all the settings in
+the list that you give to this method exist. It is preferred to use these
+methods to see if an setting or list of settings exists before accessing them
+with one of the get*Setting() methods to prevent exceptions from being thrown.
+
+Using the Reader/Writer Classes Directly
+----------------------------------------
+
+
+
File Format
===========
Modified: packages/Configuration/trunk/docs/tutorial_example_01.php
===================================================================
--- packages/Configuration/trunk/docs/tutorial_example_01.php 2006-01-29
11:45:00 UTC (rev 2081)
+++ packages/Configuration/trunk/docs/tutorial_example_01.php 2006-01-29
11:45:17 UTC (rev 2082)
@@ -1,4 +1,15 @@
<?php
require_once 'tutorial_autoload.php';
+$cfg = ezcConfigurationManager::getInstance();
+$cfg->init( 'ezcConfigurationIniReader', dirname( __FILE__ ) . '/examples' );
+
+$pw = $cfg->getSetting( 'settings', 'db', 'password' );
+echo "The password is <$pw>.\n";
+
+$settings = $cfg->getSettings( 'settings', 'db', array( 'user', 'password' ) );
+echo "Connecting with {$settings['user']}:{$settings['password']}.\n";
+
+list( $user, $pass ) = $cfg->getSettingsAsList( 'settings', 'db', array(
'user', 'password' ) );
+echo "Connecting with {$user}:{$pass}.\n";
?>
--
svn-components mailing list
[email protected]
http://lists.ez.no/mailman/listinfo/svn-components
