WordPress / WordPress/WordPress-Coding-Standards

Use a PHPCS bootstrap file to auto-detect text-domain and minimum supported wp version

Open
#995 8 comments 3 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Type: Enhancement
Dominant language
PHP
Stars
2.8k
Forks
521
Avg merge
5d 20h
Merged PRs (30d)
1

Description

The I18n sniff needs a text_domain property to be set in a custom ruleset to trigger the text-domain checks.
The DeprecatedFunctions, DeprecatedClasses and the upcoming DeprecatedParameters (#826) sniffs need a minimum_supported_version property.

When the sniffs are used on plugins and themes, this information is typically already available in the theme/plugin headers in style.css/ readme.txt or the main plugin file and - at least for the minimum_supported_version a pain to keep in sync.

Since PHPCS 2.5.0 there appears to be a - rarely used - option to bootstrap a file to be run between when the sniffs are loaded and when they are actually run.
See:

I would like to suggest we explore the possibility of auto-detecting the above mentioned properties using a bootstrap file.

Some thoughts:

  • Look only in the root of the directory being sniffed for any of the files mentioned & if the file is found, parse the top of the file similar to how WP core does. Looking further down or up can quickly become more complicated than is warranted.
  • Custom text_domain properties if set should still be respected as this is an array and the property can be used to pass more than one text-domain.
    • So I suggest for the in-sniff logic to check for a custom property first and if none is found, use the auto-detected info. Alternatively, the auto-detected property could be merged into the custom property.
  • Custom minimum_supported_version properties should be overruled if something different is auto-detected, as that is the "official" minimum supported version so this should always be leading.

I suggest this to be added to the Extra ruleset as these sniffs are typically contained therein.

Opinions ?

/cc @grappler This principle may also be useful for the theme sniffs.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the I18n, DeprecatedFunctions, DeprecatedClasses, and upcoming DeprecatedParameters sniffs, the Extra ruleset, and PHPCS's bootstrap-file documentation. Review how style.css, readme.txt, and the main plugin file expose headers, then define the auto-detection behavior and how custom text_domain and minimum_supported_version properties should interact.

Written by the indexing model from the issue text.

Assessment

Tech stack
php
Domain
tooling
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.