Refactored the service layer (again).

 * Renamed `Configuration` to `StandardServiceContainer`
 * Created `ServiceContainerInterface`
 * Added proxy methods in `Propel` for the methods of`ServiceContainerInterface`, and used these methods in the documentation

UPDATE.md

@@ -1,15 +1,17 @@
 # List of Backwards Incompatible Changes
 
-## `Propel\Runtime\Propel` replaced by the `Propel\Runtime\Configuration` singleton.
+## `Propel\Runtime\Propel` methods renamed.
 
-The static methods from the `Propel` class have been moved to a singleton. Therefore, you must replace the following occurrences in your code:
+Some static methods from the `Propel` class have been renamed. Therefore, you must replace the following occurrences in your code:
 
-    Replace...                                With...
-    use Propel\Runtime\Propel                               use Propel\Runtime\Configuration
-    Propel::getDatabase($name)                              Configuration::getInstance()->getDatabase($name)
-    Propel::getDB($name)                                    Configuration::getInstance()->getAdapter($name)
-    Propel::getConnection($name, Propel::CONNECTION_READ)   Configuration::getInstance()->getReadConnection($name)
-    Propel::getConnection($name, Propel::CONNECTION_WRITE)  Configuration::getInstance()->getWriteConnection($name)
-    Propel::getDefaultDB()                                  Configuration::getInstance()->getDefaultDatasource()
+    Replace...                                              With...
+    Propel::CONNECTION_WRITE                                ServiceContainerInterface::CONNECTION_WRITE
+    Propel::CONNECTION_READ                                 ServiceContainerInterface::CONNECTION_READ
+    Propel::getDB($name)                                    Propel::getAdapter($name)
+    Propel::getConnection($name, Propel::CONNECTION_READ)   Propel::getReadConnection($name)
+    Propel::getConnection($name, Propel::CONNECTION_WRITE)  Propel::getWriteConnection($name)
+    Propel::getDefaultDB()                                  Propel::getDefaultDatasource()
 
-The generated model is automatically updated once you rebuild your model.
+The generated model is automatically updated once you rebuild your model.
+
+>**Tip**: Internally, `Propel::getAdapter()` proxies to `Propel::getServiceContainer()->getAdapter()`. The `Propel` class was refactored to keep only one static class and to be more extensible. It remains the easy entry point to all the necessary services provided by Propel.

documentation/cookbook/replication.markdown

@@ -57,23 +57,23 @@ The `<slaves>` section is at the same level as the master `<connection>` and con
 
 The replication functionality is implemented in the Propel connection configuration and initialization code and in the generated Peer and Object classes.
 
-### `Configuration::getReadConnection()` and `Configuration::getWriteConnection()` ###
+### `Propel::getReadConnection()` and `Propel::getWriteConnection()` ###
 
-When requesting a connection from Propel (`Configuration::getInstance()->getConnection()`), you get a write connection by default. 
+When requesting a connection from Propel (`Propel::getConnection()`), you get a write connection by default. 
 
 You can also specify that you want a READ connection (slave) or a WRITE connection (master).  Methods that are designed to perform READ operations, like `ModelCriteria::find()`, will always request a READ connection like so:
 
 {% highlight php %}
 <?php
-$con = Configuration::getInstance()->getReadConnection(MyPeer::DATABASE_NAME);
+$con = Propel::getReadConnection(MyPeer::DATABASE_NAME);
 $books = BookQuery::create()->find($con);
 {% endhighlight %}
 
 Other methods that are designed to perform write operations, like `ModelCriteria::update()` or `ModelCriteria::delete()`; will explicitly request a WRITE connection:
 
 {% highlight php %}
 <?php
-$con = Configuration::getInstance()->getWriteConnection(MyPeer::DATABASE_NAME);
+$con = Propel::getWriteConnection(MyPeer::DATABASE_NAME);
 BookQuery::create()->deleteAll($con);
 {% endhighlight %}
 
@@ -85,22 +85,22 @@ Both READ (slave) and WRITE (master) connections are only configured on demand.
 
 {% highlight php %}
 <?php
-$con = Configuration::getInstance()->getReadConnection(MyPeer::DATABASE_NAME);
+$con = Propel::getReadConnection(MyPeer::DATABASE_NAME);
 $stmt = $con->query('SELECT * FROM my');
 /* ... */
 {% endhighlight %}
 
 ### `ConnectionManager::setForceMasterConnection()` ###
 
