Phpstan Rules Laravel Package

Product Decisions This Supports

• Enhanced Developer Productivity: Integrate Solido-specific static analysis into the development workflow to catch DTO-related bugs early, reducing debugging time and improving code quality. This aligns with shift-left testing principles, where issues are identified during development rather than in production.
• Architectural Consistency: Enforce Solido’s domain-driven design (DDD) patterns (e.g., DTO immutability, repository interactions) across the codebase, ensuring consistency and reducing technical debt. This is particularly valuable for teams adopting Solido’s enhanced DTOs or migrating legacy systems to a DDD architecture.
• Build vs. Buy Decision: Avoid reinventing custom PHPStan rules for Solido-specific patterns (e.g., DTO validation, repository safety checks) by leveraging this lightweight, maintained package. This reduces development effort and ensures alignment with Solido’s evolving conventions.
• Scalability for Growth: Standardize static analysis across multiple teams or microservices using Solido, ensuring uniform enforcement of architectural rules. This is critical for scaling development in large organizations or when adopting a modular architecture.
• Risk Mitigation: Proactively identify type-related vulnerabilities (e.g., invalid DTO usage, type mismatches) that could lead to security flaws (e.g., injection risks) or performance bottlenecks (e.g., inefficient data transfers). This aligns with secure coding practices and performance optimization goals.
• Toolchain Modernization: Justify investment in modern PHP tooling (e.g., PHPStan, Solido) by demonstrating tangible benefits like fewer runtime errors, faster onboarding, and improved maintainability. This supports broader initiatives to upgrade legacy systems or adopt best practices in static analysis.

When to Consider This Package

• Already Using Solido Suite: Only relevant if your project relies on Solido’s DTOs, repositories, or domain-driven patterns. Not suitable for general PHP projects or those using alternative frameworks (e.g., Symfony, Laravel without Solido).
• Need for DTO-Specific Enforcement: Ideal if you want to enforce rules such as:
  • DTO Instantiation: Prevent direct new calls for DTOs (enforce factory methods or builders).
  • Property Access: Validate that only allowed properties are accessed (e.g., no dynamic property access).
  • Type Safety: Catch type mismatches in DTO properties or repository interactions.
  • Interface Exclusions: Skip validation for non-DTO interfaces (e.g., NonDTOInterface) to avoid false positives.
• Existing PHPStan Integration: Requires an active PHPStan setup (e.g., configured in phpstan.neon, integrated into CI/CD). Not a standalone solution—assumes PHPStan is already part of your toolchain.
• Small to Medium Projects: Low overhead (minimal configuration, 2 stars) makes it suitable for teams already familiar with PHPStan. Larger teams may need to customize or extend the rules further.
• High-Assurance or Legacy Modernization: Particularly valuable for projects where DTOs are critical (e.g., APIs, financial systems) or where legacy code is being refactored to adopt Solido patterns.
• Not for General PHPStan Needs: Look elsewhere (e.g., phpstan/phpstan, phpstan/extension-installer) if you need broader static analysis without Solido-specific rules or lack expertise in custom PHPStan rules.

Avoid if:

• You’re not using Solido’s DTOs or repositories.
• Your team lacks PHPStan expertise (custom rules require understanding of PHPStan’s configuration and error reporting).
• You need enterprise-grade support (package is niche, unmaintained, and lacks community backing).
• Your project uses alternative DTO patterns (e.g., Symfony’s native DTOs, Laravel’s collections) that don’t align with Solido’s conventions.

How to Pitch It (Stakeholders)

For Executives:

"This package helps us automate code quality checks for Solido’s DTOs and repositories, catching critical bugs early and reducing costly fixes in production. For example, it prevents invalid DTO usage—like creating objects directly—which could lead to runtime errors or security vulnerabilities. With minimal setup, it integrates into our existing PHPStan pipeline, saving development time and improving reliability. Think of it as a ‘linter for Solido patterns’: low effort, high impact for teams using this framework.

Key Benefits:

• Fewer production bugs related to DTOs or repositories.
• Faster developer onboarding with clear error messages and standardized rules.
• Alignment with our Solido investment, ensuring we follow best practices for domain-driven design.
• Proactive risk mitigation by catching type-related issues before they reach production.

ROI: Reduced debugging time, fewer security risks, and consistent code quality across teams."

For Engineering (Developers/Tech Leads):

*"This adds Solido-specific PHPStan rules to enforce critical patterns in our codebase, such as:

• DTO Purity: No direct instantiation (e.g., new UserDTO()), ensuring we use factory methods or builders.
• Property Access: Validates that only allowed properties are accessed, preventing dynamic or invalid property calls.
• Type Safety: Catches mismatches in DTO properties or repository interactions, reducing runtime errors.
• Interface Exclusions: Skips validation for non-DTO interfaces (e.g., NonDTOInterface) to avoid false positives.

Why Adopt Now?

• We’re adopting Solido’s DTOs/repositories—this ensures we don’t introduce technical debt early on.
• Configuration is simple: Add DTO namespaces to phpstan.neon and exclude interfaces as needed.
• It runs in our existing CI pipeline with no major overhead.

Trade-offs:

• Requires PHPStan to be set up (but we already use it).
• Rules are opinionated—we’ll need to review defaults (e.g., excluded interfaces) and suppress rules where necessary.

Next Steps:

1. Install the package and configure phpstan.neon with our DTO namespaces.
2. Run locally to identify false positives/negatives and adjust the configuration.
3. Gradually enforce rules in CI/CD, starting with warnings before moving to errors."

For Engineering (Architects/Tech Leads):

*"This package addresses architectural consistency and risk reduction by enforcing Solido’s DTO and repository patterns through static analysis. Here’s how it fits into our broader goals:

Key Architectural Benefits:

• Enforces DDD Principles: Ensures DTOs are used correctly (e.g., immutability, property access rules), aligning with our domain-driven design.
• Reduces Technical Debt: Catches violations early, preventing anti-patterns (e.g., mutable DTOs, invalid type usage) from persisting.
• Supports Modularity: Works seamlessly across microservices or teams using Solido, ensuring uniform enforcement of rules.

Integration Considerations:

• Performance: Rules add static analysis overhead; benchmark with large codebases to validate scalability.
• Extensibility: Customize rules via extension.neon if Solido’s conventions evolve (e.g., new interfaces or annotations).
• CI/CD Impact: Start with warnings to allow teams to adapt, then enforce as errors once adoption is confirmed.

Recommendation: Adopt this as part of our Solido migration strategy, particularly for projects where DTOs are critical (e.g., APIs, domain services). Pair it with team training on Solido’s DTO patterns to minimize false positives."