README

Cally is a minimal, elegant, and strict PSR-11–compatible service locator for PHP 8+.
It provides a simple API for defining services, factories, singletons, lazy-loaded objects, and values.

Cally is designed to be:

• Small – no dependencies
• Predictable – explicit, no magic
• Strict – throws meaningful exceptions
• PSR-11 compliant – works with existing standards
• Fast – closures only, no reflection

Features

• PSR-11 ContainerInterface compatible
• Register lazy-loaded services
• Register singletons
• Register factories
• Register simple values
• Freeze the container to prevent modification
• Meaningful exception hierarchy:
  • FrozenRegistryException
  • KeyAlreadyExistsException
  • KeyNotFoundException

Missing Essentials

• No circular dependency detection - Lazy services could create infinite loops if A depends on B depends on A
• No error context - Exceptions don't capture which dependency failed during complex resolution chains
• No type safety - Can't specify/validate what type a key should return
• No autowiring - Must manually register everything (fine for simple apps, tedious for large ones)
• No container awareness - Factories can't receive the container itself to resolve their own dependencies
• No unfreeze/clear - Once frozen, you're stuck (problematic for testing)

Debatable Missing Features

• Aliases - Point multiple keys to same service
• Tags/groups - Retrieve all services of a certain type
• Service decoration/extension - Wrap existing services
• Performance - No caching of resolution paths for complex dependency graphs

Production Readiness

For a small-to-medium application with straightforward dependencies, it's probably fine. For production at scale, you'd likely want at least circular dependency detection and better error context. The rest depends on your specific needs.

Future

I plan to implement all missing features (and possibly some debatable ones) in future, while also staying commited to Cally's minimalistic nature.

Installation

Install via Composer:

composer require taujor/cally

Quick Start

Create the container

use Taujor\Cally\Cally;

$container = new Cally();

Registering Services

Singleton

A single shared instance:

$pdo = new PDO('sqlite::memory:');

$container->singleton('db', $pdo);

Usage:

$db = $container->get('db'); // always returns the same instance

Lazy Service

Instantiated only once on first use:

$container->lazy('config', function () {
    return parse_ini_file('app.ini');
});

Factory

Produces a new instance every time:

$container->factory('uuid', fn() => bin2hex(random_bytes(16)));

$id1 = $container->get('uuid');
$id2 = $container->get('uuid');

// always different

Value

Stores a simple immutable value:

$container->value('version', '1.0.0');

echo $container->get('version'); // "1.0.0"

Retrieving Services

$service = $container->get('key');

If the key does not exist:
KeyNotFoundException

Checking Keys

if ($container->has('cache')) {
    // ...
}

Freezing the Container

After freezing the container, no new services can be registered.

$container->freeze();

$container->set('foo', fn() => 'bar'); 
// Throws FrozenRegistryException

Error Handling

Cally throws clear, meaningful exceptions:

All exceptions implement PSR-11 interfaces where appropriate.

Why Cally?

• No unnecessary abstraction layers
• A clean alternative to overly complex DI containers
• Explicit over magic

License

MIT license