Feature/scheduled drafts

[oddvalue]

Scheduled drafts

Adds the ability to schedule a draft to be published at a future date, revived from the original 2023 branch and reworked on top of current main.

Usage

$draft = $post->createDraft(['title' => 'Hello World']);

// Schedule (saves the record)
$draft->schedulePublishing(now()->addWeek());

// Change your mind (remember to save)
$draft->clearScheduledPublishing()->save();

Due drafts are published by the new artisan command, intended to run on the scheduler:

Schedule::command(PublishScheduledDrafts::class, [Post::class])->everyMinute();

What's included

• will_publish_at timestamp column, added by the drafts()/dropDrafts() blueprint macros and overridable via config or a WILL_PUBLISH_AT model constant
• schedulePublishing(CarbonInterface $date) / clearScheduledPublishing() on HasDrafts
• drafts:publish {model} command; publishing fires the usual publishing/published events, and publishing a draft directly clears any scheduled date
• Optional Contracts\Draftable interface covering the stable consumer-facing API. The trait satisfies it; implementing it is recommended and will become required in a future major. UPGRADING.md documents a tested Rector rule (AddInterfaceByTraitRector) that adds it to existing models
• New UPGRADING.md covering enabling scheduled drafts and auto drafts on existing installations
• Tests: scheduling flows, command validation, disabled-flag behaviour, and a MissingWillPublishAtColumnTest regression suite mirroring the is_auto one

Backwards compatibility

Non-breaking; ships as a minor:

• The feature is opt-in behind drafts.scheduled_drafts.enabled (default false), mirroring the auto drafts flag. While disabled no query references the will_publish_at column, so existing tables without it keep working; the scheduling API throws
• The column is only added to tables created with $table->drafts() from here on; upgrading installations add it manually before enabling (documented)
• No existing method signatures changed; the blueprint macros gain optional trailing parameters only
• The Draftable contract is optional and purely a consumer-facing typehint; the drafts:publish command requires an Eloquent model using the HasDrafts trait

Changes from the original branch

• Dropped the 40-method Draftable interface in src/Contacts/ (namespace typo) in favour of a slim contract in src/Contracts/ that excludes internal plumbing, so future trait changes don't force interface breaks
• Command requires an Eloquent model using the trait (the contract alone cannot guarantee the query APIs the command relies on), uses publish() instead of raw setLive() so model events fire, eachById() so batches aren't skipped, and <= for the due-time comparison
• Everything gated behind the config flag (the original referenced the column unconditionally, which would have broken existing installs)

[oddvalue]

The scheduled publishing implementation still has one contract mismatch that should be resolved before merging.

PublishScheduledDrafts::handle() accepts any class implementing Draftable, but the contract does not require scheduledDraftsEnabled(), newQuery(), or the onlyDrafts() scope. A contract-only implementation therefore passes the validation at src/Commands/PublishScheduledDrafts.php:25 and then fails at runtime.

Please either restrict the command to Eloquent models using HasDrafts, or expand the abstraction and remove the command's reliance on APIs that the contract does not guarantee.

I also found two scheduled-publishing defects and fixed them locally for follow-up: the live row retained will_publish_at after the draft/live attribute swap, and offset-based each() could skip due drafts beyond the first batch. Those changes have not been pushed.