Pular para o conteúdo principal

Singleton Pattern

The singleton pattern as one trait: add it to a class, and that class has exactly one instance.

Sponsor Build Status Opensource ByJG Install MCP Server GitHub source GitHub license GitHub release

Why​

A singleton is a few lines that every project writes again, and usually incompletely: the constructor is private, but the instance can still be duplicated with clone or with unserialize().

Add the trait and the class gets getInstance(), one instance per class (subclasses get their own), and blocks cloning, serializing and unserializing. One trait, no dependencies.

Documentation​

Requirements​

PHP 8.3 or higher

Installation​

composer require "byjg/singleton-pattern"

Creating a Singleton Class​

<?php
require "vendor/autoload.php";

class Example
{
    // Use the Singleton trait to implement the pattern
    use \ByJG\DesignPattern\Singleton;
    
    // You can add properties to your singleton
    public string $someProperty;
    
    // The constructor MUST be private or protected
    private function __construct()
    {
        // Optional initialization code
        $this->someProperty = "Initial value";
    }
    
    // Add your own methods and properties here
    public function doSomething(): void
    {
        // Your code here
    }
}

IMPORTANT:

  1. Your class MUST use a private or protected constructor.
  2. Singleton classes do not accept arguments in the constructor.
  3. Attempting to clone, serialize, or unserialize a singleton will throw a SingletonException.

Using your Singleton class​

// Get the singleton instance
$example = Example::getInstance();

// The same instance is always returned
$anotherReference = Example::getInstance();
$example->someProperty = "Changed value";

// This will output "Changed value" because both variables reference the same instance
echo $anotherReference->someProperty;

// This will throw a SingletonException
try {
    $cloned = clone $example;
} catch (\ByJG\DesignPattern\SingletonException $e) {
    echo "Cannot clone a singleton!";
}

How It Works​

The Singleton trait:

  • Implements the getInstance() static method to create and manage a single instance
  • Prevents cloning by overriding the __clone() method
  • Prevents serialization and deserialization by overriding __sleep() and __wakeup()
  • Uses a static local variable within getInstance() to store instances of each class that uses the trait

Running Tests​

vendor/bin/phpunit

References​

Open source ByJG