phalcon/cphalcon · error · Phalcon\Support\Collection\Exceptions\ReadOnlyViolation

The object is read only

Error message

The object is read only

What it means

Phalcon\Support\Collection\ReadOnlyCollection is the immutable variant of Collection: it initializes once in the constructor and then all mutators are locked. clear() unconditionally throws Phalcon\Support\Collection\Exceptions\ReadOnlyViolation ("The object is read only") because wiping the data would mutate frozen state. The class exists so components can hand out safe, shareable views of data.

Source

Thrown at phalcon/Support/Collection/ReadOnlyCollection.zep:73

        let this->constructed = false;

        try {
            parent::__unserialize(data);
        } catch \Throwable, ex {
            let this->constructed = true;

            throw ex;
        }

        let this->constructed = true;
    }

    /**
     * @throws ReadOnlyViolation
     */
    public function clear() -> void
    {
        throw new ReadOnlyViolation();
    }

    /**
     * @throws ReadOnlyViolation
     */
    public function init(array data = []) -> void
    {
        if (this->constructed) {
            throw new ReadOnlyViolation();
        }

        parent::init(data);
    }

    /**
     * Delete the element from the collection
     *
     * @throws ReadOnlyViolation

View on GitHub (pinned to b7419de9cd)

Solutions

1. Build a new object instead of clearing: $mutable = new Collection($readOnly->toArray()); then mutate the copy
2. Return a fresh empty instance if you need a 'cleared' value: new ReadOnlyCollection([])
3. Guard shared helpers: check instanceof ReadOnlyCollection before calling any mutator

Example fix

// before
$collection->clear(); // throws ReadOnlyViolation

// after
$collection = new Collection([]); // new instance, source untouched

use Phalcon\Support\Collection;
use Phalcon\Support\Collection\ReadOnlyCollection;

if ($collection instanceof ReadOnlyCollection) {
    $collection = new Collection($collection->toArray()); // mutable copy
}

$collection->clear();

function isReadOnlyCollection($collection): bool
{
    return $collection instanceof \Phalcon\Support\Collection\ReadOnlyCollection;
}

use Phalcon\Support\Collection\Exceptions\ReadOnlyViolation;

try {
    $collection->clear();
} catch (ReadOnlyViolation $e) {
    $collection = new \Phalcon\Support\Collection($collection->toArray());
}

When it happens

Trigger: Calling ->clear() on a ReadOnlyCollection obtained from a library or another component; reusing generic 'clear then repopulate' code written for the mutable Collection: $col->clear(); $col->init($newData);

Common situations: Library-returned value objects or shared config exposed as read-only on purpose. Generic collection utilities (cache reset, batch refresh) break when pointed at the immutable variant.

Related errors

• Row is an immutable ArrayAccess object
• The sort callback must be callable or null
• Value must be of type '{type}', '{actual}' given
• No route matched the request.
• Class '{className}' is not an ADR Action.

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