[Sommaire] [Imprimer]

   1  ** Introduction:
   2  
   3  PEAR MDB is a project to merge PEAR DB and Metabase into one DB
   4  abstraction layer.
   5  
   6  You can get info on these at:
   7    PEAR DB: http://pear.php.net
   8    Metabase: http://phpclasses.upperdesign.com/browse.html/package/20/
   9  
  10  At these URLs you will also find the licensing information on these two
  11  projects along with the credits.
  12  
  13  If you have any questions or suggestions you can contact me (Lukas Smith)
  14  at this email address:
  15    smith@backendmedia.com
  16  Co-Author is Christopher Linn:
  17    clinn@backendmedia.com
  18  
  19  Or even better post a message to these 3 mailinglists (please include
  20  all of these because there are people on each of these mailinglists that
  21  care about this project and have asked to be included in any
  22  discussion):
  23    pear-dev@lists.php.net
  24    metabase-dev@yahoogroups.com
  25    dev@binarycloud.tigris.org
  26  
  27  ** Features
  28  
  29  MDB provides a common API for all support RDBMS. The main difference to most
  30  other DB abstraction packages is that MDB goes much further to ensure
  31  portability. Among other things MDB features:
  32  * An OO-style query API
  33  * A DSN (data source name) or array format for specifying database servers
  34  * Datatype abstraction and on demand datatype conversion
  35  * Portable error codes
  36  * Sequential and non sequential row fetching as well as bulk fetching
  37  * Ordered array and associative array for the fetched rows
  38  * Prepare/execute (bind) emulation
  39  * Sequence emulation
  40  * Replace emulation
  41  * Limited Subselect emulation
  42  * Row limit support
  43  * Transactions support
  44  * Large Object support
  45  * Index/Unique support
  46  * Extension Framework to load advanced functionality on demand
  47  * Table information interface
  48  * RDBMS management methods (creating, dropping, altering)
  49  * RDBMS independent xml based schema definition management
  50  * Altering of a DB from a changed xml schema
  51  * Reverse engineering of xml schemas from an existing DB (currently only MySQL)
  52  * Full integration into the PEAR Framework
  53  * Wrappers for the PEAR DB and Metabase APIs
  54  * PHPDoc API documentation
  55  
  56  Currently supported RDBMS:
  57  MySQL
  58  PostGreSQL
  59  Oracle (beta)
  60  Frontbase SQL (alpha)
  61  Querysim
  62  Other soon to follow. 
  63  
  64  ** Getting started:
  65  
  66  I would first recommend taking a look at MDB_test.php.
  67  This should give you a general feel of how to interact with MDB.
  68  
  69  After that you may want to take a look at the rather large API
  70  at www.backendmedia.com/MDB/docs. There you will also find a document
  71  describing the xml schema format and a little tutorial (it was
  72  just recently ported from Metabase, so it may contain errors).
  73  
  74  ** Current State:
  75  
  76  The current release can be found at the PEAR webpage:
  77    http://pear.php.net/package-info.php?package=MDB
  78  
  79  ----------------------------------- WARNING -----------------------------------
  80  MDB is still undergoing active development and therefore its API might
  81  change slightly until drivers for ODBC and Sybase/MS-SQL have been added. But
  82  since MDB is heavily based on PEAR DB and Metabase who both have drivers for
  83  these RDBMS this is probably fairly unlikely to happen or have large effects.
  84  It is unlikely that BC specific code will be written to maintain BC for only
  85  release prior to this version.
  86  
  87  Furthermore the manager might see some drastic changes in the future which would
  88  affect the manager.php and the get*Definition() methods in the manager_*.php.
  89  However this will most likely be extending the functionality and not changing
  90  existing functionality.
  91  ----------------------------------- WARNING -----------------------------------
  92  
  93  All but the MySQL driver are still missing the reverse engineering of xml schemas.
  94  
  95  The core of MDB is very stable since quite sometime, with very few bugs that
  96  had to be fixed or API changes that had to be made. The manager is still in a
  97  bit of flux as the API is still not final and some methods still need to be
  98  split up into smaller methods to improve readability and flexability. Also
  99  new features will be added as needed by the MDB_frontend project.
 100  
 101  The 1.0 of MDB can be considered stable for the RDBMS it currently
 102  supports. As with any software there is the possiblity of bugs which I am
 103  commited to fix quickly. As explained above there may be changes in the API
 104  that may break BC until we hit 1.1. The version number 1.0 was just a natural
 105  progression from the initial version number of 0.9. This 1.0 release is a
 106  definite milestone and the version number reflects this. The next milestone
 107  will be 1.1 to be expected in Fall 2002 (see the Roadmap for details).
 108  
 109  ** Package Content:
 110  
 111  As a user the only php script you will need to include is MDB.php which will
 112  install to your PEAR root directory. All other files and their containing
 113  classes will be included via MDB::factory(), MDB::connect(), MDB::loadFile().
 114  
 115  Currently the supported drivers are mysql and pgsql.
 116  File you may include are:
 117  peardb_wrapper (PEAR DB Wrapper)
 118  metabase_wrapper (Metabase Wrapper)
 119  Date (MDB_Date class which helps in converting MDB Timestamps to other formats)
 120  Manager (MDB_Manager class which does the XML schema handling)
 121  
 122  The only exception to this rule is reverse_engineer_xml_schema.php which you
 123  have to call directly from a browser. This very simple script will help you
 124  with handling schema files and create schema files from existing databases. This
 125  script requires PEAR::Var_Dump package.
 126  
 127  The package also contains various files that explain how MDB works. These files
 128  will install into your docs dir found in the PEAR root dir.
 129  
 130  Furthermore MDB provides an extensive testing framework that works through a
 131  browser and command line interface. There are several other test that test the
 132  two wrappers. These files will install into your test dir found in the
 133  PEAR root dir.
 134  
 135  ** Documentation:
 136  
 137  PHPDoc generated documentation can be found at: http://www.backendmedia.com/MDB/docs/
 138  
 139  The entire "public" API and most of the "private" methods (except for some of
 140  the lob classes) have been documented with PHPDoc comments. Most of the API
 141  is borrowed from PEAR DB, so you can look there for detailed documentation.
 142  Since there are a large number of new methods available thanks to the Metabase
 143  heritage of MDB you will also have to take a look in the Metabase documentation
 144  (which can be found at the URL mentioned above, but does require that
 145  you register with phpclasses). Most of these Metabase functions have
 146  been renamed. Looking at the metabase_wrapper.php file should help finding
 147  the new method name in MDB.
 148  
 149  For example ($db being an MDB object):
 150    $converted_value = MetabaseGetTimestampFieldValue($database, $value);
 151  would now be
 152    $converted_value = $db->getTimestampValue($value);
 153  
 154  If you want to help out with documentation please email me.
 155  
 156  ** Testing:
 157  
 158  For most of the tests you can set the username/password/hostname in the relevant
 159  config file. The user will need to have the right to create new databases.
 160  
 161  test.php/clitest.php/testchoose.php: Is the native testing suite provided by
 162  MDB. Please see the README in the tests directory for details.
 163  
 164  driver_test.php: Is the testing suite provided by Metabase you will need
 165  to configure what driver to test and the relevant section in the array found in
 166  driver_test_config.php to fit your enviornment.
 167  
 168  MDB_test.php: Several test calls to MDB's native API.
 169  MDB_pear_wrapper_test.php: Several test calls to MDB's PEAR DB Wrapper.
 170  
 171  MDB_test.php and MDB_pear_wrapper_test.php require PEAR::VAR_Dump package and
 172  are configured to use the following settings:
 173  username = metapear
 174  password = funky
 175  hostname = localhost
 176  
 177  ** How to write new Drivers:
 178  
 179  Skeleton drivers are provided in the docs directory of the MDB package.
 180  
 181  MDB is mostly based in Metabase. The method naming and formatting is
 182  changed to better match the PEAR CS however. Therefore the best starting
 183  point is to first take one of the Metabase drivers (metabase_[DRIVER NAME].php)
 184  and compare it with a corresponding MDB driver ([DRIVER NAME].php and
 185  manager_[DRIVER NAME].php). This will give a good idea what changes you have to
 186  make to an existing Metabase driver in order to make it MDB compatible.
 187  
 188  (Note: In order to get the Metabase code you will need to download it from
 189  phpclasses using the URL provided at the top).
 190  
 191  Alot of methods have been renamed from the original Metabase API. The best
 192  place to find the name to what a method has been renamed you should look
 193  at the metabase_wrapper.php file.
 194  
 195  Please also note that some methods have been taken from PEAR DB so for some
 196  missing methods you can check the PEAR DB driver.
 197  
 198  Another alternative would be to take a MDB driver and hack it to fit
 199  the new RDBMS. I would however recommend working with the existing
 200  Metabase driver for that RDBMS when doing those changes. This will
 201  surely be faster and it will ensure that the new driver takes full
 202  advantage of the MDB framework (which is to large parts based on
 203  Metabase).
 204  
 205  In order to check compliance of the driver with MDB you can use the testing
 206  suite (see the "testing" section above)
 207  
 208  ** History
 209  
 210  MDB was started after Manuel broad be into the discussion about getting the
 211  features of Metabase into PEAR that was going on (again) in December 2001. He
 212  suggested that I could take on this project. After alot of discussion about
 213  how when and if etc I started development in February 2002.
 214  
 215  MDB is based on Metabase but has been reworked severely to better match
 216  the PEAR DB API and PEAR CS. The approach I have taken so far is to take DB.php
 217  from PEAR DB and make it create a Metabase object. I have changed the
 218  Metabase structure slightly. The formatting has been reworked
 219  considerably to better fit the final structure (MDB standalone with a
 220  BC-wrapper for Metabase and PEAR DB), to fit the PEAR CS and to make it
 221  easier for other people to contribute.
 222  
 223  The metabase_interface.php was been renamed to metabase_wrapper.php and
 224  now only serves as a wrapper to keep BC with Metabase. A wrapper will
 225  have to be created for PEAR DB as well.
 226  
 227  Basically the result is a Metabase that is really close to the PEAR DB
 228  structure. I have also added any missing methods from PEAR DB. Work on
 229  moving the error handling to PEAR error handling is under way but still
 230  needs some work.
 231  
 232  ** Credits (never to early for those huh? :-)  ):
 233  
 234  I would especially like to thank Manuel Lemos (Author of Metabase) for
 235  getting me involved in this and generally being around to ask questions.
 236  I would also like to thank Tomas Cox and Stig S. Bakken from the PEAR
 237  projects for help in undertstanding PEAR, solving problems and trusting
 238  me enough. Paul Cooper for the work on the pgsql driver. Furthermore I
 239  would like to thank Alex Black for being so enthusiastic about this
 240  project and offering binarycloud as a test bed for this project.
 241  Christian Dickmann for being the first to put MDB to some real use,
 242  making MDB use PEAR Error and working on the XML schema manager.
 243  
 244  Finally Peter Bowyer for starting the discussion that made people pick
 245  up this project again after the first versions of what was then called
 246  "metapear" have been ideling without much feedback. I guess I should
 247  also thank BackendMedia (my company :-)  ) for providing the necessary means
 248  to develop this on company time (actually for the most part my entire
 249  life is company time ... so it goes)