All jobs

Fix "Return type should either be compatible with ArrayAccess::offsetGet" Deprecations on PHP 8.1

Yes. An agent adds real return types where your supported PHP versions allow, uses #[\ReturnTypeWillChange] where they do not, and runs the code on PHP 8.

Run this on RushOpens the console with this prompt ready to send, in a Project that has your repository.

What the agent does

PHP 8.1 gave return types to the methods of its built-in interfaces, and a class that implements one without matching types now logs a notice when it is loaded: Deprecated: Return type of Row::offsetGet($offset) should either be compatible with ArrayAccess::offsetGet(mixed $offset): mixed, or the #[\ReturnTypeWillChange] attribute should be used to temporarily suppress the notice. There is one notice per method, so a single class implementing ArrayAccess produces four. Nothing fails yet. But a framework or test runner that converts PHP errors into exceptions turns the notice into a fatal error at the moment the class is declared, and the notice itself describes the attribute as a temporary measure.

leomarquine/php-etl has two such classes. src/Row.php declares class Row implements ArrayAccess with offsetExists($offset), offsetGet($offset), offsetSet($offset, $value) and offsetUnset($offset), none of them typed. src/Pipeline.php declares class Pipeline implements Iterator with untyped current(), next(), key(), valid() and rewind(). That is nine notices on PHP 8.1 and later. The agent finds them by loading the code, not by pattern matching: it runs every file under src through the PHP 8 interpreter with deprecations reported, and collects the class, method and expected signature from each message. That catches classes a text search misses, such as one that inherits the interface from a parent.

Choosing the fix for each method depends on which PHP versions the package supports, so the agent reads that first. Here composer.json has no php constraint at all, and .travis.yml tests PHP 7.1 and 7.2. Return types of bool and void are valid on PHP 7.1, so offsetExists, offsetSet, offsetUnset, next, valid and rewind get real types. Iterator::key() is declared mixed, and a narrower type is allowed; key() returns the integer counter $this->key, so : int is correct and works on PHP 7. offsetGet and current are the hard ones. Their interface type is mixed, which exists only from PHP 8.0, so on a package that still runs on PHP 7 they receive #[\ReturnTypeWillChange], which PHP 7 reads as a comment.

The agent takes types from the method bodies, never from the docblocks. In this repository the docblock on Pipeline::current() says @return void while the body is return $this->current->toArray();. Copying that annotation into a real type would make the pipeline throw on its first row. After editing, the agent loads every class again on PHP 8 and confirms that no notice remains, then runs the tests. That step exposes a second problem here: composer.json requires phpunit/phpunit ^7.3, and PHPUnit 7 declares php ^7.1, so Composer will not install the test suite on PHP 8. The agent reports the conflict, runs the tests on PHP 7 if that interpreter is available, and leaves the PHPUnit upgrade for a separate change.

Start it with one API call

POST https://api.phoenix.so/o/{org}/sessions with this body:

