Upgrade Guide: v5.x to v6.0

Overview

Warning

Please don't upgrade multiple versions at once (eg. from v4 to v6). Please upgrade one step at a time.

To get started with the upgrade process, follow the below steps:

1. As Runway is now part of The Rad Pack, you'll need to uninstall the addon under its old name and re-install under the Rad Pack:

composer remove doublethreedigital/runway
composer require statamic-rad-pack/runway:^6.0
composer remove doublethreedigital/runway
composer require statamic-rad-pack/runway:^6.0

2. Next, you'll need to update references to Runway's traits in your Eloquent models.

<?php
 
use Illuminate\Database\Eloquent\Model;
use DoubleThreeDigital\Runway\Traits\HasRunwayResource;
use StatamicRadPack\Runway\Traits\HasRunwayResource;
use DoubleThreeDigital\Runway\Routing\Traits\RunwayRoutes;
use StatamicRadPack\Runway\Routing\Traits\RunwayRoutes;
 
class Order extends Model
{
use HasRunwayResource, RunwayRoutes;
}
<?php
 
use Illuminate\Database\Eloquent\Model;
use DoubleThreeDigital\Runway\Traits\HasRunwayResource;
use StatamicRadPack\Runway\Traits\HasRunwayResource;
use DoubleThreeDigital\Runway\Routing\Traits\RunwayRoutes;
use StatamicRadPack\Runway\Routing\Traits\RunwayRoutes;
 
class Order extends Model
{
use HasRunwayResource, RunwayRoutes;
}

3. Next, run this command to move your Runway blueprints so they're editable in the Control Panel:

php please runway:migrate-blueprints
php please runway:migrate-blueprints

4. After this step, clear your route & view caches to make sure everything is fresh:

php artisan route:clear
php artisan view:clear
php artisan route:clear
php artisan view:clear

5. You've now updated to Runway v6! Please review the changes in this guide and make any necessary changes to your site.

Please test locally before deploying to production!

Changes

High: Blueprints work differently

You can now manage blueprints directly from the Control Panel, gone are the days of managing huge arrays or copying YAML from collection blueprints. 🚀

As part of this, blueprints will now live as YAML files in the resources/blueprints/vendor/runway directory.

During the update process, you will have moved your blueprints to their new location. You can now remove the blueprint key from your resource configs in config/runway.php and delete any old blueprint files.

Medium: Augmentation

Runway v6 changes the way augmentation works behind the scenes, to bring it more inline with how Statamic itself handles augmentation.

Relationships

Previously, all Eloquent relationships from your model were available in your Antlers templates, even without associated Has Many or Belongs To fields.

However, with v6, only relationships with Has Many or Belongs To fields in the blueprint will be output by augmentation.

Changes to the methods used to augment models

If you are manually calling Runway's augmentation methods, you should refactor them to instead call the toAugmentedArray method on your Eloquent model:

// Previously....
$resource->augment($model);
AugmentedModel::augment($model, $resource->blueprint());
 
// Now..
$model->toAugmentedArray();
// Previously....
$resource->augment($model);
AugmentedModel::augment($model, $resource->blueprint());
 
// Now..
$model->toAugmentedArray();

Every field will now return Value objects, rather than just the augmented value.

Medium: Has Many Fieldtype - Table Mode removed

Runway previously included a special "Table" mode for the Has Many fieldtype. However, the Table mode has been removed to help reduce complexity of Runway's fieldtypes.

If you were using the Table mode on any of your Has Many fields, you should switch the mode to default.

Don't know if you're using the Table mode? You can find out by searching these terms in your code editor of choice:

  • mode: table
  • 'mode' => 'table'

Previous upgrade guides


You may also view a diff of changes between v5.x and v6.0