php - get_instance() in Codeigniter: Why assign it to a variable?

Question

In Codeigniter, get_instance() is a globally available function that returns the Controller super-object which contains all the currently loaded classes (it returns the Controller class instance). I'll include the current source code:

get_instance() is defined in Codeigniter.php

// Load the base controller class
require BASEPATH.'core/Controller.php';

function &get_instance()
{
    return CI_Controller::get_instance();
}

And CI_Controller is defined in Controller.php

class CI_Controller {

    private static $instance;

    /**
     * Constructor
     */
    public function __construct()
    {
        self::$instance =& $this;

        // Assign all the class objects that were instantiated by the
        // bootstrap file (CodeIgniter.php) to local class variables
        // so that CI can run as one big super object.
        foreach (is_loaded() as $var => $class)
        {
            $this->$var =& load_class($class);
        }

        $this->load =& load_class('Loader', 'core');

        $this->load->set_base_classes()->ci_autoloader();

        log_message('debug', "Controller Class Initialized");
    }

    public static function &get_instance()
    {
        return self::$instance;
    }
}

Here's how it is recommended to be used in the user guide for creating libraries:

Utilizing CodeIgniter Resources within Your Library

To access CodeIgniter's native resources within your library use the get_instance() function. This function returns the CodeIgniter super object.

Normally from within your controller functions you will call any of the available CodeIgniter functions using the $this construct: $this->load->helper('url'); $this->load->library('session'); $this->config->item('base_url'); etc.

$this, however, only works directly within your controllers, your models, or your views. If you would like to use CodeIgniter's classes from within your own custom classes you can do so as follows:

First, assign the CodeIgniter object to a variable:

$CI =& get_instance();

Once you've assigned the object to a variable, you'll use that variable instead of $this: $CI =& get_instance(); $CI->load->helper('url'); $CI->load->library('session'); $CI->config->item('base_url'); etc.

Note: You'll notice that the above get_instance() function is being passed by reference:

$CI =& get_instance();

This is very important. Assigning by reference allows you to use the original CodeIgniter object rather than creating a copy of it.

Related posts: explain $CI =& get_instance(); / Codeigniter: Get Instance

So, here is my actual question:

Why does the user guide recommend assigning get_instance() to a variable? I'm fairly certain I understand the implications of not assigning by reference, but why is it recommended to assign it to a variable when get_instance()->load->model() works fine?

I see a lot of user defined or third party classes in CI that assign to a property of the object:

class MY_Class {

    private $CI;

    function __construct()
    {
        $this->CI =& get_instance();
    }
    function my_func()
    {
        $this->CI->load->view('some_view');
    }
    function my_other_func()
    {
        $this->CI->load->model('some_model');
    }
}

Poor example, but I see this frequently. Why bother with this method instead of just calling get_instance() directly? It seems like assigning the entire Controller object to a class variable wouldn't be a great idea, even if it is a reference. Maybe it doesn't matter.

I want to write a wrapper function for get_instance() so it's easier to type, and I don't have to constantly assign it to a variable.

function CI()
{
    return get_instance();
}

Or:

function CI()
{
    $CI =& get_instance();
    return $CI;
}

Then I could use CI()->class->method() from anywhere without the hassle of assigning it to a variable, it's very easy to write and understand what it does, and can result in shorter, more elegant code.

• Is there any reason not to take this approach?
• Is there any difference between the two CI() functions above?
• Why is it recommended to assign get_instance() to a variable rather than calling it directly?
• What does the & in function &get_instance(){} mean where it is defined? I know a bit about what references are for and I use them when appropriate, but I've never seen a function defined this way. If I do write a wrapper function, should I use this as well?

Please note that this is not so much a style question, but a technical one. I want to know if there are any issues, performance or otherwise, with using the method I'm suggesting.

EDIT: So far we have:

• Method chaining is not available in php4, so assigning to a variable is a workaround (although this is fairly irrelevant as Codeigniter has dropped php4 support)
• The minor overhead of calling a function more than once to return the object, rather than calling it once and assigning to a variable.

Anything else, or are these the only potential issues?

Answer 1

As far as I know, it's a matter of convenience more than anything. Chances are that you will be using the CI super object a lot in your libraries so why not assign it to a variable to make it a little easier to work with?

There are a few other things to consider...

1. If you put this method in a helper, that method becomes a dependency for any class you are using it in. This might not be a big deal for you, but if you want to share libraries with anyone else they may not be happy about the dependency, especially since there is already a standard way of handling this in the CI community.
2. There is a slight impact on performance because you are calling get_instance() every time you use the helper rather than storing its result in a variable.
3. Since this is a helper method that is supposed to save you time, for anyone who is working mostly in the core MVC files of CI, setting up a helper like this would take longer than just setting it to a variable in the few places you need it.