Coding Standard Laravel Package

Technical Evaluation

Architecture Fit

• Purpose Alignment: The package provides a custom PHP coding standard tailored to ShipMonk’s internal conventions, which may align with a TPM’s need for consistent, enforceable code quality in a Laravel/PHP ecosystem.
• Laravel Compatibility: Since Laravel is PHP-based, this standard can enforce team-wide consistency in naming, structure, and best practices, reducing onboarding friction and technical debt.
• Extensibility: Built on top of slevomat/coding-standard, it allows for custom rule overrides while leveraging a mature foundation.

Integration Feasibility

• Low-Coupling: The package is standalone (no Laravel-specific dependencies) and integrates via PHP_CodeSniffer, making it easy to adopt in any PHP project.
• Toolchain Fit: Works seamlessly with CI/CD pipelines (e.g., GitHub Actions, GitLab CI) for automated linting.
• No Runtime Impact: Runs only in development/testing, avoiding production overhead.

Technical Risk

• Custom Rules: ShipMonk-specific rules may conflict with Laravel conventions (e.g., naming, PSR standards). Requires validation against existing codebase.
• Maintenance Burden: If ShipMonk’s rules diverge from broader PHP/Laravel standards, future updates may require manual adjustments.
• Dependency Age: Last release in 2026 (future date) suggests potential for breaking changes if rules evolve rapidly.

Key Questions

1. Does this standard align with Laravel’s PSR-12 or introduce conflicting rules?
2. Are there ShipMonk-specific dependencies (e.g., custom sniffs) that may not apply to other projects?
3. How will rule conflicts be resolved if the team uses other standards (e.g., laravel-shift/coding-standard)?
4. What’s the long-term maintenance plan if ShipMonk updates their rules?
5. Does the team have bandwidth to enforce and adapt these rules?

Integration Approach

Stack Fit

• PHP_CodeSniffer Integration: Works natively with Laravel’s PHP ecosystem (Composer, Artisan, CI).
• CI/CD Readiness: Can be gated in PRs (e.g., fail builds on violations) or run pre-commit (via php-cs-fixer).
• IDE Support: Compatible with PHPStorm, VSCode for real-time linting.

Migration Path

1. Pilot Phase:
   • Install in a non-critical branch and test against existing code.
   • Compare violations with PSR-12 or other standards to identify conflicts.
2. Incremental Adoption:
   • Start with auto-fixable rules (phpcbf) to reduce friction.
   • Gradually enforce non-auto-fixable rules via CI.
3. Configuration Customization:
   • Override ShipMonk-specific rules in phpcs.xml.dist if needed.
   • Merge with existing standards (e.g., slevomat/coding-standard) if required.

Compatibility

• Laravel-Specific: No direct conflicts, but naming conventions (e.g., use App\...) may need alignment.
• Tooling: Works with:
  • php-cs-fixer (for auto-fixing)
  • roave/security-advisories (if combined with security checks)
  • rector/rector (for modernizing legacy code)

Sequencing

1. Setup:
   • Add to composer.json (require-dev).
   • Configure phpcs.xml.dist (adjust file paths if needed).
2. Validation:
   • Run phpcs on the entire codebase to baseline violations.
3. Enforcement:
   • Add to CI (e.g., GitHub Actions) to block merges on failures.
4. Iteration:
   • Refine rules based on team feedback and false positives.

Operational Impact

Maintenance

• Rule Updates: Requires periodic review if ShipMonk updates their standard.
• Dependency Management: Monitor slevomat/coding-standard for breaking changes.
• Documentation: Maintain a team guide on how to resolve common violations.

Support

• Onboarding: Reduces context-switching for new devs by enforcing consistent style.
• Debugging: Clear error messages help identify issues early.
• Tooling Overhead: Minimal—primarily a development-time tool.

Scaling

• Performance: phpcs runs locally or in CI; no runtime cost.
• Team Growth: Scales well with new contributors by enforcing standards.
• Multi-Repo: If used across multiple Laravel packages, ensure consistent configuration.

Failure Modes

• False Positives: Custom rules may flag legitimate Laravel patterns as violations.
• Tooling Breakage: If PHP_CodeSniffer or slevomat/coding-standard deprecates APIs, the package may need updates.
• Resistance: Developers may ignore or bypass linting if rules feel overly restrictive.

Ramp-Up

• Initial Cost: 1–2 weeks to:
  • Integrate and configure.
  • Baseline existing code.
  • Train the team on common violations.
• Long-Term Benefit: Reduced technical debt, faster onboarding, and consistent code quality.
• Training Needs:
  • Workshop on reading PHPCS output.
  • Examples of how to fix violations (e.g., phpcbf usage).