Getting Started

Minimal Steps to First Use

Installation:
```
composer require --dev eckinox/eckinox-cs
```
This auto-generates config files, scripts, and hooks in your project.
Set Up Dependencies:
```
npm install
chmod +x DEV/**/*
```
First Run (Pre-Commit):
- Stage a PHP file with intentional errors (e.g., missing semicolon).
- Attempt to commit:
```
git add app/Http/Controllers/TestController.php
git commit -m "Test CS"
```
- Observe the pre-commit hook block the commit and show violations.
Manual Fixing: Run PHP-CS-Fixer directly to auto-fix issues:
```
./DEV/cs/php-cs-fixer
```
CI Integration: Push to GitHub to trigger the GitHub Actions workflow (check "Checks" tab).

First Use Case: Onboarding a New Developer

Goal: Ensure new team members adhere to project standards without manual setup.
Steps:
1. Clone the repo.
2. Run composer install (installs eckinox/eckinox-cs dev dependencies).
3. Make a small change (e.g., edit a Blade file).
4. Attempt to commit—pre-commit hook blocks violations.
5. Use ./DEV/cs/all to run all linters and fix issues.

Where to Look First

Scripts: DEV/cs/ directory contains one-liners for each tool (e.g., ./DEV/cs/phpstan).
Config Files: .php_cs.dist, phpstan.neon, .eslintrc.json—do not edit manually (they’ll be overwritten on updates).
Git Hooks: .git/hooks/pre-commit (symlink to DEV/git-hooks/pre-commit).
GitHub Actions: .github/workflows/coding-standards.yml.

Implementation Patterns

Daily Workflow Integration

Pre-Commit Hooks:
- Automatic: Runs PHP-CS-Fixer, PHPStan, and PHPMD only on staged files (git-aware).
- Bypass Mode: Use ./DEV/git-hooks/pre-commit-with-bypass to commit despite failures (interactive prompts per tool).
- Example:
```
git add app/Models/User.php
git commit -m "Add user model"  # Fails if violations exist
```

Manual Linting:

Fix PHP Code:

./DEV/cs/php-cs-fixer --dry-run  # Preview changes
./DEV/cs/php-cs-fixer --allow-risky=yes  # Auto-fix

Static Analysis:

./DEV/cs/phpstan --level=max  # Strictest checks

JavaScript/CSS:
```
./DEV/cs/eslint
./DEV/cs/stylelint
```

Twig Templates:

./DEV/cs/twig-cs-fixer resources/views/*.twig

CI Feedback:
- GitHub Actions runs all tools on every push/PR. Failures appear as "Required checks" in PRs.

Laravel-Specific Patterns

Ignoring Vendor Files:
- Config files (e.g., phpstan.neon) already exclude vendor/ by default. No action needed.
Blade Template Linting:
- Use twig-cs-fixer for Blade files (treated as Twig templates):
```
./DEV/cs/twig-cs-fixer resources/views/**/*.blade.php
```
Database Migrations:
- PHPStan’s phpstan.neon includes Doctrine-specific rules (e.g., ignores TMaybeContained in collections).
Artisan Command Linting:
- Run PHPStan on app/Console/:
```
./DEV/cs/phpstan app/Console/
```

Integration Tips

Custom Rules Without Overwriting Configs:
- Extend configs by creating .php_cs (for PHP-CS-Fixer) or phpstan.neon without the .dist suffix in the root. The package will merge these with its defaults.
- Example for PHPStan:
```
includes:
    - %vendor_dir%/eckinox/eckinox-cs/phpstan.neon
    - phpstan.neon  # Your custom rules
```
Excluding Files:
- Use .php_cs.dist or .eslintignore to exclude files/folders. Example:
```
# .eslintignore
/node_modules/
/resources/js/vendor/
```
Symfony Projects:
- The package includes Symfony-specific rules (e.g., PHPMD ignores MissingImport for Symfony configs). Works seamlessly with Laravel’s Symfony components.
Node Version Management:
- The package specifies a minimum Node.js version in package.json. Use nvm or Docker to ensure compatibility:
```
nvm use  # Ensure Node version matches package.json engines field
```

Gotchas and Tips

Pitfalls

Config Overwrites:
- Never edit .php_cs.dist, phpstan.neon.dist, etc. These are recreated on updates.
- Solution: Use .php_cs or phpstan.neon (without .dist) for customizations.
Git Hook Conflicts:
- If you already have a pre-commit hook, the package won’t overwrite it. Merge manually or remove the old hook.
- Fix broken symlinks:
```
rm -f .git/hooks/pre-commit
ln -s DEV/git-hooks/pre-commit .git/hooks/pre-commit
```
PHPStan False Positives:
- Doctrine collections may trigger TMaybeContained errors. These are intentionally ignored in the default config (see v1.7.0).
Node.js Dependencies:
- If npm install fails, ensure Node.js is v16+ (check package.json engines field). Use:
```
nvm install 18
nvm use 18
```
GitHub Actions Authentication:
- For private repos, add COMPOSER_AUTH to GitHub Secrets. The workflow auto-detects this secret.

Debugging Tips

Dry Runs:

Test tools without fixing:

./DEV/cs/php-cs-fixer --dry-run --diff
./DEV/cs/phpstan --level=max --no-progress

Verbose Output:
- Add -v or --verbose flags to scripts (e.g., ./DEV/cs/phpstan -vv).

Isolate Issues:

Run a single tool on a specific file:

./DEV/cs/phpstan app/Http/Controllers/UserController.php

Bypass Specific Tools:
- Use pre-commit-with-bypass to skip failing tools interactively.

Extension Points

Custom PHP-CS-Fixer Rules:

Add rules to .php_cs:

rules:
    @PhpCsFixer: true
    no_unused_imports: true

PHPStan Extensions:

Install custom extensions and reference them in phpstan.neon:

includes:
    - %vendor_dir%/eckinox/eckinox-cs/phpstan.neon
    - vendor/your-extension/phpstan-extensions.neon

ESLint Plugins:

Add plugins to .eslintrc.json:

{
    "plugins": ["your-plugin"],
    "rules": {
        "your-plugin/rule": "error"
    }
}

GitHub Actions Customization:

Extend the workflow in .github/workflows/coding-standards.yml:

jobs:
    coding-standards:
        steps:
            - uses: actions/checkout@v4
            - run: ./DEV/cs/all
            - run: ./DEV/cs/phpstan --level=max  # Add custom steps

Pro Tips for Laravel Devs

Optimize PHPStan for Large Projects:
- Cache results with phpstan --generate-baseline and commit baseline.php:
```
./DEV/cs/phpstan --generate-baseline
git add phpstan
```

Eckinox Cs Laravel Package