Code Style Laravel Package

Technical Evaluation

What the package actually is. artisanpack-ui/code-style is not a library or framework integration — it is a ruleset artifact: a Composer dev dependency that registers a PHP_CodeSniffer standard named ArtisanPackUIStandard, composed of ~16 custom sniffs plus an inherited base. From a TPM perspective this places it in the developer tooling / quality gate category, not the application runtime category. That has three consequences worth stating up front:

1. Blast radius is contained to CI and developer machines. It ships no runtime code, no service provider, no migrations. Removing it is a one-line Composer change. This is the single strongest argument for a low-risk pilot.
2. Value is entirely derived from enforcement. The package has no intrinsic utility; it only pays back if phpcs runs in CI and/or pre-commit and the team acts on the output. Adoption is therefore a process investment, not a dependency investment.
3. The opinions are the product. Unlike a utility package where you consume an API, here you consume a set of judgments (tabs, spaces inside parentheses, Yoda conditionals, uppercase magic methods, mandatory type declarations). Accepting the package means accepting someone else's judgement as your team's default — and several of those judgments conflict with PSR-12 and with the Laravel ecosystem's de facto standard, Laravel Pint.

Architecture fit. Good on mechanics, contentious on policy.

• Mechanically, it fits any Composer/PHP 8.2+ project. PHP_CodeSniffer is the right tool for this job specifically because it can tokenise and lint PHP embedded in Blade templates — something PHP-CS-Fixer/Pint handles far less gracefully. The README's dedicated Blade ControlStructures sniff (alternative syntax if : endif; in templates, braces elsewhere) and the PhpTags rule (no PHP tags in Blade) are genuinely useful and are the kind of thing a generic formatter will not give you. If Blade-heavy code review friction is a real pain point for us, this is the strongest technical justification for choosing PHPCS-over-Pint, and this package is a ready-made starting point.
• Politically, the standard diverges from what most PHP developers and most AI coding assistants produce by default. Notable conflict points: space inside parentheses if ( $x ) { (violates PSR-12 and Laravel conventions); tabs for indentation (PSR-12 mandates 4 spaces); Yoda conditionals (widely regarded as hostile to readability and actively discouraged in many style guides); uppercase magic methods __CONSTRUCT() (legal — PHP magic methods are case-insensitive — but surprising, and likely to trip IDEs, static analysers, and reviewers); mandatory type declarations across all functions and properties. The TypeDeclaration sniff does carve out an exception for Laravel Models (property types break Eloquent's magic attribute handling), which shows the author understands Laravel — but that carve-out is a signal that more exceptions will be needed (facades, macros, Blade components, form requests, closures in config files, migrations).

Integration feasibility. Technically trivial, organisationally non-trivial.

• Install is a single composer require --dev, one phpcs.xml, one CLI invocation. Any engineer can have it running in ten minutes.
• The real work is remediation volume. Introducing any new standard to an existing Laravel codebase produces findings in the thousands, dominated by two sniffs: Indentation (if we are a spaces shop, every line of every file is a violation) and Spacing (the parenthesis-space rule hits nearly every control structure). This is the crux of the go/no-go decision, and it must be measured before it is debated.
• PHPCS 3.x has no first-class baseline/suppression mechanism for pre-existing violations; PHPCS 4.x introduces one but the maturity is unproven. Our fallback is a committed phpcs.xml that starts by exclude-ing the sniffs we cannot afford to retrofit, then ratchets them on per-directory. That is workable but requires ongoing ownership.

Technical risk. Rated low-to-moderate, and almost entirely supply-chain and governance risk rather than engineering risk.

• Supply chain / bus factor (highest risk). 0 stars, 0 dependents, no evident community. The README points to GitLab for issues while the repository link is GitHub — a documentation inconsistency that suggests the project is maintained informally, possibly single-maintainer. A style standard is a low-stakes thing to depend on, but it is also a policy dependency: if the maintainer disappears, we cannot get a bug fixed in a sniff that is blocking our CI.
• Mitigation is unusually cheap. MIT licence, and the entire artifact is a directory of sniff classes and an XML ruleset. If the project stalls, forking in-house is a days-not-weeks exercise. This substantially defuses the bus-factor risk — but only if we consciously decide "we can fork" now, rather than discovering the need during a blocked release.
• Version-drift risk (underrated). The ruleset is the package. Any upstream release can add or tighten a sniff and turn a green build red on code nobody touched. The listed last release (2026-08-18) is unusually recent relative to a 0-star, 0-dependent project, which raises a question about release discipline and semver hygiene rather than answering it. We must pin an exact version and treat rule changes as a deliberate, reviewed upgrade.
• False confidence in the "security" sniffs. The README advertises security sniffs for input validation and output escaping. PHPCS sniffs are pattern-matchers over a token stream; they cannot do taint analysis. If this package gets adopted and someone concludes "we have security linting", we have created a real risk by displacing the conversation about SAST/Psalm taint analysis or a proper scanner. Must be positioned explicitly as style, not security assurance.
• PHP 8.2 minimum excludes any legacy application we still run, and is a hard constraint on where this can be deployed.

Key questions to resolve before commitment.

1. What is the measured violation count on one representative repo under the full standard, broken down by sniff? Without this, every subsequent discussion is speculation. (One engineer, half a day, --report=summary plus a per-sniff tally.)
2. Which sniffs do we actually want? Is our goal consistency, or specifically the Blade-template rules and naming/enforcement we cannot get from Pint? The answer determines whether we adopt the standard whole, adopt a subset, or fork a trimmed ruleset.
3. Is this part of a broader ArtisanPack-UI commitment? If other ArtisanPack packages are in the estate, this ruleset is a coherence play and gets strategic weight. If it stands alone, it is a stylistic preference with a dependency attached — a much weaker case.
4. Who is the maintainer, what is the release cadence and issue-response record, and which tracker is authoritative? Check the GitLab issue history, not just the GitHub repo.
5. PHPCS version support — does composer.json constrain PHP_CodeSniffer to ^3 or ^4? This determines whether we can use a baseline and whether a future PHPCS major breaks us.
6. Do we standardise on Pint or PHPCS as the single formatter/linter? Running both is a known source of contradictory auto-fixes and developer confusion. This is a one-way-door architectural decision and should be made explicitly, not by accretion.
7. Will TypeDeclaration survive contact with our framework code beyond Models — facades, macros, Blade components, service providers, config closures? Expect to need additional exclusions.

Integration Approach

Stack fit. Composer-native, dev-only, zero runtime footprint — fits any Laravel 10/11/12 or standalone PHP 8.2+ project. It sits alongside, not inside, the application. The only genuine differentiation versus the ecosystem default (Laravel Pint) is Blade-aware sniffing and custom organisational rules; on pure PHP formatting, Pint is more idiomatic, faster, and first-party. Frame the decision as: "Do we need Blade-template enforcement and custom naming rules badly enough to run PHPCS as well as, or instead of, Pint?"

Make the formatter decision first. Three viable end states, in ascending order of cost:

• A — Pint only (status quo default). Cheapest, most idiomatic, no Blade-template enforcement. Reject the package.
• B — Pint for formatting + a trimmed PHPCS ruleset for the rules Pint can't express. Recommended if Blade friction is real. We reference ArtisanPackUIStandard but exclude Indentation, Spacing, YodaConditionals, and MagicMethods so PHP-CS-Fixer and PHPCS do not fight over the same tokens, keeping ControlStructures, PhpTags, ImportOrdering, ClassStructure, DisallowedFunctions, and NamingConventions. This captures most of the differentiated value at a fraction of the remediation cost.
• C — Full ArtisanPackUIStandard as the single authority. Highest coherence, highest cost, requires accepting tab indentation and Yoda conditionals org-wide. Only defensible for a greenfield project with a team that has already bought in.

Migration path. Treat this as a ratchet, never a big bang.

1. Audit (½–1 day). Install on a branch, run against one representative repo, capture per-sniff violation counts and a sample of the top offenders. Produce the actual number.
2. Baseline decision. With counts in hand, choose B or C. Draft phpcs.xml with explicit per-sniff exclusions and the rationale in a comment block — the config file becomes the record of the decision.
3. Warn-only CI. Add a non-blocking job for two to four weeks. Publish a weekly violation count so the trend is visible. This is the ramp-up period and the cheapest possible way to discover false positives.
4. New code first. Make the (trimmed) standard blocking on changed files only — incremental diff linting in the PR pipeline — so new code is clean from day one without a mass reformat.
5. Opportunistic remediation of old code. Apply auto-fixable rules via phpcbf in dedicated, isolated formatting-only commits (no functional changes, added to .git-blame-ignore-revs). Never mix a reformat with a feature branch.
6. Ratchet. Enable each excluded sniff per-directory as directories are cleaned, moving toward C only if the team asks for it.
7. Re-evaluate at quarter end. If the trimmed ruleset is not catching real defects or real review friction, drop the package — the exit cost is a single Composer removal.

Compatibility considerations.

• Pin the exact version ("artisanpack-ui/code-style": "1.x.y", not ^1.0). Ruleset content is the contract; float is drift.
• Indentation is the highest-friction fork in the road. If we are a 4-space shop, adopting Indentation reformats every file and creates merge conflicts across every open branch. Sequence it for a quiet period, or exclude it permanently and let Pint own whitespace.
• Blade handling requires care. Confirm --extensions=php behaviour against .blade.php files and verify the Blade sniffs do not false-positive on heavy @directive usage or inline Alpine/JS. This is the sniff-set most likely to crash or misfire and it is also the one we care most about — test it explicitly.
• IDE parity is a prerequisite, not a nice-to-have. Developers need the same findings in PHPStorm (PHPCS inspection pointed at vendor/bin/phpcs and the standard name) as in CI, or the gate feels arbitrary. Budget for a short setup guide and verify it during ramp-up.
• CI cost. PHPCS is single-threaded and slow on large trees. Use --cache, --report=summary for the always-on job, split by directory across parallel jobs if wall-clock matters, and keep the full report for nightly.

Sequencing recommendation. Pilot on one repo, warn-only, trimmed ruleset (option B), pinned version, four weeks, with a written exit criterion. Do not roll to the fleet until the violation-count trend and false-positive rate are known.

Operational Impact

Maintenance. Ongoing cost is low in absolute terms but concentrated in one place: the phpcs.xml file. That file, not the package, is the operational asset — it encodes which opinions we have adopted and why. Assign a named owner (a platform/tooling engineer or the tech lead on the pilot repo) and put phpcs.xml and the CI lint job under CODEOWNERS. Without a named owner, the ruleset silently rots: someone adds an exclude to unblock a PR and the standard quietly erodes. Budget roughly 1–2 days per quarter for sniff upgrades, false-positive triage, and exception requests.

Support. Three tiers to plan for:

• Internal. Expect a predictable first-month volume of "why is my code failing" questions, dominated by Spacing, Indentation, and YodaConditionals. A one-page internal cheat-sheet with correct/incorrect examples (the README's sniff reference is a good base, but write our own covering our exclusions) will absorb most of it.
• Upstream. 0 stars, 0 dependents, and a GitHub/GitLab tracker inconsistency mean upstream support should be assumed unavailable. Do not build a process that depends on someone else fixing a sniff. The correct posture: pin, work around with a local exclusion, and fork if it becomes a recurring blocker. Because the package is MIT and consists of a small set of sniff classes, in-house forking is a credible, pre-approved escape hatch — decide this in advance and name who would own the fork.
• Ecosystem. PHP_CodeSniffer itself is mature and well-supported; the risk is in the ruleset, not the runner.

Scaling. Scales fine on the dependency axis (dev-only, no runtime load, adding repos is one phpcs.xml each). It scales poorly on two axes:

• Wall-clock. PHPCS run time grows linearly with file count and is a known CI complaint on large monorepos. Mitigate with caching, directory-split parallel jobs, and scoping the blocking job to changed files. Do not let a 15-minute lint job sit in the critical path of every PR — that is how tooling gets disabled.
• Governance. Each new repo is another place the standard can drift. If we adopt, prefer a shared, versioned phpcs.xml.dist distributed to repos over per-repo hand-maintained copies, so the standard stays one thing rather than fifteen.

Failure modes to pre-plan.

Ramp-up. Plan for two to four weeks of warning-period operation before the gate becomes blocking, and roughly 3–8 engineer-days total for the pilot: ~1 day audit, ~1 day ruleset authoring and CI wiring, ~1 day IDE setup guide and team comms, and the remainder for triage and iteration. Fleet rollout is dominated by remediation effort, not integration effort, and its size is knowable only after the audit step. A fully greenfield project can compress this to 2–3 days.

Bottom line for the decision record. The integration is cheap and the exit is cheap, which argues for piloting rather than debating. The package's genuine, defensible value is Blade-aware enforcement plus custom naming/structure rules that Pint cannot express; its weakest aspects are opinionated formatting choices that collide with the ecosystem and a near-zero community footprint. Recommend option B — trimmed ruleset, warn-only pilot, pinned version, named owner, pre-agreed fork escape hatch — and gate fleet rollout on the measured violation trend. If the audit shows the differentiated sniffs catch little real review friction, reject cleanly and stay on Pint; the sunk cost is a few days.