Getting Started

Minimal Steps

Install the Package Run:
```
composer require novius/laravel-filament-publishable
```
Ensure your project meets requirements: Laravel 11+, Filament 4+, and PHP 8.2+.

Ensure Models Use Publishable Trait Add the trait to your model (e.g., Post):

use Novius\Publishable\Traits\Publishable;

class Post extends Model
{
    use Publishable;
    // ...
}

Integrate into a Filament Resource Add publishable fields to your resource’s form() method:

use Novius\LaravelFilamentPublishable\Fields\PublicationStatus;
use Novius\LaravelFilamentPublishable\Fields\PublishedAt;
use Novius\LaravelFilamentPublishable\Fields\ExpiredAt;

public static function form(Form $form): Form
{
    return $form->schema([
        PublicationStatus::make('publication_status'),
        PublishedAt::make('published_at'),
        ExpiredAt::make('expired_at'),
        // ... other fields
    ]);
}

Add Table Column and Filters Include the publishable column and filter in your resource’s table() method:

use Novius\LaravelFilamentPublishable\Columns\PublicationColumn;
use Novius\LaravelFilamentPublishable\Filters\PublicationStatusFilter;

public static function table(Table $table): Table
{
    return $table
        ->columns([
            PublicationColumn::make('publication_status'),
            // ... other columns
        ])
        ->filters([
            PublicationStatusFilter::make('publication_status'),
            // ... other filters
        ]);
}

Enable Bulk Actions (Optional) Add the bulk action to your table:

use Novius\LaravelFilamentPublishable\Actions\PublicationBulkAction;

public static function table(Table $table): Table
{
    return $table
        ->actions([
            PublicationBulkAction::make(),
            // ... other actions
        ]);
}

Publish Language Files (If Needed) Customize translations by publishing the lang files:

php artisan vendor:publish --provider="Novius\LaravelFilamentPublishable\LaravelFilamentPublishableServiceProvider" --tag="lang"

First Use Case

Publish a Blog Post

Create a PostResource with publishable fields.
Use the PublicationStatus field to toggle between draft, published, and expired.
Set published_at and expired_at dates.
Save the record to automatically update the publishable state in the database.
Verify the status appears correctly in the table’s PublicationColumn.

Implementation Patterns

Usage Patterns

1. Basic Field Integration

Replace manual status/date fields with publishable fields for consistency:

// Before (manual)
Select::make('status')
    ->options(['draft', 'published', 'expired'])
    ->required(),

// After (publishable)
PublicationStatus::make('publication_status'),
PublishedAt::make('published_at'),
ExpiredAt::make('expired_at'),

2. Conditional Field Visibility

Show/hide fields based on the publication status using Filament’s visible modifier:

PublishedAt::make('published_at')
    ->visible(fn ($record) => $record->publication_status !== 'draft'),

3. Customizing Field Labels and Placeholders

Override default labels/placeholders:

PublicationStatus::make('publication_status')
    ->label('Content Status')
    ->placeholder('Select status'),

4. Table-Specific Customization

Customize the PublicationColumn to display icons or badges:

PublicationColumn::make('publication_status')
    ->badge()
    ->colors([
        'draft' => 'info',
        'published' => 'success',
        'expired' => 'danger',
    ]),

5. Filtering by Publication Status

Use the PublicationStatusFilter to let users filter records:

PublicationStatusFilter::make('publication_status')
    ->label('Filter by Status'),

6. Bulk Publishing/Unpublishing

Add the bulk action to publish/unpublish multiple records:

PublicationBulkAction::make()
    ->label('Update Publication Status'),

7. Integration with Filament Actions

Trigger custom logic when records are published/expired:

use Filament\Actions\Action;

Action::make('notifyOnPublish')
    ->action(function (Post $record) {
        // Send notification when published
        Notification::send($record->author, new PostPublished($record));
    })
    ->visible(fn ($record) => $record->publication_status === 'published'),

Workflows

Content Moderation Workflow

Draft Creation: User creates a post with publication_status = 'draft'.
Review: Editor changes status to published and sets published_at.
Expiration: Automatically or manually set expired_at to hide the post later.
Filtering: Use PublicationStatusFilter to view only published or expired posts.
Bulk Updates: Use PublicationBulkAction to publish/unpublish multiple posts at once.

Scheduled Publishing

Set published_at to a future date.
Use Laravel’s scheduler or a queue worker to check for records due for publishing.
Automatically update publication_status to published when the date arrives.

Localization Support

Combine with Filament’s localization features:

use Filament\Resources\Resource;
use Novius\LaravelFilamentPublishable\Fields\PublishedAt;

class LocalizedPost extends Resource
{
    public static function form(Form $form): Form
    {
        return $form->schema([
            PublishedAt::make('published_at'),
            // ... other localized fields
        ]);
    }
}

Integration Tips

1. Database Seeders

Seed publishable models with default states:

Post::factory()->create([
    'publication_status' => 'draft',
    'published_at' => null,
    'expired_at' => null,
]);

2. Model Observers

Listen for publishable state changes:

class PostObserver
{
    public function saved(Post $post)
    {
        if ($post->wasChanged('publication_status')) {
            // Trigger custom logic (e.g., notifications, cache updates)
        }
    }
}

3. API Resources

Expose publishable fields in API responses:

public function toArray($request)
{
    return [
        'id' => $this->id,
        'title' => $this->title,
        'publication_status' => $this->publication_status,
        'published_at' => $this->published_at,
        // ...
    ];
}

4. Testing

Test publishable workflows in PHPUnit:

public function test_publish_post()
{
    $post = Post::factory()->create(['publication_status' => 'draft']);

    $this->actingAs($user)
         ->put("/admin/resources/posts/{$post->id}", [
             'publication_status' => 'published',
             'published_at' => now(),
         ]);

    $this->assertEquals('published', $post->fresh()->publication_status);
}

5. Custom Validation

Add validation rules for publishable fields:

public static function form(Form $form): Form
{
    return $form->schema([
        PublicationStatus::make('publication_status')
            ->rules([
                Rule::required(),
                Rule::in(['draft', 'published', 'expired']),
            ]),
        PublishedAt::make('published_at')
            ->requiredIf(fn ($record) => $record->publication_status === 'published'),
    ]);
}

Gotchas and Tips

Pitfalls

1. Missing `Publishable` Trait

Error: Fields like PublicationStatus will fail if the model lacks the Publishable trait.
Fix: Ensure all models using these fields include:
```
use Novius\Publishable\Traits\Publishable;
```

2. Database Column Mismatches

Error: The package expects specific columns (publication_status, published_at, expired_at). Custom column names may break functionality.
Fix: Use the default column names or extend the package to support custom names.

3. Filament Version Conflicts

Error: The package is designed for Filament 4+. Using it with Filament 3 may cause runtime errors.
Fix: Upgrade Filament or use

Laravel Filament Publishable Laravel Package