README

Laravel Publisher

⚠️ Package is under active development. Wait for v1.0.0 for production use. ⚠️

Publisher is a package aimed at providing a simple and flexible way to manage the publishing workflow of content in a Laravel application. It is designed to be used with any type of content, such as blog posts, pages, or any other type of content that may require a publishing workflow.

A key requirement Publisher aims to solve, is the ability to work on existing content without the changes being visible to your site's regular users until the changes are ready to be published, without the existing published version going missing from your site.

In Version 2+, Publisher will also provide the ability to manage relationships to content that is in a draft state without that related draft content being visible to your site's regular users.

Table of Contents

• Installation
• Configuration
  • Migration Columns
  • Middleware
  • URL Rewriting
  • Admin Panel
  • Gates & Abilities
• Contributing
• Credits
• License
• Security Vulnerabilities

Installation

1. You can install the package via composer:

   composer require plank/publisher

2. Add the Plank\Publisher\Concerns\IsPublishable trait and the Plank\Publisher\Contracts\Publishable interface to the models you want to respect the publishing workflow.

3. Use the package's install command to complete the installation:

   php artisan publisher:install

Configuration

The package's configuration file is located at config/publisher.php. If you did not publish the config file during installation, you can publish the configuration file using the following command:

php artisan vendor:publish --provider="Plank\Publisher\PublisherServiceProvider" --tag="config"

Migration Columns

Each Publishable Model requires 3 columns on their table to function properly:

1. workflow
   • The workflow columns stores the current state of the model. Whether is is currently published, or being worked on as a draft.
2. draft
   • The draft column stores the working values of the attributes in a json column
3. has_been_published
   • The has_been_published column stores a boolean value to indicate if the model has ever been published.

As a further note, you could in theory extend the values of the workflow column to include more states, such as "in_review". However, there are two important states that are required for the package to function properly: a "published" state, and an "unpublished" state. These states are configurable in the IsPublishable trait, by overriding the publishedState and unpublishedState methods.

Whenever a model is transitioned to the "published" state, the has_been_published column is set to true, and the model is considered to have been published.

Whenever a model is transitioned out of the "published" state, changes to the model's attributes will be persisted to the draft column, and the workflow column will be set to the "unpublished" state.

Middleware

The package provides a route middleware that can toggle the visiblity of draft content in the application. This is useful for allowing specific users to preview draft content in a production environment.

If you want to use the package's middleware globally, you should place it in your \App\Http\Kernel just before \Illuminate\Routing\Middleware\SubstituteBindings::class.

URL Rewriting

This package provides an opt-out feature which overrides all URL generation done by the frameworks methods like url() and route() to preserve the current visiblity of the draft content.

You can disable the feature by setting the urls.rewrite key to false in the configuration file.

You can also configure the GET query parameter used to signify the site should display draft content by setting the urls.previewKey key to the desired value.

When the value configured in previewKey is present in the GET query, AND the user has the Gate ability to view-draft-content, the package will allow draft content and rewrite all urls to include the previewKey.

Draft Paths

You can specify request path patterns for endpoints you wish to force draft content to be enabled on. This is especially important for your Admin Panel and CMS routes, as you will want to be working with unpublished content during the editing/creation process.

By default, this package defaults to the Plank's standard for using Laravel Nova with admin/*, nova-api/* and nova-vendor/* defined.

Gates & Abilities

All gates defined on the package can be overriden in your app by defining the gate with the same name in an Application Service Provider.

The package implementation of all gates is as follows:

Gate::define('publish', function ($user, $model) {
    return $user !== null;
});

publish

This gate is used to determine if a user has the ability to publish a model. By default, the gate is defined as follows:

unpublish

This gate is used to determine if a user has the ability to unpublish a model. By default, the gate is defined as follows:

view-draft-content

This gate is used to determine if a user has the ability to view draft content. By default, the gate is defined as follows:

Contributing

Please see CONTRIBUTING for details.

Credits

• Kurt Friars
• Massimo Triassi
• All Contributors

License

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

Security Vulnerabilities

If you discover a security vulnerability within siren, please send an e-mail to security@plank.co. All security vulnerabilities will be promptly addressed.

Check Us Out!

Plank focuses on impactful solutions that deliver engaging experiences to our clients and their users. We're committed to innovation, inclusivity, and sustainability in the digital space. Learn more about our mission to improve the web.