welbertymartins/php-singleton

Minimal and testable singleton container for object sharing and retrieval

v8.2.0 2025-06-29 02:41 UTC

Requires

• php: ^8.2

Requires (Dev)

• phpunit/phpunit: ^9.6
• squizlabs/php_codesniffer: ^3.7
• vimeo/psalm: ^5.10

MIT

• Welberty Martins

• dependency injection
• container
• php
• singleton
• service locator

README

A minimal and testable singleton container for managing and retrieving shared instances in PHP.

📦 Installation

composer require welbertymartins/php-singleton

🚀 Quick Start

use WelbertyMartins\Singleton\Singleton;

// Store a shared object in the global singleton container
Singleton::root()->remember(fn() => new MyService());

// Retrieve it later
$service = Singleton::root()->make(MyService::class);

Or use an isolated container:

$container = Singleton::local();

$container->remember(fn() => new MyService(), 'custom_service');

$service = $container->make('custom_service');

🧪 Running Tests

composer install
composer test

Includes PHPUnit tests, PSR-12 code style checking, and static analysis via Psalm.

📁 Project Structure

src/     → Main singleton implementation  
test/   → PHPUnit test suite  

✅ Features

• 🧩 Global and isolated singleton instances
• 🛡️ Strict type safety
• ⚡ Lightweight, zero-dependency
• ✅ PSR-4 autoloading
• 🧪 Fully tested

📘 API Overview

Singleton::root(): Singleton

Returns the globally shared singleton instance.

Singleton::local(): Singleton

Returns a new isolated singleton instance.

remember(callable $factory, string $name = '', bool $force = false): self

Stores an object returned by a factory under a given name (or class name by default).

make(string $name = ''): ?object

Retrieves a stored instance by name, or the last remembered instance.

📄 License

This project is open-sourced under the MIT license.

🤝 Contributing

Contributions, issues, and feature requests are welcome!

1. Fork this repository
2. Create a feature branch (git checkout -b feature/your-feature)
3. Submit a pull request 🚀

🔗 Useful Links

• 📦 Packagist

---

Would you like me to create the `LICENSE`, `.gitignore`, `.gitattributes`, and `GitHub Actions` workflow file (`test.yml`) next?