Coding Standard Laravel Package

Technical Evaluation

Architecture Fit

• Purpose Alignment: This package is a PHPCS rule set designed to enforce Zeta Components' legacy coding standards, which may include PHP 5.x quirks and non-PSR-compliant conventions. It is not a Laravel-specific tool but can be integrated into Laravel projects where Zeta’s legacy codebase exists or where strict alignment with Zeta’s conventions is required.

  • Laravel Compatibility: Laravel’s default coding standards (PSR-12) may conflict with Zeta’s rules (e.g., naming conventions, brace styles, or legacy syntax tolerances). This package is best suited for teams maintaining legacy Zeta-influenced code or migrating from Zeta to Laravel while preserving historical conventions.
  • Use Case Fit: Ideal for:
    • Teams inheriting Zeta Components codebases.
    • Projects requiring backward compatibility with Zeta’s legacy standards.
    • Organizations enforcing strict, opinionated coding standards across mixed PHP versions.

• Key Features:

  • Custom PHPCS rules tailored to Zeta’s "snowflake" conventions (e.g., specific naming, spacing, or docblock formats).
  • Designed for legacy PHP 5.x/7.x compatibility, which may introduce conflicts with modern Laravel (PHP 8.x+).
  • No runtime dependencies—pure static analysis tool.

Integration Feasibility

• Laravel-Specific Challenges:

  • Rule Conflicts: Zeta’s rules may clash with Laravel’s PSR-12 (e.g., CamelCase vs. snake_case for methods, strict brace styles).
  • Legacy Syntax: Rules may enforce PHP 5.x practices (e.g., array() instead of []), which are deprecated in modern Laravel.
  • Tooling Overlap: Laravel already integrates with php-cs-fixer and phpmd; this package adds another layer of static analysis.

• Integration Pathways:

  • PHPCS Integration: Works natively with Laravel’s existing PHPCS setup (via dealerdirect/phpcodesniffer).
  • CI/CD: Can be added to GitHub Actions, GitLab CI, or Laravel Forge as a pre-merge check.
  • IDE Support: Compatible with PHPStorm, VSCode (via PHPCS plugins), and other IDEs with PHPCS integration.

• Migration Strategy:

  • Incremental Adoption: Start with a pilot phase (e.g., audit a subset of the codebase) before full enforcement.
  • Hybrid Approach: Combine with php-cs-fixer or PSR-12 rulesets to balance Zeta’s legacy standards with modern Laravel practices.
  • Custom Rulesets: Override or disable conflicting rules in a custom ruleset.xml to align with Laravel’s conventions.

Technical Risk

• Medium-High Risk:

  • Rule Conflicts: Zeta’s standards may block modern Laravel patterns (e.g., short array syntax, type hints, or PSR-12 compliance).
  • Legacy Dependencies: Rules may enforce deprecated PHP 5.x syntax, requiring manual overrides or exceptions.
  • Maintenance Burden: The package is unmaintained (0 stars, no dependents), so long-term viability depends on internal upkeep.
  • Performance: PHPCS can be slow on large codebases, potentially slowing CI pipelines.

• Mitigation Strategies:

  • Rule Customization: Create a custom ruleset to disable or modify conflicting rules.
  • Pilot Testing: Run against a small subset of the codebase first to identify critical conflicts.
  • Document Exceptions: Clearly document where Zeta’s rules diverge from Laravel best practices.
  • Hybrid Workflow: Use php-cs-fixer for modern formatting and PHPCS for Zeta-specific rules.

Key Questions for TPM

1. Business Justification:

   • Why enforce Zeta’s standards? Is this for legacy code maintenance, interoperability, or historical compliance?
   • Are there costs to deviating from Zeta’s rules (e.g., vendor contracts, compliance)?

2. Technical Feasibility:

   • Which Zeta rules are non-negotiable, and which can be relaxed or overridden?
   • Example: Should CamelCase methods be enforced globally, or only in legacy modules?
   • How will conflicts with PSR-12/Laravel conventions be resolved?

