Laravel Publishable Laravel Package

Technical Evaluation

Architecture Fit

• State Management: The package provides a standardized 4-state workflow (draft, published, unpublished, scheduled) with published_first_at for chronological ordering, which is ideal for content-heavy applications (e.g., blogs, news sites, marketing pages). This reduces boilerplate and enforces consistency across models.
• Eloquent Integration: Leverages Eloquent macros and traits, ensuring minimal disruption to existing codebases. The publishable() migration macro simplifies schema changes, while the trait adds publishable behavior without requiring base class inheritance.
• Query Scoping: Built-in scopes (published(), draft(), scheduled()) streamline filtering, reducing manual query complexity. The published_first_at field enables efficient sorting and caching strategies.
• Extensibility: While opinionated (4 states), the package can be extended for custom logic (e.g., additional states, validation) via model methods or observers.
• Soft Deletes Compatibility: Works alongside Laravel’s SoftDeletes, though explicit handling is needed to avoid conflicts (e.g., a soft-deleted record cannot be unpublished).

Integration Feasibility

• Low Coupling: Adoptable model-by-model, making it suitable for gradual migration in large codebases.
• Minimal Schema Changes: The publishable() macro adds only 3 columns (status, published_first_at, published_at), requiring no complex refactoring.
• Nova/Laravel Agnostic: Core functionality works in vanilla Laravel, though the laravel-nova-publishable extension (if used) adds Nova-specific tooling.
• Event-Driven Potential: Can be paired with Laravel events (e.g., published, unpublished) to trigger workflows like notifications or cache invalidation.

Technical Risk

• State Transition Logic: The package does not enforce business rules (e.g., who can publish). Custom validation or policies are required, adding complexity.
• Performance: Heavy reliance on published_first_at for sorting may need database indexing to avoid performance degradation.
• AGPL License: Incompatible with proprietary SaaS unless relicensed. Requires legal review for commercial use.
• Limited Adoption: Low stars/dependents suggest unproven stability. Edge cases (e.g., timezone handling for scheduled posts) may need custom fixes.
• PHP 8.2+ Requirement: Blocks legacy systems unless polyfills are added.
• Soft Deletes Conflict: Potential ambiguity in state transitions (e.g., can a soft-deleted record be unpublished?). Explicit handling is required.

Key Questions

1. State Validation: How will we enforce publish permissions (e.g., role-based access)? Will we use Policies, Middleware, or custom validation?
2. Scheduled Posts: How will timezone handling work for scheduled posts? Does the package account for Laravel’s config('app.timezone'), or will we need custom logic?
3. Caching: Will published/unpublished states invalidate caches (e.g., Redis, Varnish)? Need integration with tags:clear or similar mechanisms.
4. Soft Deletes Interaction: How will publishable() interact with SoftDeletes? Can a deleted record be unpublished, or should it be treated as permanently hidden?
5. Testing: Are there pre-built tests for edge cases (e.g., concurrent state transitions, database deadlocks)? Will we need to write custom tests?
6. Nova Integration: If using Nova, does the package fully support Nova’s resource tooling (e.g., toolbars, filters, tooltips)? Or will we need to build custom UI components?
7. Migration Strategy: For existing tables, how will we backfill published_first_at and state fields without downtime? Will we use a data migration or a separate script?
8. API Contracts: How will publishable states be exposed in APIs? Will we use query parameters (e.g., ?status=published) or custom endpoints?
9. Localization: Does the package support multi-language content with publishable states? If not, will we need to extend it for localization workflows?
10. Audit Logging: How will we log state changes (e.g., who published/unpublished a record)? Will we use Laravel’s activitylog package or a custom solution?

Integration Approach

Stack Fit

• Ideal For:
  • Content platforms (blogs, news sites, marketing pages) with editorial workflows.
  • Laravel apps requiring dynamic content visibility (e.g., user-generated content with moderation).
  • Projects using Laravel Nova (if extending with laravel-nova-publishable for admin UI consistency).
  • Applications needing scheduled publishing (e.g., "coming soon" sections, time-sensitive promotions).
• Less Ideal For:
  • High-frequency CRUD apps (e.g., e-commerce inventory) where publish states add unnecessary complexity.
  • Systems with fine-grained ACLs (e.g., role-based publish permissions require custom logic).
  • Monolithic apps where state management is already handled by a dedicated service (e.g., a headless CMS).
  • Legacy Laravel/PHP environments (<10.0 or <8.2) without upgrade paths.

Migration Path

1. Assessment Phase:
   • Audit models: Identify candidates for publishable states (e.g., Post, Article, Product).
   • Review existing logic: Document current publish/unpublish workflows to assess overlap or redundancy.
   • Stakeholder alignment: Confirm business requirements for states (e.g., do we need a "reviewed" state?).
2. Pilot Implementation:
   • Select a single model (e.g., Post) to test:
     • Add publishable() to its migration.
     • Apply the PublishableTrait to the model.
     • Implement state transitions in controllers/services.
     • Test query scopes (published(), draft(), etc.).
   • Validate edge cases: Scheduled posts, timezone handling, soft deletes interaction.
3. Incremental Rollout:
   • Phase 1: Add to content-heavy models (e.g., BlogPost, NewsArticle).
   • Phase 2: Extend to non-content models (e.g., Product, Event) if needed.
   • Phase 3: Deprecate custom publish logic in favor of the trait.
4. Database Changes:
   • New tables: Use the publishable() macro in migrations.
   • Existing tables: Create a migration to add:

     $table->string('status')->default('draft');
     $table->timestamp('published_first_at')->nullable();
     $table->timestamp('published_at')->nullable()->after('published_first_at');
     

   • Backfill data: Use a data migration or script to populate published_first_at (e.g., set to created_at for existing published records).
   • Add indexes: Ensure status and published_first_at are indexed for performance:

     $table->index('status');
     $table->index('published_first_at');
     

Compatibility

• Laravel 10+: Fully compatible with modern Laravel features (e.g., model observers, events, testing).
• PHP 8.2: Requires runtime updates if using older versions. Consider polyfills or feature flags if supporting PHP 8.1.
• Databases: Works with MySQL, PostgreSQL, SQLite (Laravel-agnostic). Test connection pooling or transactions if using high-concurrency setups.
• Testing: Compatible with Pest/PHPUnit. May need custom assertions for state transition tests (e.g., assertPublished(), assertScheduled()).
• Frontend: No direct impact, but API responses must filter by state. Example:

  // API Controller
  public function index(Request $request)
  {
      $status = $request->query('status', 'published');
      return Post::query()->$status()->get();
  }
  

• Caching: Integrate with tagged caching (e.g., cache()->tags(['posts'])->remember()) to invalidate caches on state changes.

Sequencing

1. Pre-Installation:
   • Update composer.json:

     "require": {
         "novius/laravel-publishable": "^3.0"
     }
     

   • Install the package:

     composer require novius/laravel-publishable
     

   • Publish assets (if needed):

     php artisan vendor:publish --provider="Novius\Publishable\LaravelPublishableServiceProvider" --tag=lang
     

2. Model Integration:
   • Add the trait to Eloquent models:

     namespace App\Models;
     
     use Illuminate\Database\Eloquent\Model;
     use Novius\Publishable\PublishableTrait;
     
     class Post extends Model
     {
         use PublishableTrait;
     
         protected $