Multiple connections in Paris

Finishes Paris side of j4mie/idiorm#15. Requires (of course) pull request at j4mie/idiorm#76, which is the Idiorm implementation.

Unit tests and documentation included. Unit tests work, but I haven't yet tried this on "real" data.

README.markdown

@@ -409,9 +409,48 @@ Despite this, Paris doesn't provide any built-in support for validation. This is
 
 However, there are several simple ways that you could add validation to your models without any help from Paris. You could override the `save()` method, check the data is valid, and return `false` on failure, or call `parent::save()` on success. You could create your own subclass of the `Model` base class and add your own generic validation methods. Or you could write your own external validation framework which you pass model instances to for checking. Choose whichever approach is most suitable for your own requirements.
 
+### Mulitple Connections ###
+Paris now works with multiple database conections (and necessarily relies on an updated version of Idiorm that also supports multiple connections). Database connections are identified by a string key, and default to `OrmWrapper::DEFAULT_CONNECTION` (which is really `ORM::DEFAULT_CONNECTION`).
+
+See [Idiorm's documentation](http://github.com/j4mie/idiorm/) for information about configuring multiple connections.
+
+The connection to use can be specified in two separate ways. To indicate a default connection key for a subclass of `Model`, create a public static property in your model class called `$_connection_key`.
+
+```php
+// A named connection, where 'alternate' is an arbitray key name
+ORM::configure('sqlite:./example2.db', 'alternate');
+
+class SomeClass extends Model
+{
+    public static $_connection_key = 'alternate';
+}
+```
+
+The connection to use can also be specified as an optional additional parameter to `OrmWrapper::for_table()`, or to `Model::factory()`. This will override the default setting (if any) found in the `$_connection_key` static property.
+
+```php
+$person = Model::factory('Author', 'alternate')->find_one(1);  // Uses connection named 'alternate'
+
+```
+
+The connection can be changed after a model is populated, should that be necessary:
+
+```php
+$person = Model::factory('Author')->find_one(1);     // Uses default connection
+$person->orm = Model::factory('Author', ALTERNATE);  // Switches to connection named 'alternate'
+$person->name = 'Foo';
+$person->save();                                     // *Should* now save through the updated connection
+```
+
+Queries across multiple connections are not supported. However, as the Paris methods `has_one`, `has_many` and `belongs_to` don't require joins, these *should* work as expected, even when the objects on opposite sides of the relation belong to diffrent connections. The `has_many_through` relationship requires joins, and so will not reliably work across different connections.
+
 ### Configuration ###
 
-The only configuration options provided by Paris itself are the `$_table` and `$_id_column` static properties on model classes. To configure the database connection, you should use Idiorm's configuration system via the `ORM::configure` method. **See [Idiorm's documentation](http://github.com/j4mie/idiorm/) for full details.**
+The only configuration options provided by Paris itself are the `$_table` and `$_id_column` static properties on model classes. To configure the database connection, you should use Idiorm's configuration system via the `ORM::configure` method.
+
+Now that multiple connections are implemented, the optional `$_connection_key` static property may also be used to provide a default string key indicating which database connection in `ORM` should be used.
+
+**See [Idiorm's documentation](http://github.com/j4mie/idiorm/) for full details.**
 
 ### Transactions ###
 

paris.php

@@ -86,10 +86,13 @@ public function filter() {
         /**
          * Factory method, return an instance of this
          * class bound to the supplied table name.
+         *
+         * A repeat of content in parent::for_table, so that
+         * created class is ORMWrapper, not ORM
          */
-        public static function for_table($table_name) {
-            self::_setup_db();
-            return new self($table_name);
+        public static function for_table($table_name, $which = parent::DEFAULT_CONNECTION) {
+            self::_setup_db($which);
+            return new self($table_name, array(), $which);
         }
 
         /**
@@ -234,9 +237,17 @@ protected static function _build_foreign_key_name($specified_foreign_key_name, $
          * responsible for returning instances of the correct class when
          * its find_one or find_many methods are called.
          */
-        public static function factory($class_name) {
+        public static function factory($class_name, $which = null) {
             $table_name = self::_get_table_name($class_name);
-            $wrapper = ORMWrapper::for_table($table_name);
+            //TODO: Populate $which if not set, as specified in class
+            if ($which == null) {
+               $which = self::_get_static_property(
+                   $class_name,
+                   '_connection_key',
+                   ORMWrapper::DEFAULT_CONNECTION
+               );
+            }
+            $wrapper = ORMWrapper::for_table($table_name, $which);
             $wrapper->set_class_name($class_name);
             $wrapper->use_id_column(self::_get_id_column_name($class_name));
             return $wrapper;