Coding Standard Laravel Package

Product Decisions This Supports

• Internal Ecosystem Standardization: Enables ShipMonk to enforce a unified coding standard across all PHP/Laravel projects, reducing cognitive load for engineers and accelerating onboarding. Eliminates subjective style debates by providing a non-negotiable baseline for formatting, annotations, and structural conventions.
• Technical Debt Mitigation: Proactively prevents drift in code quality by automating enforcement of modern PHP best practices (e.g., @template* annotation ordering, trait usage rules). Aligns with ShipMonk’s long-term goal of maintainable, high-quality codebases while reducing manual review overhead.
• Build vs. Buy Decision: Validates a "buy" approach by eliminating the need to invest in custom PHPCS configuration or maintenance. Leverages ShipMonk’s internal expertise to deliver a pre-validated, zero-effort solution with no additional engineering lift.
• CI/CD Optimization: Enables automated quality checks in pipelines (e.g., GitHub Actions, GitLab CI) to catch style violations early, reducing production defects. Reduces manual review overhead by shifting enforcement to pre-commit or pre-merge hooks.
• PHP 8.5 Readiness: Supports modern PHP features (e.g., @template* annotations) critical for ShipMonk’s roadmap, ensuring compatibility with upcoming Laravel releases and future-proofing the codebase.
• Governance Clarity: Provides a clear boundary for internal vs. external use—ShipMonk projects adopt this package, while open-source or third-party projects use slevomat/coding-standard directly. Reduces maintenance burden by scoping the package to internal needs only.

When to Consider This Package

Adopt this package if:

• Your project is exclusively part of ShipMonk’s internal ecosystem (e.g., ShipMonk-owned packages, microservices, or Laravel applications).
• You need immediate standardization without customization and can align with ShipMonk’s preconfigured rules.
• Your team prioritizes consistency over flexibility and wants to enforce ShipMonk’s conventions without deviation.
• You are using ShipMonk’s toolchain (PHPStan, Rector, Laravel) and want to align linting rules with their existing workflows.
• Your project requires PHP 8.5 compatibility and leverages ShipMonk’s specific tweaks (e.g., annotation ordering, trait use rules).
• You lack the resources to maintain a custom coding standard and prefer a pre-configured, battle-tested solution.

Avoid this package if:

• Your project is external to ShipMonk (e.g., open-source, client-facing, or third-party). Use slevomat/coding-standard or PSR-12 directly instead.
• You require Laravel-specific rules (e.g., Blade syntax, Facade patterns, Eloquent conventions). This package lacks native support for these.
• Your codebase uses PHP versions below 8.1 or relies on sniffs that ShipMonk has explicitly removed (e.g., RequireSelfReference).
• You need highly customizable rules or plan to override/extend the standard. This package is rigid and not designed for heavy modification.
• Your project already enforces strict standards via other tools (e.g., phpstan, rector, or Laravel’s Pint), making PHPCS redundant or causing conflicts.
• You require community support, extensive documentation, or active maintenance. This package has minimal adoption (0 dependents, 1 star) and is primarily maintained for ShipMonk’s internal use.

How to Pitch It (Stakeholders)

For Executives/Leadership

*"This package standardizes our PHP and Laravel codebases across all ShipMonk projects, driving efficiency and quality at scale. By adopting ShipMonk’s pre-configured coding standard, we eliminate the need to reinvent linting rules, ensuring consistency without additional engineering overhead. This aligns with our long-term goals of maintaining high-quality, maintainable codebases while accelerating development velocity.

For projects outside ShipMonk’s ecosystem, we recommend using slevomat/coding-standard directly to avoid lock-in and ensure community support. This package is a strategic ‘buy’ decision—it leverages ShipMonk’s existing investment in coding standards, reducing our technical debt and improving collaboration across teams."*

For Engineering Teams

