File: readme.txt

$Date: 2002/03/29 16:43:06 $
$Revision: 1.2 $

+---------------------------+
| CONFIG MANAGER 0.1 README |
+---------------------------+
by: Keyvan Minoukadeh - keyvan@k1m.com - http://www.k1m.com
Last update: 26-March-2002

******************
* INTRO
******************
I don't really like writing this readme stuff,
but I'll try and explain this as best I can...

This is a set of PHP classes which can be used to manage (read, write, edit)
plain text config files.


******************
* FEATURES
******************
+ Allows caching of the config file as a serialized array stored in a file
+ Supports arrays and associative arrays
+ Supports 4 basic variable types: string, integer, double and boolean
+ Supports special characters when enclosed within double quotes: \n \r \t
+ Allows editing of the config file through a friendly web interface (html form)
+ Allows writing of config files through the config writer class
+ Leading and trailing white space allowed, also white space before and after
  the separator allowed


******************
* FAQ
******************
-- WHAT IS IT?
 A set of PHP classes to help manage plain text
 config files.

-- WHY USE IT?
 If you write PHP scripts which require people
 to modify a config file with their own settings,
 this should hopefully make life a little easier.

-- WHY IS IT SPLIT INTO 4 CLASS FILES?
 I didn't want to put all features into the 1 class file because
 not everyone would be using all features.
 The 3 main classes all extend the base class: class.config_base.php which
 contains methods potentially useful to all the classes.
 Config Manager consists of:
 + class.config_base.php : The base class used by all the other classes
 + class.config_reader.php : The reader class used to read the config file
 + class.config_writer.php : The writer class used to write config files
 + class.config_webedit.php : The web editor used to modify the config file

-- WHY A CONFIG WRITER CLASS?
 I personally don't think this is very useful, but it could be useful
 if you've got an application which stores users settings in a database
 of some sort and would like to offer these details to a user in a
 format easier to understand.

-- HOW CAN I SPECIFY A VARIABLE TO BE A CERTAIN TYPE?
 Simply prepend the variable name with:
 + str_  : string
 + int_  : integer
 + dbl_  : double
 + bool_ : boolean
 So if you'd like Config Reader to automatically cast this variable to
 type double: myvar = 23.44 simply rewrite as: dbl_myvar = 23.44
 NOTE: Ignore the type prefix when accessing the variable,
       in the above example, both variables would be accessed by the name
       myvar (if you want to access a variable as int_myvar, you will need
       to write it as: int_int_myvar)

-- HOW WOULD I SPECIFY A BOOLEAN VALUE?
 Make sure the variable name has bool_ prepended to it
 and use either of these values:
 + true:  true, on, yes, 1
 + false: false, off, no, 0
 eg. bool_myvar = on

-- HOW ARE ARRAYS HANDLED?
 If a variable name occurs twice in a section, then that variable will
 automatically be returned as an array.
 Rather than returning a numeric array, you can also specify a key name
 by appending a dot '.' and the key name to the end of a variable name,
 eg. myarray.key = 'testing'

-- WHAT IS A VALID CONFIG LINE?
 Either...
 + an empty line (ignored)
 + a line with any amount of white space (ignored)
 + a line with a section name: '!^\[[a-zA-Z0-9_][a-zA-Z0-9_ ]*\]!' *
 + a comment line: '!^#!' **
 + assigning value to variable: '!^(str_|int_|dbl_|bool_)?([a-zA-Z_][a-zA-Z0-9_]*)(\.[a-zA-Z0-9_]+)?\s*=\s*(["\']?)(.*)\4$!i' ***

 *    = leading and trailing white space trimmed before attempting to match with regex
 **   = the comment character '#' can be changed in the class
 ***  = the separator character '=' can be changed in the class

-- HOW ARE THE VALUES RETURNED?
 The Config Reader class can return the values as either an associative array
 or an object
 // assoc array
 $reader->set('fetch_mode', CONFIGMAN_FETCH_ASSOC);
 // object
 $reader->set('fetch_mode', CONFIGMAN_FETCH_OBJECT);

-- IF I ENABLE THE CACHE OPTION, HOW LONG WILL A CACHED COPY LAST?
 The cached copy is only used if the modification time of your main config
 file matches the modification time of the cached file.
 Each time the cache file is written, the modification time is set to the same
 value as the main config file.
 Each time the config file is read the modification time of both files are
 compared, if they match the cache file will be used, otherwise the main config
 file will be used.

-- WHY ARE ALL QUOTES ESCAPED AUTOMATICALLY?
 The Config Manager class assumes you have magic_quotes_runtime off.
 If you have this switched on, or you're on a shared server and don't have
 access to modify this setting.  Then make sure before you call any other
 config function to call this:
 $object->magic_quotes_runtime(false);
 this will log your existing magic_quotes_runtime setting and turn it off
 for the duration of the script.
 To switch back to your previous setting (if you have other functions that
 expect this feature to be on) simply call the same function, this time
 passing a value of true:
 $object->magic_quotes_runtime(true);
 NOTE: It's recommended you use this regardless of magic_quotes_runtime being
       on or off (there are no adverse effects)

-- WHAT ABOUT MAGIC_QUOTES_GPC?
 This only effects the webedit class, where the config values are POST'ed back.
 The webedit class will check for this and if found to be on, will automatically
 strip the slashes from the values.


******************
* EXAMPLE CONFIG
******************
[A section name]
# a string
test_var = 'Simple Text'
# a integer
testing = 203
# a string with special characters
test_string = "new line\n a tab\t"

[Array Example]
# array example
# an integer
an_int = 10
# duplicate variable name
# an_int will now be returned as an array
an_int = 20
# an_int with a key name
an_int.test = 100

[Type casting]
# a string
str_var1 = 10
# an integer
int_var2 = 10
# a boolean value
bool_var3 = true
# a double
dbl_var4 = 23.34

# White space is also allowed
   testing	= 'test'
# This is also allowed
testing=10


******************
* QUICK EXAMPLE
* reading a config file [see test_reader.php]
******************
require_once('class.config_base.php');
require_once('class.config_reader.php');

$reader = new config_reader('valid_config.txt');

$reader->set('config_cache_dir', '/home/site/tmp/cache/');

// load config from text
$c = $reader->load();


******************
* QUICK EXAMPLE
* writing a config file [see: test_writer.php]
******************
require_once('class.config_base.php');
require_once('class.config_writer.php');

$test_var = "Hello";
$test_int = 203;
$an_array = array(10, '20', 'test'=>30);

$writer = new config_writer('writable_config.txt');

$writer->set_param('test_var', $test_var, 'comment for first var');
$writer->set_param('test_int', $test_int, 'comment for second var');
$writer->set_param('an_array', $an_array, 'comment for array');

$writer->write();


******************
* QUICK EXAMPLE
* editing a config file through a web interface
******************
[see test_webedit.php]



Let me know if you're experiencing problems and your question wasn't answered
here, email me at: keyvan@k1m.com or visit: http://www.k1m.com