3. Tooling and Workflow:

   • Will this replace php-cs-fixer, or run alongside it?
   • How will violations be surfaced (CI, PR checks, local dev)?
   • What is the performance impact on CI pipelines?

4. Long-Term Viability:

   • Is Zeta Components actively maintained? If not, will this standard become a maintenance burden?
   • Should the team fork and maintain this package independently?
   • How will this integrate with future Laravel upgrades (e.g., PHP 9.x)?

5. Team Adoption:

   • How will developers learn and adapt to Zeta’s conventions?
   • Will this increase onboarding time for new Laravel developers?
   • Are there alternatives (e.g., php-cs-fixer presets, custom PSR-12 extensions) that could achieve similar goals with lower risk?

Integration Approach

Stack Fit

• PHP Ecosystem:

  • PHPCS/PHP-CS-Fixer: Native integration with Laravel via Composer and CI/CD tools.
  • IDE Support: Works with PHPStorm, VSCode, and other IDEs via PHPCS plugins.
  • CI/CD: Plugins available for GitHub Actions, GitLab CI, CircleCI, etc.

• Laravel-Specific:

  • No Runtime Impact: Runs as a static analysis tool, not a framework dependency.
  • Potential Synergy:
    • Use with Laravel’s pint (PHP 8’s built-in formatter) for hybrid workflows.
    • Combine with rector for modernizing legacy code while preserving Zeta’s conventions.
  • Tooling Conflicts:
    • PHPCS vs. PHP-CS-Fixer: Zeta’s rules are PHPCS-native; php-cs-fixer may not support all rules directly.
    • Solution: Use PHPCS for Zeta rules and php-cs-fixer for Laravel-specific formatting.

Migration Path

1. Assessment Phase:

   • Install PHPCS and Zeta’s rules:

     composer require --dev zetacomponents/coding-standard phpcs/phpcs
     

   • Run against a sample of the codebase to identify violations:

     vendor/bin/phpcs --standard=ZetaComponents --report=full src/
     

   • Document conflicts with PSR-12/Laravel conventions.

2. Pilot Phase:

   • Integrate into CI as a warning-only check:

     # GitHub Actions example
     - name: PHPCS (Zeta)
       run: vendor/bin/phpcs --standard=ZetaComponents --warning-severity=3 --error-severity=5 src/
     

   • Gradually enforce in PR checks (start with warnings, then errors).

3. Full Adoption:

   • Update IDE settings to auto-fix where possible (e.g., PHPStorm PHPCS plugin).
   • Train developers on Zeta’s conventions (e.g., docblock formats, naming rules).
   • Consider a hybrid ruleset:

     <!-- .phpcs.xml.dist -->
     <config name="standard" value="ZetaComponents"/>
     <rule ref="ZetaComponents.Classes.ClassDeclaration.MustNotBeFinal">
         <severity>0</severity> <!-- Disable conflicting rule -->
     </rule>
     

4. Hybrid Workflow:

   • Use php-cs-fixer for modern formatting (e.g., imports, braces).
   • Use PHPCS for Zeta-specific rules (e.g., naming, legacy syntax).
   • Example php-cs-fixer config:

     return (new PhpCsFixerConfig())
         ->setRules([
             '@PSR12' => true,
             '@ZetaComponents' => true, // If supported
             'array_syntax' => ['syntax' => 'short'], // Override Zeta's preference
         ]);
     

Compatibility

• PHP Version:

  • Zeta’s rules may include PHP 5.x/7.x tolerances, which could conflict with Laravel’s PHP 8.x+ requirements.
  • Risk: Some rules may be deprecated or incompatible with modern PHP features (e.g., named arguments, match expressions).
  • Mitigation: Test rules against your minimum PHP version and disable incompatible rules.

• Tooling Conflicts:

  • PHPCS vs. PHP-CS-Fixer: Zeta’s rules are PHPCS-native; php-cs-fixer may