Mo4 Coding Standard Laravel Package

Getting Started

Minimal Setup

1. Install via Composer (preferred):

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

2. Run PHPCS on a file:

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

3. Auto-fix violations (where possible):

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

First Use Case: Enforcing Use Statement Order

Run PHPCS on a file with unsorted use statements:

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

Fix automatically:

./vendor/bin/phpcbf --standard=MO4 app/Http/Controllers/

Key Commands

• Check a directory:

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

• Set as default standard (add to ~/.phpcs or project config):

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

• View available standards:

  ./vendor/bin/phpcs -i
  

Implementation Patterns

Workflow Integration

1. Pre-commit Hooks Use phpcs in a pre-commit hook to block violations:

   # .git/hooks/pre-commit
   #!/bin/sh
   ./vendor/bin/phpcs --standard=MO4 --warning-severity=3 --errors-on-warning $1
   

2. CI/CD Pipeline Add to Laravel’s GitHub Actions or GitLab CI:

   # .github/workflows/lint.yml
   - name: PHP CodeSniffer
     run: ./vendor/bin/phpcs --standard=MO4 --warning-severity=3 --errors-on-warning .
   

3. IDE Integration Configure PHPStorm to use MO4:

   • Settings > Languages & Frameworks > PHP > Code Sniffer:
     • Standard: MO4
     • Installed Paths: ./vendor/bin/phpcs

Common Patterns

• Alphabetical Use Statements: Configure sorting in ruleset.xml:

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

• Auto-fix Arrays: Use phpcbf for MO4.Arrays.ArrayDoubleArrowAlignment and MO4.Arrays.MultiLineArray.

• Property Documentation: Enforce multiline @var with:

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

Laravel-Specific Tips

1. Service Provider Files: Apply MO4 to app/Providers/ to enforce consistent use statements and array formatting.
2. Migrations: Run PHPCS on database/migrations/ to catch array alignment issues in factory methods.
3. Test Files: Use MO4 in tests/ to standardize test assertions and data providers.

Gotchas and Tips

Pitfalls

1. PHP 8.1+ Compatibility:

   • Requires PHPCS 4.0+ and PHP 8.1+ (since v11.0.0).
   • Downgrade if using older PHP versions (e.g., v10.x for PHP 7.4+).

2. Auto-fix Limitations:

   • MO4.Strings.VariableInDoubleQuotedString cannot auto-fix complex cases (e.g., $obj->prop).
   • Use phpcbf cautiously; review changes for edge cases.

3. Use Statement Sorting Quirks:

   • Trait use statements may not sort correctly (fixed in v11.0.2).
   • Case-insensitive sorting (string-case-insensitive) may group namespaces unexpectedly.

4. Property Access in Strings:

   • MO4.Strings.VariableInDoubleQuotedString fails on:

     echo "{$user->name}"; // Fails (property access)
     echo "{$arr['key']}"; // Fails (array access)
     

   • Workaround: Manually wrap or disable the rule for such cases.

5. Symfony CS Conflicts:

   • MO4 does not enforce:
     • Class docblocks (optional).
     • License headers (optional).
   • Override in ruleset.xml if needed:

     <rule ref="Symfony">
         <exclude name="Classes.ClassDocComment.Missing"/>
     </rule>
     

Debugging Tips

1. Verbose Output: Use --verbose to debug rule application:

   ./vendor/bin/phpcs --standard=MO4 --verbose app/Models/User.php
   

2. Ignore Specific Rules: Disable a rule in ruleset.xml:

   <rule ref="MO4.Arrays.MultiLineArray">
       <exclude name="app/Helpers/legacy.php"/>
   </rule>
   

3. Custom Ruleset: Extend MO4 in phpcs.xml:

   <config name="installed_paths" value="./vendor/mayflower/mo4-coding-standard"/>
   <config name="standard" value="MO4"/>
   <rule ref="MO4">
       <exclude name="MO4.WhiteSpace.MultipleEmptyLines"/>
   </rule>
   

Extension Points

1. Custom Sniffs: Add project-specific rules by extending the ruleset.xml:

   <rule ref="MO4">
       <config name="custom_sniffs_dir" value="./sniffs"/>
   </rule>
   

2. PHPCS Configuration: Override default PHPCS behavior in phpcs.xml:

   <config name="encoding" value="utf-8"/>
   <config name="tab_width" value="4"/>
   

3. Auto-fix Scripts: Create a custom script (bin/fix-mo4) to run phpcbf with MO4:

   #!/bin/bash
   ./vendor/bin/phpcbf --standard=MO4 --diff --report=full .
   

Performance

• Exclude Large Directories: Speed up checks by excluding vendor/, node_modules/, etc.:

  ./vendor/bin/phpcs --standard=MO4 --exclude=vendor,node_modules app/
  

• Parallel Processing: Use parallel-lint or pct for large codebases:

  composer require --dev dealerdirect/php-pct
  ./vendor/bin/pct --standard=MO4