Laravel Stubs Laravel Package

Technical Evaluation

Architecture Fit

• Pros:
  • Expanded Laravel 13.x support aligns with the latest LTS release, ensuring long-term compatibility.
  • PHP 8.5 support future-proofs the package against upcoming PHP updates.
  • Continues to adhere to modern Laravel/PHP best practices (strict types, minimalism, no forced opinions).
  • No breaking changes in this release, maintaining backward compatibility with v2.0.0.
• Cons:
  • Opinionated nature remains unchanged (e.g., no down() migrations, minimal docblocks), which may still conflict with team conventions.
  • Lack of down() migrations persists as a potential workflow disruptor for rollback-heavy projects.
  • No trait inheritance in controllers still requires manual adjustments for shared logic.
  • Removed docblocks may continue to impact onboarding for less experienced developers.

Integration Feasibility

• Low-risk for new projects: Ideal for greenfield projects on Laravel 11–13.x and PHP 8.2–8.5.
• Moderate risk for existing projects:
  • Laravel 13.x adoption: Teams upgrading to Laravel 13.x can now leverage this package natively.
  • PHP 8.5 readiness: Early adopters of PHP 8.5 can integrate without compatibility concerns.
  • Requires team alignment on stub preferences (e.g., no down() migrations, guarded attributes).
  • May need custom overrides for stubs not covered (e.g., policies, observers).
• Package support: Continues to work with orchestra/canvas for package development.

Technical Risk

• Minimal: Release is non-breaking, well-tested, and MIT-licensed.
• Potential pitfalls:
  • Laravel 13.x-specific features: Teams using experimental Laravel 13.x features may encounter edge cases.
  • PHP 8.5-specific behaviors: New PHP 8.5 features (e.g., typed class constants) may interact unexpectedly with generated stubs.
  • Backward compatibility: Teams using Laravel <11.x or PHP <8.2 will still need upgrades.
  • Tooling conflicts: Conflicts may arise with other stub packages (e.g., laravel-shift/stubs).

Key Questions

1. Team alignment: Does the team agree with the stub opinions (e.g., no down() migrations, no guarded attributes)?
2. Migration strategy: How will existing stubs be transitioned without breaking workflows?
3. Customization needs: Are there stubs (e.g., policies, observers) not covered that require customization?
4. CI/CD impact: Will the absence of down() migrations affect rollback testing?
5. Onboarding: How will new developers adapt to minimal docblocks and strict typing?
6. Package compatibility: If used with orchestra/canvas, is the namespace/configuration overhead justified?
7. Laravel 13.x readiness: Are there Laravel 13.x-specific features (e.g., new CLI commands, bootstrapping) that could conflict with stubs?
8. PHP 8.5 adoption: Does the team plan to adopt PHP 8.5, and are there potential interactions with new PHP features?

Integration Approach

Stack Fit

• Best for:
  • Modern Laravel stacks (11–13.x) with PHP 8.2–8.5.
  • Teams prioritizing clean, minimal boilerplate and strict typing.
  • Projects using orchestra/canvas for package development.
  • Teams upgrading to Laravel 13.x or adopting PHP 8.5.
• Less ideal for:
  • Legacy Laravel projects (<11.x) or PHP <8.2.
  • Teams requiring detailed docblocks or base controllers.
  • Workflows heavily reliant on migration rollbacks (down()).

Migration Path

1. Pilot phase:
   • Install in dev dependencies (composer require --dev rawilk/laravel-stubs:^2.1).
   • Publish stubs (php artisan custom-stub:publish) and test with a non-critical feature in Laravel 13.x (if applicable).
   • Compare generated files against default Laravel stubs.
2. Gradual rollout:
   • Update composer.json to auto-publish stubs on post-update-cmd:

     "scripts": {
       "post-update-cmd": ["@php artisan custom-stub:publish --force"]
     }
     

   • Train developers on the new stub conventions, emphasizing Laravel 13.x and PHP 8.5 compatibility.
3. Full adoption:
   • Remove default Laravel stubs (if desired) by configuring config/stubs.php.
   • Update CI/CD pipelines to account for down() migration removal and test in Laravel 13.x environments.

Compatibility

• Laravel: 11.x–13.x (tested; 10.x via v1.1.4).
• PHP: 8.2–8.5 (8.1 may work but untested).
• Tooling:
  • Works with orchestra/canvas for package development.
  • May conflict with other stub packages (e.g., laravel-shift/stubs).
• Database: down() migrations removed; rollbacks must use alternative strategies (e.g., manual SQL or third-party tools like laravel-migration-generator).
• Laravel 13.x: Test for compatibility with new features (e.g., bootstrap/app.php, bootstrap/providers.php).

Sequencing

1. Prerequisites:
   • Upgrade Laravel/PHP to supported versions if needed (especially for Laravel 13.x).
   • Resolve any existing stub customizations.
2. Core integration:
   • Install and publish stubs.
   • Test artifact generation (migrations, models, controllers) in Laravel 13.x (if applicable).
3. Workflow adjustments:
   • Update documentation/onboarding for new stub conventions and Laravel 13.x changes.
   • Modify CI/CD to handle down() migration removal and test in PHP 8.5 environments.
4. Validation:
   • Audit generated code for compliance with team standards in Laravel 13.x.
   • Gather feedback from developers on usability, especially regarding PHP 8.5 interactions.

Operational Impact

Maintenance

• Pros:
  • Reduced boilerplate lowers maintenance overhead for scaffolding.
  • Strict typing (declare(strict_types=1)) catches type-related bugs early.
  • Minimal stubs reduce merge conflicts in shared projects.
  • Laravel 13.x support ensures alignment with the latest framework updates.
• Cons:
  • Custom stubs: Any deviations from the package’s opinions will require manual maintenance.
  • Rollback strategy: Teams must implement alternatives to down() migrations (e.g., database backups, custom scripts).
  • Documentation: Team must document the rationale behind stub choices and Laravel 13.x-specific adjustments.
  • PHP 8.5 interactions: New PHP features may require updates to stubs or generated code.

Support

• Developer ramp-up:
  • Pros: Strict typing and minimalism may appeal to experienced developers.
  • Cons: New developers may struggle with missing docblocks or unfamiliar stub structures, especially in Laravel 13.x.
  • Mitigation: Provide a stub comparison guide (e.g., "Default Laravel vs. Custom Stubs") and highlight Laravel 13.x changes.
• Troubleshooting:
  • Issues likely stem from opinion clashes (e.g., guarded attributes, base controllers) or Laravel 13.x-specific quirks.
  • Debugging may require reverting to default stubs temporarily or testing in PHP 8.5.
• Community support:
  • Low-starred package; rely on GitHub issues or author responses for help, especially regarding Laravel 13.x or PHP 8.5.

Scaling

• Performance: No runtime impact; stubs only affect code generation.
• Team scaling:
  • Pros: Consistent stubs reduce onboarding time for new hires, and Laravel 13.x support future-proofs the stack.
  • Cons: Opinionated choices may limit flexibility as the team grows, especially with PHP 8.5 features.
• Multi-repo projects:
  • Useful for monorepos or shared packages via orchestra/canvas.
  • Ensure stubs are version-controlled and consistent across repos, including Laravel 13.x-specific adjustments.

Failure Modes