Grumphp Bom Task Laravel Package

Product Decisions This Supports

• Eliminating Technical Debt: Automatically prevents UTF-8 BOM artifacts in text files (PHP, JSON, YAML, etc.), reducing cross-platform encoding issues that cause deployment failures, API malfunctions, or database corruption.
• CI/CD Optimization: Acts as a preemptive gate in pipelines to block BOM-containing files before they reach staging/production, reducing flaky tests and rollback incidents.
• Developer Experience (DX): Shifts BOM-related debugging from runtime/debugging to pre-commit/pre-push, saving engineering time and frustration (especially for teams using mixed editors like VS Code, PHPStorm, or Sublime).
• Compliance with Standards: Aligns with PSR-12 and internal coding guidelines by enforcing consistent file encoding practices across repositories.
• Build vs. Buy Decision: Buy—this is a zero-maintenance, high-impact solution compared to building a custom GrumPHP task or relying on manual checks. Ideal for teams already using GrumPHP.
• Use Cases:
  • Pre-commit hooks: Block BOMs before they enter version control.
  • CI pipeline gates: Fail builds if BOMs are detected in critical files (e.g., composer.json, package.json, or config files).
  • Onboarding tool: Enforce consistency across new repositories or legacy migrations.
  • Legacy system cleanup: Identify and remediate BOMs in existing codebases during refactoring.

When to Consider This Package

Adopt if:

• Your team frequently encounters BOM-related issues (e.g., UTF-8 BOM errors in logs, API responses, or database imports).
• You already use GrumPHP or are willing to adopt it for static analysis in PHP/Laravel projects.
• Your codebase includes text-based files vulnerable to BOMs (e.g., JSON, YAML, SQL, PHP, or config files) and spans multiple environments/editors.
• You prioritize automation over manual reviews for encoding consistency.
• Your CI/CD pipeline experiences flaky tests or deployments due to encoding inconsistencies.

Look elsewhere if:

• Your team doesn’t use GrumPHP and isn’t willing to integrate it (alternatives: custom PHP scripts, IDE plugins like VS Code’s "Remove BOM" extension, or manual pre-commit hooks).
• BOMs are rare or non-existent in your stack (e.g., primarily binary files or projects with strict encoding controls).
• You need real-time IDE feedback (consider a VS Code extension or PHPStorm inspection tool).
• Your license requirements conflict with LGPL-3.0 (verify dependencies; this package is LGPL-3.0, not GPL-3.0 as initially stated in the description).
• You require auto-fixing BOMs (this package detects but does not automatically remove BOMs; check if GrumPHP’s core or other extensions support this).

How to Pitch It (Stakeholders)

For Executives: "This is a 5-minute fix to eliminate a recurring technical debt source—UTF-8 BOMs in text files cause deployment failures, API errors, and support tickets. By integrating this lightweight GrumPHP task, we’ll automatically block problematic files before they reach production, saving hundreds of hours annually in debugging and incident response. It’s a no-code solution with zero runtime overhead, aligning with our quality and DX goals while requiring no additional tooling beyond our existing GrumPHP setup."

For Engineering/DevOps: *"We’re adding a pre-commit/pre-push check to detect and reject files with UTF-8 BOMs, targeting:

• Critical files: composer.json, package.json, .env, config/*.php, and SQL migrations.
• Common pain points: Encoding issues in logs, API responses, or database imports. Why this matters:
• Fails fast: Catches issues before CI or deployments, reducing flaky tests.
• Zero maintenance: Just add it to grumphp.yml and composer.json.
• Battle-tested: Used in [X] repositories with no false positives in production. Let’s pilot it in [Repo Name] and expand if it reduces encoding-related incidents by >60%."*

For Developers: *"Tired of UTF-8 BOM errors breaking your local setup or CI? This adds a 1-line GrumPHP task to block files with BOMs before you commit or push. It:

• Runs automatically in the background (no manual fixes).
• Works across all editors (VS Code, PHPStorm, Sublime, etc.).
• Saves you time—no more debugging encoding issues in production. How to use it:

1. Install: composer require --dev pluswerk/grumphp-bom-task
2. Add to grumphp.yml (takes 2 minutes).
3. Profit: No more BOM headaches. Pro tip: If you see a false positive, exclude the file in .grumphp.yml under plus_bom_fixer.ignore."*