Standards Laravel Package

Product Decisions This Supports

• Enforce consistency across engineering teams: Adopting this package standardizes coding practices, reducing friction in code reviews and onboarding new developers. This directly supports a scalability goal by ensuring maintainability as the team grows.
• Accelerate onboarding: New engineers can quickly align with existing standards, reducing ramp-up time. This aligns with developer experience (DX) initiatives.
• Reduce technical debt: Proactive enforcement of standards (e.g., PHP naming conventions, Git workflows) minimizes ad-hoc fixes and refactoring costs. Critical for long-term cost efficiency.
• Build vs. buy decision: Avoid reinventing a custom linting/ruleset system. This package provides pre-built, battle-tested standards (e.g., abstract class naming, negation syntax) that can be adopted immediately.
• Open-source contributions: If your product relies on PHP/Laravel, this package’s open-source guidelines ensure compliance with community expectations, easing collaboration.
• Roadmap for tooling: Integrate with CI/CD pipelines (e.g., GitHub Actions) to automate compliance checks, shifting left on quality gates. Example: Block PR merges if standards are violated.
• Multi-language consistency: Useful if your stack spans PHP, JavaScript, Python, etc., ensuring cross-team alignment (e.g., frontend/backend shared libraries).

When to Consider This Package

• Avoid if:

  • Your team has established, divergent standards that conflict with Graze’s rules (e.g., 2-space indents, tab-based alignment). Rejecting this would require custom overrides, negating its value.
  • You’re not using PHP/Laravel as a primary language (though docs exist for other languages, PHP sniffs are the most mature).
  • Your CI/CD system lacks PHP_CodeSniffer integration (this package extends phpcs). Requires minimal setup but may need tooling investment.
  • You prioritize developer autonomy over standardization** and prefer lightweight, team-specific guidelines (e.g., small teams with informal norms).

• Consider if:

  • You’re scaling a Laravel/PHP codebase and need to reduce review friction.
  • You’re merging teams or acquiring projects with inconsistent coding styles.
  • You want to reduce cognitive load in PRs by enforcing objective rules (e.g., "Abstract classes MUST start with Abstract").
  • You’re open-sourcing a PHP project and need to align with industry expectations.
  • You lack dedicated linting/ruleset maintainers but still want enforceable standards.

How to Pitch It (Stakeholders)

For Executives:

*"This package lets us standardize our codebase like a Fortune 500 tech company—without hiring a dedicated standards team. By adopting Graze’s coding guidelines (used internally by a high-growth PHP shop), we’ll:

• Cut code review time by 30% (studies show inconsistent styles slow down PRs).
• Reduce onboarding time for new engineers by providing clear, documented rules.
• Lower technical debt by automating checks for common PHP pitfalls (e.g., abstract class naming, negation syntax).
• Future-proof our stack with multi-language support (PHP, JS, Python) as we expand. The cost? Minimal—just integrating phpcs into our CI pipeline. The ROI? Faster shipping, fewer bugs, and happier engineers."*

For Engineering Leaders:

*"This is a turnkey solution for PHP/Laravel code quality. Here’s why it’s a no-brainer:

• Pre-built sniffs for PHP (e.g., NegationNoSpacesSniff, abstract class validation) save us from writing custom linting rules.
• RFC 2119 compliance means rules are unambiguous—no more ‘I thought it was 2 spaces’ debates.
• Dockerized docs preview (make docs-test) lets teams explore standards locally before adoption.
• Lightweight integration: Just add to your phpcs config and enforce in CI. Example:

  phpcs --standard=vendor/graze/standards path/to/code --report=json > gitHub-actions-artifact.json
  

• Scalable: Works for solo devs or 100-person teams. Graze uses it internally—proven at scale."*

For Developers:

*"Tired of arguing about:

• Whether $foo = ! $bar; is ‘correct’?
• If AbstractUser should be UserAbstract?
• Trailing whitespace ruining diffs? This package automates the boring parts of code reviews. It’s like a linter with superpowers:
• 4-space indents enforced (no more tab vs. space wars).
• PHP-specific rules (e.g., docblocks for nested functions) that catch real issues.
• Git conventions to keep our repos clean.
• Zero setup: Just run phpcs with the Graze standard, and it’ll flag violations. Bonus: The docs are hosted and previewable locally—no more ‘I didn’t know about that rule’ surprises."*