PHP extension detection and requirements documentation

[fredden]

This is a follow-up to squizlabs/PHP_CodeSniffer#3754. See also #1388.

The lists of PHP extensions in composer.json's "require" and "suggest" sections are incomplete. Running maglnet/composer-require-checker as described in squizlabs/PHP_CodeSniffer#3754 on this codebase (as at 8b1c267) yields the following issues (and a long list of PHP_CodeSniffer-internal T_* constants).

ComposerRequireChecker 4.0.1-111-g8b1c26745-dev
The following unknown symbols were found:
+-------------------------------------------------------+--------------------+
| unknown symbol                                        | guessed dependency |
+-------------------------------------------------------+--------------------+
| Composer\Autoload\ClassLoader                         |                    |
| PHP_CodeSniffer\Tests\Standards\AbstractSniffTestCase |                    |
| PHP_CodeSniffer\Tests\ConfigDouble                    |                    |
| PHP_CODESNIFFER_VERBOSITY                             |                    |
| PHP_CODESNIFFER_CBF                                   |                    |
| iconv_strlen                                          | ext-iconv          |
| libxml_use_internal_errors                            | ext-libxml         |
| libxml_get_errors                                     | ext-libxml         |
| libxml_clear_errors                                   | ext-libxml         |
| json_encode                                           | ext-json           |
| iconv                                                 | ext-iconv          |
| DOMElement                                            | ext-dom            |
| DOMDocument                                           | ext-dom            |
| DOMNode                                               | ext-dom            |
| json_decode                                           | ext-json           |
| posix_isatty                                          | ext-posix          |
| pcntl_fork                                            | ext-pcntl          |
| pcntl_waitpid                                         | ext-pcntl          |
| pcntl_wexitstatus                                     | ext-pcntl          |
+-------------------------------------------------------+--------------------+

✅ \Composer\Autoload\ClassLoader

No action required here.

The use of this class is wrapped in suitable safeguarding code.

✅ PHP_CodeSniffer\Tests\Standards\AbstractSniffTestCase and PHP_CodeSniffer\Tests\ConfigDouble

No action required here.

These show up due to the way that I wrote the temporary 'autoload' section within composer.json and can safely be ignored.
This is a feature of the filesystem layout, having tests for each standard within the src/ directory.

✅ PHP_CODESNIFFER_VERBOSITY and PHP_CODESNIFFER_CBF

No action required here.

These are internal PHP_CodeSniffer constants which are always defined in the entrypoints used to run PHP_CodeSniffer.

Similarly, there is a long list of T_* constants which showed up in the tool output, which I have validated and removed before opening this issue.

🔲 ext-dom

This extension is used within the "generator" feature, and is used by all three generators (HTML, Markdown, Text).
While this extension is enabled by default within PHP, it is possible to disable it at compile time.

Actions required:

• Add a check to the start-up code. If a generator has been requested, and the extension is not available: throw some kind of error with a suitable message to the user.
• Update the wiki to show that this extension is required when using the generator feature. - PR Wiki/Requirements: improve information about required PHP extensions PHP_CodeSniffer-documentation#97

🔲 ext-iconv

Actions required:

• Create a new way for reports to declare what extensions they need.
  • Add a new constant to the Report interface (with a default value, thus making this feature optional). Reports will use this constant to declare what PHP extensions they require in order to operate properly.
  • Add a check to the start-up code. For each report that has been requested: loop through all of the PHP extensions that it declares are necessary and assert that these are loaded. If any required PHP extensions are not present, throw some kind of error with a suitable message to the user.
• Add iconv to the list of "required extensions" for the 'checkstyle' report.
• Add iconv to the list of "required extensions" for the 'junit' report.
• Add iconv to the list of "required extensions" for the 'xml' report.
• Update the wiki to show that this extension is required when using the these reports. - PR Wiki/Requirements: improve information about required PHP extensions PHP_CodeSniffer-documentation#97

🔲 ext-json

This extension is used without suitable checks in the 'json' report and the cache feature.
While this extension is enabled by default within PHP, it is possible to disable it at compile time for PHP versions below 8.0.
(From PHP 8.0 and above, this extension can no longer be disabled.)

Actions required:

• Add json to the list of "required extensions" for the 'json' report. (See above for details of this new "required extensions" list.)
• Add a check to the start-up code. If the cache feature was requested, and the extension is not available: disable the cache feature, warn the user that the cache feature has been disabled with a suitable message, and proceed with the run.
  • Be sure to include a code comment reminding us that this check can be removed when we have a minimum PHP version of 8.0+.
• Update the wiki to show that this extension is required when using the cache feature. - PR Wiki/Requirements: improve information about required PHP extensions PHP_CodeSniffer-documentation#97
• Update the wiki to show that this extension is required when using the 'json' report. - PR Wiki/Requirements: improve information about required PHP extensions PHP_CodeSniffer-documentation#97

🔲 ext-libxml

This extension is a requirement of the SimpleXML extension which we already declare a depenency on.
While this extension is enabled by default within PHP, it is possible to disable it at compile time.

Actions required:

• Add ext-libxml to the "require" section of composer.json. - PR Composer: clarify that the PHP libxml extension is required #1409
• Add libxml to the list of required extensions in requirements.php and its associated tests. - PR Wiki/Requirements: improve information about required PHP extensions PHP_CodeSniffer-documentation#97

🔲 ext-pcntl

This extension is not currently available on Windows. This extension powers the "parallel" feature.

We already detect the existence of this extension and silently disable the parallel feature. I have discussed this with @jrfnl and we have agreed that this "automatic disable" should remain silent.

Actions required:

• Add a debug message to show that the parallel feature was silently disabled due to the absense of this extension.
• Update the wiki to show that this extension is required when using the parallel feature. - PR Wiki/Requirements: improve information about required PHP extensions PHP_CodeSniffer-documentation#97

✅ ext-posix

No action required here.

This is used in exactly one place within the codebase (\PHP_CodeSniffer\Util\Common::isStdinATTY()). It is wrapped in a suitable check, and the code safely falls back to other methods to detect if the output will be going to a terminal or not.

[jrfnl]

Thanks for opening this issue @fredden ! I concur with the proposed actions.

Notes:

• Documentation changes (Wiki) can be made via the https://github.com/PHPCSStandards/PHP_CodeSniffer-documentation repo and would be great first issues and quick wins. Let's get those PRs rolling 😉
• Some of the other changes will be more involved as they will need updates to the Config class or the Reports functionality, which currently barely have any tests at all and considering this is about detecting whether PHP extensions are available, writing tests to cover the changes will be a challenge in itself.
  Aside from the odd bug report about unexpected behaviour when iconv was missing, there haven't been significant bug reports about things breaking which can be explained by extensions missing.
  With that in mind, I would prefer a structural solution with tests properly set up, instead of a quick & dirty untestable solution.
  I realize that might mean that it will be a while before this issue is fully addressed. Considering the lack of problems reported, I do not think that is a problem.

[jrfnl]

I've pulled PR PHPCSStandards/PHP_CodeSniffer-documentation#97 to the docs repo to finish off the Wiki "Requirements" page changes.