Support versioned extension stub maps

[Simon Podlipsky (simPod)]

Summary

• Generate a version-aware PhpStormStubsMap::EXTENSION_VERSIONS map for extension directories with suffixes like ds_v2 and couchbase_v2.
• Keep the existing flat CLASSES, FUNCTIONS, and CONSTANTS maps backward-compatible by continuing to point them at default extension stubs.
• Regenerate PhpStormStubsMap.php so consumers can select versioned extension symbols, such as Ds\\Seq from ds_v2, without losing the existing default ds map.

[Simon Podlipsky (simPod)]

Ivan Fedorov (@isfedorov) what can I do to move this forward

[Ivan Fedorov (isfedorov)]

Simon Podlipsky (@simPod) there are a couple of things:

1. Initially, the script to generate this map was introduced in the scope of WI-46976 as a workaround for BetterReflection and PHP-Scoper's Reflector and commit was done by Théo FIDRY (@theofidry) so I wonder if such changes in the map can cause any issues with those tools (despite mentioned by you point 2) and cause any problems for other users. We need to add other interested persons to the review.
2. If tools are ok with such changes, you need to update your fork (since a lot of changes were done in the test framework), and update test \StubTests\StubsStructureValidatorTest::checkGenerateStubsMapScript to properly validate the new structure of the map

[Théo FIDRY (theofidry)]

So long as PhpStormStubsMap::CLASSES, FUNCTIONS and CONSTANTS are not touched, there should be no problem on PHP-Scoper side.

I do wonder however what is the expected behaviour there if a symbol is found for either versions, especially in the case where its definition changes from a version to another.

[Simon Podlipsky (simPod)]

EXTENSION_VERSIONS contains independent, complete maps per extension version. A consumer must select the extension version before it looks up a symbol.

For example, EXTENSION_VERSIONS['ds']['default'] resolves Ds\Map to ds/ds.php, while EXTENSION_VERSIONS['ds'][2] resolves it to ds_v2/ds.php.

This lets consumers use the installed extension version to select the correct definition. The existing CLASSES, FUNCTIONS, and CONSTANTS maps remain unchanged and continue to use the default extension stubs for backward compatibility.

[Copilot]

Pull request overview

Adds version-aware extension stub maps while preserving existing flat-map behavior.

Changes:

• Detects version-suffixed extension directories.
• Generates versioned and default symbol maps.
• Regenerates the map and checks for the new constant.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.

File	Description
tests/Framework/Tools/generate-stubs-map.php	Generates version-aware maps.
PhpStormStubsMap.php	Adds Couchbase and DS version mappings.
tests/StubsStructureValidatorTest.php	Checks that the new constant is generated.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.