documentation + some adjustments

README.md

@@ -1,29 +1,27 @@
 [![Latest Version on Packagist](https://img.shields.io/packagist/v/sethsharp/blog-crud.svg?style=flat-square)](https://packagist.org/packages/sethsharp/blog-crud)
 
 # Blog
-A fully develop Blog CRUD package that allows you to manage blogs, using Blog content managing meta data with Tags & Collections.
+A fully developed Laravel Blog CRUD package that allows you to manage blogs, tags & collections.
 
 **How does this package work?**
-This package offers a few aspects and provides a great base for creating a blog page for your project. The main features are:
-1. A Blog model with the ability to add tags and make it part of a collection
-2. Ability to add more users with author roles (which have default policy rules - which can be overwritten)
+This package offers a few models and provides a great base for creating a blog page for your project. The main features are:
+1. A Blog model with the ability to add Tags and make it part of a Collection
+2. Inbuilt role system and policies to control what actions can be performed
 3. Built in Factories for easy seeding, development & testing
-4. CRUD operations such as Actions, Requests & Controllers to be used - Controllers are coming soon...
+4. Files to make CRUD easy - including Actions & Requests
 
-
-**For Future reference**
-The main 3 models of this package are:
+**The main 3 models of this package are:**
 1. Blog: Containing columns such as `title`, `author_id`, meta related columns and `content` ... and more
 2. Tag: A `name` but can be added to a blog (A Blog HasMany Tags) - used to help users understand the base topics of the blog
 3. Collection: A `name` and `description` - best used for concepts like a tutorial series (A blog BelongsToOne)
 
 **Example Use Case**
-1. A personal blog page which you want an easy implementation for to manage blogs
+1. A personal blog page which you want an easy implementation for to manage blogs - [check out this repository](https://github.com/SethSharp/portfolio/)
 2. A new blog page where you can add multiple users with restrictions through the author rule + additional roles & policies
 
 **What this package does not offer**
 1. At this point in time this package does not offer a set of front end components. This is strictly a laravel crud package.
-2. Manage separate users
+2. Controllers: This package is not subjective so Controllers + additional logic is up to your implementation
 
 ## Steps for Development
 ### Installation (via composer)
@@ -43,17 +41,19 @@ Then to publish the migrations:
 `php artisan vendor:publish --tag="blog-crud-migrations"`
 
 ### Publishing the Config File
-The config file contains package reliant values. When published that can be edited to suit the project and your coding style.
+Publish for when you need to edit values to suit your project:
+
 `php artisan vendor:publish --tag="blog-crud-config"`
+
 Things that you can override include:
-1. Models: Allows you to create your own models - by replacing it is automatically injected into relationships within other package models
+1. Models: Allows you to create your own models - they are automatically injected into relationships within other package models
 2. Image Driver: We use the laravel-intervention library for image resizing - this defaults to `gd()`, but `imagick()` is available
-3. Bucket Paths: Allows you to specify your own paths for local & production environment in your S3 bucket
+3. Bucket Paths: Allows you to specify your own paths for S3 buckets in local & production environments
 
 ### Other Requirements
 **File System**
 This package does rely on AWS S3 logic when it comes to file uploads, via the Blog Cover or the images you can upload within your blog.
-So ensure that your AWS credentials are properly configured, specifically this array within your `config/filesystems`:
+So ensure that your AWS credentials are properly configured, specifically this config file in your project `config/filesystems`:
 ```php
 's3' => [
     'driver' => 's3',
@@ -68,10 +68,28 @@ So ensure that your AWS credentials are properly configured, specifically this a
 ],
 ```
 
-## Usage
-It is encouraged that you explore this package, it is very straight forward and simple so it is easy to integrate what it has to offer for your use case.
-As the logic you implement to use Actions & Requests may be different to others, as well as other practises.
+**Additional requirements:**
+
+1. It is encouraged that you explore this package, it is very straight forward and simple. But it is necessary
+you know what is contained within this package to suit your use case.
 However, lets go over some basic use cases.
+2. This package implements [CodingLabs Laravel Roles](https://github.com/codinglabsau/laravel-roles), so that configuration will need to be carried out as well (don't worry its nice & easy)
+
+### Models
+## Factory Integration
+All models integrate a factory for ease of development so make sure to use them.
+
+### Policies
+There are policies for each available model in the package to add validation/protection to your routes.
+They must be booted in your `AppServiceProvider` like so:
+```php
+public function boot()
+{
+    Gate::policy(Blog::class, BlogPolicy::class);
+    Gate::policy(Tag::class, TagPolicy::class);
+    Gate::policy(Collection::class, CollectionPolicy::class);
+}
+```
 
 ### Update a Blog
 ```php
@@ -98,26 +116,13 @@ class UpdateBlogController extends Controller
 This is an example `UpdateBlogController`, using all the files from the package; `Blog`, `UpdateBlogRequest` & `UpdateBlogAction`.
 Reading each of these files will ive you an understanding of what they expect - so its up to you to ensure you pass the correct information.
 
-### Booting Policies
-This package contains 3 policies; Blog, Tag and Collection Policies. Each needing to be booted into your project for proper use
-
-```php
-use SethSharp\BlogCrud\Models\Blog\Tag;
-use SethSharp\BlogCrud\Models\Blog\Blog;
-use SethSharp\BlogCrud\Policies\TagPolicy;
-use SethSharp\BlogCrud\Policies\BlogPolicy;
-use SethSharp\BlogCrud\Models\Blog\Collection;
-use SethSharp\BlogCrud\Policies\CollectionPolicy;
-
-// the rest of your provider
+### How does this package rely on S3
+S3 is used for any images used within your content - uploading on the fly or via the blog cover.
+Images can be accomplished within the content as well. This can be done using the actions `StoreFileAction` & `DestoryFileAction`. For optimal S3 management you can also use
+the `StoreBlogFileRequest` - example [here](https://github.com/SethSharp/Portfolio/blob/main/app/Http/Controllers/Dashboard/Blogs/StoreBlogImageController.php).
+This example and the use of the `CleanBlogContentAction` file management at the S3 and DB level at in sync.
 
-public function boot()
-{
-    Gate::policy(Blog::class, BlogPolicy::class);
-    Gate::policy(Tag::class, TagPolicy::class);
-    Gate::policy(Collection::class, CollectionPolicy::class);
-}
-```
+If you want to do this the best option is to use the [TipTap Editor](https://tiptap.dev/product/editor)
 
 ### Tips
 If you wanted to add another column such as `publish_at` to define when to publish the blog through a console command, you just need to define this

src/Actions/Blogs/CleanBlogContentAction.php

@@ -18,21 +18,25 @@ class CleanBlogContentAction
      */
     public function __invoke(Blog $blog): Blog
     {
-        // Replace height attribute with style attribute
+        /**
+         * Any files with the height attribute is converted to a style
+         */
         $newContent = preg_replace('/height="(\d+)"/', 'style="height: $1px"', $blog->content);
 
         $blog->update([
             'content' => $newContent
         ]);
 
-        // Sometimes a file may be deleted within the editor, this finds all the file ids and ensures they are all exist
-        // otherwise delete the unused ones (s3 and entry)
+        /**
+         * Files may be removed from the editor, this searches for the existing file ids (fileid="id") within the content
+         * With this we get all the files attached to the blog - looping over each one to see if the file exists within
+         * the content. If not, we destroy the file at the S3 and DB level
+         */
         $matches = [];
         preg_match_all('/fileid="([^"]+)"/', $blog->content, $matches);
 
         $fileIds = $matches[1];
 
-        // recent files that need replacing
         File::where('blog_id', $blog->id)
             ->get()
             ->each(function (File $file) use ($fileIds) {

src/Database/Factories/Domain/Blog/Models/BlogFactory.php

@@ -62,7 +62,7 @@ protected function getRandomCover(): string
         return $this->coverImages()[array_rand($this->coverImages())];
     }
 
-    private function coverImages(): array
+    public static function coverImages(): array
     {
         return [
             'seeding/desk-1.avif',

src/Policies/BlogPolicy.php

@@ -35,7 +35,7 @@ public function show(?User $user, Blog $blog): bool
     {
         if (! $blog->is_published) {
             if (auth()->check()) {
-                if (! auth()->user()->hasRole([User::ROLE_ADMIN])) {
+                if (! $user->hasRole([User::ROLE_ADMIN])) {
                     return false;
                 }
             } else {

src/Policies/CollectionPolicy.php

@@ -8,10 +8,6 @@ class CollectionPolicy
 {
     public function manage(User $user): bool
     {
-        if ($user->hasRole(User::ROLE_ADMIN)) {
-            return true;
-        }
-
-        return false;
+        return $user->hasRole(User::ROLE_ADMIN);
     }
 }