Codestyle Laravel Package

Getting Started

blumilksoftware/codestyle is a dev-only preset package: it ships a curated ruleset (PHP-CS-Fixer style, possibly alongside PHPStan config) for Blumilk's internal projects. It has no runtime footprint in your Laravel app, so adopting it is low-risk — you're only adding a dev dependency and a config file.

Minimal steps:

composer require --dev blumilksoftware/codestyle

Then inspect what you actually got before writing config — this package is small and internally focused, so the README may be terse:

ls vendor/blumilksoftware/codestyle
cat vendor/blumilksoftware/codestyle/README.md
# look for: src/, config/, .php-cs-fixer.dist.php, composer.json "extra"

Create .php-cs-fixer.php in your project root, requiring the package's preset and pointing it at your source tree:

<?php

require_once __DIR__ . '/vendor/autoload.php';

$config = new Blumilk\Codestyle\Config(); // class name per vendor README/src

$config
    ->setFinder(
        PhpCsFixer\Finder::create()
            ->in(__DIR__ . '/app')
            ->in(__DIR__ . '/tests')
            ->in(__DIR__ . '/database')
    );

return $config;

Wire up Composer scripts so the whole team uses the same invocation:

"scripts": {
    "cs": "php-cs-fixer fix",
    "cs:check": "php-cs-fixer fix --dry-run --diff"
}

First real use case: run composer cs across a fresh or existing Laravel app as its own isolated commit/PR, then enable composer cs:check in CI. Do not mix the formatting sweep with feature work — the diff will be unreviewable otherwise.

Implementation Patterns

Baseline-then-gate. The canonical rollout is two PRs: (1) apply the preset everywhere and merge with no review of individual hunks, (2) add a CI step that fails on --dry-run --diff. After that, style never appears in review comments again.

Layer, never edit vendor. Treat the preset as a base class and add project-specific rules on top in .php-cs-fixer.php:

$config->setRules(array_merge(
    $config->getRules(),
    ['declare_strict_types' => false] // e.g. opt out of a rule you can't adopt yet
));

Later calls to setRules override earlier ones; always merge your overrides after the package config is constructed.

CI integration (GitHub Actions):

- uses: actions/checkout@v4
- uses: shivammathur/setup-php@v2
  with:
    php-version: '8.3'
    tools: php-cs-fixer
- run: composer cs:check

Keep php-cs-fixer installed via Composer (or composer global) pinned to the same major the preset was written against — fixer rule names and behavior shift across majors.

Pre-commit guard. Pair the CI gate with a fast local hook so developers fix before pushing. CaptainHook or a simple pre-commit running composer cs -- --dirty (PHP-CS-Fixer supports fixing only changed files) keeps feedback in seconds.

Editor format-on-save. Point the PHP CS Fixer extension at your root .php-cs-fixer.php. This makes the CI failure mode rare rather than routine.

Legacy / partial adoption. If you can't reformat everything at once, scope the Finder per directory and progressively widen it. Laravel's default storage/, bootstrap/cache/, and vendor/ are outside your finder anyway if you enumerate directories explicitly — prefer explicit ->in() over ->in(__DIR__)->exclude(...), it's harder to get wrong.

Sibling static analysis. If the package also ships a PHPStan/Larastan config, mirror the same layering pattern: require the base phpstan.neon, include it, then append your paths and ignoreErrors. Run it as a second CI job so style and type failures report independently.

Gotchas and Tips

• It's an internal-first package (13 stars). There is no large community to surface breakages. Pin a minor version ("blumilksoftware/codestyle": "~1.2" or a specific tag) and read the diff on every bump.
• Don't run Pint and this together. Laravel Pint is a competing fixer with its own preset. Having both in composer.json (and both in CI or editor-on-save) produces flip-flopping diffs. Pick one and remove the other.
• Risky rules change behavior, not just whitespace. Fixers like declare_strict_types, strict_comparison, void_return, or no_unneeded_final_method can break tests or subtle runtime semantics. Run composer cs with the full test suite immediately afterward the first few times.
• Fixer ordering matters. PHP-CS-Fixer sorts by priority internally, but your array_merge overrides can unintentionally re-enable a fixer the preset disabled for a reason. Cross-check with php-cs-fixer describe <rule>.
• Debug one file, verbosely:

  vendor/bin/php-cs-fixer fix app/Models/User.php --diff --verbose --using-cache=no
  vendor/bin/php-cs-fixer list-files   # confirm your Finder matches what you think
  

  --using-cache=no is the fastest way to rule out a stale .php-cs-fixer.cache when a rule "isn't applying."
• Cache file in .gitignore. .php-cs-fixer.cache should never be committed; it causes confusing CI behavior across PHP versions.
• Pin the PHP platform. If CI runs 8.2 and a developer is on 8.4, fixers gated on target PHP version produce different output. Set "config": { "platform": { "php": "8.3" } } in composer.json.
• Exclusions that bite: migration files (historical — reformatting them rewrites checksums in some workflows), resources/views/*.blade.php (not plain PHP), and any generated code (ide_helper.php, _ide_helper_models.php, *.generated.php).
• Line endings. If your repo is CRLF (Windows contributors), the line_ending fixer will create churn on every run unless .gitattributes / .editorconfig normalize to LF first.
• Extension points: the preset class is your seam. Subclass it, or register custom fixers with $config->registerCustomFixers([...]) for anything genuinely house-specific. Keep such customizations in your app repo, not in a fork of the package — forking a 13-star internal package is a maintenance trap.
• If it ships PHP_CodeSniffer instead of PHP-CS-Fixer, the same principles apply but the invocation differs (vendor/bin/phpcs --standard=vendor/blumilksoftware/codestyle/...), and there's no --diff --dry-run autofix loop — you'd pair it with phpcbf. Confirm which toolchain the preset targets from its composer.json require block before writing scripts.
• No lockfile-level guarantee. Because the package is thin, the real risk isn't the preset itself — it's version skew between PHP-CS-Fixer, PHP, and the ruleset. Bump all three together and let CI prove it.