-You can force Propel to always return a WRITE (master) connection when calling `Configuration::getInstance()->getReadConnection()`, even though there are some slaves connections defined.
+You can force Propel to always return a WRITE (master) connection when calling `Propel::getServiceContainer()->getReadConnection()`, even though there are some slaves connections defined.
 
 To do so, call the `setForceMasterConnection()` method on the related `ConnectionManager`, as follows:
 
 {% highlight php %}
 <?php
-$manager = Configuration::getInstance()->getConnectionManager(MyPeer::DATABASE_NAME);
+$manager = Propel::getServiceContainer()->getConnectionManager(MyPeer::DATABASE_NAME);
 $manager->setForceMasterConnection(true);
-$con = Configuration::getInstance()->getReadConnection(MyPeer::DATABASE_NAME);
+$con = Propel::getReadConnection(MyPeer::DATABASE_NAME);
 // $con is a WRITE connection
 {% endhighlight %}
 

documentation/documentation/03-basic-crud.markdown

@@ -165,8 +165,8 @@ As Propel uses PDO to query the underlying database, you can always write custom
 
 {% highlight php %}
 <?php
-use Propel\Runtime\Configuration;
-$con = Configuration::getInstance()->getConnection(BookPeer::DATABASE_NAME);
+use Propel\Runtime\Propel;
+$con = Propel::getConnection(BookPeer::DATABASE_NAME);
 $sql = "SELECT * FROM book WHERE id NOT IN "
         ."(SELECT book_review.book_id FROM book_review"
         ." INNER JOIN author ON (book_review.author_id=author.ID)"

documentation/documentation/06-transactions.markdown

