Save this content to: .claude/skills/php-lint/SKILL.md

# Add a PHP lint rule

Grow the blocking `PHP lint` job one check at a time. Do not turn this
into a formatter or PSR-12 gate.

Background: [tooling/php-lint/README.md](../../../tooling/php-lint/README.md).

## Decide PHPCS vs custom script

Use a **PHPCS sniff** when the check is a stock sniff (file shape, tokens,
forbidden constructs). Edit `tooling/php-lint/phpcs.xml`.

Use a **custom script** when the invariant is repo-specific (forbidden
APIs, generated-file drift, naming). Add
`tooling/php-lint/scripts/<name>.php` or `<name>.sh`.

Do not add both for the same check.

## Hard constraints

- Scope is first-party `src/` only. Generated bridge files
  (`src/bridge/_generated_*.php`) and `tests/Frameworks/` stay out.
- The job runs once on current NTS PHP. It does not compile the
  extension and is not matrixed across PHP 7.0-8.5.
- Checks must be version-agnostic. Do not parse PHP with the runner's
  engine unless the result is valid for every supported PHP.
- Never enable `<rule ref="PSR12"/>` wholesale.
- Do not enable `Generic.PHP.Syntax` (`php -l`) or
  `Generic.PHP.DeprecatedFunctions` unless the user explicitly accepts
  the version / tool-upgrade risk. Those stay commented in `phpcs.xml`.
- Do not add `PHP lint` to `.gitlab/flaky-jobs.txt` or set
  `allow_failure`. The job is meant to block merge-gate.

## Workflow — PHPCS sniff

1. Read `tooling/php-lint/phpcs.xml`. Prefer uncommenting a sniff that
   is already documented there over adding a new one.
2. Add **one** sniff, for example:

   ```xml
   <rule ref="Generic.Files.EndFileNewline"/>
   ```

3. Run `composer ci-lint` (or `bash tooling/php-lint/run.sh`) from the
   repo root. Use PHP 7.4+ and Composer; the extension is not required.
4. If it fails:
   - Mechanical cleanup (newline, tabs, trailing space) is OK in the
     same change. Prefer `tooling/php-lint/vendor/bin/phpcbf
     --standard=tooling/php-lint/phpcs.xml` when the sniff is
     auto-fixable.
   - If a **generated** file fails, fix the generator so regeneration
     still passes. Do not leave a manual edit that the next generate
     will wipe. Example: `tooling/stubs/generate-stubs.php` must append
     a trailing newline to `src/ddtrace_php_api.stubs.php`.
   - If the cleanup is large or opinionated, comment the sniff back out
     (with the failing files named) and stop. Ask before a repo-wide
     reformat.
5. Keep the sniff only if `composer ci-lint` exits 0.
6. Update the enabled-sniff list in `tooling/php-lint/README.md` if you
   changed what is on.

## Workflow — custom script

1. Add `tooling/php-lint/scripts/<name>.php` or `<name>.sh`.
   - `*.php` is run with `php`
   - `*.sh` is run with `bash`
   - `README.md` and `.gitkeep` are ignored
2. CWD is the repo root. Exit 0 to pass, non-zero to fail.
3. Print the failing paths and why. Do not depend on the `+x` bit;
   `run.sh` dispatches by extension.
4. Keep the script small. Do not scan `tests/Frameworks/` or
   `vendor/`.
5. Run `composer ci-lint`. The runner continues after a failure so
   PHPCS output is still visible.

## Local commands

```bash
composer ci-lint
# or
bash tooling/php-lint/run.sh
```

PHPCS lives in `tooling/php-lint/vendor/` (isolated Composer install).
`run.sh` runs `composer install` there on first use.