PDO driver docs - the split begins

Posted on Fri 12 August 2005 in misc

Until very recently, the entire set of PDO documentation, including the docs for seven different database drivers, was contained within the PDO documentation. While this was fine in the early days of PDO when there were only a handful of users, as PHP 5.1 starts entering the era of release candidates having crystal clear documentation for the peculiarites of each database driver is going to be much more important.

Tonight, as a first step towards that goal, I committed a phpdoc patch that moves the DSN (data source name, or connection string) syntax out of the generic PDO constructor documentation and into driver-specific sections of the manual. As part of that patch, I also implemented a fix for the Functions Reference section of the manual to ensure that the table of contents is organized by the descriptive name of the module, and not simply by the module directory name.

Without that fix, the table of contents for the manual would have grouped all of the PDO drivers together next to the general PDO interface documentation, while the legacy database drivers would be spread throughout the table of contents by database name. That may not sound too bad, but it was: without the patch, the results looked something like:

Firebird/Interbase Functions
...
Microsoft SQL Server Functions
...
Oracle 8 Functions
...
Firebird/Interbase Functions (PDO_FIREBIRD)
Microsoft SQL Server Functions (PDO_DBLIB)
ODBC and DB2 Functions (PDO_ODBC)
Oracle Functions (PDO_OCI)
SQLite Functions (PDO_SQLITE)
PDO Functions
...
SQLite Functions
...
ODBC Functions (Unified)

After the fix, the table of contents looks like:

Firebird/Interbase Functions
Firebird/Interbase Functions (PDO_FIREBIRD)
...
Microsoft SQL Server Functions
Microsoft SQL Server Functions (PDO_DBLIB)
...
ODBC and DB2 Functions (PDO_ODBC)
ODBC Functions (Unified)
...
Oracle 8 Functions
Oracle Functions (PDO_OCI)
...
PDO Functions
...
SQLite Functions
SQLite Functions (PDO_SQLITE)

I hope you'll agree that the latter structure makes much more sense. If you don't agree, then I'm going to send the men in the white suits after you. Note: I used to call myself an information architect, and although I'm feeling much better these days, I still get pretty passionate about the subject of information retrieval optimization. Now that our manual has the basic stubs for driver-specific sections, I hope to follow that up with more information about each driver: for example:

Installation information for both PHP 5.0.x (PECL) and 5.1 (core)
Driver behavior differences (for example, PDO_PGSQL returns data as PHP native types rather than plain strings)
Driver-specific constants, attributes, and ini-file entries (for example, PDO_ODBC connection pooling)
Additional methods (for example, PDO_SQLITE's SqliteCreateAggregate() and SqliteCreateFunction() methods)

I have my limits, however: as an IBM DB2 employee, most of my day-to-day experience is with the PDO_ODBC driver. I hope that other writers will be able to pitch in and help document the quirks and extensions of the other PDO drivers.