project canvas

austintoddj/canvas

Simple, Powerful Blog Publishing Platform

, _(*1)

, _(*2)

Introduction

Canvas is a fully open source package to extend your existing Laravel 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!, _(*3)

System Requirements

• PHP >= 7.3
• Laravel >= 6.0
• One of the five supported databases by Laravel

Installation

You may use composer to install Canvas into your Laravel project:, _(*4)

composer require austintoddj/canvas

Publish the assets and primary configuration file using the canvas:install Artisan command:, _(*5)

php artisan canvas:install

Create a symbolic link to ensure file uploads are publicly accessible from the web using the storage:link Artisan command:, _(*6)

php artisan storage:link

Configuration

After publishing Canvas's assets, a primary configuration file will be located at config/canvas.php. This file allows you to customize various aspects of how your application uses the package., _(*7)

Canvas exposes its UI at /canvas by default. This can be changed by updating either the path or domain option:, _(*8)

/*
|--------------------------------------------------------------------------
| Base Domain
|--------------------------------------------------------------------------
|
| This is the subdomain where Canvas will be accessible from. If the
| domain is set to null, Canvas will reside under the defined base
| path below. Otherwise, this will be used as the subdomain.
|
*/

'domain' => env('CANVAS_DOMAIN', null),

/*
|--------------------------------------------------------------------------
| Base Path
|--------------------------------------------------------------------------
|
| 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
| 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:, _(*9)

/*
|--------------------------------------------------------------------------
| Route Middleware
|--------------------------------------------------------------------------
|
| These middleware will be attached to every route in Canvas, giving you
| the chance to add your own middleware to this list or change any of
| the existing middleware. Or, you can simply stick with the list.
|
*/

'middleware' => [
    'web',
],

Canvas uses the storage disk for media uploads. You may configure the different filesystem options here:, _(*10)

/*
|--------------------------------------------------------------------------
| Storage
|--------------------------------------------------------------------------
|
| This is the storage disk Canvas will use to put file uploads. You may
| use any of the disks defined in the config/filesystems.php file and
| you may also change the maximum upload size from its 3MB default.
|
*/

'storage_disk' => env('CANVAS_STORAGE_DISK', 'local'),

'storage_path' => env('CANVAS_STORAGE_PATH', 'public/canvas'),

'upload_filesize' => env('CANVAS_UPLOAD_FILESIZE', 3145728),

Roles & Permissions

Canvas comes with 3 pre-defined roles out-of-the-box:, _(*11)

• Contributor (A user who can write and manage their own posts but cannot publish them)
• Editor (A user who can publish and manage posts including the posts of other users)
• Admin (A user 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., _(*12)

Canvas UI

Want a beautiful, Medium.com-inspired frontend? Use the canvas:ui Artisan command to install the scaffolding:, _(*13)

php artisan canvas:ui

After generating the frontend scaffolding, your package.json file will include the necessary dependencies to install and compile:, _(*14)

# Using NPM
npm install
npm run dev

# Using Yarn
yarn
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., _(*15)

Unsplash Integration

Want access to the entire Unsplash library? Set up a new application at https://unsplash.com/oauth/applications, grab your access key, and update config/canvas.php:, _(*16)

/*
|--------------------------------------------------------------------------
| Unsplash Integration
|--------------------------------------------------------------------------
|
| Visit https://unsplash.com/oauth/applications to create a new Unsplash
| app. Use the confidential Access Key given to you to integrate with
| the API. Note that demo apps are limited to 50 requests per hour.
|
*/

'unsplash' => [
    'access_key' => env('CANVAS_UNSPLASH_ACCESS_KEY'),
]

E-mail Notifications

Want a weekly summary? Canvas allows users to receive a weekly digest of their authored content. Once your application is configured for sending mail, update config/canvas.php:, _(*17)

/*
|--------------------------------------------------------------------------
| E-Mail Notifications
|--------------------------------------------------------------------------
|
| This option controls e-mail notifications that will be sent via the
| default application mail driver. A default option is provided to
| support the notification system as an opt-in feature.
|
|
*/

'mail' => [
    'enabled' => env('CANVAS_MAIL_ENABLED', false),
]

Since this feature runs on Laravel's Scheduler, you'll need to add the following cron entry to your server:, _(*18)

* * * * * cd /path-to-your-project && php artisan schedule:run >> /dev/null 2>&1

API

Installing 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., _(*19)

Using the published scope will allow you to only retrieve posts that have a published date in the past:, _(*20)

Canvas\Models\Post::published()->get()

You can also retrieve the inverse with a draft scope:, _(*21)

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:, _(*22)

$post = Canvas\Models\Post::with('user', 'tags', 'topic')->firstWhere('slug', $slug);

Important: In the same method that returns a post, make sure you fire the PostViewed event, or else a view/visit will not be recorded., _(*23)

event(new Canvas\Events\PostViewed($post));

You can find a tag by a given slug:, _(*24)

Canvas\Models\Tag::with('posts')->firstWhere('slug', $slug);

And a similar query can be used for a topic:, _(*25)

Canvas\Models\Topic::with('posts')->firstWhere('slug', $slug);

Users can be retrieved by their id, username, or email:, _(*26)

$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:, _(*27)

$user->posts()->published()->with('topic')

Updates

Canvas follows Semantic Versioning and increments versions as MAJOR.MINOR.PATCH numbers. - Major versions will contain breaking changes, so follow the upgrade guide for a 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:, _(*28)

You may update your Canvas installation using composer:, _(*29)

composer update

Run any new migrations using the canvas:migrate Artisan command:, _(*30)

php artisan canvas:migrate

Re-publish the assets using the canvas:publish Artisan command:, _(*31)

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:, _(*32)

{
    "scripts": {
        "post-update-cmd": [
            "@php artisan canvas:publish --ansi"
        ]
    }
}

Contributing

Thank you for considering contributing to Canvas! The contribution guide can be found here., _(*33)

Testing

Run the tests with:, _(*34)

composer test

Troubleshooting

If you're running into problems, feel free to open a new issue or check the Discussions forum to see if anyone else has run into something similar., _(*35)

License

Canvas is open-sourced software licensed under the MIT license., _(*36)

Credits

• @austintoddj
• @talvbansal
• @reliq
• @mithicher
• @themsaid
• @NinaLimpi