Laravel Package Tools Laravel Package

Technical Evaluation

Architecture Fit

• Modularity & Opinionated Structure: The package enforces a standardized directory structure (e.g., src/, config/, resources/) and lifecycle hooks, aligning with Laravel’s ecosystem. This reduces cognitive load for developers familiar with Laravel conventions.
• Decoupling: The PackageServiceProvider abstracts registration logic (config, migrations, routes, etc.), enabling clean separation between package internals and host application code.
• Extensibility: Supports customization via configurePackage() and lifecycle hooks (e.g., booted(), register()), allowing TPMs to adapt the package to niche use cases without forking.
• Laravel-Centric: Deep integration with Laravel’s service container, Artisan commands, and publishable resources (e.g., vendor:publish) ensures seamless adoption.

Integration Feasibility

• Low Friction: Designed for Laravel packages, requiring minimal host-app changes (e.g., no manual service provider registration if using hasInstallCommand).
• Dependency Management: Leverages Composer autoloading and Laravel’s package discovery, reducing manual configuration.
• Version Compatibility: Actively maintained (last release: 2026-05-19) with broad Laravel version support (tested against LTS releases).
• Tooling Synergy: Works with Spatie’s package-skeleton-laravel repo, providing a pre-configured starter template.

Technical Risk

• Opinionated Design: The rigid directory structure may conflict with existing package architectures or custom workflows (e.g., non-Laravel PHP projects).
• Migration Complexity: Automatic migration discovery (discoversMigrations()) could lead to unintended side effects if migrations are poorly named or depend on host-app schema.
• Publishable Resources: Overuse of vendor:publish tags might clutter the host app’s publishable assets, requiring disciplined tag naming (e.g., {package-name}-{resource-type}).
• Inertia/Vue.js Dependencies: Inertia component support assumes Laravel’s Inertia integration, adding complexity for non-Inertia projects.

Key Questions

1. Host App Compatibility:
   • Does the target Laravel version (e.g., 10.x vs. 11.x) align with the package’s tested versions?
   • Are there existing service providers or migrations in the host app that could conflict with the package’s auto-registration?
2. Customization Needs:
   • Does the package’s opinionated structure (e.g., src/, resources/dist/) conflict with the team’s preferred architecture?
   • Are there requirements for dynamic configuration (e.g., runtime package behavior changes) beyond what configurePackage() offers?
3. Performance:
   • Could the package’s asset/publishable resource handling introduce latency during vendor:publish or package bootstrapping?
   • Are there plans to scale the package’s usage across multiple Laravel instances (e.g., microservices)?
4. Maintenance Overhead:
   • How will the team handle updates to the package (e.g., breaking changes in PackageServiceProvider)?
   • Are there internal tools or CI/CD pipelines that need to adapt to the package’s lifecycle hooks (e.g., booted())?

Integration Approach

Stack Fit

• Primary Use Case: Ideal for Laravel-first projects where the goal is to distribute reusable functionality (e.g., auth modules, reporting tools, or domain-specific features) as Composer packages.
• Secondary Use Case: Useful for monorepos or modular Laravel apps where teams want to enforce consistency across sub-packages.
• Non-Fit Scenarios:
  • Non-Laravel PHP applications (e.g., Symfony, Lumen).
  • Projects requiring dynamic package loading (e.g., plugins loaded at runtime).
  • Teams with strict custom directory structures (e.g., app/Packages/ instead of src/).

Migration Path

1. Assessment Phase:
   • Audit existing package structure against Spatie’s skeleton (e.g., src/, config/, resources/).
   • Identify conflicts (e.g., custom service providers, non-standard migration paths).
2. Refactor Phase:
   • Option A (Greenfield): Use package-skeleton-laravel as a template for new packages.
   • Option B (Incremental): Gradually adopt the package’s patterns (e.g., start with hasConfigFile() and hasMigrations()).
3. Integration Phase:
   • Replace custom package bootstrapping (e.g., manual ServiceProvider::register() calls) with PackageServiceProvider.
   • Update composer.json to include the package and its dependencies.
   • Implement configurePackage() in the existing service provider.
4. Testing Phase:
   • Verify publishable resources (e.g., vendor:publish --tag={package}-config).
   • Test lifecycle hooks (e.g., booted() for post-registration logic).
   • Validate migration auto-discovery or manual registration.

Compatibility

• Laravel Versions: Confirm compatibility with the host app’s Laravel version (e.g., package supports 8.0+; host uses 10.x).
• PHP Extensions: Ensure no missing dependencies (e.g., spatie/laravel-package-tools has minimal PHP requirements).
• Third-Party Conflicts: Check for overlapping vendor:publish tags or service provider names.
• IDE/Tooling: Update IDE configurations (e.g., PHPStorm’s Composer autoloading) to recognize new package paths.

Sequencing

1. Core Dependencies:
   • Install spatie/laravel-package-tools via Composer.
   • Extend PackageServiceProvider in the package’s main provider.
2. Resource Registration:
   • Declare config files, migrations, and routes in configurePackage().
   • Publish stubs (e.g., resources/stubs/{Provider}.php.stub) for service providers.
3. User Experience:
   • Implement an InstallCommand to automate vendor:publish for end users.
   • Document custom tags (e.g., {package}-assets) for clarity.
4. Validation:
   • Add tests for package bootstrapping, publishable resources, and lifecycle hooks.
   • Test edge cases (e.g., duplicate migrations, missing config files).

Operational Impact

Maintenance

• Package Updates:
  • Monitor Spatie’s release notes for breaking changes (e.g., PackageServiceProvider API updates).
  • Update composer.json constraints to pin major versions (e.g., ^2.0).
• Dependency Management:
  • Track transitive dependencies (e.g., spatie/laravel-package-tools may pull in spatie/laravel-permission).
  • Use composer why-not to audit dependency conflicts.
• Custom Logic:
  • Isolate package-specific logic in booted() or register() to minimize merge conflicts during updates.

Support

• Debugging:
  • Leverage Spatie’s GitHub issues and documentation for common problems (e.g., migration publishing failures).
  • Add logging in configurePackage() for troubleshooting (e.g., Log::debug('Package configured:', $package->toArray())).
• User Guidance:
  • Document vendor:publish tags and their purposes (e.g., {package}-migrations vs. {package}-config).
  • Provide a README example for end users (e.g., "Run php artisan vendor:publish --tag={package}-assets to install CSS").
• Rollback Plan:
  • Maintain a backup of custom service providers or migrations if auto-registration is disabled.

Scaling

• Multi-Package Environments:
  • Use unique vendor:publish tags to avoid collisions (e.g., acme-auth-config vs. acme-billing-config).
  • Consider namespacing publishable resources (e.g., public/vendor/{package-name}/).
• Performance:
  • Avoid discoversMigrations() in large packages; explicitly list migrations to reduce discovery overhead.
  • Lazy-load heavy resources (e.g., assets) via conditional hasAssets() registration.
• Distributed Systems:
  • For microservices, ensure migrations are idempotent and use runsMigrations() judiciously to avoid race conditions.

Failure Modes