|
1 | | -# Laravel Draftable |
2 | | - |
3 | | -Draft and publish your eloquent models. |
4 | | - |
5 | | -```php |
6 | | -// Get published posts. |
7 | | -Post::all(); |
8 | | - |
9 | | -// Get all posts. |
10 | | -Post::withDrafts()->get(); |
11 | | - |
12 | | -// Get drafted posts. |
13 | | -Post::onlyDrafts()->get(); |
14 | | -``` |
15 | | - |
16 | | -## Installation |
17 | | - |
18 | | -You can install the package via composer: |
19 | | - |
20 | | -```bash |
21 | | -composer require optix/draftable |
22 | | -``` |
23 | | - |
24 | | -## Usage |
25 | | - |
26 | | -Add the following column to your model's table: |
27 | | - |
28 | | -```php |
29 | | -$table->timestamp('published_at')->nullable(); |
30 | | -``` |
31 | | - |
32 | | -Then use the `Optix\Draftable\Draftable` trait in your model. |
33 | | - |
34 | | -```php |
35 | | -<?php |
36 | | - |
37 | | -namespace App; |
38 | | - |
39 | | -use Optix\Draftable\Draftable; |
40 | | -use Illuminate\Database\Eloquent\Model; |
41 | | - |
42 | | -class Post extends Model |
43 | | -{ |
44 | | - use Draftable; |
45 | | -} |
46 | | -``` |
47 | | - |
48 | | -Posts are "published" when the `published_at` column is not null and in the past. |
49 | | - |
50 | | -Posts are "drafted" when the `published_at` column is null or in the future. |
51 | | - |
52 | | -```php |
53 | | -Post::create([ |
54 | | - 'published_at' => Carbon::now() // Published |
55 | | - // Carbon::tomorrow() - Drafted until tomorrow |
56 | | - // null - Indefinitely drafted |
57 | | -]); |
58 | | -``` |
59 | | - |
60 | | -## License |
61 | | - |
62 | | -The MIT License (MIT). Please see [License File](LICENSE.md) for more information. |
| 1 | +# Eloquent Draftable |
| 2 | + |
| 3 | + |
| 4 | + |
| 5 | + |
| 6 | + |
| 7 | +Add draftable functionality to your eloquent models. |
| 8 | + |
| 9 | +## Installation |
| 10 | + |
| 11 | +You can install this package via composer. |
| 12 | + |
| 13 | +```bash |
| 14 | +composer require optix/eloquent-draftable |
| 15 | +``` |
| 16 | + |
| 17 | +## Setup |
| 18 | + |
| 19 | +1. Add a nullable timestamp `published_at` column to your model's database table. |
| 20 | + |
| 21 | + ```php |
| 22 | + $table->timestamp('published_at')->nullable(); |
| 23 | + ``` |
| 24 | + |
| 25 | +2. Include the `Optix\Draftable\Draftable` trait in your model. |
| 26 | + |
| 27 | + ```php |
| 28 | + class Post extends Model |
| 29 | + { |
| 30 | + use Draftable; |
| 31 | + } |
| 32 | + ``` |
| 33 | + |
| 34 | +## Usage |
| 35 | + |
| 36 | +**Query scopes** |
| 37 | + |
| 38 | +When the `Draftable` trait is included in a model, a global scope will be registered to automatically exclude |
| 39 | +draft records from query results. Therefore, in order to query draft records you must apply one of the local |
| 40 | +scopes outlined below. |
| 41 | + |
| 42 | +```php |
| 43 | +// Only retrieve published records... |
| 44 | +$onlyPublished = Post::all(); |
| 45 | + |
| 46 | +// Retrieve draft & published records... |
| 47 | +$withDrafts = Post::withDrafts()->get(); |
| 48 | + |
| 49 | +// Only retrieve draft records... |
| 50 | +$onlyDrafts = Post::onlyDrafts()->get(); |
| 51 | +``` |
| 52 | + |
| 53 | +**Publish a model** |
| 54 | + |
| 55 | +```php |
| 56 | +$post = Post::withDrafts()->first(); |
| 57 | + |
| 58 | +// Publish without saving... |
| 59 | +$post->setPublished(true); |
| 60 | + |
| 61 | +// Publish and save... |
| 62 | +$post->publish(); // or $post->publish(true); |
| 63 | +``` |
| 64 | + |
| 65 | +When you attempt to publish a model that's already been published, the `published_at` timestamp will not be updated. |
| 66 | + |
| 67 | +**Draft a model** |
| 68 | + |
| 69 | +```php |
| 70 | +// Draft without saving... |
| 71 | +$post->setPublished(false); |
| 72 | + |
| 73 | +// Draft and save... |
| 74 | +$post->draft(); // or $post->publish(false); |
| 75 | +``` |
| 76 | + |
| 77 | +**Schedule a model to be published** |
| 78 | + |
| 79 | +```php |
| 80 | +$publishDate = Carbon::now()->addWeek(); |
| 81 | +// $publishDate = '2020-01-01 00:00:00'; |
| 82 | +// $publishDate = '+1 week'; |
| 83 | + |
| 84 | +// Schedule without saving... |
| 85 | +$post->setPublishedAt($publishDate); |
| 86 | + |
| 87 | +// Schedule and save... |
| 88 | +$post->publishAt($publishDate); |
| 89 | +``` |
| 90 | + |
| 91 | +The methods outlined above both require a `$date` parameter of type `DateTimeInterface|string|null`. |
| 92 | + |
| 93 | +**Get the published status of a model** |
| 94 | + |
| 95 | +```php |
| 96 | +// Determine if the model is published... |
| 97 | +$post->isPublished(); |
| 98 | + |
| 99 | +// Determine if the model is draft... |
| 100 | +$post->isDraft(); |
| 101 | +``` |
| 102 | + |
| 103 | +## License |
| 104 | + |
| 105 | +This package is licensed under the [MIT license](LICENSE.md). |
0 commit comments