Getting Started

Minimal Steps

Install the package in your Laravel project:

composer require --dev shipmonk/coding-standard

Create phpcs.xml.dist in your project root with the provided template:

<?xml version="1.0"?>
<ruleset>
    <arg name="basepath" value="."/>
    <arg name="cache" value="var/phpcs.cache"/>
    <file>src/</file>
    <file>tests/</file>
    <config name="installed_paths" value="vendor/slevomat/coding-standard,vendor/shipmonk/coding-standard"/>
    <rule ref="ShipMonkCodingStandard"/>
</ruleset>

Run PHPCS to check your code:
```
vendor/bin/phpcs
```
Auto-fix issues (where possible):
```
vendor/bin/phpcbf
```

First Use Case

Integrate into CI/CD Pipeline Add a GitHub Actions step to enforce coding standards pre-merge:

- name: Run PHPCS
  run: vendor/bin/phpcs --standard=ShipMonkCodingStandard --warning-severity=3

This ensures all PRs comply with ShipMonk’s standards before merging.

Implementation Patterns

Usage Patterns

Project-Wide Enforcement
- Apply the ruleset to all src/ and tests/ files by default (as configured in phpcs.xml.dist).
- Exclude specific directories if needed:
```
<exclude-pattern>*/Resources/*</exclude-pattern>
```

Pre-Commit Hooks Integrate with tools like Husky or Laravel Git to run PHPCS automatically:

composer require --dev laravel/git
laravel git:hook pre-commit

Add a script to package.json:

"scripts": {
  "lint": "vendor/bin/phpcs --standard=ShipMonkCodingStandard --warning-severity=3"
}

Custom Rule Overrides Override specific rules in phpcs.xml.dist:

<rule ref="ShipMonkCodingStandard">
    <exclude name="SlevomatCodingStandard.TypeHints.DisallowMixedTypeHint"/>
</rule>

PHPStan Integration Combine with PHPStan for static analysis:

composer require --dev phpstan/phpstan
vendor/bin/phpstan analyse --level=max
vendor/bin/phpcs

Laravel-Specific Workarounds
- Facade Imports: Disable UseStatementOrder for Laravel Facades:
```
<rule ref="SlevomatCodingStandard.Classes.UseStatement">
    <exclude name="UseStatementOrder"/>
</rule>
```
- Exception Handling: Temporarily exclude middleware files from CatchExceptionsOrder:
```
<exclude-pattern>app/Http/Middleware/*</exclude-pattern>
```

Workflows

Daily Development
- Run PHPCS before committing:
```
composer lint
```
- Use phpcbf to auto-fix non-breaking issues:
```
vendor/bin/phpcbf --standard=ShipMonkCodingStandard
```
Code Reviews
- Flag PHPCS violations in PRs with a GitHub Actions badge or comment.
- Example: Use phpcs in a workflow to post comments via github-script.

Onboarding New Developers

Include a CONTRIBUTING.md section with:

## Coding Standards
Run `composer lint` to check your code against ShipMonk’s standards.
Use `composer fix` to auto-correct common issues.

Legacy Code Migration
- Gradually enforce standards by excluding directories initially:
```
<exclude-pattern>*/Legacy/*</exclude-pattern>
```
- Re-enable rules incrementally as legacy code is refactored.

Integration Tips

Cache Performance: Enable PHPCS caching (var/phpcs.cache) to speed up repeated runs.

Parallel Testing: Combine with php-parallel-lint for faster linting in large codebases:

composer require --dev php-parallel-lint/php-parallel-lint
vendor/bin/parallel-lint src/ tests/

IDE Integration: Configure your IDE (PHPStorm, VSCode) to use PHPCS for real-time feedback:
- PHPStorm: Enable "Inspections by PHPCS" in Settings > PHP > Quality Tools.
- VSCode: Install the "PHP Intelephense" extension and add to settings.json:
```
"intelephense.environment.php": {
  "phpcsExecutablePath": "vendor/bin/phpcs",
  "phpcsStandard": "ShipMonkCodingStandard"
}
```

Gotchas and Tips

Pitfalls

Laravel-Specific Conflicts
- Facade Reordering: UseStatementOrder may reorder Laravel Facades (e.g., Log, Cache), breaking IDE autocompletion or explicit namespace usage. Fix: Disable the rule for Facade-heavy files:
```
<rule ref="SlevomatCodingStandard.Classes.UseStatement">
    <exclude name="UseStatementOrder"/>
</rule>
```
- Exception Handling: CatchExceptionsOrder may misorder middleware exceptions (e.g., HttpResponseException). Fix: Exclude middleware files from PHPCS:
```
<exclude-pattern>app/Http/Middleware/*</exclude-pattern>
```
Auto-Fix (phpcbf) Risks
- Breaking Changes: phpcbf may reorder use statements, class keywords, or annotations in ways that invalidate Laravel’s magic methods (e.g., __callStatic for Facades). Fix: Test phpcbf in a staging environment first. Use --dry-run to preview changes:
```
vendor/bin/phpcbf --dry-run
```
PHP Version Mismatches
- The package requires PHP 8.1+ and explicitly drops support for older versions (e.g., removed RequireSelfReference for PHPStan compatibility). Fix: Ensure your project’s php.ini and CI environment match ShipMonk’s PHP version.
Template Annotation Quirks
- Rules like @template* wildcard handling may conflict with Laravel’s typed properties or collection methods. Fix: Review false positives in tests/ directories and exclude if needed:
```
<file>src/</file>
<file>tests/Unit/</file>
```
CI/CD Flakiness
- PHPCS may fail intermittently in CI due to cache corruption or permission issues (var/phpcs.cache). Fix: Add a cleanup step before running PHPCS:
```
- name: Clean PHPCS cache
  run: rm -rf var/phpcs.cache
- name: Run PHPCS
  run: vendor/bin/phpcs
```

Debugging

Isolate Rule Violations Run PHPCS with --report=full to see detailed error messages:

vendor/bin/phpcs --standard=ShipMonkCodingStandard --report=full

Example output:

FILE: src/Models/User.php
----------------------------------------------------------------------
FOUND 1 ERROR AFFECTING 1 LINE
----------------------------------------------------------------------
  40 | ERROR | [x] Missing return type declaration for method
  |      |     getFullName(): string

Disable Rules Temporarily Override a rule in phpcs.xml.dist to debug:

<rule ref="ShipMonkCodingStandard">
    <exclude name="SlevomatCodingStandard.TypeHints.MissingReturnTypeDeclaration"/>
</rule>

Check Rule Sources Identify whether a rule comes from slevomat/coding-standard or shipmonk/coding-standard:
```
vendor/bin/phpcs --standard=ShipMonkCodingStandard --report=checkstyle | grep "shipmonk\|slevomat"
```

Config Quirks

Basepath Misconfiguration If PHPCS ignores files, verify basepath in phpcs.xml.dist:
```
<arg name="basepath" value="."/> 
```
Cache Directory Permissions Ensure var/phpcs.cache is writable:
```
mkdir -p var/phpcs.cache
chmod -R 777 var/phpcs.cache
```
Installed Paths Order The installed_paths config must list slevomat/coding-standard before `shipmonk/coding-standard

Coding Standard Laravel Package