PDO driver docs - the split begins - Coffee|Code : Dan Scott, Caffeinated Librarian Geek

About Me

I'm Dan Scott, barista, library geek, and open source dabbler. You may know me from such projects as PHP (PEAR's File_MARC package and PDO documentation), Apache Derby, and the Evergreen open-source ILS project.

I'm the Systems Librarian for Laurentian University. You can reach me by email at dan@coffeecode.net.

License

This work is licensed under a Creative Commons Attribution-Noncommercial-Share Alike 2.5 Canada License.

Syndicate This Blog

RSS 0.91 feed

RSS 1.0 feed

RSS 2.0 feed

ATOM 0.3 feed

ATOM 1.0 feed

RSS 2.0 Comments

Zend Certification

Thursday, August 11. 2005

PDO driver docs - the split begins

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.

Posted by Dan Scott in PHP at 23:52 | Comments (2)

Comments

Display comments as (Linear | Threaded)

I took a look at livedocs and all looks good. Perhaps we can soon close this "bug": http://bugs.php.net/bug.php?id=33696

#1 Ben Ramsey (Homepage) on 2005-08-12 09:49 (Reply)

Throughout the manual we really need to move the extension specific CONSTANT lists on their own pages.

#2 Philip Olson on 2005-08-19 18:21 (Reply)

Add Comment

Name
Email
Homepage
In reply to
Comment	Enclosing asterisks marks text as bold (word), underscore are made via _word_. Standard emoticons like :-) and ;-) are converted to images. E-Mail addresses will not be displayed and will only be used for E-Mail notifications To prevent automated Bots from commentspamming, please enter the string you see in the image below in the appropriate input box. Your comment will only be submitted if the strings match. Please ensure that your browser supports and accepts cookies, or your comment cannot be verified correctly. Enter the string from the spam-prevention image above: Enclosing asterisks marks text as bold (word), underscore are made via _word_.
	Remember Information? Subscribe to this entry
Submitted comments will be subject to moderation before being displayed.