phalcon/cphalcon · error · Phalcon\Events\Exceptions\InvalidSubscriberConfiguration

Invalid event subscriber configuration for {eventName}

Error message

Invalid event subscriber configuration for {eventName}

What it means

When you register a subscriber via addSubscriber()/removeSubscriber(), each value in its static getSubscribedEvents() map must be a method-name string or an array specification. processSubscriberEntry() throws InvalidSubscriberConfiguration when the value is a non-string scalar (int, float, bool) — for example an event mapped to a bare priority number.

Source

Thrown at phalcon/Events/Manager.zep:1246

        var firstParam, listener, methodName, priority;

        if typeof params == "string" {
            if detaching {
                this->detach(eventName, [subscriber, params]);
            } else {
                this->insertHandlerEntry(
                    eventName,
                    [subscriber, params],
                    1,
                    self::DEFAULT_PRIORITY
                );
            }

            return;
        }

        if unlikely typeof params != "array" {
            throw new InvalidSubscriberConfiguration(eventName);
        }

        if !fetch firstParam, params[0] {
            throw new InvalidSubscriberConfiguration(eventName);
        }

        if typeof firstParam == "string" {
            let methodName = firstParam;
            let priority   = self::DEFAULT_PRIORITY;

            if isset params[1] {
                let priority = params[1];
            }

            if detaching {
                this->detach(eventName, [subscriber, methodName]);
            } else {
                this->insertHandlerEntry(

View on GitHub (pinned to b7419de9cd)

Solutions

Give the method name: 'db:beforeQuery' => 'onBeforeQuery' (default priority)
Give method plus priority as an array: 'db:beforeQuery' => ['onBeforeQuery', 100]
For several methods on one event, use a list of pairs: 'db:beforeQuery' => [['onBeforeQuery', 100], ['logQuery', 500]]

Example fix

// before
public static function getSubscribedEvents(): array
{
    return ['db:beforeQuery' => 100]; // throws InvalidSubscriberConfiguration
}

// after
public static function getSubscribedEvents(): array
{
    return ['db:beforeQuery' => ['onBeforeQuery', 100]];
}

Defensive patterns

Strategy: type-guard

Validate before calling

function validSubscriberMap(array $map): bool
{
    foreach ($map as $params) {
        if (is_string($params)) { continue; }
        if (is_array($params) && isset($params[0])) { continue; }
        return false;
    }
    return true;
}

Type guard

function assertSubscriberMap(array $map): void
{
    foreach ($map as $event => $params) {
        if (is_string($params)) { continue; }
        if (!is_array($params) || !isset($params[0])) {
            throw new InvalidArgumentException(sprintf(
                'Bad subscriber spec for %s: need method string, [method, priority], or list of pairs; got %s',
                $event,
                get_debug_type($params)
            ));
        }
    }
}

Try / catch

use Phalcon\Events\Exceptions\InvalidSubscriberConfiguration;
try {
    $em->addSubscriber($subscriber);
} catch (InvalidSubscriberConfiguration $e) {
    throw new RuntimeException(get_class($subscriber) . ' has a malformed getSubscribedEvents(): ' . $e->getMessage(), 0, $e);
}

Prevention

Do not port Symfony subscriber maps verbatim — Phalcon has no bare-int priority form
Add a unit test per subscriber that runs assertSubscriberMap(SubscriberClass::getSubscribedEvents())

When it happens

Trigger: class AuditSubscriber implements Subscriber { public static function getSubscribedEvents(): array { return ['db:beforeQuery' => 100]; } } — the int is rejected because a priority alone does not say which method to call; $em->addSubscriber(new AuditSubscriber()) then throws for that entry.

Common situations: Copying Symfony's EventSubscriberInterface idiom where 'eventName' => int priority is legal — Phalcon requires the method name; a class constant used as the value being defined as an int instead of a string; refactoring configs into the map and leaving placeholder numbers.

Related errors

AI-assisted analysis of phalcon/cphalcon@b7419de9cd (2026-08-21). Data as JSON: /api/errors/9b7a833ded98d3ed. Report an issue: GitHub.