Download the PHP package oddvalue/laravel-drafts without Composer

A simple, drop-in drafts/revisions system for Laravel models

• Installation
• Usage
  • Preparing your models
  • Add the trait
  • Relations
  • Database
  • The API
  • Creating a new record
  • Relations
  • Interacting with records
  • Published revision
  • Current Revision
  • Revisions
  • Auto drafts
  • Preview mode
  • Middleware
  • WithDraftsMiddleware
• Testing
• Changelog
• Contributing
• Security Vulnerabilities
• Credits
• License

Version compatibility

Installation

You can install the package via composer:

You can publish the config file with:

This is the contents of the published config file:

Usage

Preparing your models

Add the trait

Add the HasDrafts trait to your model. Optionally implement the Draftable contract as well; the trait satisfies it, and it lets your own code typehint against the contract instead of a concrete model. A future major version will require the contract, so new models should implement it now. See UPGRADING.md for a Rector rule that adds it to existing models automatically.

Relations

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.

Alternatively you may override the getDraftableRelations method.

Database

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

There are two helper methods added to the schema builder for use in your migrations that will add/remove all these columns for you:

The API

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 record
• onlyDrafts() Select only drafts, exclude published

Creating a new record

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.

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.

This will create a draft record and the original record will be left unchanged.

Interacting with records

Published revision

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.

Current Revision

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.

Revisions

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.

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

Auto drafts

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:

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.

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_auto column 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.

Scheduled publishing

Drafts can be scheduled to be published at a later date. The scheduled date is stored in the will_publish_at column and scheduled drafts are published by the drafts:publish artisan command.

Scheduled drafts are opt-in. Enable them in config/drafts.php:

While disabled (the default) no query references the will_publish_at column, so existing installations keep working unchanged, and the scheduling API (schedulePublishing(), clearScheduledPublishing(), drafts:publish) throws an exception.

Add the publish command to your scheduler for each model that uses scheduled drafts:

Publishing a draft directly clears any scheduled date on it.

Note If you are upgrading from a version without scheduled draft support you will need to add the will_publish_at column to your existing tables before enabling the feature: $table->timestamp('will_publish_at')->nullable(); New tables created with $table->drafts() include the column already.

Preview Mode

Enabling preview mode will disable the global scope that fetches only published records and will instead fetch the current revision regardless of published state.

Middleware

WithDraftsMiddleware

If you require a specific route to be able to access drafts then you can use the WithDraftsMiddleware middleware.

There is also a helper method on the router that allows you to create a group with that middleware applied.

Testing

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• jim
• All Contributors

License

The MIT License (MIT). Please see License File for more information.