Coding Standard Laravel Package

Getting Started

The package is not a runtime library — it is a PHP_CodeSniffer ruleset. Nothing ships into your application code; everything lives in require-dev. Start by pulling the linter and the standard together:

composer require --dev squizlabs/php_codesniffer keboola/coding-standard

As of 16.1.0 the standard raised its php_codesniffer version requirement, so prefer letting the standard resolve PHPCS for you (drop the explicit squizlabs/php_codesniffer line, or keep it unpinned) and check vendor/keboola/coding-standard/composer.json for the exact constraint. Pinning a PHPCS version older than that constraint will make Composer either upgrade you unexpectedly or refuse to install.

Then create a phpcs.xml.dist at the project root that points at the ruleset shipped in vendor/:

<?xml version="1.0"?>
<ruleset name="Project">
    <rule ref="vendor/keboola/coding-standard/ruleset.xml"/>
    <file>src</file>
    <file>tests</file>
</ruleset>

Run it once to see the damage, then let the auto-fixer do the mechanical work:

vendor/bin/phpcs                 # report
vendor/bin/phpcbf                # fix what is safely fixable

Where to look first: open vendor/keboola/coding-standard/ruleset.xml directly. It is a short, readable XML file listing the sniffs it enables on top of PSR-12 (typically Slevomat, declare(strict_types=1), import ordering, trailing commas, unused-use detection). Reading that file tells you exactly what the standard enforces far faster than fighting error messages. Also check composer.json inside the package for the pinned slevomat/coding-standard and php_codesniffer versions — those dictate which sniffs exist, and the PHPCS constraint is exactly what changed in 16.1.0.

First use case: run vendor/bin/phpcs -s src on an existing Keboola-style project to get a baseline, then wire the same command into a Composer script so it matches what CI will run. Add a --report=summary pass if the full report is overwhelming on a first run.

Implementation Patterns

Composer scripts as the single entry point. Don't let developers memorise raw flags; expose two scripts and treat them as the contract:

"scripts": {
    "check-cs": "phpcs --parallel=4",
    "fix-cs":   "phpcbf --parallel=4"
}

--parallel matters on any non-trivial codebase; this standard enables enough sniffs that serial runs become a coffee break.

Register the standard with the installer plugin. Add dealerdirect/phpcodesniffer-composer-installer and you can invoke --standard=Keboola by name instead of hard-coding the long vendor/... path. The plugin sets PHPCS's installed_paths during composer install, so it works in CI without extra setup. Do this before bumping to 16.1.0 if you currently hard-code the vendor path — it removes one of the two things a PHPCS version bump can break.

Split rulesets per directory. Keboola's ruleset is strict (strict types, fully-typed signatures, no unused imports). That's usually right for src/ and excessive for tests/ or generated code. Keep a root phpcs.xml.dist for src, and add a nested tests/phpcs.xml that extends the same ruleset but excludes sniffs like SlevomatCodingStandard.TypeHints or Generic.Files.LineLength where readability suffers:

<ruleset name="Tests">
    <rule ref="vendor/keboola/coding-standard/ruleset.xml"/>
    <exclude name="SlevomatCodingStandard.TypeHints.ParameterTypeHint"/>
</ruleset>

PHPCS picks up the nearest ruleset when run from a subdirectory, so phpcs tests/ will use it automatically.

CI integration. Run composer check-cs as a distinct job, not bundled with tests — a CS failure should be a fast, obvious red X, and it lets you cache the PHPCS result cache across runs (--cache=vendor/.phpcs-cache). Keep the CI PHP version and the PHPCS version visible in the job output; after a dependency bump like 16.1.0 you want to see which linter actually ran. Combine with composer validate --strict in the same job.

Editor wiring. PhpStorm and the VSCode phpcs extension both accept a "Coding standard" path. Point them at phpcs.xml.dist (not the vendor ruleset) so per-directory exclusions behave identically to CI. This is the biggest day-to-day leverage: the standard catches declare(strict_types=1) omissions and unused use statements the moment you save. After upgrading the standard, re-check that the editor plugin's bundled PHPCS is new enough to satisfy the raised requirement — an editor silently running an older linter is the classic "passes locally, fails in CI" cause.

