Mo4 Coding Standard Laravel Package

Getting Started

Minimal Setup

1. Install via Composer (preferred):

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

2. Verify Installation:

   ./vendor/bin/phpcs -i  # Check if MO4 appears in installed standards
   

3. First Run:

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

   • Use --diff to preview changes before fixing:

     ./vendor/bin/phpcbf --standard=MO4 --diff app/Models/User.php
     

Key Commands

First Use Case: Onboarding

• New Developer Setup:

  composer require --dev mayflower/mo4-coding-standard
  ./vendor/bin/phpcs --standard=MO4 app/
  

• CI/CD Integration (e.g., GitHub Actions):

  - name: Run MO4 Coding Standard
    run: ./vendor/bin/phpcs --standard=MO4 --warning-severity=3 app/
  

Implementation Patterns

Workflow Integration

1. Pre-Commit Hooks (using husky or pre-commit):

   # .git/hooks/pre-commit
   #!/bin/sh
   ./vendor/bin/phpcs --standard=MO4 --colors --report=emacs app/ || exit 1
   

2. IDE Integration (PHPStorm/VSCode):
   • Configure PHP_CodeSniffer plugin to use MO4 as the default standard.
   • Example VSCode settings.json:

     {
       "php-cs-fixer.executablePath": "./vendor/bin/phpcbf",
       "php-cs-fixer.rules": "@MO4"
     }
     

Common Patterns

<rule ref="MO4.Formatting.AlphabeticalUseStatements">
    <properties>
        <property name="order" value="string-locale"/>
    </properties>
</rule>
``` |
| **Array Alignment**              | Auto-fix with:
```bash
./vendor/bin/phpcbf --standard=MO4 --ruleset=MO4/ruleset.xml app/
``` |
| **Variable Interpolation**       | Replace `$var` with `{$var}` in strings:
```bash
./vendor/bin/phpcbf --standard=MO4 --ruleset=MO4/ruleset.xml app/
``` |

### Laravel-Specific Tips
1. **Service Provider Files**:
- Run MO4 on `app/Providers/` to enforce consistent `use` statements and array formatting.
- Example:
  ```bash
  ./vendor/bin/phpcs --standard=MO4 app/Providers/
  ```
2. **Migration Files**:
- Use `--ignore=*/database/migrations/*` to exclude migrations if needed:
  ```bash
  ./vendor/bin/phpcs --standard=MO4 --ignore=*/database/migrations/* app/
  ```
3. **Custom Rulesets**:
- Extend `MO4/ruleset.xml` to disable specific rules (e.g., `MO4.WhiteSpace.MultipleEmptyLines`):
  ```xml
  <rule ref="MO4.WhiteSpace.MultipleEmptyLines">
      <severity>0</severity>
  </rule>
  ```

---

## Gotchas and Tips
### Common Pitfalls
| Issue                                  | Solution                                                                 |
|----------------------------------------|--------------------------------------------------------------------------|
| **`phpcs` not detecting MO4**         | Run `./vendor/bin/phpcs --config-set installed_paths vendor/mayflower/mo4-coding-standard` or update `~/.phpcs.dist`:
```ini
installed_paths = vendor/mayflower/mo4-coding-standard
``` |
| **Auto-fix fails on arrays**          | Use `--ruleset=MO4/ruleset.xml` explicitly:
```bash
./vendor/bin/phpcbf --standard=MO4 --ruleset=MO4/ruleset.xml app/
``` |
| **Trait `use` statements mis-sorted** | Update to `v11.0.2+` (fixes [#235](https://github.com/mayflower/mo4-coding-standard/issues/235)). |
| **Variable interpolation errors**     | Ensure `{$var}` is used (not `$var`) in double-quoted strings. Auto-fix with `phpcbf`. |
| **PHP 8.1+ attributes misaligned**   | MO4 enforces `SlevomatCodingStandard.Attributes.AttributesOrder`. Use:
```bash
./vendor/bin/phpcbf --standard=MO4 --ruleset=MO4/ruleset.xml app/
``` |

### Debugging Tips
1. **Verbose Output**:
```bash
./vendor/bin/phpcs --standard=MO4 --verbose app/Models/User.php

2. Rule-Specific Checks:
   • Isolate a rule (e.g., AlphabeticalUseStatements):

     ./vendor/bin/phpcs --standard=MO4 --rules=MO4.Formatting.AlphabeticalUseStatements app/
     

3. Ignore Specific Files:

   ./vendor/bin/phpcs --standard=MO4 --ignore=*/tests/* app/
   

Extension Points

1. Custom Rulesets:
   • Override MO4/ruleset.xml in your project root to disable/enable rules.
   • Example: Disable MultipleEmptyLines:

     <rule ref="MO4.WhiteSpace.MultipleEmptyLines">
         <severity>0</severity>
     </rule>
     

2. PHPCS Configuration:
   • Store global settings in ~/.phpcs.dist:

     [MO4]
     encoding = utf-8
     tab_width = 4
     

3. CI-Specific Configs:
   • Use --warning-severity=3 to treat warnings as errors in CI:

     ./vendor/bin/phpcs --standard=MO4 --warning-severity=3 app/
     

Pro Tips

• Leverage phpcbf for 80% of Fixes:

  ./vendor/bin/phpcbf --standard=MO4 --diff app/  # Preview changes
  ./vendor/bin/phpcbf --standard=MO4 app/         # Apply fixes
  

• Exclude Vendors:

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

• PHP 8.1+ Support:
  • Ensure your project uses PHP 8.1+ (MO4 drops support for older versions).
  • Check for SlevomatCodingStandard.Attributes.* rules in new code.

Anti-Patterns to Avoid

1. Manual Overrides:
   • Avoid manually fixing MO4 violations (e.g., aligning arrays) to prevent drift.
2. Ignoring Warnings:
   • Treat warnings as errors in CI to catch subtle issues early.
3. Outdated PHPCS:
   • MO4 requires PHPCS 4.0+. Update with:

     composer require --dev squizlabs/php_codesniffer:^4.0