Getting Started

Minimal Steps

Installation:
```
composer require --dev worksome/coding-style
composer generate-coding-style-stubs
```
This generates the required config files (ecs.php, phpstan.neon, rector.php) in your project root.

Add Scripts to composer.json:

"scripts": {
    "ecs": "vendor/bin/ecs",
    "ecs:fix": "vendor/bin/ecs --fix",
    "phpstan": "vendor/bin/phpstan analyse",
    "rector": "vendor/bin/rector process --dry-run --ansi",
    "rector:fix": "vendor/bin/rector process --ansi"
}

First Use Case: Run a dry check on your codebase:
```
composer ecs
composer phpstan
composer rector
```
Use --fix flags to auto-correct issues where possible:
```
composer ecs:fix
composer rector:fix
```

Implementation Patterns

Daily Workflow Integration

Pre-Commit Hooks: Integrate with tools like Husky or Git Hooks to run composer ecs and composer phpstan before commits:
```
composer ecs --dry-run
composer phpstan analyse --level=5
```
Fail the commit if violations are found.

CI/CD Pipeline: Add checks to your CI (e.g., GitHub Actions, GitLab CI) to enforce coding standards:

# Example GitHub Actions step
- name: Run ECS and PHPStan
  run: |
    composer ecs
    composer phpstan analyse --level=5

Onboarding New Developers: Document the coding style in your CONTRIBUTING.md and include a one-time setup guide:

## Setup Coding Standards
```bash
composer require --dev worksome/coding-style
composer generate-coding-style-stubs
composer ecs:fix  # Auto-fix common issues

Project-Specific Customization: Override default rules by extending the generated configs:

// ecs.php
return [
    'rules' => [
        'Worksome\CodingStyle\Sniffs\Laravel\DisallowEnvUsageSniff' => null, // Disable for specific files
        'SlevomatCodingStandard\Sniffs\TypeHints\ParameterTypeHintSpacingSniff' => true,
    ],
    'paths' => [
        __DIR__.'/src',
        // Exclude specific directories
        !__DIR__.'/tests',
    ],
];

Leveraging Rector for Refactoring: Use Rector for automated refactoring (e.g., upgrading PHP versions, migrating syntax):
```
composer rector --ansi --dry-run  # Preview changes
composer rector:fix              # Apply changes
```

Gotchas and Tips

Pitfalls

Strict PHPStan Rules:
- The worksome.disallowPhpunit rule blocks PHPUnit tests entirely. If your project uses PHPUnit, either:
  - Disable the rule in phpstan.neon:
```
includes:
    - vendor/worksome/coding-style/phpstan/laravel.neon
services:
    Worksome\CodingStyle\PHPStan\DisallowPHPUnitRule: ~
```
  - Migrate to Pest PHP.
Artisan Command Naming:
- The worksome.laravel.kebabCaseArtisanCommands rule enforces kebab-case for Artisan commands. Ensure your commands follow this convention:
```
// ❌ Avoid
php artisan make:auth

// ✅ Prefer
php artisan make:auth --kebab-case
```
Factory Usage:
- The DisallowHasFactorySniff rule requires factories to be called directly (e.g., User::factory() instead of $user->create() with HasFactory). Update your models and tests:
```
// ❌ Avoid
class User extends Model {
    use HasFactory;
}

// ✅ Prefer
class User extends Model {}
User::factory()->create();
```
Blade Files Outside resources:
- The DisallowBladeOutsideOfResourcesDirectorySniff will fail if .blade.php files exist elsewhere. Move them to resources/views/ or rename them.
Environment Checks:
- The worksome.laravel.disallowEnvironmentCheck rule discourages app()->environment() checks. Use driver-based configurations (e.g., config('services.stripe.enabled')) instead.

Enum Case Naming:

Enums must use PascalCase for cases (e.g., Status::Active). Avoid snake_case or camelCase:

// ❌ Avoid
enum Status { ACTIVE, INACTIVE } // snake_case
enum Status { active, inactive }  // camelCase

// ✅ Prefer
enum Status { Active, Inactive }

Config File Naming:
- Config files must use kebab-case (e.g., app-config.php). Rename existing files:
```
mv config/app_config.php config/app-config.php
```

Debugging Tips

Isolate Rule Violations: Run ECS/PHPStan on specific files to debug:

composer ecs src/Models/User.php
composer phpstan analyse src/Models/User.php

Temporarily Disable Rules: Disable a rule in ecs.php or phpstan.neon to bypass it during debugging:

// ecs.php
return [
    'rules' => [
        'Worksome\CodingStyle\Sniffs\Laravel\DisallowEnvUsageSniff' => null,
    ],
];

Understand Auto-Fix Limitations:
- Not all rules support auto-fixing (e.g., custom sniffs like DisallowTodoCommentsSniff). Manually fix these or extend the package.
Leverage --verbose: Run tools with verbose output for detailed error messages:
```
composer ecs --verbose
composer phpstan analyse --verbose
```
Check for Deprecated Rules: If a rule fails unexpectedly, verify it hasn’t been deprecated or replaced in newer versions of the package.

Extension Points

Custom Rules: Extend the package by adding your own rules. For example, create a custom PHPStan rule:

// app/Rules/CustomRule.php
namespace App\Rules;

use PHPStan\Rules\Rule;
use PHPStan\Rules\RuleErrorBuilder;

class CustomRule implements Rule {
    public function getNodeType(): string {
        return 'PHPStan\Analyser\Node\Expr\MethodCall';
    }

    public function processNode(Node $node, Scope $scope) {
        if ($node->getMethodName() === 'oldWay') {
            return RuleErrorBuilder::message('Use newWay instead.')
                ->build();
        }
    }
}

Include it in phpstan.neon:

services:
    - App\Rules\CustomRule

Override Configs: Copy the generated configs (ecs.php, phpstan.neon, rector.php) to config/ and customize them:
```
cp ecs.php config/ecs.php
```
Then update your composer.json scripts to point to the new location:
```
"ecs": "vendor/bin/ecs --config=config/ecs.php"
```
Integrate with IDE: Configure your IDE (e.g., PHPStorm, VSCode) to use the same coding standards:
- PHPStorm: Install PHP CS Fixer and point it to your ecs.php.
- VSCode: Use the PHP Intelephense extension with ECS integration.
Partial Application: Apply the coding style selectively (e.g., only to new features):
```
// ecs.php
return [
    'paths' => [
        __DIR__.'/src/NewFeature',
    ],
];
```

Coding Style Laravel Package