meaning and location of string inside Magento's Mage:getSingleton

Question

Here is a string I see a lot of similar in Magento:

Mage::getSingleton('checkout/type_onepage');

However, I'm trying to find out where that class is located, and what the meaning of the string is specifically. Can anyone explain this to me?

Answer 1

1/ Model

You have to know that Mage::getSingleton() is going to send you a singleton (which is a common development design pattern). For magento, only Models can be instantiated as a Singleton

Snippet from app/Mage.php where you can see that Magento is actually using getModel behind the scene, and also register it to have a single instance of this model if you call it twice via getSingleton (the purpose of the singleton pattern itself, as you may know)

public static function getSingleton($modelClass='', array $arguments=array())
{
    $registryKey = '_singleton/'.$modelClass;
    if (!self::registry($registryKey)) {
        self::register($registryKey, self::getModel($modelClass, $arguments));
    }
    return self::registry($registryKey);
}

2/ Handle

Magento is going to map its components to classes via what we call handles. Those are defined in the config.xml of the modules.

Snippet from app/code/core/Mage/Checkout/etc/config.xml stripped from a lot of xml

<?xml version="1.0"?>
<config>
    <modules>
        <Mage_Checkout>
            <version>1.6.0.0</version>
        </Mage_Checkout>
    </modules>
    <global>
        <models>
            <checkout>
                <class>Mage_Checkout_Model</class>
            </checkout>
        </models>
    </global>
</config>

This snippet instruct to magento to add at its global configuration, for all the models it knows a new set of model that could be referenced through the handle checkout which maps to the classes beginning with Mage_Checkout_Model.

3/ The right file or class

Magento does inherit from Zend Framework mapping of Class_To_File_Path

Class names may only contain alphanumeric characters. Numbers are permitted in class names but are discouraged in most cases. Underscores are only permitted in place of the path separator; the filename "Zend/Db/Table.php" must map to the class name "Zend_Db_Table".

Source : http://framework.zend.com/manual/1.12/en/coding-standard.naming-conventions.html

That means that the type of construction like type_onepage would map to a file having in its path Type/Onepage.php and its class name Type_Onepage

4/ One handle to rule them all

(I had to place that pun somehow, sorry.)

Now you have the handle to you model which map to Mage_Checkout_Model and your class which is Type_Onepage Magento can assemble those two in a class being Mage_Checkout_Model_Type_Onepage and to a file being Mage/Checkout/Model/Type/Onepage.php. So this whole handle (checkout/type_onepage) is constructed from two part, the first one before the slash is the handle to a model (in this case, but could also be to an helper or a block... controller are a little different) and the second one, after the slash being the path to the file from the folder / class prefix defined by the handle.

5/ And you thought that was all ?

To be completely extensive in this explanation you also have to know that modules are defined via an xml which stands on app/etc/modules. Since you are asking for a core module, the file to look at is Mage_All.xml which I, once again stripped of a lot of code.

<?xml version="1.0"?>
<config>
    <modules>
        <Mage_Checkout>
            <active>true</active>
            <codePool>core</codePool>
            <depends>
                <Mage_Sales/>
                <Mage_CatalogInventory/>
            </depends>
        </Mage_Checkout>
    </modules>
</config>

For other module the recommended way to do it is by having a file app/code/Mage_Checkout.xml where the name of the file is the name of the handle beside the <modules> node in the xml. But for the core, since there is a lot of module they grouped a lot of them in Mage_All.xml.

In this file you can see that it has fairly the same start as the config.xml of our module we saw earlier, so Magento would be able to match the fact that this config.xml belongs to this module defined in this Mage_All.xml file. Then you also see the codePool of that module. In this case, core, the stock modules of Magento. But you could also have there community or local.

For now on, Magento can really map to the file correctly.
You file is in
app/code/ -- fixed, all the code is there.
core/ -- the codePool of your module
Mage/Checkout/Model/ -- the handle mapped to the right class defined in config.xml and then translated to a path based on Zend Framework convention
Type/Onepage.php -- The file mapped from type_onepage, following once again Type/Onepage convention.

All in one :

echo get_class(Mage::getSingleton('checkout/type_onepage'));
// will output Mage_Checkout_Model_Type_Onepage
// which is located at app/code/core/Mage/Checkout/Model/Type/Onepage.php