Add pcntl and grpc docs by rodrigoprimo · Pull Request #95 · PHPCSStandards/PHP_CodeSniffer-documentation

rodrigoprimo · 2026-03-06T14:14:03Z

Description

Follow-up to #91.

This PR introduces two changes to the Requirements wiki page:

Documents PCNTL as a strongly recommended PHP extension, as it is required for parallel processing via the --parallel CLI option.
Adds a warning about the gRPC PHP extension, which is known to cause PHP_CodeSniffer to hang when parallel processing is enabled.

Related issues/external references

PR checklist

I have checked there is no other PR open for the same change.
I have read the Contribution Guidelines.
I grant the project the right to include my changes under the BSD-3-Clause license (and I have the right to grant these rights).
I have verified that my changes comply with the projects coding standards.
[When adding a new Wiki page] I have added the new page to the _Sidebar.md file.
[When adding/updating output examples] I have verified via the GitHub Actions artifact that the pre-processing handles the command correctly.

The gRPC PHP extension is known to cause PHP_CodeSniffer to hang when running with parallel processing enabled. Refs PHPCSStandards/PHP_CodeSniffer 294

github-actions · 2026-03-06T14:14:58Z

=== This is an auto-generated comment ===

Thank you for your PR.
A dry-run has been executed on your PR, executing all markdown pre-processing for the wiki files.

Please review the resulting final markdown files via the created artifact.
This is especially important when adding new pages or updating auto-generated output blocks.

N.B.: the above link will automatically be updated when this PR is updated.

jrfnl

LGTM! Thanks @rodrigoprimo !

P.S.: I'll hold off on merging for the moment until you've had a chance to read the discussion between @fredden and me in PHPCSStandards/PHP_CodeSniffer#1388 and indicated how you want to move forward in light of that.

jrfnl · 2026-03-09T14:55:52Z

wiki/Requirements.md

