Janus Laravel Package

Technical Evaluation

Architecture Fit

• Opportunity for Laravel-Specific Standardization: Janus provides a pre-configured, Laravel-aware toolchain for static analysis (PHPStan), code formatting (PHP-CS-Fixer), and Doctrine validation. It bridges the gap between generic PHP tools and Laravel’s conventions (e.g., Eloquent, Blade, Symfony components), making it ideal for teams prioritizing consistency without customization overhead.
• Symfony 8+ and Doctrine Focus: The package is optimized for modern Laravel stacks (Symfony 8+, Doctrine ORM), offering features like DQL type support and schema validation—critical for reducing runtime errors in data-layer code. This aligns with Laravel’s evolving architecture (e.g., Symfony integration in Laravel 10+).
• Composer Plugin Integration: The auto-execution via Composer plugin reduces friction for developers, ensuring checks run without manual CLI commands. This is a productivity multiplier for teams with CI/CD pipelines.
• PHPStan Enhancements: Custom rules (e.g., Task class naming) and PHPUnit extensions demonstrate Laravel-specific static analysis, addressing gaps in generic PHPStan configs.

Integration Feasibility

• Low-Coupling Design: Janus is configuration-first, meaning it can be adopted incrementally (e.g., start with PHP-CS-Fixer, then add PHPStan). The Composer plugin ensures zero-configuration adoption for basic use cases.
• Laravel Compatibility: Works alongside Laravel’s existing tooling (e.g., Pest, Doctrine Migrations) without conflicts. The Symfony 8+ requirement is a blocker only for legacy projects (pre-Laravel 9).
• CI/CD Readiness: Pre-configured for GitHub Actions, GitLab CI, or Jenkins with minimal setup. Example workflow:

  - name: Janus Linting
    run: composer janus
  

• Backward Compatibility: Supports BC layers for deprecated commands (e.g., init-symfony → init symfony), easing migration from custom setups.

Technical Risk

• Low Maintenance Risk: MIT-licensed with active development (releases every 6–12 months). The lack of stars/dependents is mitigated by:
  • Forkability: Customize rules via phpstan.neon or php-cs-fixer.php.
  • Symfony 8+ Focus: Aligns with Laravel’s future direction.
• Dependency Risks:
  • PHPStan v2: Requires PHPStan 2.x (no breaking changes from v1).
  • Symfony 8+: May need Laravel 9+ (Symfony 6+) for full compatibility.
• False Positives/Negatives:
  • Disabled rules (e.g., doctrine.columnType) may hide legitimate issues in Symfony forms. Requires manual review of suppressed checks.
  • PHPStan’s PHPUnit extension may need tuning for Pest test suites.

Key Questions for TPM

1. Stack Alignment:
   • Is the project using Laravel 9+ (Symfony 6+) or Symfony 8+ directly? If not, what’s the upgrade path?
   • Are we using Doctrine ORM? If yes, does Janus’s schema validation cover our use cases?
2. Customization Needs:
   • Do we need to override Janus’s rules (e.g., for project-specific naming conventions)?
   • How will we handle false positives (e.g., doctrine.columnType)?
3. CI/CD Impact:
   • What’s the expected runtime of Janus in CI? Will it slow down builds?
   • Should Janus run locally (via Composer plugin) or only in CI?
4. Toolchain Conflicts:
   • Are we using Pest instead of PHPUnit? Janus’s PHPUnit extension may need adjustments.
   • Do we have existing PHPStan/PHP-CS-Fixer configs that conflict with Janus’s defaults?
5. Long-Term Viability:
   • Given the lack of community adoption, should we fork and maintain Janus internally?
   • Are there alternatives (e.g., laravel-pint, custom PHPStan configs) that better fit our needs?

Integration Approach

Stack Fit

• Laravel Ecosystem: Janus is optimized for Laravel/Symfony projects, offering:
  • PHPStan: Laravel-specific rules (e.g., Eloquent method calls, Blade syntax).
  • PHP-CS-Fixer: Laravel-aware fixes (e.g., Blade template formatting).
  • Doctrine: Schema validation and DQL type support.
• Composer-Centric: Leverages Composer scripts/plugins, fitting seamlessly into Laravel’s dependency management.
• CI/CD Native: Designed for GitHub Actions/GitLab CI with pre-configured workflows.

Migration Path

1. Assessment Phase:
   • Audit existing PHPStan/PHP-CS-Fixer configs for conflicts.
   • Test Janus’s Symfony 8+ compatibility with the current stack.
2. Pilot Integration:
   • Add Janus to composer.json:

     "require-dev": {
       "21torr/janus": "^2.1"
     }
     

   • Run incrementally:
     • Start with composer janus check (PHP-CS-Fixer).
     • Add composer janus analyze (PHPStan) later.
3. Configuration Overrides:
   • Customize rules via .janus.php or override configs in phpstan.neon.
   • Example: Disable doctrine.columnType if it causes false positives:

     includes:
       - vendor/21torr/janus/phpstan.neon
     services:
       phpstan.doctrine.columnType: false
     

4. CI/CD Rollout:
   • Add to .github/workflows/linting.yml:

     - name: Janus
       run: composer janus
     

   • Optional: Enable Composer plugin for local checks:

     "scripts": {
       "post-install-cmd": ["@janus"]
     }
     

Compatibility

Sequencing

1. Phase 1: PHP-CS-Fixer (low risk, high ROI).
2. Phase 2: PHPStan (medium risk; validate against existing configs).
3. Phase 3: Doctrine validation (high impact for data-layer projects).
4. Phase 4: Composer plugin (optional; enables local checks).

Operational Impact

Maintenance

• Low Overhead:
  • Pre-configured: No need to maintain custom PHPStan/PHP-CS-Fixer rules.
  • Composer-Driven: Updates via composer update 21torr/janus.
• Customization Costs:
  • Rule Overrides: Requires .janus.php or config file edits.
  • False Positives: May need manual tuning (e.g., disabling doctrine.columnType).
• Dependency Updates:
  • PHPStan/PHP-CS-Fixer: Janus bumps versions; test for compatibility.

Support

• Developer Onboarding:
  • Pros: Reduces "why did my PR fail?" questions by standardizing checks.
  • Cons: Initial learning curve for Janus-specific commands (e.g., composer janus).
• Troubleshooting:
  • Verbose Output: Janus includes -v flags for PHPStan to debug errors.
  • Fallback: Can revert to manual PHPStan/PHP-CS-Fixer if issues arise.
• Community Support:
  • Limited: No stars/dependents; rely on GitHub issues or fork internally.

Scaling

• Performance:
  • PHP-CS-Fixer: Fast (~seconds for large codebases).
  • PHPStan: Slower (~minutes); optimize with parallelization or CI caching.
  • Doctrine Validation: Adds overhead for projects with complex schemas.
• Parallelization:
  • Run PHP