*"This is ShipMonk’s official PHPCS ruleset—a turnkey solution to enforce our coding standards across Laravel and PHP projects. Here’s why it’s valuable:

• Consistency: Ensures all ShipMonk projects adhere to the same rules, reducing friction during code reviews and knowledge sharing.
• Speed: Auto-fixes common issues (e.g., formatting, ordering) in seconds, so you don’t waste time on manual style fixes.
• Integration: Works seamlessly with our toolchain (PHPStan, Rector, Laravel) and supports PHP 8.5.
• Zero Maintenance: Built and maintained internally, so you don’t have to configure or update it—just use it.

To adopt:

1. Install: composer require --dev shipmonk/coding-standard.
2. Configure phpcs.xml.dist with the provided template.
3. Run vendor/bin/phpcs to catch issues or vendor/bin/phpcbf to auto-fix them.

For non-ShipMonk projects, use slevomat/coding-standard directly, as this package is tailored exclusively for our internal use. If you encounter conflicts (e.g., Laravel-specific patterns), coordinate with the team to override rules in phpcs.xml or exclude directories as needed."

For Developers

*"This package enforces ShipMonk’s coding standards for PHP/Laravel projects. Here’s how to use it:

1. Install:

   composer require --dev shipmonk/coding-standard
   

2. Configure PHPCS: Add this to your phpcs.xml.dist:

   <ruleset>
       <arg name="basepath" value="."/>
       <arg name="cache" value="var/phpcs.cache"/>
       <file>src/</file>
       <file>tests/</file>
       <config name="installed_paths" value="vendor/slevomat/coding-standard,vendor/shipmonk/coding-standard"/>
       <rule ref="ShipMonkCodingStandard"/>
   </ruleset>
   

3. Run:
   • Check code: vendor/bin/phpcs
   • Fix issues: vendor/bin/phpcbf

Key notes:

• This is ShipMonk-specific, so some rules (e.g., @template* annotations) may differ from other standards.
• If a rule feels off, check if it’s a ShipMonk tweak (e.g., removed RequireSelfReference for PHPStan compatibility).
• For custom rules, coordinate with the team—this package isn’t designed for heavy modification.

Pro tip: Add this to your CI pipeline to enforce rules early and keep your codebase clean! Example GitHub Actions step:

- name: Run PHPCS
  run: vendor/bin/phpcs --standard=ShipMonkCodingStandard --warning-severity=3
```"

### **For Technical Leads/Architects**
*"This package is a **monolithic, opinionated** PHPCS ruleset built for ShipMonk’s internal use. While it provides immediate standardization, its rigid design and ShipMonk-specific tweaks introduce tradeoffs:

**Pros:**
- **Fast adoption**: Ready-to-use with minimal configuration.
- **Toolchain alignment**: Works with ShipMonk’s PHPStan, Rector, and Laravel setup.
- **PHP 8.5 support**: Future-proofs your codebase for modern PHP features.

**Cons:**
- **Laravel limitations**: **No native Laravel support**—rules like `CatchExceptionsOrder` or `ThrowsAnnotationsOrder` may conflict with Laravel’s **middleware exception handling** or **Facade aliasing**.
- **Auto-fix risks**: `phpcbf` could reorder code in ways that break Laravel patterns (e.g., Facade imports, middleware).
- **Lock-in**: ShipMonk’s rules may conflict with Laravel’s idiomatic practices or other static analyzers.

**Recommendation:**
- Use this package **only for ShipMonk-owned projects** where alignment with internal conventions is critical.
- For external Laravel projects, use `slevomat/coding-standard` with a custom config or PSR-12.
- If adopting, test `phpcbf` thoroughly in a staging environment to avoid breaking changes.
- Consider adding a **pre-commit hook** or **CI check** to enforce rules without blocking development:
  ```bash
  composer require --dev laravel-pint
  vendor/bin/pint --test  # Optional: Add Pint for Laravel-specific formatting
  ```"