Replace patchable get_model with a provider #20

README.md

@@ -2149,9 +2149,10 @@ foreach ($connections as $id => $connection)
 
 
 
-### The models provider
+### Model collection
 
-The models provider manages models.
+Models are managed using a model collection that resolves model attributes (such as database
+connections) and instantiate them.
 
 
 
@@ -2314,6 +2315,38 @@ var_dump($models->is_installed()); // [ "nodes" => false, "contents" => false ]
 
 
 
+#### Model provider
+
+The `get_model()` helper retrieves models using their identifier. It is used by active records to
+retrieve their model when required, and by queries during joins. Models are retrieved using the
+model collection returned by [ModelProvider][].
+
+The following example demonstrates how to define a model provider:
+
+```php
+<?php
+
+use ICanBoogie\ActiveRecord;
+use ICanBoogie\ActiveRecord\ModelProvider;
+use function ICanBoogie\ActiveRecord\get_model;
+
+/* @var $models ActiveRecord\ModelCollection */
+
+ModelProvider::define(function($id) use($models) {
+
+	return $models[$id];
+
+});
+
+$nodes = get_model('nodes');
+```
+
+> **Note:** A `LogicException` is thrown if no provider is defined when `get_model()` require it.
+
+
+
+
+
 ## Records caching
 
 By default, each model uses an instance of [RuntimeActiveRecordCache][] to cache its records.
@@ -2397,34 +2430,7 @@ already instantiated model.
 
 
 
-## Patching
-
-### Retrieving models from a provider
-
-The `get_model()` helper retrieves models using their identifier. It is used by active
-records to retrieve their model when required, and by queries during joins. You need to patch
-this helper according to your application logic because the default implementation only throws
-`\RuntimeException`.
-
-In the following example, the `get_model()` helper is patched to retrieve models from a provider
-similar to the one we've seen in previous examples.
-
-```php
-<?php
-
-use ICanBoogie\ActiveRecord;
-use ICanBoogie\ActiveRecord\Helpers;
-
-/* @var $models ActiveRecord\ModelCollection */
-
-Helpers::patch('get_model', function($id) use($models) {
-
-	return $models[$id];
-
-});
-
-$nodes = ActiveRecord\get_model('nodes');
-```
+----------
 
 
 
@@ -2509,6 +2515,7 @@ The package is continuously tested by [Travis CI](http://about.travis-ci.org/).
 [ModelAlreadyInstantiated]:     http://api.icanboogie.org/activerecord/4.0/class-ICanBoogie.ActiveRecord.ModelAlreadyInstantiated.html
 [ModelNotDefined]:              http://api.icanboogie.org/activerecord/4.0/class-ICanBoogie.ActiveRecord.ModelNotDefined.html
 [ModelCollection]:              http://api.icanboogie.org/activerecord/4.0/class-ICanBoogie.ActiveRecord.ModelCollection.html
+[ModelProvider]:                http://api.icanboogie.org/activerecord/4.0/class-ICanBoogie.ActiveRecord.ModelProvider.html
 [Query]:                        http://api.icanboogie.org/activerecord/4.0/class-ICanBoogie.ActiveRecord.Query.html
 [RecordNotFound]:               http://api.icanboogie.org/activerecord/4.0/class-ICanBoogie.ActiveRecord.RecordNotFound.html
 [RecordNotValid]:               http://api.icanboogie.org/activerecord/4.0/class-ICanBoogie.ActiveRecord.RecordNotValid.html

helpers.php

@@ -12,15 +12,17 @@
 namespace ICanBoogie\ActiveRecord;
 
 /**
- * Returns the requested model.
+ * Returns a given model.
  *
  * @param string $id Model identifier.
  *
  * @return Model
+ *
+ * @throws ModelNotDefined if the model cannot be found.
  */
 function get_model($id)
 {
-	return Helpers::get_model($id);
+	return ModelProvider::provide($id);
 }
 
 /**

lib/ActiveRecord/ModelProvider.php

@@ -0,0 +1,85 @@
+<?php
+
+/*
+ * This file is part of the ICanBoogie package.
+ *
+ * (c) Olivier Laviale <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace ICanBoogie\ActiveRecord;
+
+/**
+ * Provides a {@link Model} instance.
+ */
+class ModelProvider
+{
+	/**
+	 * @var callable {@link Model} provider
+	 */
+	static private $provider;
+
+	/**
+	 * Defines the {@link Model} provider.
+	 *
+	 * @param callable $provider
+	 *
+	 * @return callable The previous provider, or `null` if none was defined.
+	 */
+	static public function define(callable $provider)
+	{
+		$previous = self::$provider;
+
+		self::$provider = $provider;
+
+		return $previous;
+	}
+
+	/**
+	 * Returns the current provider.
+	 *
+	 * @return callable|null
+	 */
+	static public function defined()
+	{
+		return self::$provider;
+	}
+
+	/**
+	 * Undefine the provider.
+	 */
+	static public function undefine()
+	{
+		self::$provider = null;
+	}
+
+	/**
+	 * Returns a {@link Model} instance using the provider.
+	 *
+	 * @param string $id Model identifier.
+	 *
+	 * @return Model
+	 *
+	 * @throws ModelNotDefined if the model cannot be provided.
+	 */
+	static public function provide($id)
+	{
+		$provider = self::$provider;
+
+		if (!$provider)
+		{
+			throw new \LogicException("No provider is defined yet. Please define one with `ModelProvider::define(\$provider)`.");
+		}
+
+		$model = $provider($id);
+
+		if (!$model)
+		{
+			throw new ModelNotDefined($id);
+		}
+
+		return $model;
+	}
+}

tests/ActiveRecordTest.php

@@ -1,38 +1,53 @@
 <?php
 
+/*
+ * This file is part of the ICanBoogie package.
+ *
+ * (c) Olivier Laviale <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
 namespace ICanBoogie;
 
-use ICanBoogie\ActiveRecord\Helpers;
 use ICanBoogie\ActiveRecord\Model;
+use ICanBoogie\ActiveRecord\ModelCollection;
 use ICanBoogie\ActiveRecord\ModelNotDefined;
+use ICanBoogie\ActiveRecord\ModelProvider;
 use ICanBoogie\ActiveRecord\RecordNotValid;
 use ICanBoogie\ActiveRecord\Schema;
 use ICanBoogie\ActiveRecordTest\Sample;
 use ICanBoogie\ActiveRecordTest\ValidateCase;
 
 /**
- * @covers \ICanBoogie\ActiveRecord
+ * @group record
  */
 class ActiveRecordTest extends \PHPUnit_Framework_TestCase
 {
 	private $sample_model;
 
 	public function setUp()
 	{
+		$sample_model = &$this->sample_model;
+
+		if ($sample_model)
+		{
+			return;
+		}
+
 		$sample_model = $this->mockModel();
 
-		Helpers::patch('get_model', function($model_id) use ($sample_model) {
+		ModelProvider::define(function($model_id) use ($sample_model) {
 
 			if ($model_id === 'sample')
 			{
 				return $sample_model;
 			}
 
-			throw new ModelNotDefined($sample_model);
+			return null;
 
 		});
-
-		$this->sample_model = $sample_model;
 	}
 
 	public function test_should_resolve_model_id_from_const()