{
  "agent": "claude",
  "input": "On PHP 8.1 or later this code logs deprecations of the form \"Return type of X::offsetGet($offset) should either be compatible with ArrayAccess::offsetGet(mixed $offset): mixed, or the #[\\ReturnTypeWillChange] attribute should be used to temporarily suppress the notice\". Find all of them, not just ArrayAccess: load every PHP file in the source directories on PHP 8.1 or later with error_reporting set to E_ALL and collect each notice with its class, method and the expected signature. Include classes implementing Iterator, IteratorAggregate, Countable, JsonSerializable and Serializable, and classes that inherit those interfaces. Read composer.json, CI configuration and the README to determine the lowest PHP version the project supports. For each method, add the real return type when that type is valid on the lowest supported PHP version (bool, int, void, array, iterable, a class name and so on). A narrower type than the interface declares is allowed when the method body always returns it. Where the required type is mixed, or another type that does not exist on the lowest supported version, add #[\\ReturnTypeWillChange] on its own line above the method instead. Take the type from what the method body returns; do not trust docblocks, and correct a docblock that contradicts the code. Do not change behaviour, do not add parameter types, and do not raise the minimum PHP version. Afterwards load every class again on PHP 8.1 or later and show that no such notice remains, lint the files on the lowest supported PHP version if you can install it, and run the test suite on each PHP version it can be installed on. If the test dependencies cannot be installed on PHP 8, report the constraint that blocks it and do not upgrade them. Open a pull request with a table of every method, the choice made for it and the reason.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
  1. Get an API key. In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
  2. Send the request. POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
  3. Read what came back. Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

What comes back

A pull request that touches only method signatures and, where they were wrong, docblocks. Its description is a table with one row per method: the class, the method, the signature PHP expects, what was written (a return type or the attribute) and the reason. For a package like the fixture that is nine rows, seven with real types and two with #[\ReturnTypeWillChange] because mixed is not available on PHP 7.

Below the table is the proof. The list of notices from loading the code on PHP 8 before the change, and the empty result after it. The test results follow, stated per PHP version, with a clear note for any version on which the suite could not be installed and the Composer message that explains why.

The reviewer reads the rows where a narrower type was chosen. A return type is a runtime check, so declaring : int on a method that can return null in some branch replaces a notice with a TypeError. The table quotes the return statements the agent relied on, which makes that review a matter of minutes.

Run it on every Linear issue labelled php-8

Teams moving to a new PHP version usually file one issue per package or module. An automation with a linear trigger on linear.issue.labeled, set to the label you use for the migration and placed in the Project that holds the repository, starts a run for each issue as it is labelled. The trigger adds the issue after the prompt and fills in no placeholder, so the prompt should tell the agent that the issue below names the package to fix.

If you would sooner drive it from a script, send the request above once per repository with your API key. A key runs up to its max_concurrent limit at once and the rest start as slots free, so a batch needs no scheduling on your side. Send each with a request_id that is a UUID v5 of the repository name and target PHP version to make the batch safe to run twice.

The use case this job follows, with its automation and trigger: Turn a Linear label into a PR.

Why run it on Rush?

Finding these notices properly means running the code on a PHP version the project may not use yet, and checking the result on the oldest version it still supports. Few developers keep both interpreters ready. The agent installs what it needs in its own sandbox, loads every class, and works from the interpreter's messages instead of a search for method names.

The risk in this job is a confident wrong type. A person fixing forty methods by hand will copy a docblock sooner or later. The run reads each method body, records the return statements it found, and keeps the before and after interpreter output in the session transcript, so every row of the table in the pull request can be traced to something PHP actually printed.

Frequently asked questions

Should I add return types or the ReturnTypeWillChange attribute?

Add the real type whenever your lowest supported PHP version understands it; that is the permanent fix. Use the attribute for methods whose interface type is mixed if you still support PHP 7, because mixed is a syntax PHP 7 rejects. The attribute suppresses the notice and does nothing else.

Is the attribute safe on PHP 7?

Yes, when it is on its own line. PHP 7 has no attributes and treats a line that starts with # as a comment, so #[\ReturnTypeWillChange] above the method is ignored. Do not put it on the same line as the function keyword, or PHP 7 will comment out the declaration too.

Does this break anything today?

On its own, no; it is a deprecation notice. It becomes a failure when errors are converted to exceptions. With an error handler that throws, PHP 8.2 stops with Fatal error: During inheritance of ArrayAccess as soon as the class is loaded, which is how many test suites first meet it.

Which interfaces are affected besides ArrayAccess?

The built-in ones whose methods gained return types in PHP 8.1, including Iterator, IteratorAggregate, Countable and JsonSerializable. For Iterator, PHP expects current(): mixed, key(): mixed, next(): void, rewind(): void and valid(): bool. The agent loads your code and lets PHP list the exact set.

Can I use a more specific type than the interface declares?

Yes. Return types may be narrower in the implementing class, so key(): int satisfies Iterator::key(): mixed. Only do it when every path through the method returns that type, since PHP enforces the declaration at run time.

More PHP jobs

More jobs like this: Turn a Linear label into a PR

Keep reading