Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://austintoddj.github.io/Canvas

Publishing on your own terms
https://austintoddj.github.io/Canvas

blog canvas laravel platform publishing

Last synced: 9 days ago
JSON representation

Publishing on your own terms

Awesome Lists containing this project

README 

        


    

        Homepage for trycanvas.app

    






    Build Status

    Total Downloads

    Latest Stable Version

    License




## 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!



## System Requirements



- PHP >= 7.3

- Laravel >= 6.0

- One of the [five supported databases](https://laravel.com/docs/10.x/database#introduction) by Laravel



## Installation



You may use composer to install Canvas into your Laravel project:



```bash

composer require austintoddj/canvas

```



Publish the assets and primary configuration file using the `canvas:install` Artisan command:



```bash

php artisan canvas:install

```



Create a symbolic link to ensure file uploads are publicly accessible from the web using the `storage:link` Artisan command:



```bash

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.



Canvas exposes its UI at `/canvas` by default. This can be changed by updating either the `path` or `domain` option:



```php

/*

|--------------------------------------------------------------------------

| 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:



```php

/*

|--------------------------------------------------------------------------

| 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:



```php

/*

|--------------------------------------------------------------------------

| 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:



- **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.



## Canvas UI



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



```bash

php artisan canvas:ui

```



After generating the frontend scaffolding, your `package.json` file will include the necessary dependencies to install and compile:



```bash

# 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.



## Unsplash Integration



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



```php

/*

|--------------------------------------------------------------------------

| 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](https://laravel.com/docs/10.x/mail), update `config/canvas.php`:



```php

/*

|--------------------------------------------------------------------------

| 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](https://laravel.com/docs/10.x/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 fire 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

- 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:



```bash

composer update

```



Run any new migrations using the `canvas:migrate` Artisan command:



```bash

php artisan canvas:migrate

```



Re-publish the assets using the `canvas:publish` Artisan command:



```bash

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:



```bash

{

    "scripts": {

        "post-update-cmd": [

            "@php artisan canvas:publish --ansi"

        ]

    }

}

```



## Contributing



Thank you for considering contributing to Canvas! The [contribution guide can be found here](https://github.com/austintoddj/canvas/blob/master/.github/CONTRIBUTING.md).



## Testing



Run the tests with:



```bash

composer test

```



## Troubleshooting



If you're running into problems, feel free to [open a new issue](https://github.com/austintoddj/canvas/issues) or check the [Discussions](https://github.com/austintoddj/canvas/discussions) forum to see if anyone else has run into something similar.



## License



Canvas is open-sourced software licensed under the [MIT license](license).



## Credits



- [@austintoddj](https://twitter.com/austintoddj)

- [@talvbansal](https://twitter.com/talv)

- [@reliq](https://twitter.com/IAmReliq)

- [@mithicher](https://twitter.com/mithicher)

- [@themsaid](https://twitter.com/themsaid)

- [@NinaLimpi](https://twitter.com/NinaLimpi)