Eloquent Publishing Laravel Package

Technical Evaluation

Architecture Fit

• Pros:

  • Enhanced Laravel Compatibility: Now requires Laravel 11+ and PHP 8.2+, aligning with modern Laravel LTS releases (11.x is the current LTS as of 2024). Reduces technical debt by enforcing newer, more secure PHP features (e.g., named arguments, enums).
  • Future-Proofing: Drops legacy support (Laravel 10/PHP 8.1), ensuring compatibility with upcoming Laravel 12/13 features and PHP 8.3+.
  • Query Scope Optimizations: Underlying query scopes are likely optimized for newer Laravel versions (e.g., improved whereNotNull handling in Eloquent 11).
  • Event-Driven Extensibility: Events remain a core feature, now tested with Laravel 11’s updated event system (e.g., ShouldQueue improvements).
  • Customization Flexibility: Supports newer PHP features like enums for publish statuses (if extended via custom traits).

• Cons:

  • Breaking Change: Laravel 10/PHP 8.1 no longer supported—requires upgrade path planning for projects on older stacks.
  • Limited to Eloquent 11+: Newer Laravel features (e.g., Model::newQueryWithoutScopes()) may interact differently with query scopes.
  • No Backward Compatibility: Existing projects must update dependencies, risking untested edge cases in custom logic.
  • PHP 8.2+ Requirement: May block integration with legacy systems or shared hosting environments.

Integration Feasibility

• Moderate Risk: Upgrade path introduces dependency changes but maintains the same core functionality.
  • Dependencies:
    • Laravel 11+: Requires updating framework, packages (e.g., laravel/framework), and PHP extensions (e.g., pdo_mysql).
    • PHP 8.2+: May need runtime updates (e.g., ext-intl, ext-mbstring).
  • Database Impact: No schema changes, but indexing recommendations (e.g., published_at) may need review for Laravel 11’s query optimizer.
  • Migration Effort: Higher due to Laravel/PHP version bump, but the package itself requires minimal changes (e.g., trait usage remains identical).

Technical Risk

• Critical Risks:

  • Laravel 11 Upgrade Risks:
    • Service Provider Changes: Laravel 11 uses App\Providers\AppServiceProvider differently (e.g., boot() → register()).
    • Route/Controller Updates: If using API routes or controllers, Laravel 11’s Route::macro() behavior may change.
    • Testing Framework: Pest 2.0+ is now default; update test suites if using older Pest/PHPUnit.
  • PHP 8.2 Breaking Changes:
    • Deprecated Features: create_function(), dynamic properties (if used in custom logic).
    • Type System: Stricter union types or attribute parsing may affect custom event listeners.
  • Package-Specific Risks:
    • Query Scope Behavior: Laravel 11’s QueryBuilder may optimize scopes differently (test onlyPublished() performance).
    • Event Dispatching: Laravel 11’s event system uses Illuminate\Events\Dispatcher under the hood; ensure custom listeners are compatible.

• Mitigation Strategies:

  • Upgrade Incrementally:
    1. Test Laravel 11 in a staging environment with the same PHP version as production.
    2. Use laravel-upgrade tool to automate dependency updates:

       composer require --dev laravel/upgrade-tool && vendor/bin/laravel-upgrade --target=11.x
       

  • Isolate Changes:
    • Start with a non-critical branch to test the package + Laravel 11.
    • Use feature flags to toggle publish functionality during rollout.
  • Fallback Plan:
    • Downgrade to 3.3.x if critical issues arise (but lose security updates).

Key Questions

1. Upgrade Feasibility:
   • Can the project upgrade Laravel to 11+ and PHP to 8.2+ within the next 3 months? If not, is 3.3.x a viable long-term option?
   • Are there third-party packages (e.g., spatie/laravel-permission) that block Laravel 11 upgrades?
2. Custom Logic Impact:
   • Does the project use custom event listeners or query scope modifications that might break in Laravel 11?
   • Are there dynamic properties or deprecated PHP features in existing code?
3. Performance Baseline:
   • How do onlyPublished() and latestPlanned() perform under Laravel 11’s query builder? (Test with DB::enableQueryLog().)
4. Testing Strategy:
   • How will Laravel 11’s testing improvements (e.g., Pest 2.0) affect the CI pipeline?
   • Should upgrade tests be added to validate the package + new Laravel version?
5. Rollback Plan:
   • What’s the downgrade path if the upgrade introduces critical bugs? (e.g., pin lemaur/eloquent-publishing:3.3.0.)

Integration Approach

Stack Fit

• Ideal For:
  • Modern Laravel Projects: Teams already on Laravel 11+ or planning to upgrade.
  • PHP 8.2+ Environments: Cloud providers (e.g., Laravel Forge, Heroku) or self-hosted setups with updated runtimes.
  • New Features: Projects leveraging Laravel 11’s improvements (e.g., Model::newQuery(), Route::macro changes).
• Less Suitable For:
  • Legacy Systems: Projects stuck on Laravel 10/PHP 8.1 due to vendor constraints.
  • Shared Hosting: Environments with PHP <8.2 (e.g., older cPanel setups).
  • High-Risk Upgrades: Teams without staging environments or CI/CD pipelines for testing.

Migration Path

1. Pre-Upgrade Assessment:
   • Run composer why-not laravel/framework 11.x to identify blocking dependencies.
   • Audit composer.json for PHP 8.2+ compatibility (e.g., ext-json version).
2. Upgrade Steps:
   • Step 1: Update composer.json:

     "require": {
         "laravel/framework": "^11.0",
         "php": "^8.2"
     },
     "lemaur/eloquent-publishing": "^4.0"
     

   • Step 2: Run composer update and resolve conflicts.
   • Step 3: Update Laravel config (e.g., APP_URL, SESSION_DOMAIN) if using new defaults.
   • Step 4: Test the package in isolation:

     use LeMaur\EloquentPublishing\Publishes;
     
     class Post extends Model {
         use Publishes;
     }
     

   • Step 5: Gradually roll out to models (start with Post, Product).
3. Post-Upgrade Validation:
   • Query Scopes: Verify onlyPublished() and latestPlanned() work as expected.
   • Events: Test custom listeners for Laravel 11’s event system changes.
   • Performance: Compare query execution plans before/after upgrade.

Compatibility

• Laravel 11:
  • Breaking Changes:
    • RouteServiceProvider → Route::macro (affects custom route logic).
    • HasFactory trait changes (if using custom factories).
    • Artisan::call() behavior (if used in custom commands).
  • New Features:
    • Improved Query Builder: May optimize whereNotNull in query scopes.
    • Pest 2.0: Better testing support for event listeners.
• PHP 8.2:
  • New Features:
    • Readonly Properties: Can be used in models for immutable fields.
    • Enums: Enable type-safe publish statuses (e.g., enum PublishStatus).
  • Deprecations:
    • create_function(), call_user_func_array() with variadic args.
• Database:
  • Laravel 11’s Schema builder may handle published_at indexes differently; verify with php artisan schema:dump.

Sequencing

1. Phase 1: Dependency Upgrade
   • Upgrade Laravel/PHP in a staging environment first.
   • Test the package in isolation before integrating with models.
2. Phase 2: Model Integration
   • Start with low-traffic models (e.g., BlogPost).
   • Use database backups before adding published_at columns.
3. Phase 3: Feature Rollout
   • Enable publish functionality via feature flags.