README

Lightweight, framework-agnostic implementation of the Observer pattern for PHP.

The package provides:

• a backward-compatible static API via wwaz\Observer
• an instance-based API via wwaz\EventBus for dependency injection

Requirements

• PHP ^8.1

Installation

composer require wwaz/observer-php

Quick examples

Static API

use wwaz\Observer;

class Document
{
    public function __construct()
    {
        Observer::subscribe($this, Button::class, 'click', function ($obj) {
            echo $obj->getName();
        });
    }
}

class Button
{
    protected string $name = 'MyButton';

    public function getName(): string
    {
        return $this->name;
    }

    public function click(): void
    {
        Observer::notify($this, 'click', null);
    }
}

$document = new Document();
(new Button())->click();

Instance-based API (dependency injection)

use wwaz\EventBus;

class Document
{
    public function __construct(private EventBus $eventBus)
    {
        $this->eventBus->subscribe($this, Button::class, 'click', function (Button $btn) {
            echo $btn->getName();
        });
    }
}

class Button
{
    protected string $name = 'MyButton';

    public function __construct(private EventBus $eventBus) {}

    public function getName(): string
    {
        return $this->name;
    }

    public function click(): void
    {
        $this->eventBus->notify($this, 'click', null);
    }
}

$eventBus = new EventBus();
$document = new Document($eventBus);
$button = new Button($eventBus);
$button->click();

API contract

All method signatures of Observer and EventBus remain backward-compatible.

subscribe()

Observer::subscribe(object $subscriber, string $observedName, string $action, callable $eventHandler): bool

• Registers a subscriber for one action, wildcard (*) or comma-separated actions.
• Duplicate subscriptions for the same subscriber/object/action triple are ignored.
• Returns true.

notify()

Observer::notify(object|string $observed, string $action, mixed $data): bool

• Calls matching handlers immediately.
• Supports exact action match and wildcard subscriptions.
• Returns false when no subscriptions are registered for the observed class/object.

unsubscribe()

Observer::unsubscribe(object $subscriber, string $observedName, string $action): bool

• Removes subscriptions for one action or all (*).
• Returns true if at least one subscription was removed.

getSubscriptions()

Observer::getSubscriptions(?string $observedName = null): array|false

• Returns all subscriptions when no name is provided.
• Returns subscriptions for one observed name when provided.
• Returns false when no subscriptions exist for the given observed name.

Development

composer install
composer lint
composer stan
composer test
composer qa

Troubleshooting

• Run composer validate --strict if Composer metadata changes.
• If tests fail unexpectedly, clear local state and reinstall dependencies.
• Ensure your local PHP version matches the supported range.

Versioning and compatibility

• This package follows SemVer.
• Existing public API behavior is preserved in this modernization.
• New functionality should be additive and optional to avoid breaking changes.