The Singleton Design Pattern for PHP

Introduction

A non-class Helper function

A separate Helper method within each class

A single Helper method for all classes

A single Helper method with class loader

References

Conclusion

Amendment History

Comments

Introduction

In software engineering, a design pattern is a general solution to a common problem in software design. A design pattern isn't a finished design that can be transformed directly into code, it is a description or template for how to solve a problem that can be used in many different situations.

One of these design patterns is called the Singleton. It's purpose can be described quite briefly as follows:

Ensure a class has only one instance and provide a global point of access to it.

It achieves this by only creating a new instance the first time it is referenced, and thereafter it simply returns the handle to the existing instance.

Why should you want this facility in the processing of a web page? There are several reasons:

• You have references to an object in multiple places, and you do not want the overhead of creating a new instance of that object for each reference.
• You may wish to pass the object's state from one reference to another rather than always starting from an initial state.

As with all design patterns there is more than one way in which it can be implemented, so in the following sections I will document some of the methods that I have encountered.

You should also be aware that the code samples in this document will work in both PHP 4 and PHP 5.

A non-class Helper function

This method uses a separate non-class function as a "helper". It contains code similar to the following:

function &getDateObject ()
// return the handle to the standard date validation object.
{
    static $instance;
    
    if (!is_object($instance)) {
        // does not currently exist, so create it
        require_once 'std.datevalidation.class.inc';
        $instance = new date_class;
    } // if
    
    return $instance;
    
} // getDateObject

It is referenced with code similar to the following:

    $dateobj =& getDateObject();

This method has the following advantages:

• Because it is designed to work with a single specific class it can also take the responsibility of ensuring that the relevant class file is loaded when necessary.

This method has the following disadvantages:

• It requires a separate helper function for each different class.

A separate Helper method within each class

This method requires the addition of a getInstance() (or similar) method within each each and every class, similar to the following:

    static function &getInstance ()
    // this implements the 'singleton' design pattern.
    {
        static $instance;
        
        if (!isset($instance)) {
            $c = __CLASS__;
            $instance = new $c;
        } // if
        
        return $instance;
        
    } // getInstance

It is referenced with code similar to the following:

    require_once 'std.datevalidation.class.inc';
    $dateobj =& date_class::getInstance();

This method has the following advantages:

• It provides a consistent method across all classes.

This method has the following disadvantages:

• It requires that the class definition be pre-loaded.
• It must be defined within each and every (sub)class where it will be needed. Due to the way that it works it cannot be inherited from a superclass because a static method in a superclass does not know of the existence of any subclasses therefore cannot be used to instantiate a subclass.

A single Helper method for all classes

This requires the creation of a separate class (called singleton in this example) with a single method (called getInstance() in this example).

class singleton
{
    static function &getInstance ($class)
    // implements the 'singleton' design pattern.
    {
        static $instances = array();  // array of instance names
        
        if (!array_key_exists($class, $instances)) {
            // instance does not exist, so create it
            $instances[$class] = new $class;
        } // if
        
        $instance =& $instances[$class];
        
        return $instance;
        
    } // getInstance
    
} // singleton

It is referenced with code similar to the following:

    require_once 'std.datevalidation.class.inc';
    $dateobj = singleton::getInstance('date_class');

This method has the following advantages:

• It provides a single method which will work for any and all classes and subclasses.
• It does not require a method to be duplicated within each class or subclass.

This method has the following disadvantages:

• It requires that the class definition be pre-loaded. If the file name could be deduced or constructed from the class name then could be built into the getInstance() method.
• Although the class names used with the new command are case-insensitive, when used as keys within an associative array they are not. This means that 'classname', 'ClassName' and 'CLASSNAME' would be treated as different keys in the array, therefore would return different instances.

A single Helper method with class loader

This is similar to the previous example, but does away with the necessity of pre-loading the class definition. Sample code is as follows:

class singleton
// ensure that only a single instance exists for each class.
{
    static function &getInstance ($class, $arg1=null)
    // implements the 'singleton' design pattern.
    {
        static $instances = array();  // array of instance names

        if (array_key_exists($class, $instances)) {
            // instance exists in array, so use it
            $instance =& $instances[$class];
            
        } else {
            // load the class file (if not already loaded)
            if (!class_exists($class)) {
                switch ($class) {
                    case 'date_class':
                        require_once 'std.datevalidation.class.inc';
                        break;

                    case 'encryption_class':
                        require_once 'std.encryption.class.inc';
                        break;

                    case 'validation_class':
                        require_once 'std.validation.class.inc';
                        break;

                    default:
                        require_once "classes/$class.class.inc";
                        break;
                } // switch
            } // if

            // instance does not exist, so create it
            $instances[$class] = new $class($arg1);
            $instance =& $instances[$class];
        } // if

        return $instance;

    } // getInstance
    
} // singleton

It is referenced with code similar to the following:

    $object = singleton::getInstance('whatever');

Notice how most of the classes exist in files with a standard name (classes/$class.class.inc) but some have to be dealt with separately. This is not a problem if the number of variations is small.

The only disadvantage (that I am aware of) to this method is the one regarding case sensitivity, but I avoid this problem by insisting that all class names are in lower case, and that '_' (underscore) be used instead of CamelCaps.

References

Some of the terms used in this document may be new to you, so here are some explanations:

• The use of the word 'static' with a local variable.

  The scope of a variable is the context in which it is defined, in this case a function or a class method. Normally the contents of a local variable are lost when program execution leaves this scope, but by defining a variable as 'static' you allow it to retain its value so that when program execution returns the previous value is still there. This value may be modified as many times as is required (as in the third example with the expanding array), so the term 'static' should not be confused with 'fixed, stable, stationary, not changing or moving'.

• The use of the double colon '::' to call a method.

  This is known as the scope resolution operator and allows a class method to be executed without the need for instantiating an object of that class. So instead of $object->method() you use class::method().

Conclusion

As you can see there is no single way to implement this design pattern, and this is the most simple pattern there is! Some people say that the singleton pattern is bad and should never be used, but I disagree. My reasons can be found in Singletons are NOT evil.

Amendment history: