Coding Standard Laravel Package

Getting Started

Install the package with Composer in your Laravel project’s dev dependencies:

composer require --dev idiosyncratic/coding-standard

Verify PHPCS detects the standard by running vendor/bin/phpcs -i — you should see Idiosyncratic listed. Run the first lint against your codebase:

vendor/bin/phpcs --standard=Idiosyncratic src/

Start with src/ and later extend to tests/. No extra config needed out of the box—it inherits Doctrine Coding Standard rules and applies the two documented deviations.

Implementation Patterns

• Zero-Config Adoption: Use the package as-is for day-to-day linting. Since dealerdirect/phpcodesniffer-composer-installer auto-registers it, no ruleset.xml is required initially.
• CI Automation: Add Composer scripts to composer.json:

  "scripts": {
    "cs:check": "phpcs --standard=Idiosyncratic src/ tests/",
    "cs:fix": "phpcbf --standard=Idiosyncratic src/ tests/"
  }
  

  Run composer cs:check in CI (e.g., GitHub Actions, GitLab CI) before merges.
• IDE Integration: Configure your editor to use vendor/bin/phpcs and set the default standard to Idiosyncratic. PHPStorm and VSCode (with PHP Intelephense or PHPCS extension) support this via CLI config or workspace settings.
• Customizing Rules: Create phpcs.xml.dist at project root to adjust inherited sniffs. Example for fine-grained control:

  <?xml version="1.0"?>
  <ruleset name="LaravelIdiosyncratic">
    <rule ref="Idiosyncratic">
      <!-- Example: explicitly disable magic property documentation warning (if added later) -->
      <exclude name="Idiosyncratic.Commenting.PublicReadonly"/>
    </rule>
    <file>src/</file>
    <file>tests/</file>
    <arg name="extensions" value="php"/>
  </ruleset>
  

• Magic Property Convention: Document intended public-read-only properties with @public-read-only:

  /**
   * @public-read-only
   */
  private array $cache = [];
  
  public function __get(string $name): mixed
  {
      return $this->cache[$name] ?? null;
  }
  

  This communicates intent clearly to teammates—even if not yet enforced by a sniff.

Gotchas and Tips

• PHP 8.4 Requirement is Critical: The package declares php: ^8.4, which is not yet released as of 2024. You cannot install or run this on any stable PHP (8.1–8.3). Verify this is a typo or placeholder. If intentional, delay adoption until PHP 8.4 RC/stable releases and your toolchain supports it.
• Equals Sign Alignment is Permissive, Not Enforced: The Generic.Formatting.MultipleStatementAlignment.NotSame sniff is excluded, meaning misaligned = signs won’t trigger PHPCS errors—but PHPCS won’t auto-fix or warn about inconsistency either. Be consistent manually or use phpcbf with a different standard for alignment fixes.
• No New Sniffs Yet—Documentation-Driven Only: Beyond Doctrine’s rules, the only “custom” behavior is the @public-read-only convention (not a sniff). Don’t expect automated validation of magic property usage yet.
• Debug Sniff Runs with -v and -s: Use phpcs -v --standard=Idiosyncratic src/ to see loaded sniffs, and phpcs -s to see exact rule names for exclusions in phpcs.xml.
• Zero Dependents ≠ Zero Risk: While built on stable foundations (Doctrine CS v14+), this has no ecosystem adoption. Track the changelog for PHPCS compatibility bumps or breaking rule changes. Consider pinning versions.
• Avoid Mixing with Laravel’s Pint: Don’t try to layer Pint + PHPCS without clear separation. Choose one standardization tool per project. If using this, skip Pint and standardize around PHPCS alone.