Mo4 Coding Standard Laravel Package

Getting Started

Minimal Setup

1. Install via Composer (recommended):

   composer require --dev mayflower/mo4-coding-standard
   

2. Run PHPCS with MO4 standard:

   ./vendor/bin/phpcs --standard=MO4 src/
   

3. Set as default (optional):

   ./vendor/bin/phpcs --config-set default_standard MO4
   

First Use Case

• Quick linting: Run on a single file to identify violations:

  ./vendor/bin/phpcs --standard=MO4 app/Http/Controllers/UserController.php
  

• Auto-fix common issues (e.g., array alignment, use statements):

  ./vendor/bin/phpcbf --standard=MO4 src/
  

Key Files to Reference

• Ruleset XML: MO4/ruleset.xml – Lists all enabled/disabled rules with comments.
• Configuration: Override defaults in .phpcs.xml or phpcs.xml.dist (see Symfony PHPCS docs).

Implementation Patterns

Workflow Integration

1. Pre-commit Hook: Use phpcs in a Git hook to enforce standards before commits:

   ./vendor/bin/phpcs --standard=MO4 --warning-severity=5 src/ || git status --porcelain
   

   (Exit code 1 if violations exist, 0 if clean.)

2. CI Pipeline: Add to Laravel’s .github/workflows/php.yml:

   - name: Run PHPCS
     run: ./vendor/bin/phpcs --standard=MO4 --warning-severity=5 --error-severity=5 src/
   

3. IDE Integration:

   • PHPStorm: Configure phpcs in Settings > Languages & Frameworks > PHP > Code Sniffer.
   • VSCode: Use the PHP Intelephense extension with PHPCS path.

Common Patterns

• Use Statement Sorting: Configure alphabetical order in .phpcs.xml:

  <rule ref="MO4.Formatting.AlphabeticalUseStatements">
      <properties>
          <property name="order" value="string-locale"/>
      </properties>
  </rule>
  

  (Default: dictionary; options: string, string-locale, string-case-insensitive.)

• Array Formatting: Auto-fix alignment with phpcbf:

  ./vendor/bin/phpcbf --standard=MO4 --ruleset=MO4/ruleset.xml src/
  

  (Targets MO4.Arrays.ArrayDoubleArrowAlignment and MO4.Arrays.MultiLineArray.)

• Property Documentation: Enforce @var in multiline docblocks:

  /**
   * @var string
   */
  private $name;
  

Laravel-Specific Tips

• Service Provider Classes: Apply MO4 to app/Providers/ to standardize:

  ./vendor/bin/phpcs --standard=MO4 app/Providers/
  

• Migrations/Seeders: Exclude from strict checks (add to .phpcs.xml):

  <exclude-pattern>database/migrations/*.php</exclude-pattern>
  

Gotchas and Tips

Pitfalls

1. PHP Version Mismatch:

   • Error: PHPCS 4.0+ required (since v11.0.0).
   • Fix: Update PHPCS:

     composer require --dev phpcs/phpcs:^4.0
     

2. Auto-fix Limitations:

   • phpcbf may fail on complex arrays or nested structures. Manually adjust or exclude problematic files:

     <exclude-pattern>app/ComplexArrayHandler.php</exclude-pattern>
     

3. Use Statement Conflicts:

   • Issue: Trait use statements may not sort correctly (fixed in v11.0.2).
   • Workaround: Temporarily disable the rule:

     <rule ref="MO4.Formatting.AlphabeticalUseStatements">
         <severity>0</severity>
     </rule>
     

4. Variable Interpolation:

   • Gotcha: VariableInDoubleQuotedString may flag array/property access (e.g., $obj->prop).
   • Fix: Update to v11.0.1+ or suppress:

     <rule ref="MO4.Strings.VariableInDoubleQuotedString">
         <properties>
             <property name="ignorePropertyAccess" value="true"/>
         </properties>
     </rule>
     

Debugging

• Verbose Output: Run with -v to debug rule application:

  ./vendor/bin/phpcs -v --standard=MO4 app/Http/Controllers/
  

• Rule-Specific Help: Check which rules apply to a file:

  ./vendor/bin/phpcs --standard=MO4 --report=summary app/Http/Controllers/UserController.php
  

Extension Points

1. Custom Ruleset: Extend MO4/ruleset.xml to disable/enable rules:

   <config name="installed_paths" value="vendor/mayflower/mo4-coding-standard/MO4"/>
   <rule ref="MO4.Arrays.ArrayDoubleArrowAlignment">
       <severity>5</severity> <!-- Treat as error -->
   </rule>
   

2. PHPCS Configuration: Override defaults in .phpcs.xml:

   <arg name="report" value="full" />
   <arg name="colors" value="false" />
   

3. Excluding Files: Use patterns to skip tests or generated files:

   <exclude-pattern>tests/*</exclude-pattern>
   <exclude-pattern>storage/*</exclude-pattern>
   

Performance Tips

• Cache Results: Use --cache to speed up repeated runs:

  ./vendor/bin/phpcs --standard=MO4 --cache=~/.phpcs_cache src/
  

• Parallel Processing: Leverage parallel for large codebases (requires PHPCS 4.0+):

  ./vendor/bin/phpcs --standard=MO4 --parallel=4 src/
  

Laravel-Specific Quirks

• Facade Usage: MO4 enforces use statements for imported classes (e.g., use Illuminate\Support\Facades\Log;). Avoid:

  // ❌ Violates MO4.Formatting.UnnecessaryNamespaceUsage
  Log::info('test');
  
  // ✅ Correct
  use Illuminate\Support\Facades\Log;
  Log::info('test');
  

• Dynamic Classes: Exclude dynamically generated classes (e.g., from make:model):

  <exclude-pattern>app/Models/Generated*.php</exclude-pattern>