Policy to load stubs for PHP extensions (core, bundled, external, PECL)

[alies-dev]

What is the policy for PHP extensions?

When I run Psalm I see something like this:

Target PHP version: 8.1 (inferred from composer.json) Extensions enabled: dom, pdo (unsupported extensions: bcmath, curl, filter, gd, hash, iconv, intl, json, mbstring, openssl, pcntl, pdo_mysql, redis, tokenizer, zip)

composer.json file example:

{
    "require": {
        "php": "^8.1",
        "ext-PDO": "*",
        "ext-bcmath": "*",
        "ext-curl": "*",
        "ext-dom": "*",
        "ext-filter": "*",
        "ext-gd": "*",
        "ext-hash": "*",
        "ext-iconv": "*",
        "ext-intl": "*",
        "ext-json": "*",
        "ext-mbstring": "*",
        "ext-openssl": "*",
        "ext-pcntl": "*",
        "ext-pdo_mysql": "*",
        "ext-redis": "*",
        "ext-tokenizer": "*",
        "ext-zip": "*",
...
}

ext types

There are few types of ext:

1. core (These are not actual extensions. They are part of the PHP core and cannot be left out of a PHP binary with compilation options.)
2. bundled (These extensions are bundled with PHP.)
3. external (These extensions are bundled with PHP but in order to compile them, external libraries will be needed.)
4. PECL (These extensions are available from PECL. They may require external libraries.)

Additionally, different PHP versions have different bundled extensions, e.g. sodium was PECL ext and became bundled as of PHP 7.2.0.

how Psalm loads stubs for extensions

• extract from composer.json
• using config: enableExtensions key

Then load stubs:

psalm/src/Psalm/Config.php

Lines 2138 to 2143 in 6b3dd56

	foreach ($this->php_extensions as $ext => $enabled) {
	if ($enabled) {
	$this->internal_stubs[] = $dir_lvl_2 . DIRECTORY_SEPARATOR . "stubs"
	. DIRECTORY_SEPARATOR . "extensions" . DIRECTORY_SEPARATOR . "$ext.phpstub";
	}
	}

Recently a new way has been introduced (probably to load ext stubs on https://psalm.dev/ snippets): using extension_loaded() function, first time used in #7614 . I think it's save to treat ext-redis as a regular extension.

proposals

1. Do not confuse users by a list of "unsupported extensions" that actually supported (usually core and some bundled one)
2. Reduce options to load extensions: do not use extension_loaded, instead, use existing 2 ways of doing this (using composer.json is consider as the best practice for doing this). Load all available ext stubs on psalm.dev (unless there are some conflicting). (a PR as an example Unify a way how to load stubs for extensions #8881)

[weirdan]

do not use extension_loaded()

Sounds good to me

[orklah]

I'm not too convinced myself.

1. I agree that having unsupported extensions is confusing, but this is due to the fact that Psalm's stubs are not yet all complete. We could just drop that phrase to avoid this confusion
2. dropping extension_loaded seems a clear downside for casual users (forcing them to manually set the configuration) with a vague upside (having less entry points)

Dropping extension_loaded now,after we just released Psalm 5 in which the config can be set for the first time, will guarantee that CIs will fail everywhere because of missing extensions for no good reason.
If we want to do it anyway, we'll have to soften the blow:

• first with a warning that any loaded extension not configured in either composer or config will be dropped in the future
• second with an automatic configuration on creation of the config file (through --init) that creates the configuration with any loaded extension at this moment

[alies-dev]

Agree, we should not break existing integrations. I've created a new PR taking into account your suggestions: #8885