Codestyle Laravel Package

Getting Started

composer require --dev k10r/codestyle

1. Find the ruleset. After install, inspect vendor/k10r/codestyle/ — the standard lives in a */ruleset.xml file (typically named after the org, e.g. K10r). Skim that XML before configuring anything; it tells you exactly which sniffs are enforced and what will fail on your first run. As of v3.1.0 there is also a PHP 8.2 migration config in the package — locate it (a separate *.xml under the package root or a migration subdirectory) and read it separately; it is not automatically part of the base standard.
2. Confirm PHPCS is present. The package provides rules, not the runner. Verify vendor/bin/phpcs --version works; if not, add squizlabs/php_codesniffer as a dev dependency. Matching the PHPCS major version the ruleset was authored against (see the package's composer.json constraints) avoids "referenced sniff does not exist" errors. The v3.1.0 PHP 8.2 config almost certainly needs a recent PHPCS plus phpcompatibility/php-compatibility-style sniffs installed — check the package's composer.json require/suggest before assuming the base install covers it.
3. Create a project ruleset in the repo root (phpcs.xml.dist) rather than passing --standard on every invocation:

<?xml version="1.0"?>
<ruleset name="Project">
    <rule ref="K10r"/>
    <file>src</file>
    <file>tests</file>
    <arg name="extensions" value="php"/>
    <arg name="colors"/>
</ruleset>

4. First use case: run vendor/bin/phpcs on a small, already-clean directory (a single well-maintained service class, or tests/) before running it repo-wide. On a mature codebase the first full run is usually thousands of violations and tells you nothing actionable. If your app is on PHP 8.2, do this first run against the new migration config as well — it is the fastest way to see what the release actually adds.
5. Add the fixer companion early. vendor/bin/phpcbf (same standard, auto-fix mode) resolves whitespace, import ordering, and bracket placement in one pass — do this before hand-fixing anything, so you're only reviewing what the tool can't handle.

Implementation Patterns

Committed base config + ignored local override. Keep phpcs.xml.dist in version control so CI and every developer run the same standard, and let contributors create a gitignored phpcs.xml to narrow scope (e.g. <file>src/MyModule</file> only) while iterating. PHPCS prefers phpcs.xml over .dist, so this works with zero extra flags.

Composer script wiring. Editors, hooks, and CI should all call the same entry points:

"scripts": {
    "lint": "phpcs",
    "lint:fix": "phpcbf",
    "lint:ci": "phpcs --report=checkstyle --report-file=build/phpcs.xml --no-colors",
    "lint:php82": "phpcs --standard=vendor/k10r/codestyle/<php82-migration-config>.xml src"
}

Keep the 8.2 migration check as its own script rather than folding it into lint — it is a one-off upgrade audit, not a permanent gate, and mixing it in makes every local run noisier.

PHP 8.2 migration audit (new in v3.1.0). Before you upgrade production PHP, run the migration config against src/ and capture the report:

vendor/bin/phpcs --standard=vendor/k10r/codestyle/<migration-config>.xml \
  --report=full --report-file=build/php82-migration.txt src

Triage the output into "auto-fixable" (phpcbf with the same --standard) and "manual" (deprecations, dynamic properties, ${var} string interpolation, utf8_encode/decode, etc.). Treat this as a one-time checklist that gets deleted when the upgrade lands — committing it as a permanent standard will just accumulate exclusions.

Pre-commit hook. Run composer lint:fix on staged files via CaptainHook, lefthook, or a plain .git/hooks/pre-commit. Use PHPCS's --filter or your hook runner's staged-file list to keep it fast:

vendor/bin/phpcbf --filter=$(git diff --cached --name-only --diff-filter=ACM | grep '\.php$' | paste -sd,)

CI as a gate, locally as a fixer. In GitHub Actions / GitLab, run composer lint:ci and consume the Checkstyle report so violations annotate the diff. Locally, developers only ever run the fixer. This split prevents the common failure mode where linting is perceived as noise.

Phase-in via sniff selection. For legacy codebases, don't adopt the whole standard at once. Reference the ruleset, then temporarily disable noisy categories:

<rule ref="K10r">
    <exclude name="K10r.Commenting"/>
    <exclude name="Generic.Files.LineLength"/>
</rule>

Remove exclusions sprint by sprint. This keeps the standard in one place instead of accumulating ad-hoc --sniffs flags.

Scoped exclusions over blanket ignores. Exclude generated code and framework stubs with <exclude-pattern> (e.g. */migrations/*, */storage/*, *.blade.php) rather than // phpcs:ignore annotations sprinkled through source — the latter rots silently.

Editor integration. Point PHPStorm's Settings → PHP → Quality Tools → PHP_CodeSniffer at vendor/bin/phpcs and the project ruleset; in VS Code, phpcs via shepherd/phpcs extension with phpcs.standard set to the ruleset path. Developers see violations in the gutter as they type, which is the single biggest driver of adoption.

Extend for project-specific conventions. The ruleset is meant to be referenced, not edited. Add your own house rules alongside it in phpcs.xml.dist using <rule ref="..."> entries — vendor/ is disposable.

Gotchas and Tips

v3.1.0 is small but not a no-op. The release adds a PHP 8.2 migration config only — no sniff removals or renames are announced, so it should be a drop-in for v3.0.0. Still, read the diff of the ruleset files before composer update: if the base ruleset.xml gained a rule alongside the new config, your next CI run turns red for reasons unrelated to your own changes. Upgrade as a dedicated commit so the resulting violations are attributable.

Source repo moved namespaces. Release notes and changelog now point at github.com/kellerkinderDE/codestyle while the Composer package remains k10r/codestyle (same vendor/k10r/codestyle path). Expect stale links in old blog posts and IDE configs — and check that the repo you're filing issues against is the one that's actually maintained.

Standard name resolution is the #1 setup failure. <rule ref="K10r"/> only works if the standard is discoverable. If you see ERROR: the "K10r" coding standard is not installed, the fix is either registering it via phpcs --config-set installed_paths vendor/k10r/codestyle or — more robustly — referencing the ruleset by explicit relative path in your phpcs.xml.dist. The installed_paths config is machine-local and will bite you in CI.

phpcbf is not phpcs. Auto-fix handles formatting; it cannot resolve naming, complexity, unused parameters, or docblock content. Budget review time for the non-fixable residue, and never run phpcbf over a huge diff without a clean working tree — you'll want to git diff the result and revert anything semantically surprising. This matters doubly for the 8.2 migration config, where some sniffs offer fixes you should read before accepting.

Enable caching. --cache turns repeat runs from seconds into milliseconds; without it, developers disable the tool because it's slow. Pair with --parallel=4 on multi-core CI runners. Add .phpcs-cache to .gitignore.

Baseline for brownfield repos. If a full run is unmanageable and phase-in isn't practical, generate a PHPCS baseline (the phpcs-baseline plugin or a report-derived ignore list) and commit it. New code is then held to the full standard from day one while existing violations are grandfathered. Revisit the baseline quarterly — an untouched baseline is technical debt masquerading as compliance.

Watch for conflicting standards. If another package also ships a phpcs.xml or registers a standard, PHPCS merges nothing — it picks one. In multi-package monorepos, be explicit about which ruleset applies per directory, and verify with phpcs -i (lists installed standards) and phpcs --config-show. The new PHP 8.2 config is a separate standard target — confirm it inherits the base rules or is intentionally standalone before you assume it checks style too.

Low adoption still applies. Two stars and effectively zero dependents means you are the QA department: the PHP 8.2 config has had one pair of eyes on it. Verify it actually fires by deliberately introducing a known-8.2-incompatible construct in a scratch file (e.g. ${var} interpolation) and confirming a violation. A green run from an untested config is not evidence of compatibility.

Extension point. The ruleset author intended it as a base layer. If you need to relax a sniff's threshold (e.g. Generic.Files.LineLength to 120), override the property in your own phpcs.xml.dist rather than forking the package — forking means you own updates permanently.

Debugging a rule that won't fire. Use phpcs -s to print sniff source codes in the report, then check the ruleset for <exclude> entries and <severity>0</severity> overrides — severity-zero is a common way rules get disabled invisibly.