## Getting Started

### Minimal Setup
1. **Install the package** via Composer:
   ```bash
   composer require --dev pluswerk/grumphp-bom-task

Configure GrumPHP (grumphp.yml):

parameters:
    tasks:
        plus_bom_fixer:
            triggered_by: [php, json, yml, txt]  # Customize file types as needed
extensions:
    - PLUS\GrumPHPBomTask\ExtensionLoader

Run GrumPHP to test:
```
./vendor/bin/grumphp run
```

First Use Case

Prevent BOM-related issues in PHP/JSON/YAML files by failing the build if any file contains a UTF-8 BOM. Ideal for:

Ensuring clean composer.json, package.json, or config files.
Blocking encoding artifacts that may break CI/CD pipelines or API responses.

Implementation Patterns

Core Workflow

Pre-commit Hook: Integrate with Git hooks (e.g., pre-commit) to scan staged files before commit:
```
./vendor/bin/grumphp run --triggered-by="php,json,yml"
```
- Pros: Catches issues early, reduces CI noise.
- Cons: May slow down local commits if scanning many files.
CI Pipeline Gate: Add as a blocking step in CI (e.g., GitHub Actions):
```
- name: Check for BOMs
  run: ./vendor/bin/grumphp run
```
- Pros: Enforces consistency across all environments.
- Cons: Fails builds if BOMs are introduced post-commit.

Integration Tips

Combine with Other Tasks: Pair with grumphp's built-in tasks (e.g., phpcs, phpstan) for a comprehensive pre-commit suite:
```
tasks:
    plus_bom_fixer:
        triggered_by: [php, json, yml]
    phpcs:
        triggered_by: [php]
```

Exclude Files/Directories: Use ignore to skip vendor files or legacy systems:

plus_bom_fixer:
    ignore:
        - vendor/
        - legacy/bom-required/

Auto-Fix (Advanced): While this package detects BOMs, you can extend it to remove them by:
1. Using grumphp's on_fail hooks to trigger a script.
2. Leveraging PHP’s file_put_contents() with FILE_UTF8 flag:
```
file_put_contents($file, file_get_contents($file), FILE_UTF8);
```

Laravel-Specific Patterns

Config Files: Enforce BOM-free config/*.php and bootstrap/app.php:

plus_bom_fixer:
    triggered_by: [php]
    exclude_files: [~^/config/.*$~]  # Optional: Exclude specific configs

Artisan Command: Add a custom Artisan command to run BOM checks:

// app/Console/Commands/CheckBOM.php
public function handle()
{
    $exitCode = Artisan::call('grumphp', ['run', '--triggered-by=php,json,yml']);
    if ($exitCode !== 0) {
        $this->error('BOM detected in files!');
        exit(1);
    }
}

Gotchas and Tips

Pitfalls

False Positives in Legacy Systems:
- Some tools (e.g., older Excel exports, legacy databases) require BOMs. Use ignore to exclude these files.
- Debug Tip: Run with --verbose to see which files fail:
```
./vendor/bin/grumphp run --verbose
```
Editor/IDE Conflicts:
- VS Code/Sublime: Some editors auto-insert BOMs in UTF-8 files. Configure them to save as UTF-8 without BOM:
  - VS Code: File > Save with Encoding > UTF-8 (ensure BOM is unchecked).
  - PHPStorm: File > Settings > Editor > File Encodings > Global Encoding = UTF-8 (W/o BOM).
GrumPHP Version Mismatch:
- Error: Class 'PLUS\GrumPHPBomTask\ExtensionLoader' not found.
- Fix: Ensure grumphp is ≥0.16 or ≥1.0 and update dependencies:
```
composer update --dev grumphp pluswerk/grumphp-bom-task
```
Case-Sensitive File Paths:
- On Linux/macOS, paths are case-sensitive. If files are ignored unexpectedly, verify:
```
plus_bom_fixer:
    ignore:
        - "Vendor/OldLibrary/"  # Note: Capital 'V' matters!
```
Binary Files:
- Gotcha: The task scans all triggered files, including binaries (e.g., .png, .pdf). Exclude them explicitly:
```
plus_bom_fixer:
    triggered_by: [php, json, yml, txt]
    exclude_files: [~^\.(png|jpg|pdf|zip)$~]
```

Debugging

Check File Contents: Use xxd or hexdump to inspect files for BOMs:

xxd -c 4 problematic-file.json  # Should NOT start with EF BB BF (BOM)

GrumPHP Logs: Enable debug mode in grumphp.yml:

parameters:
    grumphp:
        process_timeout: 60
        hide_circumvention_tips: false
        stop_on_failure: false

Dry Run: Test without failing:
```
./vendor/bin/grumphp run --dry-run
```

Extension Points

Custom File Types: Extend triggered_by for niche formats (e.g., .env, .md):
```
plus_bom_fixer:
    triggered_by: [php, json, yml, txt, env, md]
```
Dynamic Ignore Rules: Use PHP to dynamically exclude files based on conditions (e.g., CI environment):
```
plus_bom_fixer:
    ignore:
        - "tests/BomTest.php"  # Example: Skip a test file
```

Custom Error Messages: Override the default failure message by extending the task class:

// app/GrumPHP/Tasks/CustomBomTask.php
namespace App\GrumPHP\Tasks;

use PLUS\GrumPHPBomTask\BomFixerTask;

class CustomBomTask extends BomFixerTask
{
    protected function getMessage(): string
    {
        return '❌ BOM detected in ' . $this->file . '. Remove it with: `dos2unix --keepdate ' . $this->file . '`';
    }
}

Then update grumphp.yml:

extensions:
    - App\GrumPHP\Tasks\CustomBomTask

Performance Tips

Limit Scanned Files: Restrict triggered_by to only necessary file types to speed up runs:

plus_bom_fixer:
    triggered_by: [php, json]  # Exclude slower-to-scan types like YML

Parallelize with GrumPHP: Combine with parallel tasks in grumphp.yml:

tasks:
    plus_bom_fixer:
        triggered_by: [php]
    phpcs:
        triggered_by: [php]
        parallel: true

Laravel-Specific Quirks

Cached Configs:
- Issue: bootstrap/cache/ files may regenerate with BOMs if created by tools like php artisan config:clear.
- Fix: Exclude cache directories:
```
plus_bom_fixer:
    ignore:
        - bootstrap/cache/
```
Vendor Files:
- Issue: Composer-generated files (e.g., vendor/composer/autoload*.php) might contain BOMs.
- Fix: Ignore vendor files entirely or use composer dump-autoload --optimize to regenerate them cleanly.
Environment-Specific Checks:
- Run BOM checks only in CI by using environment variables:
```
plus_bom_fixer:
    triggered_by: [php]
    only_when: "%env('CI') == 'true'"
```

Backport Note (10.2.8)

No Breaking Changes: The release backports PR #112 to the 10.x branch, primarily addressing internal improvements (e.g., CI/CD optimizations

Grumphp Bom Task Laravel Package