Implement Loader method chaining

Requested in issue #2165
Supersedes PR #2319

3 files changed, 75 insertions, 57 deletions

diff --git a/system/core/Loader.php b/system/core/Loader.php
index 28b9502fd..daf326f25 100644
--- a/system/core/Loader.php
+++ b/system/core/Loader.php
@@ -174,13 +174,13 @@ class CI_Loader {
 	 * @param	string	$library	Library name
 	 * @param	array	$params		Optional parameters to pass to the library class constructor
 	 * @param	string	$object_name	An optional object name to assign to
-	 * @return	void
+	 * @return	object
 	 */
 	public function library($library, $params = NULL, $object_name = NULL)
 	{
 		if (empty($library))
 		{
-			return;
+			return $this;
 		}
 		elseif (is_array($library))
 		{
@@ -189,7 +189,7 @@ class CI_Loader {
 				$this->library($class, $params);
 			}
 
-			return;
+			return $this;
 		}
 
 		if ($params !== NULL && ! is_array($params))
@@ -198,6 +198,7 @@ class CI_Loader {
 		}
 
 		$this->_ci_load_class($library, $params, $object_name);
+		return $this;
 	}
 
 	// --------------------------------------------------------------------
@@ -210,13 +211,13 @@ class CI_Loader {
 	 * @param	string	$model		Model name
 	 * @param	string	$name		An optional object name to assign to
 	 * @param	bool	$db_conn	An optional database connection configuration to initialize
-	 * @return	void
+	 * @return	object
 	 */
 	public function model($model, $name = '', $db_conn = FALSE)
 	{
 		if (empty($model))
 		{
-			return;
+			return $this;
 		}
 		elseif (is_array($model))
 		{
@@ -224,7 +225,8 @@ class CI_Loader {
 			{
 				is_int($key) ? $this->model($value, '', $db_conn) : $this->model($key, $value, $db_conn);
 			}
-			return;
+
+			return $this;
 		}
 
 		$path = '';
@@ -246,7 +248,7 @@ class CI_Loader {
 
 		if (in_array($name, $this->_ci_models, TRUE))
 		{
-			return;
+			return $this;
 		}
 
 		$CI =& get_instance();
@@ -283,7 +285,7 @@ class CI_Loader {
 
 			$CI->$name = new $model();
 			$this->_ci_models[] = $name;
-			return;
+			return $this;
 		}
 
 		// couldn't find the model
@@ -300,8 +302,8 @@ class CI_Loader {
 	 * @param	bool	$query_builder	Whether to enable Query Builder
 	 *					(overrides the configuration setting)
 	 *
-	 * @return	void|object|bool	Database object if $return is set to TRUE,
-	 *					FALSE on failure, void in any other case
+	 * @return	object|bool	Database object if $return is set to TRUE,
+	 *					FALSE on failure, CI_Loader instance in any other case
 	 */
 	public function database($params = '', $return = FALSE, $query_builder = NULL)
 	{
@@ -327,6 +329,7 @@ class CI_Loader {
 
 		// Load the DB class
 		$CI->db =& DB($params, $query_builder);
+		return $this;
 	}
 
 	// --------------------------------------------------------------------
@@ -336,7 +339,7 @@ class CI_Loader {
 	 *
 	 * @param	object	$db	Database object
 	 * @param	bool	$return	Whether to return the DB Utilities class object or not
-	 * @return	void|object
+	 * @return	object
 	 */
 	public function dbutil($db = NULL, $return = FALSE)
 	{
@@ -358,6 +361,7 @@ class CI_Loader {
 		}
 
 		$CI->dbutil = new $class($db);
+		return $this;
 	}
 
 	// --------------------------------------------------------------------
@@ -367,7 +371,7 @@ class CI_Loader {
 	 *
 	 * @param	object	$db	Database object
 	 * @param	bool	$return	Whether to return the DB Forge class object or not
-	 * @return	void|object
+	 * @return	object
 	 */
 	public function dbforge($db = NULL, $return = FALSE)
 	{
@@ -401,6 +405,7 @@ class CI_Loader {
 		}
 
 		$CI->dbforge = new $class($db);
+		return $this;
 	}
 
 	// --------------------------------------------------------------------
@@ -415,7 +420,7 @@ class CI_Loader {
 	 *				to be extracted for use in the view
 	 * @param	bool	$return	Whether to return the view output
 	 *				or leave it to the Output class
-	 * @return	void|string
+	 * @return	object|string
 	 */
 	public function view($view, $vars = array(), $return = FALSE)
 	{
@@ -429,7 +434,7 @@ class CI_Loader {
 	 *
 	 * @param	string	$path	File path
 	 * @param	bool	$return	Whether to return the file output
-	 * @return	void|string
+	 * @return	object|string
 	 */
 	public function file($path, $return = FALSE)
 	{
@@ -448,7 +453,7 @@ class CI_Loader {
 	 *					An associative array or object containing values
 	 *					to be set, or a value's name if string
 	 * @param 	string	$val	Value to set, only used if $vars is a string
-	 * @return	void
+	 * @return	object
 	 */
 	public function vars($vars, $val = '')
 	{
@@ -466,6 +471,8 @@ class CI_Loader {
 				$this->_ci_cached_vars[$key] = $val;
 			}
 		}
+
+		return $this;
 	}
 
 	// --------------------------------------------------------------------
@@ -475,11 +482,12 @@ class CI_Loader {
 	 *
 	 * Clears the cached variables.
 	 *
-	 * @return  void
+	 * @return  object
 	 */
 	public function clear_vars()
 	{
 		$this->_ci_cached_vars = array();
+		return $this;
 	}
 
 	// --------------------------------------------------------------------
@@ -517,7 +525,7 @@ class CI_Loader {
 	 * Helper Loader
 	 *
 	 * @param	string|string[]	$helpers	Helper name(s)
-	 * @return	void
+	 * @return	object
 	 */
 	public function helper($helpers = array())
 	{
@@ -574,6 +582,8 @@ class CI_Loader {
 				show_error('Unable to load the requested file: helpers/'.$helper.'.php');
 			}
 		}
+
+		return $this;
 	}
 
 	// --------------------------------------------------------------------
@@ -586,11 +596,11 @@ class CI_Loader {
 	 *
 	 * @uses	CI_Loader::helper()
 	 * @param	string|string[]	$helpers	Helper name(s)
-	 * @return	void
+	 * @return	object
 	 */
 	public function helpers($helpers = array())
 	{
-		$this->helper($helpers);
+		return $this->helper($helpers);
 	}
 
 	// --------------------------------------------------------------------
@@ -602,18 +612,19 @@ class CI_Loader {
 	 *
 	 * @param	string|string[]	$files	List of language file names to load
 	 * @param	string		Language name
-	 * @return	void
+	 * @return	object
 	 */
 	public function language($files, $lang = '')
 	{
 		$CI =& get_instance();
-
 		is_array($files) OR $files = array($files);
 
 		foreach ($files as $langfile)
 		{
 			$CI->lang->load($langfile, $lang);
 		}
+
+		return $this;
 	}
 
 	// --------------------------------------------------------------------
@@ -646,8 +657,8 @@ class CI_Loader {
 	 * @param	array		$params		Optional parameters to pass to the driver
 	 * @param	string		$object_name	An optional object name to assign to
 	 *
-	 * @return	void|object|bool	Object or FALSE on failure if $library is a string
-	 *					and $object_name is set. void otherwise.
+	 * @return	object|bool	Object or FALSE on failure if $library is a string
+	 *				and $object_name is set. CI_Loader instance otherwise.
 	 */
 	public function driver($library, $params = NULL, $object_name = NULL)
 	{
@@ -657,10 +668,10 @@ class CI_Loader {
 			{
 				$this->driver($driver);
 			}
-			return;
-		}
 
-		if ($library === '')
+			return $this;
+		}
+		elseif (empty($library))
 		{
 			return FALSE;
 		}
@@ -696,7 +707,7 @@ class CI_Loader {
 	 *
 	 * @param	string	$path		Path to add
 	 * @param 	bool	$view_cascade	(default: TRUE)
-	 * @return	void
+	 * @return	object
 	 */
 	public function add_package_path($path, $view_cascade = TRUE)
 	{
@@ -711,6 +722,8 @@ class CI_Loader {
 		// Add config file path
 		$config =& $this->_ci_get_component('config');
 		$config->_config_paths[] = $path;
+
+		return $this;
 	}
 
 	// --------------------------------------------------------------------
@@ -738,7 +751,7 @@ class CI_Loader {
 	 * added path will be removed removed.
 	 *
 	 * @param	string	$path	Path to remove
-	 * @return	void
+	 * @return	object
 	 */
 	public function remove_package_path($path = '')
 	{
@@ -780,6 +793,8 @@ class CI_Loader {
 		$this->_ci_model_paths = array_unique(array_merge($this->_ci_model_paths, array(APPPATH)));
 		$this->_ci_view_paths = array_merge($this->_ci_view_paths, array(APPPATH.'views/' => TRUE));
 		$config->_config_paths = array_unique(array_merge($config->_config_paths, array(APPPATH)));
+
+		return $this;
 	}
 
 	// --------------------------------------------------------------------
@@ -795,7 +810,7 @@ class CI_Loader {
 	 * @used-by	CI_Loader::view()
 	 * @used-by	CI_Loader::file()
 	 * @param	array	$_ci_data	Data to load
-	 * @return	void
+	 * @return	object
 	 */
 	protected function _ci_load($_ci_data)
 	{
@@ -919,6 +934,8 @@ class CI_Loader {
 			$_ci_CI->output->append_output(ob_get_contents());
 			@ob_end_clean();
 		}
+
+		return $this;
 	}
 
 	// --------------------------------------------------------------------
diff --git a/tests/codeigniter/core/Loader_test.php b/tests/codeigniter/core/Loader_test.php
index 8fbeaec7b..799bcd967 100644
--- a/tests/codeigniter/core/Loader_test.php
+++ b/tests/codeigniter/core/Loader_test.php
@@ -31,12 +31,12 @@ class Loader_test extends CI_TestCase {
 		$this->assertFalse($this->load->is_loaded(ucfirst($lib)));
 
 		// Test loading as an array.
-		$this->assertNull($this->load->library(array($lib)));
+		$this->assertInstanceOf('CI_Loader', $this->load->library(array($lib)));
 		$this->assertTrue(class_exists($class), $class.' does not exist');
 		$this->assertAttributeInstanceOf($class, $lib, $this->ci_obj);
 
 		// Test a string given to params
-		$this->assertNull($this->load->library($lib, ' '));
+		$this->assertInstanceOf('CI_Loader', $this->load->library($lib, ' '));
 
 		// Create library w/o class
 		$lib = 'bad_test_lib';
@@ -47,7 +47,7 @@ class Loader_test extends CI_TestCase {
 			'RuntimeException',
 			'CI Error: Unable to load the requested class: '.ucfirst($lib)
 		);
-		$this->assertNull($this->load->library($lib));
+		$this->assertInstanceOf('CI_Loader', $this->load->library($lib));
 	}
 
 	// --------------------------------------------------------------------
@@ -63,7 +63,7 @@ class Loader_test extends CI_TestCase {
 		$this->ci_vfs_create($ext, '<?php class '.$ext.' extends '.$class.' { }', $this->ci_app_root, 'libraries');
 
 		// Test loading with extension
-		$this->assertNull($this->load->library($lib));
+		$this->assertInstanceOf('CI_Loader', $this->load->library($lib));
 		$this->assertTrue(class_exists($class), $class.' does not exist');
 		$this->assertTrue(class_exists($ext), $ext.' does not exist');
 		$this->assertAttributeInstanceOf($class, $name, $this->ci_obj);
@@ -71,13 +71,13 @@ class Loader_test extends CI_TestCase {
 
 		// Test reloading with object name
 		$obj = 'exttest';
-		$this->assertNull($this->load->library($lib, NULL, $obj));
+		$this->assertInstanceOf('CI_Loader', $this->load->library($lib, NULL, $obj));
 		$this->assertAttributeInstanceOf($class, $obj, $this->ci_obj);
 		$this->assertAttributeInstanceOf($ext, $obj, $this->ci_obj);
 
 		// Test reloading
 		unset($this->ci_obj->$name);
-		$this->assertNull($this->load->library($lib));
+		$this->assertInstanceOf('CI_Loader', $this->load->library($lib));
 		$this->assertObjectNotHasAttribute($name, $this->ci_obj);
 
 		// Create baseless library
@@ -91,7 +91,7 @@ class Loader_test extends CI_TestCase {
 			'RuntimeException',
 			'CI Error: Unable to load the requested class: '.$lib
 		);
-		$this->assertNull($this->load->library($lib));
+		$this->assertInstanceOf('CI_Loader', $this->load->library($lib));
 	}
 
 	// --------------------------------------------------------------------
@@ -114,7 +114,7 @@ class Loader_test extends CI_TestCase {
 
 		// Test object name and config
 		$obj = 'testy';
-		$this->assertNull($this->load->library($lib, NULL, $obj));
+		$this->assertInstanceOf('CI_Loader', $this->load->library($lib, NULL, $obj));
 		$this->assertTrue(class_exists($class), $class.' does not exist');
 		$this->assertAttributeInstanceOf($class, $obj, $this->ci_obj);
 		$this->assertEquals($cfg, $this->ci_obj->$obj->config);
@@ -133,7 +133,7 @@ class Loader_test extends CI_TestCase {
 		$this->ci_vfs_create(ucfirst($lib), '<?php class '.$class.' { }', $this->ci_app_root, 'libraries');
 
 		// Load library
-		$this->assertNull($this->load->library($lib));
+		$this->assertInstanceOf('CI_Loader', $this->load->library($lib));
 
 		// Was the model class instantiated.
 		$this->assertTrue(class_exists($class), $class.' does not exist');
@@ -155,17 +155,17 @@ class Loader_test extends CI_TestCase {
 		$this->ci_vfs_create(ucfirst($driver), $content, $this->ci_base_root, 'libraries/'.$dir);
 
 		// Test loading as an array.
-		$this->assertNull($this->load->driver(array($driver)));
+		$this->assertInstanceOf('CI_Loader', $this->load->driver(array($driver)));
 		$this->assertTrue(class_exists($class), $class.' does not exist');
 		$this->assertAttributeInstanceOf($class, $driver, $this->ci_obj);
 
 		// Test loading as a library with a name
 		$obj = 'testdrive';
-		$this->assertNull($this->load->library($driver, NULL, $obj));
+		$this->assertInstanceOf('CI_Loader', $this->load->library($driver, NULL, $obj));
 		$this->assertAttributeInstanceOf($class, $obj, $this->ci_obj);
 
 		// Test a string given to params
-		$this->assertNull($this->load->driver($driver, ' '));
+		$this->assertInstanceOf('CI_Loader', $this->load->driver($driver, ' '));
 	}
 
 	// --------------------------------------------------------------------
@@ -180,14 +180,14 @@ class Loader_test extends CI_TestCase {
 		$this->ci_vfs_create($model, $content, $this->ci_app_root, 'models');
 
 		// Load model
-		$this->assertNull($this->load->model($model));
+		$this->assertInstanceOf('CI_Loader', $this->load->model($model));
 
 		// Was the model class instantiated.
 		$this->assertTrue(class_exists($model));
 		$this->assertObjectHasAttribute($model, $this->ci_obj);
 
 		// Test no model given
-		$this->assertNull($this->load->model(''));
+		$this->assertInstanceOf('CI_Loader', $this->load->model(''));
 	}
 
 	// --------------------------------------------------------------------
@@ -206,7 +206,7 @@ class Loader_test extends CI_TestCase {
 
 		// Load model
 		$name = 'testors';
-		$this->assertNull($this->load->model($subdir.'/'.$model, $name));
+		$this->assertInstanceOf('CI_Loader', $this->load->model($subdir.'/'.$model, $name));
 
 		// Was the model class instantiated?
 		$this->assertTrue(class_exists($model));
@@ -240,8 +240,8 @@ class Loader_test extends CI_TestCase {
 
 	// public function testDatabase()
 	// {
-	// 	$this->assertNull($this->load->database());
-	// 	$this->assertNull($this->load->dbutil());
+	// 	$this->assertInstanceOf('CI_Loader', $this->load->database());
+	// 	$this->assertInstanceOf('CI_Loader', $this->load->dbutil());
 	// }
 
 	// --------------------------------------------------------------------
@@ -265,7 +265,7 @@ class Loader_test extends CI_TestCase {
 		$this->ci_instance_var('output', $output);
 
 		// Test view output
-		$this->assertNull($this->load->view($view, array($var => $value)));
+		$this->assertInstanceOf('CI_Loader', $this->load->view($view, array($var => $value)));
 	}
 
 	// --------------------------------------------------------------------
@@ -311,8 +311,8 @@ class Loader_test extends CI_TestCase {
 		$val1 = 'bar';
 		$key2 = 'boo';
 		$val2 = 'hoo';
-		$this->assertNull($this->load->vars(array($key1 => $val1)));
-		$this->assertNull($this->load->vars($key2, $val2));
+		$this->assertInstanceOf('CI_Loader', $this->load->vars(array($key1 => $val1)));
+		$this->assertInstanceOf('CI_Loader', $this->load->vars($key2, $val2));
 		$this->assertEquals($val1, $this->load->get_var($key1));
 		$this->assertEquals(array($key1 => $val1, $key2 => $val2), $this->load->get_vars());
 	}
@@ -333,7 +333,7 @@ class Loader_test extends CI_TestCase {
 		$this->ci_vfs_create($this->prefix.$helper.'_helper', $content, $this->ci_app_root, 'helpers');
 
 		// Load helper
-		$this->assertNull($this->load->helper($helper));
+		$this->assertInstanceOf('CI_Loader', $this->load->helper($helper));
 		$this->assertTrue(function_exists($func), $func.' does not exist');
 		$this->assertTrue(function_exists($exfunc), $exfunc.' does not exist');
 
@@ -378,7 +378,7 @@ class Loader_test extends CI_TestCase {
 		$this->ci_vfs_create($files, NULL, $this->ci_base_root, 'helpers');
 
 		// Load helpers
-		$this->assertNull($this->load->helpers($helpers));
+		$this->assertInstanceOf('CI_Loader', $this->load->helpers($helpers));
 
 		// Verify helper existence
 		foreach ($funcs as $func) {
@@ -395,7 +395,7 @@ class Loader_test extends CI_TestCase {
 		$lang = $this->getMock('CI_Lang', array('load'));
 		$lang->expects($this->once())->method('load')->with($file);
 		$this->ci_instance_var('lang', $lang);
-		$this->assertNull($this->load->language($file));
+		$this->assertInstanceOf('CI_Loader', $this->load->language($file));
 	}
 
 	// --------------------------------------------------------------------
@@ -413,24 +413,24 @@ class Loader_test extends CI_TestCase {
 
 		// Add path and verify
 		$path = APPPATH.$dir.'/';
-		$this->assertNull($this->load->add_package_path($path));
+		$this->assertInstanceOf('CI_Loader', $this->load->add_package_path($path));
 		$this->assertContains($path, $this->load->get_package_paths(TRUE));
 
 		// Test successful load
-		$this->assertNull($this->load->library($lib));
+		$this->assertInstanceOf('CI_Loader', $this->load->library($lib));
 		$this->assertTrue(class_exists($class), $class.' does not exist');
 
 		// Add another path
 		$path2 = APPPATH.'another/';
-		$this->assertNull($this->load->add_package_path($path2));
+		$this->assertInstanceOf('CI_Loader', $this->load->add_package_path($path2));
 		$this->assertContains($path2, $this->load->get_package_paths(TRUE));
 
 		// Remove last path
-		$this->assertNull($this->load->remove_package_path());
+		$this->assertInstanceOf('CI_Loader', $this->load->remove_package_path());
 		$this->assertNotContains($path2, $this->load->get_package_paths(TRUE));
 
 		// Remove path and verify restored paths
-		$this->assertNull($this->load->remove_package_path($path));
+		$this->assertInstanceOf('CI_Loader', $this->load->remove_package_path($path));
 		$this->assertEquals($paths, $this->load->get_package_paths(TRUE));
 
 		// Test failed load without path
diff --git a/user_guide_src/source/changelog.rst b/user_guide_src/source/changelog.rst
index 892bbfbdf..32d033c9b 100644
--- a/user_guide_src/source/changelog.rst
+++ b/user_guide_src/source/changelog.rst
@@ -381,6 +381,7 @@ Release Date: Not Released
 
    -  :doc:`Loader Library <libraries/loader>` changes include:
 
+      -  Added method chaining support.
       -  Added method ``get_vars()`` to the Loader to retrieve all variables loaded with ``$this->load->vars()``.
       -  ``_ci_autoloader()`` is now a protected method.
       -  Added autoloading of drivers with ``$autoload['drivers']``.