Peck Laravel Package

Product Decisions This Supports

• Developer Experience (DX) Enhancement:

  • Automated Code Clarity: Integrate Peck into CI/CD pipelines to enforce consistent, typo-free naming conventions (e.g., filenames, classes, methods) and documentation, reducing cognitive friction for developers.
  • Onboarding Efficiency: Standardize codebase terminology and reduce onboarding time by flagging inconsistencies early, ensuring new hires work with a polished, professional codebase.
  • Pre-Merge Quality Gates: Block pull requests with spelling/grammar errors in code or docs, aligning with Laravel’s emphasis on maintainable, high-quality software.

• Roadmap Prioritization:

  • Build vs. Buy: Avoid reinventing a spell-checking tool; Peck’s GNU Aspell integration provides a ready-made solution, saving development time and effort.
  • Scalability: Use Peck as a foundation for future "code clarity" features, such as custom dictionaries for domain-specific terms or integration with static analysis tools (e.g., PHPStan, Pest).
  • Open-Source Contribution: Evaluate Peck’s potential as a critical dependency and contribute to its development (e.g., adding Laravel-specific rules or improving performance).

• Use Cases:

  • CI/CD Pipeline Integration: Automate spell-checking in GitHub Actions or GitLab CI to catch issues before production, reducing manual review burden.
  • Local Development: Integrate Peck into pre-commit hooks (e.g., via Husky) or IDE plugins (e.g., PHPStorm) for real-time feedback during coding.
  • Documentation Quality: Ensure consistency in Markdown, Blade templates, and docblocks by scanning for spelling/grammar errors.
  • Legacy Code Refactoring: Identify and standardize naming inconsistencies in large or inherited codebases, improving readability and maintainability.

When to Consider This Package

• Adopt Peck if:

  • Your team prioritizes consistent, professional naming conventions and high-quality documentation in PHP/Laravel projects.
  • You are using PHP 8.2+ and can manage GNU Aspell dependencies (e.g., via CI or local setup).
  • Your codebase is large or growing, and manual reviews of filenames, classes, or documentation are error-prone.
  • You are open to early-stage tools and can tolerate minor instability in exchange for long-term benefits.
  • You want a lightweight, CLI-based solution that integrates with existing workflows (e.g., Composer, CI/CD).

• Look Elsewhere if:

  • You require a production-ready, stable tool with no breaking changes, as Peck is still in active development (not yet ready for critical pipelines).
  • Your team relies on highly customized naming rules or domain-specific terminology that Peck’s Aspell-based approach cannot handle without significant manual configuration.
  • You prefer IDE-native solutions (e.g., PHPStorm’s built-in spell-check) over CLI tools, as Peck lacks real-time IDE integration.
  • Your project includes non-PHP assets (e.g., JavaScript, TypeScript) that Peck does not support.
  • You are unable or unwilling to install and maintain system-level dependencies like GNU Aspell across development environments.

How to Pitch It (Stakeholders)

For Executives:

*"Peck is a low-cost, high-impact tool that automates spell-checking for PHP/Laravel codebases—filenames, classes, methods, and documentation—just like Grammarly for written content. By integrating Peck into our workflows, we can:

• Reduce bugs and inconsistencies caused by misnamed variables, methods, or files, improving maintainability.
• Accelerate onboarding by ensuring a standardized, professional codebase for new hires.
• Save time by catching issues early in development, before they require manual fixes in production.
• Leverage open-source innovation without reinventing the wheel, aligning with our cost-effective, scalable approach. This tool is easy to pilot in non-critical branches and can be fully adopted once stabilized, making it a safe investment."*

For Engineering Teams:

*"Peck is a CLI tool that uses GNU Aspell to identify spelling/grammar mistakes in your PHP/Laravel codebase. Here’s why it’s worth adopting:

• Seamless Integration: Works like other CLI tools (e.g., Pint, Pest) and can be added to Composer or CI pipelines with minimal effort.
• Customizable: Ignore false positives (e.g., config, namespace) or use presets like the Laravel preset to skip common terms.
• Lightweight and Fast: Designed for speed, making it ideal for large codebases or CI/CD environments.
• Early-Stage but Promising: While not yet production-ready, Peck is actively developed and could become a critical part of our code quality toolchain. Proposal: Let’s test Peck in a dedicated branch or feature project to validate its effectiveness and identify any integration challenges before wider adoption."*

For Developers:

*"Peck is like a spell-checker for your code—it catches typos and inconsistencies in filenames, class names, methods, and documentation. Here’s how it helps:

• Catch Errors Early: Identify spelling mistakes before they reach production or require manual fixes.
• Consistent Naming: Enforce clean, professional naming conventions across the codebase.
• Easy to Use: Just run ./vendor/bin/peck in your project, or integrate it into CI/CD for automated checks.
• Customizable: Ignore specific words or paths, or use presets like the Laravel preset to skip common terms. *Try it out locally or in a test branch to see how it fits into your workflow!"

Key Selling Point: "Peck turns your codebase into a polished, professional workspace—just like Grammarly for your documentation and variable names."