Legacy adoption via baseline. On an old codebase, don't try to fix everything at once. Either run phpcbf on the whole tree and commit the diff as one noisy-but-separate "code style" commit, or generate a baseline XML of existing violations and enforce zero new violations. The former is simpler and matches how Keboola itself tends to adopt it.

Pair with PHPStan. This standard governs formatting and hygiene; it is not a type-checker. The natural combo is PHPCS (this package) for style + PHPStan for types, both in require-dev, both in the CI matrix.

Gotchas and Tips

• The ruleset path is version-coupled. Referencing vendor/keboola/coding-standard/ruleset.xml breaks if the file is renamed or moved between major versions. Pin the package with a caret constraint (^16.1) and read the CHANGELOG before bumping — Slevomat sniff renames propagate straight into PHPCS error codes.
• 16.1.0 is a dependency-constraint release, not a ruleset change. The only entry is "Update php_codesniffer version requirement". No new sniffs, no renames, no deprecations — but it does narrow the set of PHPCS versions that can coexist with the standard. Symptoms of forgetting this: a Composer solver conflict against a pinned squizlabs/php_codesniffer, or a PHPCS that installs fine but is older than the standard expects. Check composer why squizlabs/php_codesniffer (or phpcsstandards/php_codesniffer on 3.8+) after any update and keep local, CI, and editor on the same resolved version.
• Slevomat is the real source of churn. Most of the sniffs you'll fight (SlevomatCodingStandard.*) come from slevomat/coding-standard, which Keboola constrains transitively. A composer update that bumps Slevomat silently changes what passes. 16.1.0 didn't touch it, so this remains the higher-risk axis; lock it in CI or audit the diff.
• phpcbf is not a magic wand. It fixes whitespace, import order, and trailing commas, but refuses to touch anything ambiguous — missing type declarations, strict_types insertion, unused use (in some versions). Expect a two-pass workflow: phpcbf first, then manual fixes for the remainder.
• Debugging a single sniff — use -s to surface the sniff code in the report, and -e to list every sniff the standard enables. When you want to exclude just one rule, <exclude name="SlevomatCodingStandard.Files.TypeNameMatchesFileName"/> in your own ruleset is far better than disabling the whole standard for a directory.
• Strict-types enforcement can be surprising. The standard generally requires declare(strict_types=1); in every PHP file. If you're bolting it onto a Laravel app that doesn't use strict types, either bulk-insert the declaration or exclude that sniff project-wide — do not leave it half-applied, because PHPCS reports it on every file and drowns out real issues.
• Line-length and framework conflicts. Some Laravel/Symfony conventions (long fluent chains, attribute-heavy code) trip Generic.Files.LineLength. Raise the limit locally rather than reformatting generated or framework-published files, and use <exclude-pattern>vendor/*</exclude-pattern> plus any storage/, bootstrap/cache/ directories.
• Caching is essential and rarely documented. Add --cache and put the cache file in vendor/ (or .phpcs-cache with a .gitignore entry). Without it, every local and CI run re-parses the full tree and the standard's sniff count makes that slow. Clear the cache after a linter bump — stale caches survive upgrades and hide new/removed sniffs.
• Extension points are XML, not code. You customise behavior by writing your own <ruleset> that <rule ref="..."/>s Keboola's and then adds <exclude> or <arg> entries. There is no PHP API to extend; if you need a custom sniff, register it via installed_paths in your own standard.
• Low adoption footprint. This is essentially Keboola's internal standard exposed publicly (1 star, no dependents outside their own repos). 16.1.0 being a one-line dependency bump reinforces that maintenance is reactive, not roadmap-driven. Treat it as "Keboola's house style, usable if you're writing Keboola-adjacent PHP or like their conventions" rather than a community standard with broad ecosystem testing. If you aren't in their orbit, evaluate whether PSR-12 + Slevomat + a small custom ruleset gives you the same result with less version-coupling risk.