Janus Laravel Package

Product Decisions This Supports

• Standardization of Code Quality: Enables consistent enforcement of Laravel/Symfony-specific coding standards (e.g., Blade templates, Eloquent conventions, Doctrine DQL) across teams, reducing technical debt and improving maintainability. Aligns with initiatives to modernize legacy codebases or onboard new developers efficiently.
• Developer Productivity: Automates repetitive style checks (PHP-CS-Fixer, PHPStan) and static analysis, allowing engineers to focus on feature development. Reduces friction in PR feedback loops by catching formatting and logical errors early (e.g., Doctrine schema validation, custom PHPStan rules for Task classes).
• CI/CD Pipeline Optimization: Provides a lightweight, pre-configured way to integrate static analysis into build processes, ensuring quality gates are met without heavy tooling overhead. Supports Symfony 8+ and Doctrine, reducing false positives in CI (e.g., disabled doctrine.columnType rule).
• Build vs. Buy Decision: Justifies adopting a maintained, Laravel-aware solution over custom tooling for teams lacking resources to build or maintain bespoke linting rules. Ideal for projects where pragmatic standardization is prioritized over cutting-edge analysis.
• Roadmap Priorities:
  • Scaling Teams: Critical for distributed teams where consistency is harder to enforce (e.g., remote-first organizations).
  • Legacy Refactoring: Helps incrementally improve code quality in older Laravel projects with minimal disruption.
  • Open-Source Contributions: Ensures contributions adhere to project standards, reducing merge conflicts and reviewer burden.
  • Toolchain Modernization: Replaces ad-hoc or outdated linting configurations with a maintained, Laravel-specific solution (e.g., PHPStan v2 support, Symfony 8+ compatibility).
  • Security and Compliance: Validates Doctrine schemas in CI, reducing runtime errors and improving data integrity.

When to Consider This Package

• Adopt if:

  • Your project relies on Laravel/Symfony conventions (e.g., Blade templates, Eloquent, Doctrine) that generic tools like php-cs-fixer or pint don’t fully address.
  • You need pre-configured rules for PHPStan, PHP-CS-Fixer, and Doctrine without writing custom configs from scratch.
  • Your team lacks a dedicated code style guide or struggles to enforce it consistently (e.g., mixed snake_case/camelCase in Blade files).
  • You’re using Symfony 8+ or Doctrine and want optimized static analysis rules (e.g., DQL type support, schema validation in CI).
  • You prioritize lightweight integration into CI/CD (e.g., GitHub Actions) with minimal setup (e.g., Composer plugin for auto-execution).
  • Your project is mid-to-large (5+ developers) and needs to balance strictness with pragmatism (e.g., disabling false-positive rules like doctrine.columnType).
  • You want to reduce PR feedback noise by automating style checks (e.g., PHP-CS-Fixer) and static analysis (e.g., PHPStan with custom rules for Task classes).

• Look elsewhere if:

  • You already have a mature custom linting setup (e.g., heavily customized php-cs-fixer or pint configs) and don’t need Laravel-specific rules.
  • Your primary goal is advanced static analysis (e.g., security, performance) rather than style enforcement—consider Psalm or PHPStan directly with custom configurations.
  • Your project is small or solo-developed, where manual checks or simpler tools (e.g., pint) suffice.
  • The package’s lack of community adoption (0 stars, no dependents) raises concerns about long-term viability. Mitigate by:
    • Forking the repo to customize rules for your needs.
    • Treating it as a temporary solution until a more maintained alternative (e.g., Laravel’s official tooling) emerges.
  • You require real-time IDE feedback (e.g., PHPStorm integration) and need deeper tooling like PHPStan’s IDE helper or Infection for mutation testing.
  • Your project uses non-standard Laravel setups (e.g., heavy custom Doctrine configurations) that conflict with Janus’s pre-configured rules.

How to Pitch It (Stakeholders)

For Executives: "Janus is a low-code, high-impact tool that automates Laravel-specific code quality checks, saving our team time on manual reviews and reducing onboarding friction. By integrating it into our CI pipeline, we’ll catch formatting and logical errors early—freeing engineers to focus on high-impact work. It’s a minimal-effort, high-reward solution to professionalize our codebase, especially as we scale. With Symfony 8+ support and Doctrine validation, it’s future-proof for our tech stack. The MIT license ensures we can customize it without vendor lock-in."

For Engineering Leaders: *"This package bundles Laravel-optimized rules for tools we already use (PHPStan, PHP-CS-Fixer, Doctrine), so we don’t have to reinvent the wheel. Key benefits:

• Reduces PR noise by automating style and static analysis checks.
• Future-proofs our toolchain with Symfony 8+ and PHPStan v2 support.
• Integrates seamlessly into GitHub Actions or our CI in under an hour.
• Validates Doctrine schemas in CI, reducing runtime errors. Let’s pilot it on [Project X] to measure its impact on build times and developer productivity. If it cuts down on style-related feedback by 30%, we can roll it out company-wide. The Composer plugin even auto-runs Janus, further streamlining workflows."*

For Developers: *"No more debates over Blade template formatting or PHPStan errors in Doctrine queries. Janus enforces our team’s rules automatically—so your PRs pass checks faster, and you spend less time fixing formatting. Here’s how to use it:

• Run locally: php vendor/bin/janus check before committing.
• Let CI handle it: No more ‘please fix your indentation’ comments.
• Customize rules: Disable or tweak rules (e.g., doctrine.columnType) if needed. It’s MIT-licensed, so it’s safe to try. If it doesn’t fit, we can switch back to pint or php-cs-fixer easily. Bonus: It includes custom PHPStan rules for Task classes and Symfony 8+ support—so it’s ready for modern Laravel!"*

For Technical Architects: *"Janus addresses a critical gap in Laravel’s tooling ecosystem by providing pre-configured, opinionated static analysis tailored to Symfony 8+ and Doctrine. Key technical advantages:

• Reduces false positives in CI with Laravel-specific rule tweaks (e.g., disabled doctrine.columnType).
• Supports PHPStan v2 and includes extensions (e.g., PHPUnit, staabm/phpstan-todo-by).
• Validates Doctrine schemas in CI, improving data integrity.
• Composer plugin enables auto-execution, reducing manual setup.
• Lightweight: No heavy dependencies; integrates with existing workflows. Recommendation: Adopt as a standardized baseline for new projects and legacy refactoring. Pair with custom rules for project-specific needs (e.g., custom PHPStan rules for domain logic)."*