Merge branch 'release/6.0.33'

* release/6.0.33:
  doc cleanup
  api documentation and dependency upgrades
  compiled assets
  asset update

public/js/app.js.LICENSE.txt

@@ -46,7 +46,7 @@
  */
 
 /*!
- * FilePondPluginImagePreview 4.6.6
+ * FilePondPluginImagePreview 4.6.7
  * Licensed under MIT, https://opensource.org/licenses/MIT/
  * Please visit https://pqina.nl/filepond/ for details.
  */

public/mix-manifest.json

@@ -1,4 +1,4 @@
 {
-    "/js/app.js": "/js/app.js?id=496a2f87c1f5caef0830",
-    "/css/app.css": "/css/app.css?id=17b9084a51cfbf270aa4"
+    "/js/app.js": "/js/app.js?id=4cd6936efc67aef641e8",
+    "/css/app.css": "/css/app.css?id=ade4a5e16f09cdfbea3c"
 }

readme.md

@@ -13,9 +13,7 @@
 
 ## Introduction
 
-Canvas is a fully open source package to extend your existing [Laravel](https://laravel.com) application and get  you
- up-and-running with a blog in just a few minutes. In addition to a distraction-free writing experience, you can
- view monthly trends on your content, get insights into reader traffic and more!
+Canvas is a fully open source package to extend your existing [Laravel](https://laravel.com) application and get you up-and-running with a blog in just a few minutes. In addition to a distraction-free writing experience, you can view monthly trends on your content, get insights into reader traffic and more!
 
 ## Table of Contents
 
@@ -24,8 +22,13 @@ Canvas is a fully open source package to extend your existing [Laravel](https://
 - [Configuration](#configuration)
 - [Roles & Permissions](#roles--permissions)
 - [Features](#features)
+    - [Canvas UI](#canvas-ui)
+    - [Unsplash](#unsplash-integration)
+    - [E-mail](#e-mail-notifications)
+- [API](#api)
 - [Updates](#updates)
 - [Contributing](#contributing)
+- [Testing](#testing)
 - [License](#license)
 - [Credits](#credits)
 
@@ -35,7 +38,7 @@ Canvas is a fully open source package to extend your existing [Laravel](https://
 - Laravel >= 6.0
 - One of the [four supported databases](https://laravel.com/docs/8.x/database#introduction) by Laravel
 
-## Installation   
+## Installation
 
 You may use composer to install Canvas into your Laravel project:
 
@@ -81,16 +84,15 @@ Canvas exposes its UI at `/canvas` by default. This can be changed by updating e
 |--------------------------------------------------------------------------
 |
 | This is the URI where Canvas will be accessible from. If the path
-| is set to null, Canvas will reside under the same path name as 
+| is set to null, Canvas will reside under the same path name as
 | the application. Otherwise, this is used as the base path.
 |
 */
 
 'path' => env('CANVAS_PATH_NAME', 'canvas'),
 ```
 
-Sometimes, you may want to apply custom roles or permissions when accessing Canvas. You can create and attach any
- additional middleware here:
+Sometimes, you may want to apply custom roles or permissions when accessing Canvas. You can create and attach any additional middleware here:
 
 ```php
 /*
@@ -132,20 +134,19 @@ Canvas uses the storage disk for media uploads. You may configure the different
 
 ## Roles & Permissions
 
-Canvas has 3 pre-defined roles:
+Canvas comes with 3 pre-defined roles out-of-the-box:
 
 - **Contributor** (Somebody who can write and manage their own posts but cannot publish them)
 - **Editor** (Somebody who can publish and manage posts including the posts of other users)
 - **Admin** (Somebody who can do everything and see everything)
 
-When you install a fresh version of Canvas, you'll have a default admin user set up automatically. From there, you
- can perform any basic CRUD actions on users, as well as assign their various roles. 
+When you install a fresh version of Canvas, you'll have a default admin user set up automatically. From there, you can perform any basic CRUD actions on users, as well as assign their various roles.
 
 ## Features
 
 > **Note:** The following features are completely optional, you are not required to use them.
 
-### Frontend
+### Canvas UI
 
 **Want a beautiful, Medium.com-inspired frontend?** Use the `canvas:ui` Artisan command to install the scaffolding:
 
@@ -166,7 +167,7 @@ yarn dev
 ```
 
 That's it! You can navigate to `/canvas-ui` and check it out for yourself. You're free to modify any aspect of it
- that you'd like.
+that you'd like.
 
 ### Unsplash Integration
 
@@ -189,9 +190,9 @@ That's it! You can navigate to `/canvas-ui` and check it out for yourself. You'r
 ]
 ```
 
-### Weekly Digest
+### E-mail Notifications
 
-**Want a weekly summary?** Canvas allows users to receive a weekly summary of their authored content. Once your application is [configured for sending mail](https://laravel.com/docs/master/mail), update `config/canvas.php`:
+**Want a weekly summary?** Canvas allows users to receive a weekly digest of their authored content. Once your application is [configured for sending mail](https://laravel.com/docs/master/mail), update `config/canvas.php`:
 
 ```php
 /*
@@ -211,17 +212,72 @@ That's it! You can navigate to `/canvas-ui` and check it out for yourself. You'r
 ]
 ```
 
-Since the weekly digest runs on [Laravel's Scheduler](https://laravel.com/docs/master/scheduling), you'll need to add the following cron entry to your server:
+Since this feature runs on [Laravel's Scheduler](https://laravel.com/docs/master/scheduling), you'll need to add the following cron entry to your server:
 
 ```bash
 * * * * * cd /path-to-your-project && php artisan schedule:run >> /dev/null 2>&1
 ```
 
+## API
+
+Installing [Canvas UI](#canvas-ui) will be the most efficient way to get up and running with a frontend interface to display your data. However many users will opt for creating this by hand since it gives flexibility to their design aesthetic.
+
+Using the `published` scope will allow you to only retrieve posts that have a published date in the past:
+
+```php
+Canvas\Models\Post::published()->get()
+```
+
+You can also retrieve the inverse with a `draft` scope:
+
+```php
+Canvas\Models\Post::draft()->get()
+```
+
+To return a single post, you'll likely want to find it by a given slug, as well as include related entities such as:
+
+```php
+$post = Canvas\Models\Post::with('user', 'tags', 'topic')->firstWhere('slug', $slug);
+```
+
+> **Important:** In the same method that returns a post, make sure you include the `PostViewed` event, or else a 
+> view/visit will not be recorded.
+
+```php
+event(new Canvas\Events\PostViewed($post));
+```
+
+You can find a tag by a given slug:
+
+```php
+Canvas\Models\Tag::with('posts')->firstWhere('slug', $slug);
+```
+
+And a similar query can be used for a topic:
+
+```php
+Canvas\Models\Topic::with('posts')->firstWhere('slug', $slug);
+```
+
+Users can be retrieved by their `id`, `username`, or `email`:
+
+```php
+$user = Canvas\Models\User::find($id);
+$user = Canvas\Models\User::firstWhere('username', $username);
+$user = Canvas\Models\User::firstWhere('email', $email);
+```
+
+Additionally, you can return the users' published posts with their associated topic:
+
+```php
+$user->posts()->published()->with('topic')
+```
+
 ## Updates
 
 Canvas follows [Semantic Versioning](https://semver.org) and increments versions as `MAJOR.MINOR.PATCH` numbers.
 - Major versions **will** contain breaking changes, so follow the [upgrade guide](.github/UPGRADE.md) for a
- step-by-step breakdown
+  step-by-step breakdown
 - Minor and patch versions should **never** contain breaking changes, so you can safely update the package by following the steps below:
 
 You may update your Canvas installation using composer:
@@ -242,9 +298,8 @@ Re-publish the assets using the `canvas:publish` Artisan command:
 php artisan canvas:publish
 ```
 
-To keep the assets up-to-date and avoid issues in future updates, you may add the `canvas:publish` command to the
- `post-update-cmd` scripts in your application's `composer.json` file:
-
+To keep the assets up-to-date and avoid issues in future updates, you may add the `canvas:publish` command to the `post-update-cmd` scripts in your application's `composer.json` file:
+
 ```bash
 {
     "scripts": {
@@ -260,14 +315,12 @@ To keep the assets up-to-date and avoid issues in future updates, you may add th
 Thank you for considering contributing to Canvas!
 
 You can open a completely prebuilt, ready-to-code development environment using Gitpod.
-                                                  
+
 [![Open in Gitpod](https://gitpod.io/button/open-in-gitpod.svg)](https://gitpod.io/#https://github.com/austintoddj/canvas/tree/master)
-
-Alternatively, you can use the [contribution guide](.github/CONTRIBUTING.md) to assist you in manually setting up an
- environment on your own machine.
-
- One of the ongoing goals for Canvas is to make it as accessible as possible. If you come across any translation
-  mistakes or issues and want to make a contribution, please [create a pull request](https://github.com/austintoddj/canvas/pulls). If you don't see your native language included in the `resources/lang` directory, feel free to add it.
+
+Alternatively, you can use the [contribution guide](.github/CONTRIBUTING.md) to assist you in manually setting up an environment on your own machine.
+
+One of the ongoing goals for Canvas is to make it as accessible as possible. If you come across any translation mistakes or issues and want to make a contribution, please [create a pull request](https://github.com/austintoddj/canvas/pulls). If you don't see your native language included in the `resources/lang` directory, feel free to add it.
 
 ## Testing
 
@@ -286,6 +339,7 @@ Canvas is open-sourced software licensed under the [MIT license](license).
 - [@austintoddj](https://twitter.com/austintoddj)
 - [@talvbansal](https://twitter.com/talv)
 - [@reliq](https://twitter.com/IAmReliq)
-- [@mithicher](https://twitter.com/mithicher) 
+- [@mithicher](https://twitter.com/mithicher)
 - [@themsaid](https://twitter.com/themsaid)
-- [@NinaLimpi](https://twitter.com/NinaLimpi) 
+- [@NinaLimpi](https://twitter.com/NinaLimpi)
+