| Package Data | |
|---|---|
| Maintainer Username: | oddvalue |
| Maintainer Contact: | jim@oddvalue.co.uk (jim) |
| Package Create Date: | 2022-06-25 |
| Package Last Update: | 2024-07-09 |
| Language: | PHP |
| License: | MIT |
| Last Refreshed: | 2024-11-11 15:03:53 |
| Package Statistics | |
|---|---|
| Total Downloads: | 63,812 |
| Monthly Downloads: | 13,079 |
| Daily Downloads: | 417 |
| Total Stars: | 390 |
| Total Watchers: | 2 |
| Total Forks: | 18 |
| Total Open Issues: | 1 |
You can install the package via composer:
composer require oddvalue/laravel-drafts
You 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',
/*
* 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:
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 quiery 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 publishedBy 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);
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 test
Please 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.