Download the PHP package laikait/laika-relay without Composer

Laika Framework Relay (Service Container & Static Proxy)

Relay is the service container and static proxy system built for the Laika Framework. It gives you a lightweight dependency injection container (RelayRegistry), a clean static proxy base (Relay), and a two-phase provider system (RelayProvider + ProviderRegistry) that lets third-party packages register their own services into the framework.

Part of laikait/laika-core · Requires PHP 8.1+

Table of Contents

• How It Works
• File Structure
• RelayRegistry
  • instance()
  • singleton()
  • bind()
  • make()
  • has()
  • forgetInstance()
  • Lifetime Comparison
• Auto-Wiring
• RelayProvider
  • register()
  • boot()
  • register() vs boot()
• ProviderRegistry
• Bootstrap
• Third-Party Integration
• Relay — The Static Proxy
  • Creating a Relay Class
  • Using a Relay
  • Method Chaining
  • Switching Instances at Runtime
• Testing
• Exceptions

How It Works

There are three independent pieces:

File Structure & Default Services

services/ [Laika\Service\*] is a convention, not a requirement. Relay classes can live anywhere.

RelayRegistry

The container. All services are registered here before the application starts handling requests.

instance()

Register an already-constructed object directly.

The registry stores exactly the object you give it — it never calls new. The object is available immediately on make().

Use when the object already exists before the registry is set up, or when construction has side effects that must be controlled manually.

singleton()

Register a singleton binding — built once on the first make() call, then cached and reused for the lifetime of the request.

Use for stateful services shared across the entire request: session, auth, config, mailer, cache.

bind()

Register a transient binding — a brand-new instance is created on every make() call. Nothing is ever cached.

Use for stateless, disposable objects where shared state would be a bug: validators, form request objects, DTOs, value objects.

make()

Resolve a binding by key and return the object.

Resolution order:

has()

Check whether a key has any binding registered.

forgetInstance()

Clear a cached singleton instance, forcing re-resolution on the next make().

Lifetime Comparison

Prefer singleton() over instance() for most services. singleton() is lazy — if nothing ever calls make('x'), the object is never constructed. instance() is eager — the object exists the moment you register it, whether anything uses it or not.

Auto-Wiring

When a class string is registered (not a Closure), the registry uses PHP reflection to resolve constructor parameters automatically.

Per-parameter resolution order:

Mixed — auto-wire objects, supply primitives:

RelayProvider

The integration point for packages. Extend RelayProvider and implement register(). Optionally override boot().

register()

Only call bind(), singleton(), or instance() here. Do not call make().

When register() runs, other providers may not have registered their services yet. Calling make() at this stage risks a RelayException if the dependency is not yet bound.

boot()

Called after all providers have run register(). Safe to call make() freely.

register() vs boot()

One-line rule: register() = bind things. boot() = use things.

ProviderRegistry

Manages the full provider lifecycle. Register providers in any order — the two-phase approach guarantees correctness.

Duplicate registrations are silently ignored — registering the same provider class twice is safe.

has() — check if a provider is registered:

Bootstrap

Complete application bootstrap sequence:

config/app.php:

Third-Party Integration

This is how an external package integrates with Laika.

1. Create a RelayProvider

2. Ship a Relay class (optional but recommended)

Full flow

Relay — The Static Proxy

Creating a Relay Class

Extend Relay, implement getRelayAccessor(), and document every proxied method with @method static tags.

@method tag rules:

• Always include static — every call through a Relay is a static call.
• Import types with use statements — same as real code.
• Union return types are valid: @method static Item|Builder end()
• Array types are valid: @method static Item[] all()
• FQCNs or short names both work (short names require use).

Using a Relay

Import the Relay class, not the underlying service class.

You do not need a Relay class to access a service. The registry is always available:

Method Chaining

Chaining works automatically. The first static call goes through __callStatic and returns whatever the underlying method returns. If that's $this, subsequent calls are normal instance calls.

Chaining ends when a method returns a non-object (string, int, array). Do not chain after terminal methods like format(), getTimestamp(), or toArray().

Switching Instances at Runtime

Use swap() to replace the resolved instance for a specific Relay — for example, switching auth guard in middleware.

Or re-register via the registry for a cleaner approach:

Testing

Inject a mock for one test

Replace the entire registry for full isolation

swapRegistry() is intentionally separate from setRegistry() so that accidental double-calls in production code throw a RelayException, while tests can swap freely.

Exceptions

All errors throw Laika\Relay\Exceptions\RelayException.

License

MIT — see LICENSE for details.

Author: Showket Ahmed Email: [email protected] Package: laikait/laika-relay GitHub: laikait/laika-relay