@@ -15,12 +15,12 @@ Propel uses PDO as database abstraction layer, and therefore uses [PDO's built-i
 
 {% highlight php %}
 <?php
-use Propel\Runtime\Configuration;
+use Propel\Runtime\Propel;
 // ...
 public function transferMoney($fromAccountNumber, $toAccountNumber, $amount)
 {
   // get the PDO connection object from Propel
-  $con = Configuration::getInstance()->getConnection(AccountPeer::DATABASE_NAME);
+  $con = Propel::getWriteConnection(AccountPeer::DATABASE_NAME);
 
   $fromAccount = AccountPeer::retrieveByPk($fromAccountNumber, $con);
   $toAccount   = AccountPeer::retrieveByPk($toAccountNumber, $con);
@@ -47,7 +47,7 @@ The transaction statements are `beginTransaction()`, `commit()` and `rollback()`
 
 In this example, if something wrong happens while saving either one of the two accounts, an `Exception` is thrown, and the whole operation is rolled back. That means that the transfer is cancelled, with an insurance that the money hasn't vanished (that's the A in ACID, which stands for "Atomicity"). If both account modifications work as expected, the whole transaction is committed, meaning that the data changes enclosed in the transaction are persisted in the database.
 
-Tip: In order to build a transaction, you need a connection object. The connection object for a Propel model is always available through `Configuration::getInstance()->getConnection([ModelName]Peer::DATABASE_NAME)`.
+Tip: In order to build a transaction, you need a connection object. The connection object for a Propel model is always available through `Propel::getReadConnection([ModelName]Peer::DATABASE_NAME)` (for READ queries) and `Propel::getWriteConnection([ModelName]Peer::DATABASE_NAME)` (for WRITE queries).
 
 ## Denormalization And Transactions ##
 
@@ -79,17 +79,17 @@ You must update this new column every time you save or delete a `Book` object; t
 <?php
 class Book extends BaseBook
 {
-  public function postSave(PropelPDO $con)
+  public function postSave(ConnectionInterface $con)
   {
     $this->updateNbBooks($con);
   }
 
-  public function postDelete(PropelPDO $con)
+  public function postDelete(ConnectionInterface $con)
   {
     $this->updateNbBooks($con);
   }
 
-  public function updateNbBooks(PropelPDO $con)
+  public function updateNbBooks(ConnectionInterface $con)
   {
     $author = $this->getAuthor();
     $nbBooks = $author->countBooks($con);
@@ -105,7 +105,7 @@ The `BaseBook::save()` method wraps the actual database INSERT/UPDATE query insi
 <?php
 class Book extends BaseBook
 {
-  public function save(PropelPDO $con)
+  public function save(ConnectionInterface $con)
   {
     $con->beginTransaction();
 
@@ -138,7 +138,7 @@ Some RDBMS offer the ability to nest transactions, to allow partial rollback of
 
 {% highlight php %}
 <?php
-function deleteBooksWithNoPrice(PropelPDO $con)
+function deleteBooksWithNoPrice(ConnectionInterface $con)
 {
   $con->beginTransaction();
   try {
@@ -152,7 +152,7 @@ function deleteBooksWithNoPrice(PropelPDO $con)
   }
 }
 
-function deleteAuthorsWithNoEmail(PropelPDO $con)
+function deleteAuthorsWithNoEmail(ConnectionInterface $con)
 {
   $con->beginTransaction();
   try {
@@ -166,7 +166,7 @@ function deleteAuthorsWithNoEmail(PropelPDO $con)
   }
 }
 
-function cleanup(PropelPDO $con)
+function cleanup(ConnectionInterface $con)
 {
   $con->beginTransaction();
   try {
@@ -194,7 +194,7 @@ A database transaction has a cost in terms of performance. In fact, for simple d
 
 {% highlight php %}
 <?php
-$con = Configuration::getInstance()->getConnection(BookPeer::DATABASE_NAME);
+$con = Propel::getConnection(BookPeer::DATABASE_NAME);
 for ($i=0; $i<2002; $i++)
 {
   $book = new Book();
@@ -222,7 +222,7 @@ You can take advantage of Propel's nested transaction capabilities to encapsulat
 
 {% highlight php %}
 <?php
-$con = Configuration::getInstance()->getConnection(BookPeer::DATABASE_NAME);
+$con = Propel::getConnection(BookPeer::DATABASE_NAME);
 $con->beginTransaction();
 for ($i=0; $i<2002; $i++)
 {
@@ -250,11 +250,11 @@ Tip: Until the final `commit()` is called, most database engines lock updated ro
 
 ## Why Is The Connection Always Passed As Parameter? ##
 
-All the code examples in this chapter show the connection object passed a a parameter to Propel methods that trigger a database query:
+All the code examples in this chapter show the connection object passed as a parameter to Propel methods that trigger a database query:
 
 {% highlight php %}
 <?php
-$con = Configuration::getInstance()->getConnection(AccountPeer::DATABASE_NAME);
+$con = Propel::getConnection(AccountPeer::DATABASE_NAME);
 $fromAccount = AccountPeer::retrieveByPk($fromAccountNumber, $con);
 $fromAccount->setValue($fromAccount->getValue() - $amount);
 $fromAccount->save($con);

documentation/documentation/07-behaviors.markdown

@@ -41,7 +41,7 @@ Then, you can force the update of the `created_at` column before every insertion
 <?php
 class Book extends BaseBook
 {
-  public function preInsert(PropelPDO $con = null)
+  public function preInsert(ConnectionInterface $con = null)
   {
     $this->setCreatedAt(time());
     return true;
@@ -384,8 +384,8 @@ class FastPkFindBehavior extends Behavior
 public function findPk(\$key, \$con = null)
 {
   \$query = 'SELECT * from `%s` WHERE id = ?';
-  if (null ### \$con) {
-    \$con = Configuration::getInstance()->getConnection(%sPeer::DATABASE_NAME);
+  if (null === \$con) {
+    \$con = Propel::getReadConnection(%sPeer::DATABASE_NAME);
   }
   \$stmt = \$con->prepare(\$query);
   \$stmt->bindValue(1, \$key);

documentation/documentation/08-logging.markdown

@@ -207,7 +207,7 @@ The debug mode is disabled by default, but you can enable it at runtime as follo
 
 {% highlight php %}
 <?php
-$con = Configuration::getInstance()->getConnection(MyObjPeer::DATABASE_NAME);
+$con = Propel::getConnection(MyObjPeer::DATABASE_NAME);
 $con->useDebug(true);
 {% endhighlight %}
 
@@ -235,7 +235,7 @@ In debug mode, `PropelPDO` keeps track of the number of queries that are execute
 
 {% highlight php %}
 <?php
-$con = Configuration::getInstance()->getConnection(MyObjPeer::DATABASE_NAME);
+$con = Propel::getConnection(MyObjPeer::DATABASE_NAME);
 $myObjs = MyObjPeer::doSelect(new Criteria(), $con);
 echo $con->getQueryCount();  // 1
 {% endhighlight %}
@@ -248,7 +248,7 @@ For debugging purposes, you may need the SQL code of the latest executed query.
 
 {% highlight php %}
 <?php
-$con = Configuration::getInstance()->getConnection(MyObjPeer::DATABASE_NAME);
+$con = Propel::getConnection(MyObjPeer::DATABASE_NAME);
 $myObjs = MyObjPeer::doSelect(new Criteria(), $con);
 echo $con->getLastExecutedQuery(); // 'SELECT * FROM my_obj';
 {% endhighlight %}
@@ -259,7 +259,7 @@ Propel also keeps track of the queries executed directly on the connection objec
 
 {% highlight php %}
 <?php
-$con = Configuration::getInstance()->getConnection(MyObjPeer::DATABASE_NAME);
+$con = Propel::getConnection(MyObjPeer::DATABASE_NAME);
 $stmt = $con->prepare('SELECT * FROM my_obj WHERE name = :p1');
 $stmt->bindValue(':p1', 'foo');
 $stmt->execute();
@@ -412,7 +412,7 @@ By default the connection log messages are logged at the `Propel::LOG_DEBUG` lev
 
 {% highlight php %}
 <?php
-$con = Configuration::getInstance()->getConnection(MyObjPeer::DATABASE_NAME);
+$con = Propel::getConnection(MyObjPeer::DATABASE_NAME);
 $con->setLogLevel(Propel::LOG_INFO);
 {% endhighlight %}
 
@@ -426,7 +426,7 @@ If you would like the queries to be logged using a different logger (e.g. to a d
 
 {% highlight php %}
 <?php
-$con = Configuration::getInstance()->getConnection(MyObjPeer::DATABASE_NAME);
+$con = Propel::getConnection(MyObjPeer::DATABASE_NAME);
 $logger = Log::factory('syslog', LOG_LOCAL0, 'propel', array(), PEAR_LOG_INFO);
 $con->setLogger($logger);
 {% endhighlight %}

documentation/reference/active-record.markdown

@@ -191,7 +191,7 @@ $book->delete();
 // DELETE FROM book WHERE id = 1234
 
 // All persistence methods accept a connection object
-$con = Configuration::getInstance()->getConnection(BookPeer::DATABASE_NAME, Propel::CONNECTION_WRITE);
+$con = Propel::getWriteConnection(BookPeer::DATABASE_NAME);
 $book->delete($con);
 {% endhighlight %}
 

documentation/reference/model-criteria.markdown

@@ -332,7 +332,7 @@ $books = BookQuery::create()
 <?php
 // All the termination methods accept a Connection object
 // So you can specify which connection to use
-$con = Configuration::getInstance()->getConnection('bookstore', Propel::CONNECTION_READ);
+$con = Propel::getReadConnection(BookPeer::DATABASE_NAME);
 $nbBooks = BookQuery::create()
   ->findOne($con);
 {% endhighlight %}

src/Propel/Generator/Behavior/Archivable/templates/queryArchive.php

@@ -23,7 +23,7 @@ public function archive($con = null, $useLittleMemory = true)
         $criteria->setFormatter(ModelCriteria::FORMAT_ON_DEMAND);
     }
     if ($con === null) {
-        $con = Configuration::getInstance()->getWriteConnection(<?php echo $modelPeerName ?>::DATABASE_NAME);
+        $con = Propel::getServiceContainer()->getWriteConnection(<?php echo $modelPeerName ?>::DATABASE_NAME);
     }
     $con->beginTransaction();
     try {

src/Propel/Generator/Behavior/NestedSet/NestedSetBehaviorObjectBuilderModifier.php

@@ -1393,7 +1393,7 @@ protected function moveSubtreeTo(\$destLeft, \$levelDelta, ConnectionInterface \
     \$treeSize = \$right - \$left +1;
 
     if (\$con === null) {
-        \$con = Configuration::getInstance()->getWriteConnection($peerClassname::DATABASE_NAME);
+        \$con = Propel::getServiceContainer()->getWriteConnection($peerClassname::DATABASE_NAME);
     }
 
     \$con->beginTransaction();
@@ -1452,7 +1452,7 @@ public function deleteDescendants(ConnectionInterface \$con = null)
         return;
     }
     if (\$con === null) {
-        \$con = Configuration::getInstance()->getReadConnection($peerClassname::DATABASE_NAME);
+        \$con = Propel::getServiceContainer()->getReadConnection($peerClassname::DATABASE_NAME);
     }
     \$left = \$this->getLeftValue();
     \$right = \$this->getRightValue();";

src/Propel/Generator/Behavior/NestedSet/NestedSetBehaviorPeerBuilderModifier.php

@@ -283,7 +283,7 @@ protected function addShiftRLValues(&$script)
 public static function shiftRLValues(\$delta, \$first, \$last = null" . ($useScope ? ", \$scope = null" : ""). ", ConnectionInterface \$con = null)
 {
     if (\$con === null) {
-        \$con = Configuration::getInstance()->getWriteConnection($peerClassname::DATABASE_NAME);
+        \$con = Propel::getServiceContainer()->getWriteConnection($peerClassname::DATABASE_NAME);
     }
 
     // Shift left column values
@@ -347,7 +347,7 @@ protected function addShiftLevel(&$script)
 public static function shiftLevel(\$delta, \$first, \$last" . ($useScope ? ", \$scope = null" : ""). ", ConnectionInterface \$con = null)
 {
     if (\$con === null) {
-        \$con = Configuration::getInstance()->getWriteConnection($peerClassname::DATABASE_NAME);
+        \$con = Propel::getServiceContainer()->getWriteConnection($peerClassname::DATABASE_NAME);
     }
 
     \$whereCriteria = new Criteria($peerClassname::DATABASE_NAME);

src/Propel/Generator/Behavior/QueryCacheBehavior.php

@@ -50,7 +50,7 @@ public function queryAttributes($builder)
 
     public function queryMethods($builder)
     {
-        $builder->declareClasses('\Propel\Runtime\Configuration', '\Propel\Runtime\Util\BasePeer');
+        $builder->declareClasses('\Propel\Runtime\Propel', '\Propel\Runtime\Util\BasePeer');
         $this->peerClassname = $builder->getStubPeerBuilder()->getClassname();
         $script = '';
         $this->addSetQueryKey($script);
@@ -177,8 +177,8 @@ protected function doSelect(\$con)
     }
     \$this->configureSelectColumns();
 
-    \$dbMap = Configuration::getInstance()->getDatabaseMap(" . $this->peerClassname ."::DATABASE_NAME);
-    \$db = Configuration::getInstance()->getAdapter(" . $this->peerClassname ."::DATABASE_NAME);
+    \$dbMap = Propel::getServiceContainer()->getDatabaseMap(" . $this->peerClassname ."::DATABASE_NAME);
+    \$db = Propel::getServiceContainer()->getAdapter(" . $this->peerClassname ."::DATABASE_NAME);
 
     \$key = \$this->getQueryKey();
     if (\$key && \$this->cacheContains(\$key)) {
@@ -211,8 +211,8 @@ protected function addDoCount(&$script)
         $script .= "
 protected function doCount(\$con)
 {
-    \$dbMap = Configuration::getInstance()->getDatabaseMap(\$this->getDbName());
-    \$db = Configuration::getInstance()->getAdapter(\$this->getDbName());
+    \$dbMap = Propel::getServiceContainer()->getDatabaseMap(\$this->getDbName());
+    \$db = Propel::getServiceContainer()->getAdapter(\$this->getDbName());
 
     \$key = \$this->getQueryKey();
     if (\$key && \$this->cacheContains(\$key)) {

src/Propel/Generator/Behavior/SoftDeleteBehavior.php

@@ -374,7 +374,7 @@ public function addPeerDoSoftDelete(&$script)
 public static function doSoftDelete(\$values, ConnectionInterface \$con = null)
 {
     if (\$con === null) {
-        \$con = Configuration::getInstance()->getWriteConnection({$this->getTable()->getPhpName()}Peer::DATABASE_NAME);
+        \$con = Propel::getServiceContainer()->getWriteConnection({$this->getTable()->getPhpName()}Peer::DATABASE_NAME);
     }
     if (\$values instanceof Criteria) {
         // rename for clarity
@@ -447,7 +447,7 @@ public function addPeerDoSoftDeleteAll(&$script)
 public static function doSoftDeleteAll(ConnectionInterface \$con = null)
 {
     if (\$con === null) {
-        \$con = Configuration::getInstance()->getWriteConnection({$this->builder->getPeerClassname()}::DATABASE_NAME);
+        \$con = Propel::getServiceContainer()->getWriteConnection({$this->builder->getPeerClassname()}::DATABASE_NAME);
     }
     \$selectCriteria = new Criteria();
     \$selectCriteria->add({$this->builder->getColumnConstant($this->getColumnForParameter('deleted_column'))}, null, Criteria::ISNULL);