Canvas is a fully open source package to extend your existingLaravelapplication 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!
- PHP >= 7.3
- Laravel >= 6.0
- One of thefive supported databasesby Laravel
You may use composer to install Canvas into your Laravel project:
composer require austintoddj/canvasPublish the assets and primary configuration file using thecanvas:installArtisan command:
php artisan canvas:installCreate a symbolic link to ensure file uploads are publicly accessible from the web using thestorage:linkArtisan command:
php artisan storage:linkAfter publishing Canvas's assets, a primary configuration file will be located atconfig/canvas.php.This file allows you to customize various aspects of how your application uses the package.
Canvas exposes its UI at/canvasby default. This can be changed by updating either thepathordomainoption:
/*
|--------------------------------------------------------------------------
| 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),
/*
|--------------------------------------------------------------------------
|BasePath
|--------------------------------------------------------------------------
|
|Thisis theURIwhereCanvaswill be accessible from.Ifthe path
| is set tonull,Canvaswill reside under the same path nameas
| the application.Otherwise,thisis usedasthe 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:
/*
|--------------------------------------------------------------------------
| 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:
/*
|--------------------------------------------------------------------------
| 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),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.
Want a beautiful, Medium -inspired frontend?Use thecanvas:uiArtisan command to install the scaffolding:
php artisan canvas:uiAfter generating the frontend scaffolding, yourpackage.jsonfile will include the necessary dependencies to install and compile:
#Using NPM
npm install
npm run dev
#Using Yarn
yarn
yarn devThat's it! You can navigate to/canvas-uiand check it out for yourself. You're free to modify any aspect of it
that you'd like.
Want access to the entireUnsplashlibrary?Set up a new application athttps://unsplash /oauth/applications,grab your access key, and updateconfig/canvas.php:
/*
|--------------------------------------------------------------------------
| Unsplash Integration
|--------------------------------------------------------------------------
|
| Visit https://unsplash /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'),
]Want a weekly summary?Canvas allows users to receive a weekly digest of their authored content. Once your application isconfigured for sending mail,updateconfig/canvas.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 onLaravel's Scheduler,you'll need to add the following cron entry to your server:
*****cd/path-to-your-project&&php artisan schedule:run>>/dev/null2>&1InstallingCanvas UIwill 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 thepublishedscope will allow you to only retrieve posts that have a published date in the past:
Canvas\Models\Post::published()->get()You can also retrieve the inverse with adraftscope:
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:
$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
PostViewedevent, or else a view/visit will not be recorded.
event(newCanvas\Events\PostViewed($post));You can find a tag by a given slug:
Canvas\Models\Tag::with('posts')->firstWhere('slug',$slug);And a similar query can be used for a topic:
Canvas\Models\Topic::with('posts')->firstWhere('slug',$slug);Users can be retrieved by theirid,username,oremail:
$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:
$user->posts()->published()->with('topic')Canvas followsSemantic Versioningand increments versions asMAJOR.MINOR.PATCHnumbers.
- Major versionswillcontain breaking changes, so follow theupgrade guidefor a step-by-step breakdown
- Minor and patch versions shouldnevercontain breaking changes, so you can safely update the package by following the steps below:
You may update your Canvas installation using composer:
composer updateRun any new migrations using thecanvas:migrateArtisan command:
php artisan canvas:migrateRe-publish the assets using thecanvas:publishArtisan command:
php artisan canvas:publishTo keep the assets up-to-date and avoid issues in future updates, you may add thecanvas:publishcommand to thepost-update-cmdscripts in your application'scomposer.jsonfile:
{
"scripts":{
"post-update-cmd":[
"@php artisan canvas:publish --ansi"
]
}
}Thank you for considering contributing to Canvas! Thecontribution guide can be found here.
Run the tests with:
composertestIf you're running into problems, feel free toopen a new issueor check theDiscussionsforum to see if anyone else has run into something similar.
Canvas is open-sourced software licensed under theMIT license.
