| Laravel | Drafts |
|---|---|
| v9.x | v1.x |
| v10.x | v1.x |
| v11.x | v2.x |
| v12.x | >2.1 |
You can install the package via composer:
composer require oddvalue/laravel-draftsYou can publish the config file with:
php artisan vendor:publish --tag="drafts-config"This is the contents of the published config file:
return [
'revisions' => [
'keep' => 10,
],
'column_names' => [
/*
* Boolean column that marks a row as the current version of the data for editing.
*/
'is_current' => 'is_current',
/*
* Boolean column that marks a row as live and displayable to the public.
*/
'is_published' => 'is_published',
/*
* Boolean column that marks a row as an auto draft: an auto-saved
* working copy that is updated in place and never published.
*/
'is_auto' => 'is_auto',
/*
* Timestamp column that stores the date and time when the row was published.
*/
'published_at' => 'published_at',
/*
* UUID column that stores the unique identifier of the model drafts.
*/
'uuid' => 'uuid',
/*
* Name of the morph relationship to the publishing user.
*/
'publisher_morph_name' => 'publisher',
],
'auth' => [
/*
* The guard to fetch the logged-in user from for the publisher relation.
*/
'guard' => 'web',
],
];Add the HasDrafts trait to your model
<?php
use Illuminate\Database\Eloquent\Model;
use Oddvalue\LaravelDrafts\Concerns\HasDrafts;
class Post extends Model
{
use HasDrafts;
...
}The package can handle basic relations to other models. When a draft is published HasOne and HasMany relations will be duplicated to the published model and BelongsToMany and MorphToMany relations will be synced to the published model. In order for this to happen you first need to set the $draftableRelations property on the model.
protected array $draftableRelations = [
'posts',
'tags',
];Alternatively you may override the getDraftableRelations method.
public function getDraftableRelations()
{
return ['posts', 'tags'];
}The following database columns are required for the model to store drafts and revisions:
- is_current
- is_published
- is_auto
- published_at
- uuid
- publisher_type
- publisher_id
The names of these columns can be changed in the config file or per model using constants
e.g. To alter the name of the is_current column then you would add a class constant called IS_CURRENT
<?php
use Illuminate\Database\Eloquent\Model;
use Oddvalue\LaravelDrafts\Concerns\HasDrafts;
class Post extends Model
{
use HasDrafts;
public const IS_CURRENT = 'admin_editing';
...
}There are two helper methods added to the schema builder for use in your migrations that will add/remove all these columns for you:
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;
Schema::table('posts', function (Blueprint $table) {
$table->drafts();
});
Schema::table('posts', function (Blueprint $table) {
$table->dropDrafts();
});The HasDrafts trait will add a default scope that will only return published/live records.
The following query builder methods are available to alter this behavior:
withoutDrafts()/published(bool $withoutDrafts = true)Only select published records (default)withDrafts(bool $withDrafts = false)Include draft recordonlyDrafts()Select only drafts, exclude published
By default, new records will be created as published. You can change this either by including 'is_published' => false in the attributes of the model or by using the createDraft or saveAsDraft methods.
Post::create([
'title' => 'Foo',
'is_published' => false,
]);
# OR
Post::createDraft(['title' => 'Foo']);
# OR
Post::make(['title' => 'Foo'])->saveAsDraft();When saving/updating a record the published state will be maintained. If you want to save a draft of a published record then you can use the saveAsDraft and updateAsDraft methods.
# Create published post
$post = Post::create(['title' => 'Foo']);
# Create drafted copy
$post->updateAsDraft(['title' => 'Bar']);
# OR
$post->title = 'Bar';
$post->saveAsDraft();This will create a draft record and the original record will be left unchanged.
| # | title | uuid | published_at | is_published | is_current | created_at | updated_at |
|---|---|---|---|---|---|---|---|
| 1 | Foo | 9188eb5b-cc42-47e9-aec3-d396666b4e80 | 2000-01-01 00:00:00 | 1 | 0 | 2000-01-01 00:00:00 | 2000-01-01 00:00:00 |
| 2 | Bar | 9188eb5b-cc42-47e9-aec3-d396666b4e80 | 2000-01-02 00:00:00 | 0 | 1 | 2000-01-02 00:00:00 | 2000-01-02 00:00:00 |
The published revision if the live version of the record and will be the one that is displayed to the public. The default behavior is to only show the published revision.
# Get all published posts
$posts = Post::all();Every record will have a current revision. That is the most recent revision and what you would want to display in your admin.
To fetch the current revision you can call the current scope.
$posts = Post::current()->get();Every time a record is updated a new row/revision will be inserted. The default number of revisions kept is 10, this can be updated in the published config file.
You can fetch the revisions of a record by calling the revisions method.
$post = Post::find(1);
$revisions = $post->revisions();Deleting a record will also delete all of its revisions. Soft deleting records will soft delete the revisions and restoring records will restore the revisions.
If you need to update a record without creating revision
$post->withoutRevision()->update($options);Auto drafts are intended for auto-save/recovery features, e.g. periodically
persisting half-finished form state. An auto draft is a single working copy
of a record that is upserted in place on every save, so it never churns the
revision history. It is saved quietly (no model events fire), is never
flagged as current or published, and is ignored by the drafts() relation,
the draft accessor, revision pruning and publish flows.
Auto drafts are opt-in. Enable them in config/drafts.php:
'auto_drafts' => [
'enabled' => true,
],While disabled (the default) no query references the is_auto column, so
existing installations keep working unchanged, and the auto draft API
(saveAsAutoDraft(), autoDraft, onlyAutoDrafts(), discardAutoDraft())
throws a LogicException.
$post = Post::find(1);
# Create or update the record's auto draft
$post->saveAsAutoDraft(['title' => 'Partially typed title']);
# Retrieve it
$autoDraft = $post->autoDraft;
# Check whether a revision is an auto draft
$autoDraft->isAutoDraft();
# Discard it
$post->discardAutoDraft();The onlyAutoDrafts() and withoutAutoDrafts() query builder scopes are
available for custom queries. Auto drafts are deleted along with the record
and its revisions.
Note If you are upgrading from a version without auto draft support you will need to add the
is_autocolumn to your existing tables before enabling the feature:$table->boolean('is_auto')->default(false);New tables created with$table->drafts()include the column already.oddvalue/filament-draft-recovery will switch its laravel-drafts driver to this API once released, using the auto draft as the store for Filament form auto-saves.
Enabling preview mode will disable the global scope that fetches only published records and will instead fetch the current revision regardless of published state.
# Enable preview mode
\Oddvalue\LaravelDrafts\Facades\LaravelDrafts::previewMode();
\Oddvalue\LaravelDrafts\Facades\LaravelDrafts::previewMode(true);
# Disable preview mode
\Oddvalue\LaravelDrafts\Facades\LaravelDrafts::disablePreviewMode();
\Oddvalue\LaravelDrafts\Facades\LaravelDrafts::previewMode(false);If you require a specific route to be able to access drafts then you can use the WithDraftsMiddleware middleware.
Route::get('/posts/publish/{post}', [PostController::class, 'publish'])->middleware(\Oddvalue\LaravelDrafts\Http\Middleware\WithDraftsMiddleware::class);There is also a helper method on the router that allows you to create a group with that middleware applied.
Route::withDrafts(function (): void {
Route::get('/posts/publish/{post}', [PostController::class, 'publish']);
});composer testPlease see CHANGELOG for more information on what has changed recently.
Please see CONTRIBUTING for details.
Please review our security policy on how to report security vulnerabilities.
The MIT License (MIT). Please see License File for more information.