Getting Started

Install and wire it up in five minutes.

composer require artisanpack-ui/code-style --dev

Requires PHP 8.2+. The package ships a PHP_CodeSniffer standard named ArtisanPackUIStandard (no separate phpcs install needed — it comes as a dependency).

Check it registered correctly before writing any config:

./vendor/bin/phpcs -i          # ArtisanPackUIStandard should be listed
./vendor/bin/phpcs -e --standard=ArtisanPackUIStandard   # lists every sniff in the ruleset

Then drop a phpcs.xml in the project root:

<?xml version="1.0"?>
<ruleset name="YourProjectStandard">
    <description>Your project's coding standard</description>

    <rule ref="ArtisanPackUIStandard"/>

    <file>app</file>
    <file>tests</file>

    <exclude-pattern>*/vendor/*</exclude-pattern>
    <exclude-pattern>*/node_modules/*</exclude-pattern>
</ruleset>

Run it:

./vendor/bin/phpcs                 # uses phpcs.xml
./vendor/bin/phpcs src/ -s -p      # explicit paths, sniff codes, progress

Where to look first: docs/sniffs/sniffs.md in the package (also readable in vendor/artisanpack-ui/code-style/docs/) is the real reference — it documents each of the 16+ sniffs with before/after examples. phpcs -e is the ground truth for exact sniff names you'll need for overrides.

First use case — measure before you enforce. Run phpcs --report=summary against an existing codebase on day one, not with the intent to fix everything, but to see the shape of the debt. A brand-new project should get phpcs clean from the first commit; an existing one will need a staged rollout (see Gotchas).

Implementation Patterns

Separate "check" from "fix" in Composer scripts

"scripts": {
    "lint": "phpcs",
    "lint:fix": "phpcbf"
}

phpcbf handles the mechanical sniffs — indentation, brace placement, spacing, quote style, array syntax, import ordering, magic method casing. It does not fix alignment, Yoda conditionals, missing type declarations, or disallowed functions; those need human edits. Run phpcbf repeatedly until it stops changing files, then phpcs to see what's left:

./vendor/bin/phpcbf >/dev/null; ./vendor/bin/phpcbf >/dev/null; ./vendor/bin/phpcs -s

Pre-commit hook on staged files only

Full-repo scans get slow; scope the hook to what's actually being committed:

git diff --name-only --cached --diff-filter=ACMR \
  | grep -E '\.php$' \
  | xargs -r ./vendor/bin/phpcs --standard=ArtisanPackUIStandard

Pair it with a .phpcs.xml.dist committed to the repo (shared defaults) and a gitignored phpcs.xml for local overrides — that's the workflow the troubleshooting docs recommend for teams.

CI: fail fast, one standard, summary report

- run: composer install --no-interaction --prefer-dist
- run: ./vendor/bin/phpcs --report=summary --extensions=php

Use --report=summary in CI logs (readable) and --report=full -s locally (shows ArtisanPackUI.NamingConventions.VariableName-style codes you can look up or exclude).

Customizing per sniff — the property override pattern

The standard is opinionated; assume you'll tune 2–3 sniffs rather than accept all of them. The documented form:

<rule ref="ArtisanPackUI.Formatting.Indentation">
    <properties>
        <property name="indent" value="2"/>
    </properties>
</rule>

And to drop a sniff entirely while keeping the rest of the standard:

<rule ref="ArtisanPackUIStandard">
    <exclude name="ArtisanPackUI.NamingConventions"/>
</rule>

Discover available property names with phpcs --generator=Markdown --standard=ArtisanPackUIStandard — it prints the sniffs and their configurable properties, which is far faster than reading source.

IDE alignment (the real day-to-day win)

Because the standard is derived from PHPStorm settings, configure your editor to match and most violations never get written: tabs for indentation, alignment of = and => in adjacent lines, spaces inside parentheses (if ( $cond )), short array syntax. Add an .editorconfig mirroring it. In PHPStorm, point the PHP_CodeSniffer inspection at vendor/bin/phpcs and select ArtisanPackUIStandard; in VS Code use shevaua.phpcs with the same path. Restart the IDE after install — the docs call this out because the standard is invisible to the IDE until it re-indexes Composer's autoload.

Gotchas and Tips

Do not run this alongside Laravel Pint or PSR-12. This standard directly contradicts PSR-12 on several axes: tabs instead of 4 spaces, spaces inside parentheses, Yoda conditionals, uppercase magic methods (__CONSTRUCT()), and 4-space indent values in the docs' override example. Pint is an opinionated PHP-CS-Fixer wrapper — the two tools will rewrite each other's output forever. Pick one per repo, and if you pick this one, remove Pint from the pipeline rather than debugging alternating diffs.

MagicMethods requiring uppercase __CONSTRUCT is the sniff most likely to surprise you. It is not a typo in the docs and it will look wrong to every PHP developer who reviews the diff. Either accept it, or exclude that sniff on day one; don't let it be the reason the team abandons the standard.

TypeDeclaration silently skips Laravel models. It auto-excludes property type checks for classes in Models directories. That's intentional (typed properties break Eloquent's magic attribute handling), but it means your models are less protected than the rest of the codebase — don't assume green CI means models are typed.

The naming convention sniff mixes scopes. It documents "table columns: snake_case" but the example shows $db_column = 'value'; inside a method — i.e. some variable names are expected to be snake_case. Expect false positives on ordinary camelCase variables that happen to look DB-ish. If you hit these, -s gives you the sniff code, then exclude or override narrowly rather than disabling the whole NamingConventions sniff.

LineLength is disabled in the ruleset. No max line length is enforced out of the box. If you re-enable it, expect a large error count on any mature codebase — turn it on as a separate, later step.

Blade files are ambiguous territory. PHPCS treats *.blade.php as PHP (extension is php), so ControlStructures will demand alternative syntax (if ( $cond ) :) while PhpTags objects to PHP tags in Blade files. If the combination produces noise, the pragmatic move is --extensions=php plus an <exclude-pattern>*/resources/views/*</exclude-pattern> until you've decided how much of the view layer you want linted.

Tabs + alignment means files need two phpcbf passes. Indentation is rewritten to tabs first; the alignment sniff then re-spaces the = on the newly-tabbed lines. A single phpcbf run can leave diffs behind — always re-run and confirm phpcs is clean before committing, otherwise you'll commit a file your hook immediately rejects.

Debugging "standard not installed": check composer show artisanpack-ui/code-style, then ./vendor/bin/phpcs -i. If the standard is missing after a composer install in CI, you likely installed with --no-dev — dev-only packages aren't available, so the lint job needs a full install or an isolated tooling step.

Performance and memory: exclude vendor, node_modules, storage, and build output; on large repos use php -d memory_limit=512M vendor/bin/phpcs and --report=summary. Batch by directory if you're memory-constrained.

The docs' issue links point at GitLab while the repo is on GitHub, and the package has essentially no adoption (0 stars, 0 dependents). Practical consequence: don't expect community answers. For any behavior the docs don't explain, read the sniff source in vendor/artisanpack-ui/code-style/ — it's the only authoritative reference, and phpcs --generator=Markdown gives you the configurable surface without reading code.

Rollout strategy for existing projects: commit the phpcs.xml with the full standard, then immediately exclude the directories you can't fix this sprint, and add a ratchet — each PR removes one exclusion. Enforcing everything at once on a legacy codebase produces a 5,000-error report nobody reads and a hook everyone bypasses with --no-verify.

Code Style Laravel Package