Practical Php Patterns: Singleton

This is the fifth post from the Practical Php Pattern series, which will touch the majority of the known design patterns, with a special look at their application in a php context and code samples.

Today we will discuss the Singleton pattern, the most controversial creational pattern.
A Singleton is a global point of access for a resource that must have only one instance in the whole application: database connections, http streams, and similar objects are the typical examples of such a class.
This behavior is implemented trough a static method which returns a lazy-created instance, and by rendering the constructor private to avoid creation of an instance from outside the class code.
The problems of a Singleton class are the same of its non object-oriented equivalent: a global variable. The Api of Clients of the Singleton lies, because they do not declare in any signature that they are taking advantage of the Singleton's capabilities; moreover, global mutable state is introduced and encapsulation is disregarded.

There is a famous credit card example, which describes the usage of a CreditCard class. One day Misko Hevery was writing some tests in a system he does not know very well, to improve his knowledge of the codebase.
He wrote this code:

testCreditCardCharge() {
  CreditCard c =  new CreditCard(
    "1234 5678 9012 3456", 5, 2008);
  c.charge(100);
}

The test ran, and at the end of the month he got the bill and see he was out $100! The story is probably made up, but you get the point: if a Client references Singletons, you have no idea of what can happen when calling a method.
The Api of CreditCard would have been honest if it was like:

testCreditCardCharge() {
  CreditCard c =  new CreditCard(
    "1234 5678 9012 3456", 5, 2008);
  c.charge(100, creditCardProcessor);
}

Have you ever seen a CreditCard that can be used without a POS?

In my opinion the classic Singleton pattern is adequate only if the static instance has no state, or it is an utility without side effects which you may want to substitute. The sample code reflects this weltanschauung.
There are people that subclass Singletons, but if you feel the need to write a subclass it probably means you are already gone too far. Refactor the code to inject the Singleton as a collaborator of Client.

PARTICIPANTS:

• Singleton: class that manages to keep one and only one instance of itself.
  
• Client: every class that references a Singleton.

The code sample follows.

<?php
/**
 * The most harmless example of a Singleton I can think of is a Logger.
 * However, I feel that injecting the Logger or managing events with an
 * Observer pattern would be better here.
 * This Singleton infringes every rule of testability:
 * - constructor does real work
 * - destructor does other work
 * - constructor is private, you cannot instantiate it in tests
 * - instance is static, you cannot throw it away
 */
class LoggerSingleton
{
    private static $_instance;
    private $_fp;
    
    /**
     * We need only one instance, which will lock the file
     * from further editing.
     */
    private function __construct()
    {
        $this->_fp = fopen('log.txt', 'a');
    }

    public function __destruct()
    {
        fclose($this->_fp);
    }

    public function log($text)
    {
        $line = $text . "\n";
        fwrite($this->_fp, $line);
    }

    /**
     * An instance of this class is lazy created and returned.
     * No further instances are created if there is already one available.
     * This method is the standard way to create a Singleton.
     */
    public static function getInstance()
    {
        if (self::$_instance === null) {
            self::$_instance = new self();
        }
        return self::$_instance;
    }
}

/**
 * The Client receives a name and returns a welcome message, while
 * logging the operation.
 * *Little* side effect: it writes a file.
 */
class Client
{
    public function createWelcomeMessage($name)
    {
        LoggerSingleton::getInstance()->log("Greeted $name");
        return "Hello $name, have a nice day.\n";
    }
}

// isn't it strange that these two lines write a file on disk?
$client = new Client();
echo $client->createWelcomeMessage('Giorgio');

The one instance myth is overrated, and there are other means to achieve the same behavior from a class. Test suites could have dozen of instances of "unique" services and connections (some of them as Fakes and Stubs); in fact, a proof of testability and good design consists in being able to run two applications in the same php script, Jvm or main method.
The difference is that maintaining a unique instance is correct, but only within the boundaries of an application. If you control the creation process, your factories will never create more than one instance of a critical resource. Using a Singleton extends this uniqueness along all the execution environment and hides a crucial dependency under the carpet, effectively causing hassle to everyone trying to figure out what is going on, in debugging as in testing.