Torpor
Pronunciation: \ˈtôr-pər\
Definition:

1. Temporary or short-term hibernation, characterized physiological activity.
2. The first mature persistence layer abstraction for PHP, provided by Yours Truly under the MIT license.

Link: torpor-php (via Google Project Hosting)

The name is a direct take off of Hibernate since it provides very similar functionality for Object Relational Mapping.  It is not, however, a port, emulation, reimplementation, or imitation of it or any other specific ORM/Persistence abstraction out there.  This is all new code from the ground up, with the project started in the last half of July 2009.

The premise is simple: having written a significant amount of database-centric code over the years, in a variety of environments and in several different development languages, I have come to understand what I feel are the basic features every good database abstraction should have in order to be genuinely useful.  I have very frequently been without those features, and spent a great deal of time re-implementing and refining them in each of the different environments in play.

By doing this so many times over I have realized that, for a well defined (preferably 3rd-normal) schema, the feature set can be deterministically derived.  In order to test that theory, and potentially save myself an inordinate amount of tedium and re-invention in the current employment-selected language, I have written Torpor (though not until after thorough examination of other potential offerings, which I found to be thoroughly lacking and usually tied to other larger frameworks which most certainly did not meet my needs).

There are a few features left to do before the code will be packaged for distribution under the 0.9β release, which should be available in the next 1-2 weeks.  This beta release will be for MySQL only, and while it’s been coded with PHP 5.1.0 in mind I can’t guarantee full compatibility with less than 5.2.8 (have not yet tested it with the target prior version).  SQLite and Oracle adapters won’t be far behind, but Oracle probably won’t be making use of the OCI bind variables yet – though this is definitely planned for a later release

Features in a nutshell:

1. Configuration is controlled via straightforward XML (produced in large part by a helper script).
2. Objects have rich accessor and mutator interfaces with just-in-time fetching and optionally selective publishing.
3. Objects are capable of acting as intelligent factories for other related objects (and sets of objects), allowing for simple and powerful code for navigating from one portion of a database to another (intrinsic deep-loading, even in data engines lacking explicit support for foreign key relationships).
4. Full support for associating related un-published objects, with optional (on by default) cascading publish of dependent objects (deep-saving) – useful for those tables whose primary keys are generated on publish.
5. Full support for multi-column keys, multiple unique keys (with or without multiple columns), and multiple reference relationships between similar object types (e.g., a User may act as both a Seller and a Customer on an Order and be accessed as each in turn).
6. Extension of provided primitives is supported and encouraged, with event-based call-back hooks and a hierarchical overload/override scheme that’s easy to configure.
7. Custom SQL support for Load, Publish (optionally differentiated by insert vs. update), Delete, including stored procedures and pseudo-bind variables (SQL placeholders filled by order of occurrence and/or named variables).
8. Criteria based select, optionally using arbitrarily nested AND/OR collections and a rich set of criteria types and controls (including custom SQL) with support for automatic joins to related tables.
9. Intermediate read/write -through caching interface support (can be used in distributed network based cache settings, such as memcache, for nearly-free lateral scalability).
10. Fully extensible and customizable.

That’s a pretty big nutshell, and it’s not anywhere near complete.  There are just a couple gaps between this list and the current revision (no. svn:35 as of this writing) on both sides: a few features which need better testing and a little internal wiring, and some features provided but not listed.  Eventually the full user documentation will fill in the gaps, but so far this list and the actual available feature set have a > 90% overlap.

Implementation example snippet:

// Singleton context; support for instance-context
// and automatic config loading also available.
Torpor()->initialize( "myconfig.xml" );

$user = Torpor()->getUserById( 12345 );

$orderHistory = $user->getOrderSet();
foreach( $orderHistory as $order ){ /* ... */ }

$order = $user->newOrder();
$order->setSeller( Torpor()->getUserById( 54321 ) );
// OR $order->setSellerId( $user->getUserId() ), etc.
$order->setPurchaseDate( date() );

$product = Torpor()->newProduct();
$product->setName( 'Something Pink' );
$product->setUnitPrice( 49.95 );

$orderItem = $order->newOrderItem();
$orderItem->setProduct( $product );
// causes $product->publish(), $order->publish() cascade:
$orderItem->publish(); 

Code is available now via Google’s project hosting: Torpor: Persistence Abstraction for PHP

Feel free to poke around, make contributions, revisions, remarks (snide or otherwise), and generally check it out.  The official beta release will be announced here with great fanfare and tremendous sighs of relief, followed shortly by the tension of worrying whether it’s good enough and trying to polish user-docs.

Update (2009-08-28 09:16)

Torpor has been submitted as a potential topic of discussion for the Utah Open Source Conference 2009, October 8th-10th! This is a rather late submission, so your votes will count to help get this one on the board!