PHPStorm inspection mismatch with composer.json PHP version

Goal: Configure PHPStorm to automatically use the PHP version declared in composer.json for its language‑level inspections so that valid modern syntax is not flagged as errors.

Constraints: The IDE does not read the require → php field from composer.json; the language level must be set manually via Settings | Languages & Frameworks | PHP. The quick‑fix “Set PHP language level to X” appears only after a file containing the offending construct is opened, and the chosen level is stored per‑project in the .idea workspace, which is not typically version‑controlled, requiring each developer to apply it individually.

Can PHPStorm be made to detect the composer.json PHP requirement and set the language level automatically on project load?
Is there a way to trigger the “Set PHP language level to X” quick‑fix without first opening a file that contains the newer syntax?
Can the language‑level setting be persisted in a version‑controlled file (e.g., .idea/misc.xml or a dedicated XML) so that all team members receive the same inspection baseline?

Answer the question first

1. No – PHPStorm does not automatically read the require‑>php field from composer.json and adjust the language level when a project is opened.

2. No – The quick‑fix “Set PHP language level to X” is a file‑contextual action that appears only after a file containing out‑of‑range syntax is opened; it cannot be triggered programmatically or from the command line.

3. Yes, with caveats – The language level is stored in .idea/misc.xml. You can edit this file to add <option name="languageLevel" value="8.1"/> and commit the file, but JetBrains recommends keeping .idea out of VCS because different developers may use different PHP interpreters, which can lead to merge conflicts or unwanted overrides.

Why the IDE behaves this way

PHPStorm determines the language level solely from the configured PHP interpreter (Settings → Languages & Frameworks → PHP). The interpreter’s version is the source of truth for the language level.
Composer is a dependency manager; its php requirement is a runtime constraint, not an IDE configuration. The IDE has no API to query Composer automatically on project load.
The quick‑fix is a user‑initiated action that writes the chosen level to .idea/misc.xml. It is intentionally tied to file opening to avoid surprises when a file contains syntax that is only valid in a newer PHP version.

Practical steps for your case

Set the interpreter to PHP 8.1:
- Open Settings | Languages & Frameworks | PHP.
- Choose or add the PHP 8.1 executable (e.g., /usr/local/bin/php8.1).
- The Language level dropdown will automatically update to 8.1 if the interpreter’s version matches.
Verify the setting:
- Open .idea/misc.xml and look for <option name="languageLevel" value="8.1"/>. If it’s missing, add it manually.
- Restart PHPStorm and open a file that uses named arguments. The inspection should no longer flag the syntax.
Persisting across team members:
- Commit .idea/misc.xml to VCS only if all developers use the same PHP interpreter. Keep the file under version control only if you’re comfortable with potential merge conflicts.
- Alternatively, create a shared .phpstorm.project file that sets the interpreter path or use a script to set the interpreter on project load (e.g., via a wrapper that calls phpstorm.sh --php-8.1).

When to ask for more information

If the PHP interpreter on a developer’s machine is older than the version required by composer.json, PHPStorm will still flag newer syntax as errors regardless of the composer.json setting. In that scenario, please confirm the interpreter path configured in Settings | Languages & Frameworks | PHP for each developer.

Key take‑aways

Use the PHP interpreter as the single source of truth for the language level.
The quick‑fix is file‑contextual and cannot be triggered without opening a file.
Persisting .idea/misc.xml is possible but discouraged unless all team members share the same interpreter setup.

Why the IDE Doesn’t Auto‑Sync

PHPStorm derives the language level solely from the PHP interpreter configured for the project. It does not read composer.json automatically, so the require‑>php field is ignored during inspection setup.

How to Share the Setting

.idea/misc.xml – Edit the file to add
```
<option name="languageLevel" value="8.1"/>
```
Commit this change to VCS. JetBrains recommends keeping .idea out of source control, but for a shared language level this is the most straightforward path.
.phpstorm.yml – From PHPStorm 2024 onward you can place a .phpstorm.yml in the project root with
```
php:
  language_level: "8.1"
```
This file is VCS‑friendly and is read on project load.

Practical Tips

Ensure every developer points the project’s PHP interpreter to the same PHP 8.1 binary (or a Docker‑based interpreter) so the IDE uses the same base version.
After committing .idea/misc.xml or .phpstorm.yml, re‑import the project or restart PHPStorm to apply the new language level.
Verify by opening a file that uses named arguments; the “Unexpected token” inspection should no longer trigger.

Unexpected token '(' in named argument inspection despite composer.json PHP 8.1 requirement

1 answer