Skip to content

Latest commit

 

History

History
376 lines (251 loc) · 10.5 KB

UPGRADE.md

File metadata and controls

376 lines (251 loc) · 10.5 KB

Upgrade Guide

Canvas follows Semantic Versioning and increments versions as MAJOR.MINOR.PATCH numbers. Major versions will contain breaking changes, so choose the appropriate guide below for a step-by-step breakdown. Minor and patch versions should never contain breaking changes, so you can safely update the package by running the following commands:

# Update the package
composer update

# Run any new migrations
php artisan canvas:migrate

# Publish any new assets
php artisan canvas:publish

Upgrading to 7.0.0 from 6.0

Important: The minimum required versions to support Canvas are PHP 8.0 and Laravel 9

Database (Export)

A few underlying changes to the database needed to be addressed, which is why we'll do an export/import of our data during the upgrade. In an effort to consolidate the migrations and not rely on database dependencies, we have some manual steps to take. Don't worry, they're simple and straightforward.

Note: The process for migrating data will be unique based on your choice of IDE and database.

The first thing to do is export all data in your Canvas-related tables to a SQL dump. It's important that your export does not include the table structure. You only want INSERT statements in the actual export. If you do include CREATE TABLE statements, it'll modify the new tables when importing later.

For example, I use Table Plus. When I exported my data, I made sure to un-check the Include table structure and Drop table if exists in the export selection screen.

The following tables need to be included in the export:

  • canvas_users
  • canvas_posts
  • canvas_posts_tags
  • canvas_tags
  • canvas_topics
  • canvas_views
  • canvas_visits

Once completed, you can drop those tables from your database.

Optional: To keep the migrations table as minimal as possible, you may delete all references to _canvas records.

Updating dependencies

Update your austintoddj/canvas dependency to ^7.0 in your composer.json file. Upgrade the package to the latest version:

composer update

Migrations

Run the new migration using the canvas:migrate Artisan command:

php artisan canvas:migrate

Database (Import)

You may now import the SQL dump that you created above into your database. Remember, your database and IDE will determine if you should run into any errors while performing this action.

Once the import is complete, you're almost done. A topic is now directly tied to the canvas_posts table via a foreign key. Because of that, none of the posts have a topic_id yet. You'll need to re-assign topics to your posts either manually or in the UI.

Assets

Publish new assets using the canvas:publish Artisan command:

php artisan canvas:publish

Clear any cached views using the view:clear Artisan command:

php artisan view:clear

Upgrading to 6.0.0 from 5.4

Important: With the release of Laravel 8 and the introduction of the legacy-factories package, Canvas no longer supports PHP <= 7.2. It does however continue to support Laravel 6/7/8 and PHP >= 7.3

Database (Export)

The canvas_user_meta table has been removed in v6.0.0, and a new table: canvas_users will take its place. Canvas will no longer rely on the default users table, or allow you to specify your own user model. This shift mimics the underlying structure of WordPress and similar apps.

Note: The process for migrating data will be unique based on your choice of IDE and database.

The first step is to export all data in Canvas-related tables to a SQL dump. The important part of this step is to make sure your export does not include the table structure. You only want INSERT statements in the actual export . If you do include CREATE TABLE statements, it'll modify the new tables when importing later.

For example, I use Sequel Pro. When I exported my data, I made sure to un-check the Structure and DROP TABLE syntax elements in the export selection screen.

The following tables need to be included in the export:

  • canvas_posts
  • canvas_posts_tags
  • canvas_posts_topics
  • canvas_tags
  • canvas_topics
  • canvas_views
  • canvas_visits

Once completed, you can drop those tables from your database.

Optional: If you want to keep the migrations table as minimal as possible, you may delete all references to _canvas records.

Updating dependencies

Update your austintoddj/canvas dependency to ^6.0 in your composer.json file. Upgrade the package to the latest version:

composer update

Migrations

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

php artisan canvas:migrate

Database (Import)

