Php Cs Fixer Config Laravel Package

Getting Started

Install via Composer:

composer require --dev mll-lab/php-cs-fixer-config

Then create a .php-cs-fixer.php file in your project root that extends the provided config:

<?php

return MllLab\PHPCSFixerConfig\Config::create();

Run the fixer locally to apply standards:

./vendor/bin/php-cs-fixer fix

This gives you immediate, consistent formatting with zero configuration—ideal for bootstrapping a new Laravel project or cleaning up legacy code. The new LineBreakBeforeThrowExpressionFixer ensures consistent line breaks before throw expressions, improving readability in exception handling.

Implementation Patterns

• Baseline Integration: Use as-is for strict adherence or as a foundation in monorepos (e.g., Symfony Flex, Laravel Monorepo patterns).
• CI Integration: Call ./vendor/bin/php-cs-fixer fix --dry-run --diff in your GitHub Actions/GitLab CI pipeline to fail builds on style violations.
• Pre-commit Hook: Wire into pre-commit (e.g., via husky + lint-staged) to auto-fix staged PHP files:

  "lint-staged": {
    "*.php": "php-cs-fixer fix"
  }
  

• Laravel-Specific Overrides: Extend the config to tweak Laravel conventions (e.g., enforce phpdoc_return_self_type for Eloquent methods). The new LineBreakBeforeThrowExpressionFixer can be leveraged to standardize exception handling in Laravel's exception handlers or middleware.
• Version Pinning: Lock to a specific config version in composer.json to prevent breaking changes from upstream rule updates.
• Exception Handling: Use the new rule to enforce consistent formatting in custom exception classes or handle() methods in Laravel middleware.

Gotchas and Tips

• Rule Conflicts: The config prioritizes PSR-12 + stricter opinions (e.g., blank_line_after_opening_tag, no_unused_imports). If your codebase uses older patterns (e.g., short_open_tag), expect many auto-fixes on first run. The new LineBreakBeforeThrowExpressionFixer may introduce changes in exception-heavy files.
• PHP Version Limitations: Ensure your project’s PHP version matches the config’s target—some rules (e.g., typed_collection) require PHP 8.0+. Check Config::MIN_PHP_VERSION.
• Extend Strategically: Override rules only in your .php-cs-fixer.php, e.g.:

  return MllLab\PHPCSFixerConfig\Config::create()
    ->setRiskyAllowed(true)
    ->setRules([
      'phpdoc_var_annotation_correct_order' => false,
      'line_break_before_throw_expression' => true, // Explicitly enable the new rule
    ]);
  

• Debugging: Run with --using-cache=no --verbose to trace rule behavior. Cache files can stale on config changes.
• VS Code Integration: Enable "editor.formatOnSave": true with the PHP Intelephense extension and php-cs-fixer binary path for IDE-level auto-formatting.
• Risky Rules: This config enables risky rules by default (e.g., no_superfluous_elseif, no_unset_cast). Always review first-run diffs carefully.
• New Rule Behavior: The LineBreakBeforeThrowExpressionFixer will enforce a line break before throw expressions. If your codebase lacks this, expect changes in exception-heavy files (e.g., App\Exceptions\Handler.php). Test with --dry-run first.