Peck Laravel Package

Product Decisions This Supports

• Developer Experience (DX) and Code Quality:

  • Automated Naming Standards: Enforce consistent, typo-free naming conventions for filenames, classes, methods, and properties, reducing cognitive load for developers and improving code readability.
  • Documentation and Comment Clarity: Catch spelling/grammar errors in docblocks, comments, and Markdown files, ensuring professionalism and reducing miscommunication.
  • CI/CD Integration: Block pull requests with spelling errors, acting as a lightweight gatekeeper for code quality alongside tools like PHPStan or Pest.

• Roadmap and Technical Strategy:

  • Build vs. Buy Decision: Avoid building a custom spell-checking solution by leveraging Peck’s GNU Aspell integration, saving development time and effort while benefiting from community-driven improvements.
  • Scalability for Future Features: Use Peck as a foundation for broader "code clarity" initiatives, such as integrating custom dictionaries for domain-specific terms or extending spell-checking to other file types (e.g., Blade templates, JSON schemas).
  • Open-Source Contribution: Evaluate Peck’s long-term viability as a dependency and contribute to its development (e.g., adding Laravel-specific rules, improving performance, or expanding language support).

• Use Cases:

  • CI/CD Pipeline Enforcement: Automate spell-checking in GitHub Actions or GitLab CI to catch issues before merging, reducing manual review overhead and ensuring consistency.
  • Local Development Workflows: Integrate Peck into pre-commit hooks (e.g., Husky) or IDE plugins (e.g., PHPStorm) for real-time feedback during development.
  • Legacy Code Refactoring: Identify and standardize naming inconsistencies in large or inherited codebases, improving maintainability and reducing technical debt.
  • Collaboration and Onboarding: Ensure new developers inherit a polished, professional codebase with consistent terminology, accelerating ramp-up time.

When to Consider This Package

• Adopt Peck if:

  • Your team values clean, 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/CD or local setup).
  • Your codebase is large, growing, or legacy-heavy, where manual reviews of filenames, classes, or documentation are error-prone or time-consuming.
  • You are open to early-stage tools and can tolerate minor instability in exchange for long-term benefits (e.g., piloting in non-critical branches).
  • You want a lightweight, CLI-based solution that integrates with existing workflows (e.g., Composer, CI/CD) without heavy IDE dependencies.

• 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 extensive 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 or plugins.
  • Your project includes non-PHP assets (e.g., JavaScript, TypeScript, Go) that Peck does not support.
  • You are unable or unwilling to install and maintain system-level dependencies like GNU Aspell across development environments (e.g., Windows without WSL or Scoop).

How to Pitch It (Stakeholders)

For Executives:

*"Peck is a low-cost, high-impact tool that automates spell-checking for PHP/Laravel code—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 and reducing technical debt.
• Accelerate onboarding by ensuring a standardized, professional codebase for new hires, cutting ramp-up time by weeks.
• Save time and resources by catching issues early in development, before they require costly 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, high-ROI investment."*

For Engineering Leaders/Tech Leads:

*"Peck is a CLI spell-checker for PHP/Laravel that uses GNU Aspell to identify typos and inconsistencies in your codebase—filenames, class names, methods, docs, and more. Here’s why it’s worth adopting:

• Seamless Integration: Works like other CLI tools (e.g., Pint, Pest) and can be added to Composer, CI/CD, or pre-commit hooks 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, identify edge cases, and plan for 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 you:

• Catch Errors Early: Identify spelling mistakes before they reach production or require manual fixes.
• Consistent Naming: Enforce clean, professional naming conventions across the codebase (e.g., UserModel vs. UsrModel).
• Easy to Use: Just run ./vendor/bin/peck in your project, or add it to 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—it’s a quick win for code quality!"*

For QA/Code Review Teams:

*"Peck helps reduce manual review burden by automating spell-checking for:

• Filenames and paths (e.g., user_controller.php vs. user_controller.php).
• Class/method/property names (e.g., getUsrData() vs. getUserData()).
• Documentation and comments (e.g., typos in docblocks or Markdown). By integrating Peck into pre-merge checks, we can shift left on these issues, saving time and reducing the number of trivial fixes in pull requests. Example: A PR with Usr instead of User everywhere would now be blocked automatically—no more manual back-and-forth!"*

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