==============================================================================
PHPOF version 2
(c)2001-2008 Tim Jackson (tim@timj.co.uk)
==============================================================================

Introduction
------------
What is PHPOF?:

- An object-oriented interface to access SQL databases which implements the
  Table Data Gateway and Row Data Gateway patterns, amongst others. Features
  include in particular:
   - automatic database schema discovery
   - SQL generation for many simple queries (updates, inserts etc.)
   - optional row-level recording and auditing of changes
- A database abstraction layer

Database abstraction is performed using an underlying library called MDB2 from
the PEAR project (http://pear.php.net/package/MDB2).

Please note that an earlier project called PHPOF (now referred to as PHPOF1) was
more like a collection of different PHP classes (doing much much than just 
database interfacing, although the database functionality was at its heart).
PHPOF2 is just a database access interface.


Installation
------------
Install using the PEAR installer (from http://pear.php.net/). You will need as a
minimum two packages:

- PHPOF2 (this package)
- PHPOF2_Driver_XXX where XXX is the database backend you wish to use. Only
                    "mysqli" is currently supported

If you want to use auditing you will need an audit driver which implements the
audit interface (see Audit/Interface.php). A (working) sample one which will 
suit most people's needs is provided in the package "PHPOF2_Audit_GenericDb", 
although this is only one example implementation and does not have to be used.


Getting started
---------------
The high level documentation is unfortunately currently a bit limited. However, 
the code is commented reasonably well and the document "quickstart.txt" gives
some brief introductory examples to get you started.

The "tests" directory also contains some sample scripts showing how to do
various things in PHPOF2 (auditing in particular).


Optimisation
------------
PHPOF2 uses MDB2 as a backend and can therefore be made to use any database
backend which MDB2 supports fairly easily (although it unfortunately does still
currently require a simple PHPOF2 driver as well, though the code in this is
minimal).

However, some particular parts of MDB2 are not very slow and for the purposes of
PHPOF2 can be optimised. Thus, some PHPOF2 drivers (including the current
"mysqli" driver) overload some of the functions of MDB2 for optimisation 
purposes.


Disabling schema auto-discovery
-------------------------------
Although PHPOF2's schema auto-discovery is extremely handy for building 
applications rapidly (including prototyping), if you have a critical table whose
structure changes rapidly then you may wish to override this. To do this, you
simply need to define some properties in your Table class (derived from
PHPOF2_DBTable):

- fields_lob
- fields_normal
- pri_keys
- fgn_keys
- key_auto_increment
	 
(see the PHPOF2_DBTable code for details on what you should populate these with).
Then just overload PHPOF2_DBTable::discoverSchema() and make it do nothing but
call self::_createSchemaCachedLists() (which creates some internal caches of the
database structure) and return. You will then save some time each time the table
class is instantiated as PHPOF2 will not have to read the schema from the 
database
.