From 470c3619f85c9368a9540b1fb6f9d8d5f73e04fc Mon Sep 17 00:00:00 2001 From: jrfnl Date: Mon, 22 Dec 2025 18:03:17 +0100 Subject: [PATCH] New reusable workflow: "find token properties" PHP_CodeSniffer originally offered a number of "token groups" as static properties in the `Tokens` class to allow re-use of these groups across sniffs. As of PHP_CodeSniffer 4.0.0, these static properties still exist, but are now (soft) deprecated in favour of class constants in the `Tokens` class for the same, which should create more stability, as this means the token groups can no longer be changed from within a(n external) sniff. PHP_CodeSniffer related projects which still support both PHPCS 3.x as well as 4.x, will, for the time being, still need to use the static properties from the `Tokens` class. Once a PHP_CodeSniffer related project has dropped support for PHPCS 3.x though, they can enforce the use of the class constants from the `Tokens` class by running this re-usable workflow in their CI. * This workflow is particularly useful for repositories which have existing open PRs at the time of the PHPCS version drop and these open PRs should not re-introduce references to the static properties. * This workflow can also be helpful for repositories which have contributors which contribute to a range of PHPCS related repos and for whom it would be very easy to overlook that they've used the "old-school" token group instead of the new-fangled token group constants. In contrast to most of the other reusable workflows, this workflow does not work based on a configuration file. One should only add a job calling this workflow to a project's CI once support for PHPCS 3.x has been dropped. Includes adding documentation about this workflow to the `README` file. --- .github/workflows/reusable-findtokenprops.yml | 24 +++++++++++++++ README.md | 29 +++++++++++-------- 2 files changed, 41 insertions(+), 12 deletions(-) create mode 100644 .github/workflows/reusable-findtokenprops.yml diff --git a/.github/workflows/reusable-findtokenprops.yml b/.github/workflows/reusable-findtokenprops.yml new file mode 100644 index 0000000..679ccf6 --- /dev/null +++ b/.github/workflows/reusable-findtokenprops.yml @@ -0,0 +1,24 @@ +name: FindTokenPropertiesRefs + +on: + workflow_call: + +jobs: + find-token-properties: + # The properties in the PHPCS Tokens class have been deprecated since PHPCS 4.0.0. + name: 'Find use of Tokens properties' + runs-on: windows-latest + + steps: + - name: Checkout code + uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1 + with: + persist-credentials: false + + - name: Find uses + id: findprops + shell: cmd + run: | + findstr /S /N /C:"Tokens::$" *.php + IF %ERRORLEVEL% NEQ 1 (Echo Please use the Tokens constants instead of the properties &Exit /b 1) + IF %ERRORLEVEL% EQU 1 (Echo All good &Exit /b 0) diff --git a/README.md b/README.md index 321669e..bac3256 100644 --- a/README.md +++ b/README.md @@ -16,7 +16,7 @@ Additional community health files may be added over time and/or when GitHub adds ## Re-usable workflows -Aside from the community health files, this repository also offers a number of configuration file driven re-usable GitHub Actions workflows. +Aside from the community health files, this repository also offers a number of (mostly) configuration file driven re-usable GitHub Actions workflows. ### What does "configuration file driven" mean and why are the workflows set up that way ? @@ -49,7 +49,10 @@ The following re-usable workflows are available: **Inputs**: + `strict`: Optional. Whether to enable strict mode. Defaults to "false". 2. [actionlint] which runs a static analysis check on GitHub Actions workflow files only. - _Note: this is the only check without a configuration file requirement._ + _Note: this check does not have a configuration file requirement._ +* [`reusable-findtokenprops.yml`][reusable-findtokenprops] to find any uses of the PHPCS static `Tokens::$groupName` properties. + These properties have been (soft) deprecated since PHP_CodeSniffer 4.0.0 and should no longer be used in code bases which have dropped support for PHP_CodeSniffer 3.x. + _Note: this check does not have a configuration file requirement._ Example configuration files for most of these can be found in the root directory of this repository. @@ -70,17 +73,19 @@ This has two benefits: > It is best practice for tags for repositories which will be used in GitHub Actions workflows to be prefixed with `v` before the version number, so tags in this repository should start with a `v` prefix too. -[community health files]: https://docs.github.com/en/communities/setting-up-your-project-for-healthy-contributions/creating-a-default-community-health-file +[community health files]: https://docs.github.com/en/communities/setting-up-your-project-for-healthy-contributions/creating-a-default-community-health-file -[reusable-markdownlint]: https://github.com/PHPCSStandards/.github/blob/main/.github/workflows/reusable-markdownlint.yml -[markdownlint-cli2]: https://github.com/DavidAnson/markdownlint-cli2 +[reusable-markdownlint]: https://github.com/PHPCSStandards/.github/blob/main/.github/workflows/reusable-markdownlint.yml +[markdownlint-cli2]: https://github.com/DavidAnson/markdownlint-cli2 -[reusable-phpstan]: https://github.com/PHPCSStandards/.github/blob/main/.github/workflows/reusable-phpstan.yml -[phpstan]: https://phpstan.org/ +[reusable-phpstan]: https://github.com/PHPCSStandards/.github/blob/main/.github/workflows/reusable-phpstan.yml +[phpstan]: https://phpstan.org/ -[reusable-remark]: https://github.com/PHPCSStandards/.github/blob/main/.github/workflows/reusable-remark.yml -[remark-lint]: https://github.com/remarkjs/remark-lint +[reusable-remark]: https://github.com/PHPCSStandards/.github/blob/main/.github/workflows/reusable-remark.yml +[remark-lint]: https://github.com/remarkjs/remark-lint -[reusable-yamllint]: https://github.com/PHPCSStandards/.github/blob/main/.github/workflows/reusable-yamllint.yml -[yamllint]: https://yamllint.readthedocs.io/en/stable/ -[actionlint]: https://github.com/rhysd/actionlint +[reusable-yamllint]: https://github.com/PHPCSStandards/.github/blob/main/.github/workflows/reusable-yamllint.yml +[yamllint]: https://yamllint.readthedocs.io/en/stable/ +[actionlint]: https://github.com/rhysd/actionlint + +[reusable-findtokenprops]: https://github.com/PHPCSStandards/.github/blob/main/.github/workflows/reusable-findtokenprops.yml