Getting Started

Minimal Steps

Installation Add the package to your Laravel project:
```
composer require rollerscapes/standards --dev
```
This installs PHP-CS-Fixer, PHPStan (with Symfony/Laravel extensions), and PHPUnit configurations.
First Command Run the integrated linter and static analyzer:
```
php artisan standards:check
```
This executes both PHP-CS-Fixer (auto-fixable) and PHPStan (static analysis) in a single pass.
Where to Look First
- Configuration: Check config/standards.php (auto-generated on first run) for customizable rules (PHP-CS-Fixer, PHPStan levels, excluded paths).
- Makefile: Use provided shortcuts:
```
make lint      # Runs PHP-CS-Fixer
make stan      # Runs PHPStan
make test      # Runs PHPUnit with internal test checks
```
- Git Hooks: Enable pre-commit checks:
```
php artisan standards:git-hook
```

Implementation Patterns

Usage Patterns

Daily Development Workflow
- Auto-Fix Style Issues:
```
php artisan standards:fix
```
  Applies PHP-CS-Fixer rules (e.g., PSR-12 compliance, PHPDoc alignment) to staged files.
- Static Analysis on Demand:
```
php artisan standards:analyze --level=5
```
  Runs PHPStan with a custom strictness level (default: max).
- Focused Checks:
```
php artisan standards:check app/Http/Controllers
```
  Targets specific directories (e.g., controllers, services).

CI/CD Pipeline Integration

Fail on Violations:

# GitHub Actions example
- name: Enforce Standards
  run: php artisan standards:check --fail-on-errors

Cache PHPStan Results:
```
php artisan standards:analyze --generate-baseline
```
Generates a baseline file (phpstan.baseline.neon) to ignore known issues temporarily.

Customization

Override Default Rules: Publish the config and modify config/standards.php:

php artisan vendor:publish --provider="Rollerscapes\Standards\StandardsServiceProvider" --tag="config"

Example: Adjust PHPStan’s level or exclude Laravel-specific false positives:

'phpstan' => [
    'level' => 7, // Lower strictness for legacy code
    'exclude_paths' => [
        'app/Providers/AppServiceProvider.php', // Skip problematic files
    ],
],

Extend PHPStan: Add custom rules by including a project-specific phpstan.neon:

includes:
  - vendor/rollerscapes/standards/phpstan.neon
  - phpstan.neon  # Your custom rules

Laravel-Specific Patterns
- Blade Template Checks: Use PHPStan’s Symfony extension to analyze Blade files (if supported):
```
php artisan standards:analyze --include-tests --include-blade
```
- Eloquent/Database Rules: Leverage phpstan/phpstan-doctrine for Doctrine/Laravel Eloquent checks (included by default).
Team Collaboration
- Onboarding Script:
```
php artisan standards:init
```
  Sets up the package, config, and Git hooks in one command.
- Shared Baseline: Commit phpstan.baseline.neon to the repo to track known issues across contributors.

Integration Tips

With Laravel Pint Replace or supplement Pint by configuring PHP-CS-Fixer in config/standards.php:

'php-cs-fixer' => [
    'rules' => [
        '@PSR12' => true,
        'no_unused_imports' => true, // Add Laravel-specific rules
    ],
],

Run via:

php artisan standards:fix

With Laravel Forge/Envoyer Add a deploy hook to run standards checks:
```
php artisan standards:check --fail-on-errors
```
With PHPUnit The package enforces internal test marking (e.g., @internal annotations). Update tests:
```
/**
 * @internal
 */
class ExampleTest extends TestCase { ... }
```
With IDE Support Configure PHPStan in your IDE (e.g., PHPStorm) to use the project’s phpstan.neon for real-time feedback.

Gotchas and Tips

Pitfalls

PHPStan Strictness
- Issue: Upgrading to level=max may break legacy Laravel code (e.g., dynamic properties, loose typing).
- Fix: Start with level=5 and incrementally increase strictness:
```
php artisan standards:analyze --level=5
```
Laravel-Specific False Positives
- Issue: PHPStan’s Symfony extension may flag Laravel-specific code (e.g., Facades, Service Providers) as errors.
- Fix: Exclude problematic paths in config/standards.php:
```
'phpstan' => [
    'exclude_paths' => [
        'app/Providers/*',
        'routes/*',
    ],
],
```
- Alternative: Use ignoreErrors in phpstan.neon:
```
parameters:
  ignoreErrors:
    - '#Method Illuminate\\\\Foundation\\\\Application::bind should not be private#'
```
PHP-CS-Fixer Conflicts
- Issue: Custom Pint rules may conflict with Rollerscapes’ PHP-CS-Fixer config.
- Fix: Merge configs by publishing and overriding:
```
php artisan vendor:publish --tag=php-cs-fixer
```
  Then edit .php-cs-fixer.dist.php to prioritize project-specific rules.
Performance Overhead
- Issue: PHPStan’s level=max can slow down CI/CD pipelines for large codebases.
- Fix:
  - Cache results with --generate-baseline.
  - Run in parallel (if supported):
```
php artisan standards:analyze --parallel
```
Git Hooks
- Issue: Pre-commit hooks may fail due to unstaged changes or large files.
- Fix: Use --allow-runtime-errors for non-critical checks:
```
php artisan standards:git-hook --allow-runtime-errors
```

Debugging Tips

Verbose Output Run with -v for detailed logs:
```
php artisan standards:check -v
```

Isolate Issues Target specific files or directories:

php artisan standards:analyze app/Http/Controllers/UserController.php

PHPStan Error Codes Look up errors in the PHPStan documentation or use:
```
php artisan standards:analyze --error-format=github
```
Configuration Validation Validate your config/standards.php:
```
php artisan standards:validate-config
```

Extension Points

Custom PHPStan Rules Add project-specific rules by extending the config:

# phpstan.neon
includes:
  - vendor/rollerscapes/standards/phpstan.neon
  - rules/custom.neon  # Your custom rules

Dynamic Rules Use PHPStan’s parameters to conditionally enable rules:
```
parameters:
  level: 7
  checkMissingIterableValueType: true
```

Hooks and Events Extend the package’s Artisan commands by binding to its events (if supported). Example:

// app/Providers/StandardsServiceProvider.php
public function boot()
{
    Standards::extend(function ($command) {
        $command->listen('before-check', function () {
            // Pre-check logic (e.g., log start time)
        });
    });
}

Forking the Package If Rollerscapes stops maintaining the package, fork it and:
- Add Laravel-specific rules (e.g., for Blade, Eloquent).
- Update the Makefile to include Laravel-specific tasks.
- Publish a custom version to Packagist.

Configuration Quirks

PHP Version Mismatch
- The package requires PHP 8.1+. If using PHP 8.0, downgrade PHPStan via composer.json:
```
"require-dev": {
    "phpstan/phpstan": "1.10.0" // PHP 8.0 compatible
}
```
**Doct

Standards Laravel Package