You may now import the SQL dump that you created above into your database. Remember, your database and IDE will determine if you should run into any errors while performing this action.

Once the import is complete, the user_id column in the following tables will need to be addressed:

  • canvas_posts
  • canvas_tags
  • canvas_topics

Since those values reflect the user ID from the default users table, you'll need to make sure you manually update those to the correct user IDs when you have them established in canvas_users.

Setting up a user

Since we don't rely on the default users table anymore, you'll need create your first user for Canvas. It's really simple, just run the following Artisan command:

php artisan canvas:user admin --email {email}

That's it! You should jump in right away and update your credentials. Now that you've given yourself Admin access , you can create new users from the UI. However, the canvas:user Artisan command is a handy little tool for creating users on the fly. You can specify more options like this:

// Somebody who can write and manage their own posts but cannot publish them
php artisan canvas:user contributor --email {email}

// Somebody who can publish and manage posts including the posts of other users
php artisan canvas:user editor --email {email}

// Somebody who can do everything and see everything
php artisan canvas:user admin --email {email}

Configuration

The base path variable name in config/canvas.php changed to be consistent with the newly-added domain variable. You'll need to make sure your .env file is up to date with the correct variable: CANVAS_PATH.

Remove the auth line from the middleware block in config/canvas.php.

Remove the entire user block from config/canvas.php.

Assets

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

php artisan canvas:publish

Clear any cached views using the view:clear Artisan command:

php artisan view:clear

Upgrading to 5.4.0 from 5.3

Important: The package name has changed from cnvs/canvas to austintoddj/canvas

Update the new austintoddj/canvas dependency to ^5.4 in your composer.json file. Upgrade the package to the latest version:

composer update

Migrations

Run the new migrations using the migrate Artisan command:

php artisan migrate

Assets

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

php artisan canvas:publish

Clear any cached views using the view:clear Artisan command:

php artisan view:clear

Upgrading to 5.3.0 from 5.2

Note: The 5.3.0 minor update contains does not contain breaking changes.

Updating dependencies

Update your cnvs/canvas dependency to ^5.3 in your composer.json file. Upgrade the package to the latest version:

composer update

Assets

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

php artisan canvas:publish

Clear any cached views using the view:clear Artisan command:

php artisan view:clear

Upgrading to 5.2.0 from 5.1

Important: The Canvas\Http\Middleware\ViewThrottle middleware was renamed to Canvas\Http\Middleware \Session. Update any usages of this class.

Important: The meta field for posts will now only support a title, description, and canonical link. The og_* and twitter_* tags were unnecessarily specific, so they were deprecated. If you use those tags in your frontend templates, simply update them with the new title and description fields.

Updating dependencies

Update your cnvs/canvas dependency to ^5.2 in your composer.json file. Upgrade the package to the latest version:

composer update

Migrations

Run the new migrations using the migrate Artisan command:

php artisan migrate

Assets

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

php artisan canvas:publish

Clear any cached views using the view:clear Artisan command:

php artisan view:clear

Upgrading to 5.1.0 from 5.0

Updating dependencies

Update your cnvs/canvas dependency to ^5.1 in your composer.json file. Upgrade the package to the latest version:

composer update

Configuration

Add the following line to the Storage block in your config/canvas.php file:

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

Rename the Weekly Digest configuration variable:

Note: Make sure that you update your .env file as well to reflect this variable change

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

Service Provider

Update the boot() method in your app/Providers/CanvasServiceProvider.php file:

$this->app->booted(function () {
    $schedule = resolve(Schedule::class);
    $schedule->command('canvas:digest')
        ->weekly()
        ->mondays()
        ->timezone(config('app.timezone'))
        ->at('08:00')
        ->when(function () {
            return config('canvas.mail.enabled');
        });
});

Migrations

Run the new migrations using the migrate Artisan command:

php artisan migrate

Assets

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

php artisan canvas:publish

Clear any cached views using the view:clear Artisan command:

php artisan view:clear