+- PCNTL: required for parallel processing via the `--parallel` CLI option. Without this extension, PHP_CodeSniffer will not be able to check multiple files simultaneously.
+
+> [!WARNING]
+> The gRPC PHP extension is known to cause PHP_CodeSniffer to hang when running with parallel processing enabled. If the gRPC extension is loaded, make sure the `grpc.enable_fork_support` and `grpc.poll_strategy` ini settings are properly configured. See [this comment](https://github.com/PHPCSStandards/PHP_CodeSniffer/issues/294#issuecomment-1906558549) for more details.


Hmm... looking at this again now, I think it would be better for the docs to include the information for which you now point to an issue.

What do you think ?

How do I configure these settings "properly"? I think the documentation should include that part as well.

I think it looks good now.

I think that is a good idea, @jrfnl! I've updated the warning to include the workaround directly in the text instead of pointing to the issue.

I used ```text instead of ```bash for the code block as the latter highlights <file|directory> which is not helpful in my opinion for this particular case.

The phpcs command added here triggered a cspell error. I opted to update the cspell markdown_code_block regex pattern to also ignore code blocks inside blockquotes. The previous pattern only matched code blocks starting with optional whitespace, so it didn't match the > ``` syntax used in this warning. Let me know if you prefer a different approach, such as applying this fix in a separate PR or simply adding the word that triggers the error to the allowlist.

jrfnl · 2026-03-09T23:28:13Z

@derrabus @mbomb007 Just pinging you - the PHPCS wiki docs are being updated to warn about how the gRPC extension can break PHPCS. If you have the chance to look this over and give an opinion on whether this update would have helped you, that would be appreciated!

mbomb007 · 2026-03-10T13:58:31Z

Personally, I probably wouldn't have seen that information, at least not without a lot of digging. Someone setting up PHPCS will most likely only read the README by scrolling down at https://github.com/PHPCSStandards/PHP_CodeSniffer. In order to get to the updated info on PHP extensions, you have to click the "GitHub wiki" link in the Documentation section, which is pretty generic (and then they have to arrive at the specific section). Perhaps a note pointing to the PHP extension info could be added in the Requirements section of the README? That definitely would have helped me.

…instead of pointing to the issue

…instead of pointing to the issue I opted to use "```text" instead of "```bash" as the latter highlights only "<file|directory>" which I don't think helps in this case.

The existing regex pattern for ignoring code blocks only matched blocks at the start of a line (with optional whitespace). This update makes it also match code blocks inside markdown blockquotes, where lines are prefixed with `>`.

rodrigoprimo · 2026-03-13T14:08:28Z

Perhaps a note pointing to the PHP extension info could be added in the Requirements section of the README? That definitely would have helped me.

I think that is a good idea, @mbomb007. I created PHPCSStandards/PHP_CodeSniffer#1393 to discuss how to address your suggestion.

.cspell.yml

wiki/Requirements.md

rodrigoprimo added 2 commits March 6, 2026 11:10

Requirements: document PCNTL as a recommended PHP extension

ec9da1c

Requirements: add warning about gRPC extension and parallel processing

e3e23ce

The gRPC PHP extension is known to cause PHP_CodeSniffer to hang when running with parallel processing enabled. Refs PHPCSStandards/PHP_CodeSniffer 294

github-actions bot added Status: triage Component: Wiki labels Mar 6, 2026

rodrigoprimo added Type: other documentation improvement and removed Status: triage labels Mar 6, 2026

rodrigoprimo mentioned this pull request Mar 6, 2026

Add suggest section to composer.json for recommended extensions PHPCSStandards/PHP_CodeSniffer#1388

Merged

12 tasks

jrfnl approved these changes Mar 6, 2026

View reviewed changes

jrfnl reviewed Mar 9, 2026

View reviewed changes

Add details on how to handle the gRPC extension directly in the text …

a4120b0

…instead of pointing to the issue

rodrigoprimo force-pushed the add-pcntl-and-grpc-docs branch from e627dec to a4120b0 Compare March 13, 2026 12:02

rodrigoprimo added 2 commits March 13, 2026 10:46

Add details on how to handle the gRPC extension directly in the text …

bc0b73c

…instead of pointing to the issue I opted to use "```text" instead of "```bash" as the latter highlights only "<file|directory>" which I don't think helps in this case.

Spellcheck: also ignore code blocks inside blockquotes

bdd42b4

The existing regex pattern for ignoring code blocks only matched blocks at the start of a line (with optional whitespace). This update makes it also match code blocks inside markdown blockquotes, where lines are prefixed with `>`.

rodrigoprimo force-pushed the add-pcntl-and-grpc-docs branch from 876308e to bdd42b4 Compare March 13, 2026 13:46

rodrigoprimo mentioned this pull request Mar 13, 2026

Add a link to the Requirements wiki page in the README? PHPCSStandards/PHP_CodeSniffer#1393

Open

jrfnl reviewed Mar 13, 2026

View reviewed changes

.cspell.yml Outdated Show resolved Hide resolved

jrfnl reviewed Mar 13, 2026

View reviewed changes

wiki/Requirements.md Outdated Show resolved Hide resolved

rodrigoprimo and others added 3 commits March 16, 2026 09:57

Fix code block regex to also handle indented code blocks

cda898f

Move individual sniff requirements above gRPC warning

28669ef

cspell: fix regex doc indentation

623c34c

jrfnl approved these changes Mar 18, 2026

View reviewed changes

jrfnl merged commit b0fb2a2 into main Mar 18, 2026
14 checks passed

jrfnl deleted the add-pcntl-and-grpc-docs branch March 18, 2026 13:23

jrfnl mentioned this pull request Mar 18, 2026

Wiki/Requirements: improve information about required PHP extensions #97

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Add pcntl and grpc docs#95

Add pcntl and grpc docs#95
jrfnl merged 8 commits intomainfrom
add-pcntl-and-grpc-docs

rodrigoprimo commented Mar 6, 2026

Uh oh!

github-actions bot commented Mar 6, 2026 •

edited

Loading

Uh oh!

jrfnl left a comment

Uh oh!

jrfnl Mar 9, 2026

Uh oh!

derrabus Mar 10, 2026

Uh oh!

mbomb007 Mar 10, 2026

Uh oh!

rodrigoprimo Mar 13, 2026

Uh oh!

jrfnl commented Mar 9, 2026

Uh oh!

mbomb007 commented Mar 10, 2026 •

edited

Loading

Uh oh!

rodrigoprimo commented Mar 13, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Milestone

Development

Uh oh!

4 participants

Uh oh!

Conversation

rodrigoprimo commented Mar 6, 2026

Description

Related issues/external references

PR checklist

Uh oh!

github-actions bot commented Mar 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jrfnl left a comment

Choose a reason for hiding this comment

Uh oh!

jrfnl Mar 9, 2026

Choose a reason for hiding this comment

Uh oh!

derrabus Mar 10, 2026

Choose a reason for hiding this comment

Uh oh!

mbomb007 Mar 10, 2026

Choose a reason for hiding this comment

Uh oh!

rodrigoprimo Mar 13, 2026

Choose a reason for hiding this comment

Uh oh!

jrfnl commented Mar 9, 2026

Uh oh!

mbomb007 commented Mar 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

rodrigoprimo commented Mar 13, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Milestone

Development

Uh oh!

4 participants

github-actions bot commented Mar 6, 2026 •

edited

Loading

mbomb007 commented Mar 10, 2026 •

edited

Loading