Standards Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require --dev graze/standards
   

   Add to your project's phpcs.xml or phpcs.xml.dist:

   <config name="installed_paths" value="./vendor/graze/standards"/>
   

2. First Run:

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

   Verify compliance with Graze’s PHP standards (e.g., abstract class naming, negation spacing).

3. Quick Check: Use the -s flag for snippet-style output:

   vendor/bin/phpcs -s --standard=Graze app/Http/Controllers/
   

First Use Case

• Onboarding: Run phpcs on a new PR to catch formatting/naming violations early.
• Code Review: Use as a reference for consistent style (e.g., "Why is this abstract class named Foo?" → "Graze requires AbstractFoo").

Implementation Patterns

Workflows

1. Pre-Commit Hook: Integrate with phpcs via a hook (e.g., using php-cs-fixer or a custom script):

   # Example: Fail build if violations exist
   vendor/bin/phpcs --standard=Graze --warning-severity=0 src/ || exit 1
   

2. CI Pipeline: Add to Laravel’s GitHub Actions (.github/workflows/lint.yml):

   - name: PHP Coding Standards
     run: vendor/bin/phpcs --standard=Graze --warning-severity=0 src/
   

3. IDE Integration:

   • PHPStorm: Configure phpcs as an external tool (Settings → Tools → External Tools).
   • VSCode: Use the PHP Intelephense extension with phpcs integration.

Laravel-Specific Patterns

• Abstract Classes: Enforce Abstract prefix (e.g., AbstractUserRepository) via the Graze.Naming.AbstractClassNaming sniff.

  // ✅ Valid
  abstract class AbstractUserRepository { ... }
  
  // ❌ Invalid (will trigger sniff)
  abstract class UserRepository { ... }
  

• Negation Operators: Avoid spaces after ! (e.g., $isValid = !$input->valid() instead of $isValid = ! $input->valid()).

• DocBlocks: Ensure child functions in anonymous functions have docblocks:

  $callback = function() {
      /** @return string */
      function inner() { return 'ok'; }
  };
  

Extending Rules

1. Custom Rulesets: Override Graze’s rules in phpcs.xml:

   <rule ref="Graze">
       <exclude name="Graze.ControlStructures.NegationNoSpaces"/>
   </rule>
   

2. Add New Sniffs: Extend Graze\Sniffs\BaseSniff and register in Graze\Sniffs\Register.php.

Gotchas and Tips

Pitfalls

1. Sniff Naming:

   • Issue: Older versions (<2.0.4) showed incorrect sniff names (e.g., graze.controlStructures.NegationNoSpaces).
   • Fix: Update phpcs and use the fully namespaced format (Graze.ControlStructures.NegationNoSpaces).

2. Abstract Class Crashes:

   • Issue: Empty abstract classes (e.g., class Foo {}) could crash the AbstractClassNaming sniff (<2.0.2).
   • Fix: Update to v2.0.2+ or avoid empty abstract classes.

3. DocBlock Parsing:

   • Issue: Nested anonymous functions without docblocks may fail (<2.0.1).
   • Fix: Add docblocks to all child functions, even in anonymous contexts.

4. Line Endings:

   • Gotcha: Mixing CRLF/LF can cause phpcs to flag "trailing whitespace" falsely.
   • Fix: Normalize line endings with:

     dos2unix src/
     

Debugging

• Verbose Output: Use --verbose to debug sniff failures:

  vendor/bin/phpcs --standard=Graze --verbose app/Models/
  

• Isolate Sniffs: Test individual sniffs with --sniffs:

  vendor/bin/phpcs --standard=Graze --sniffs=Graze.Naming src/
  

Tips

1. Partial Compliance: Use --ignore to bypass specific rules temporarily:

   vendor/bin/phpcs --standard=Graze --ignore=Graze.ControlStructures.NegationNoSpaces app/
   

2. Autofix: Combine with php-cs-fixer for automatic fixes:

   vendor/bin/php-cs-fixer fix --rules=@Graze --dry-run
   

3. Documentation:

   • Preview local docs with:

     make docs-test  # Starts MkDocs on port 8000
     

   • Key sections: PHP Standards, Git Conventions.

4. Laravel-Specific:

   • Service Providers: Prefix with Abstract (e.g., AbstractMailServiceProvider).
   • Migrations: Use snake_case for table/column names (covered in SQL docs).

5. Performance: Cache phpcs results for large codebases:

   vendor/bin/phpcs --standard=Graze --cache-file=.phpcs.cache src/