PTom Logo

Torpor 1.0

As of this morning, after extensive testing and its first production beta deployment (which did result in a few minor bug fixes), I am pleased to announce that Torpor has reached release 1.0 (slightly delayed to allow for other DataStore adapters and management of pigfluenza in the home, but close enough for open source).

Things to check out:

On the whole, everything works.  Case sensitive collations under SQLite and SQL Server have issues, but mostly due to he limitations of those particular databases, and SQL Server cannot enforce DISTINCT selection when returned records include TEXT/CLOB columns (so DISTINCT is temporarily disabled in SQL Server – I’ve chosen to go live with the bug).  All told, these are fairly minor issues when everything else works so well.  All major features work in:

  • MySQL
  • Oracle
  • SQLite
  • SQL Server

An identical database has been ported to each of these database engines in turn, and the same code and same configuration XML (with minor adjustments to specify the new DataStore adapter) pass, exercise the full suite, on each.  Additionally, the provided Memcache adapter allows for distributed read/write-through caching for horizontal scalability at the app layer.

All DataStore and Cache adapters use generic interfaces, and the provided code serves well as examples of working implementations.  It should be possible with minimal effort to add additional DataStore components (even non-RDBMS adapters for XML, SOAP, etc.) or Cache’s.

The 1.1 road map is being assembled, to include better performance through leveraging bind variables in those adapters which support it, Postgres (which will almost certainly come as an earlier component release), inferred joins and a join hint syntax, and custom reports / aggregate functions, etc.  Have a suggestion?  Create an issue in the project home page (same goes for bugs).

While it sounds like there’s a lot to do, this is still an incredibly strong 1.0 offering especially in the PHP world (did I mention it passes E_ALL|E_STRICT error reporting?), and is being made use of professionally at the day job with excellent results.

The one lament, and this will be remedied over time, is the lack of end user documentation.  I’ve settled on the use of TiddlyWiki as a convenient mechanism for creating, storing, and distributing the documentation with the project, and will begin adding this as time permits (though it’s now in competition with other projects, so not likely to move at the same speed with which Torpor has also matured).

For now: download, use, enjoy!

Zend Devzone PHP Abstract Podcast: Torpor

Recently I had the pleasure of being interviewed by Eli White of Zend, “The PHP Company,” for the Devzone podcast PHP Abstract (by and for PHP developers).  The topic of discussion was Torpor, what it is, what it offers, and why it’s being developed.

Despite my rambling on there’s some useful information to be found – hardly all inclusive, but it should stand on its own as an introduction to the level of forethought that’s gone into an undertaking of this complexity.

The ~20 minute recording posted today – go check out Episode 46!

Torpor 0.9β Released!

The 0.9 beta release of Torpor (all major features work, but only in MySQL and there’s some definite clean-up and organization to be done) is available now:

TorporPHP_0.9b.tar.gz (via Google project hosting)

I also need to correct a statement I made earlier during the introduction of Torpor – this is not the first mature persistence layer abstraction.  I’ve come across others (turns out the buzz word for googling is “PHP ORM”, not “PHP persistence abstraction”) since I delved into this foray in the first place, though I can say I’m not especially impressed.  I can also say that Torpor easily stands on its own among these, with its philosophies fitting an appropriate niche and providing some of its own innovations (especially the intermediate cache interface and the complexity of the intrinsic deep-loading and relationship introspection).

Those feeling adventurous, enjoy!

Those without the cycles to spare, 1.0 should be available in 3-4 weeks, enabling additional database interfaces and cleaning things up.  Between 0.9b and 1.0 there may be some minor changes in naming conventions, but overall structure will remain the same.  Much documentation will be forthcoming as well.

Good luck, and good night!


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

  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:

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!

Older posts