Stubs Laravel Package

Technical Evaluation

Architecture Fit

• Low architectural impact: This package provides stubs (type hints and method signatures) for the php-decimal extension, enabling better IDE autocompletion, static analysis (e.g., PHPStan, Psalm), and tooling support (e.g., PHPStorm, VSCode). It does not modify runtime behavior—it’s purely a developer experience (DX) enhancement.
• Complementary to php-decimal: Requires the underlying php-decimal/php-decimal extension to be installed and functional. Without it, the stubs are inert.
• Isolation: Stubs are self-contained and can be added to any project using php-decimal without coupling to other systems.

Integration Feasibility

• Minimal setup: Requires only:
  1. Installation of the php-decimal extension (PECL or Docker-based).
  2. Composer dependency addition (php-decimal/stubs).
  3. IDE/configuration updates (e.g., enabling stubs in PHPStorm or psalm.xml).
• No runtime dependencies: Stubs are static files—no PHP runtime changes or configuration overrides needed.
• Toolchain compatibility:
  • IDE Support: Works with PHPStorm, VSCode (with Intelephense), and other editors using PHP language servers.
  • Static Analysis: Integrates with PHPStan, Psalm, and similar tools via their stub-loading mechanisms.
  • CI/CD: No impact on build pipelines unless static analysis is part of the workflow.

Technical Risk

• False positives/negatives: Stubs may not perfectly match the actual php-decimal extension’s behavior, leading to:
  • IDE warnings about "undefined methods" (if stubs lag behind the extension).
  • Static analysis errors (e.g., Psalm flagging unused stubs or missing signatures).
  • Mitigation: Validate stubs against the latest php-decimal extension version.
• Extension compatibility: If php-decimal evolves (e.g., new methods, deprecated features), stubs may become stale.
  • Mitigation: Monitor php-decimal updates and refresh stubs as needed.
• IDE-specific quirks: Some IDEs (e.g., PHPStorm) may require manual stub path configuration.
  • Mitigation: Document IDE-specific setup in internal runbooks.

Key Questions

1. Does the team use static analysis (PHPStan/Psalm)?
   • If yes, stubs will directly improve code quality checks.
   • If no, the value is limited to IDE DX.
2. Is php-decimal already in use, or is this a new adoption?
   • If new, assess whether the extension’s runtime benefits justify the stubs’ DX improvements.
3. What IDEs/tools are standardized in the org?
   • Ensure stubs work with the primary tools (e.g., PHPStorm vs. VSCode).
4. How is the php-decimal extension versioned?
   • Stubs must align with the deployed extension version to avoid mismatches.
5. Are there existing stubs or type hints for php-decimal?
   • Avoid duplication if another solution (e.g., custom stubs) exists.

Integration Approach

Stack Fit

• PHP-centric stacks: Ideal for projects using:
  • Laravel, Symfony, or other PHP frameworks leveraging php-decimal for precise decimal arithmetic (e.g., financial apps).
  • Monolithic PHP apps where IDE DX is critical for maintainability.
• Non-PHP stacks: No direct relevance (stubs are PHP-specific).
• Toolchain dependencies:
  • IDE: Requires IDEs with stub support (e.g., PHPStorm, VSCode with Intelephense).
  • Static Analysis: Works with tools that load stubs (PHPStan, Psalm, Rector).
  • CI/CD: Optional but recommended for static analysis integration.

Migration Path

1. Pre-requisite: Ensure php-decimal extension is installed and functional.
   • Verify via php -m | grep decimal or php -r 'var_dump(class_exists("Decimal"));'.
2. Add stubs to Composer:

   composer require --dev php-decimal/stubs
   

3. Configure IDE:
   • PHPStorm: Add stubs path in Settings > Languages & Frameworks > PHP > Stub files.
   • VSCode: Ensure Intelephense is configured to load Composer stubs.
4. Static Analysis Setup:
   • PHPStan: Add to psalm.xml:

     <file-list include-internal-dirs="true">
       <directory>vendor/php-decimal/stubs</directory>
     </file-list>
     

   • Psalm: Similar configuration in psalm.xml.
5. Validate:
   • Test IDE autocompletion for Decimal class methods.
   • Run static analysis to confirm no stub-related errors.

Compatibility

• Backward compatibility: Stubs are additive—no breaking changes unless php-decimal itself changes.
• Version alignment: Stubs must match the php-decimal version in use.
  • Example: If using php-decimal:1.3.0, ensure stubs are from the same release.
• IDE agnosticism: Stubs are language-agnostic but require IDE/tool support.

Sequencing

1. Phase 1: Install php-decimal extension and test basic functionality.
2. Phase 2: Add stubs to a non-production environment (e.g., dev branch).
3. Phase 3: Configure IDEs and static analysis tools.
4. Phase 4: Roll out to production environments (if static analysis is part of CI).
5. Phase 5: Monitor for stub-related issues (e.g., false positives) and update as needed.

Operational Impact

Maintenance

• Low ongoing effort:
  • Stubs are static files—no runtime maintenance required.
  • Updates only needed when php-decimal extension changes.
• Dependency management:
  • Track php-decimal/stubs updates alongside the extension.
  • Consider pinning versions in composer.json to avoid surprises:

    "require-dev": {
      "php-decimal/stubs": "1.3.0"
    }
    

• IDE/tool updates:
  • Ensure IDEs and static analysis tools are updated to support the latest stub formats.

Support

• Troubleshooting:
  • Common issues:
    • Stubs not loading (check IDE/tool configuration).
    • Mismatched stubs/extension versions (validate alignment).
  • Debugging: Use composer show php-decimal/stubs to verify installed version.
• Documentation:
  • Create internal docs for:
    • IDE setup steps.
    • Static analysis configuration.
    • Version alignment procedures.
• Escalation paths:
  • For stub-related bugs, open issues in the php-decimal/stubs repo.
  • For php-decimal extension issues, use its issue tracker.

Scaling

• Performance impact: None—stubs are static and loaded at IDE/tool startup.
• Team adoption:
  • Pros: Improves DX for all developers using php-decimal.
  • Cons: Minimal value if team doesn’t use IDEs/static analysis.
• Large teams:
  • Standardize IDE/tool configurations to avoid fragmentation.
  • Consider CI checks for stub compatibility (e.g., PHPStan in PR pipelines).

Failure Modes

Ramp-Up

• Developer onboarding:
  • Time to benefit: Immediate for IDE autocompletion; 1–2 hours for static analysis setup.
  • Training needed: Minimal—stubs are passive. Focus on IDE/tool configuration.
• Team adoption barriers:
  • Low: No runtime changes; purely a DX improvement.
  • High: If team resists static analysis or IDE tooling.
• Pilot recommendation:
  • Test with a small team (e.g., backend developers) before org-wide rollout.
  • Measure metrics like:
    • Reduction in IDE-related questions (e.g., "Why isn’t this method showing?").
    • Static analysis error resolution time.