Upgrading

  1. Update composer.json to the version you want (or leave a ^ in the version...)
  2. Run enso composer update --with-dependencies yadda/enso-core
  3. Follow any relevant notes below (from bottom to top)

Publishing Assets

You will probably need to publish Enso JS, CSS, webpack.mix.js etc.

# Publish ALL files (won't overwrite existing files)
enso artisan vendor:publish

# Force re-publish only css and js files
enso artisan vendor:publish --force --tag=assets
Warning!
You probably don't want to use `--force` without also using `--tag=assets`!

Upgrade notes

v3.3.9

To enable Video thumbnails, publish the FFMpeg config file...

php artisan vendor:publish --provider="ProtoneMedia\LaravelFFMpeg\Support\ServiceProvider"

Then add the paths to ffmpeg and ffprobe to `.env. You can get these by running, e.g.

$ which ffmpeg
/usr/bin/ffmpeg
$ which ffprobe
/usr/bin/ffprobe

# .env
FFMPEG_BINARIES=/usr/bin/ffmpeg
FFPROBE_BINARIES=/usr/bin/ffprobe

v3.3.2

  • Update Changes second argument of crud.update.rules Controller Eventy filter from $model->getKey() to $model. If you have added items to this filter, you will need to update them.

v3.3.1

  • SiteMenus have had their crud_name changed from site_menu to sitemenu, and a new publishable file has been added. Update accordingly.

v3.3.0 includes breaking changes

  • Re-publish assets.

Crud config structure changes

  • config/enso/crud.php has been deprecated. The individual crud configurations defined in this file have been moved to their own separate files within a crud folder, with each file being named after the $crud_name of the crud e.g. config/enso/crud/page.php for Pages. The existing config/enso/crud.php file will continue to work for a period of time, but will be phased out later. As such, we recommend migrating your existing config to separate files now. You may run php artisan vendor:publish --tag enso-config to publish new files (if not already present) provided by Ensō for the core Cruds, then update then to match your existing config.

  • The remaining "global" crud settings have been moved to config/enso/settings.php, such as currency and layout. You should update your local file to match the installable file at vendor/yadda/enso-core/installable/config/settings.php. Note that there are also new settings which you should also be replicated. If your app contains code that relies on these config settings (for example, the published file resources/views/admin/dashboard.blade.php has the line @extends(config('enso.crud.layout'))), you will need to update these too.

  • Crud config values for config, controller and model should once again be specified using ::class and do NOT require a preceeding \. See the installable files for examples.

  • Protected records config no longer sits in it's own file. Instead of referencing protected records for a given crud by searching for config data at enso.crud.protected_records.crud_name, the protected records data should be moved to sit within each of the new files, so enso.crud.crud_name.protected_records.

  • Templated records config no longer sits in it's own file. Instead of referencing templated records for a given crud by searching for config data at enso.crud.templated_records.crud_name, the templated records data should be moved to sit within each of the new files, so enso.crud.crud_name.templated_records.

  • The crud_name for EnsoSettings has been changed from settings to setting to keep to the standard singular names. If you have overridden the configuration for settings in your config files, you should this update accordingly.

Crud SelectFields

Both the front and backend functionality for SelectFields (and fields which extend them) has changed in an effort to standardise data flow. When these fields make xhr requests to get their options, results are now returned by passing them into a ListResource. A result of this is that the default label setting on these fields has been changed from name to label. This will invalidate data selections that are saved within flexible content as they are saved as full objects. To get around this, you should update the config value at enso.settings.select_label_by from label back to name.

Due to the standardization of Ensō xhr data, and the extration of the global select_label_by Ensō setting, you should remove instances where you override the labelling property name (usually setSetting('label', 'other_field') or similar). Overriding a labelling property may still be relevant for non-xhr routes, so you'll need to determine this on a case-by-case basis.

Other changes

The deprecated disabledSlugs functionality has been removed. If you had not already migrated to the protected_records functionality, you MUST do this now.

The HasTemplates and ModelHasTemplates traits have been moved from yadda/enso-utilities to yadda/enso-core. If you used these in your app, you will need to change the import paths. Additionally, if you have an Ensō package that used the versions in EnsoUtilities, we recommend you update those packages as the traits will be removed from that pacakge as of version 2.0.3.

$crud_name is now computed based upon the config files, and has been removed from Crud Controllers. You should remove it from any Controllers that you have added it to.

v3.2.5

IsCrudModel trait has been updated and added to all core Enso models. If you have extended core Enso models and added IsCrudModel yourself, you can now remove that.

As IsCrudModel now defines getUrl as the function name to be called if you want the explicit url for a model. If you have implemented this under a different name, consider renaming (or calling your function from within getUrl)

Crud models now implement a getCrudLabel function, where the default value is name, falling back to title, falling back to id. If your model has neither name nor title, implement this yourself to return some distinct data of your choosing.

v3.2.4

If you have not already done so, you MUST now swap out page Admin routes for it's EnsoCrud::crudRoutes as details in the Other section of these notes.

If you have overridden limitByUser on the Page class, you should add the following where it makes sense:

if (!is_null($this->getPublishViewOverridePermission())
    && $user->hasPermission($this->getPublishViewOverridePermission())) {
    return $query;
}

v3.2.0

If using the Mailer you will need to manually require the Mandrill API package:

composer require mandrill/mandrill:1.0.*

v3.1.19

The published .editorconfig now uses 4 spaces for blade files. You may wish to update yours in the same way.

v3.1.1 - v3.1.18

  • Re-publish assets.
  • Changes have been made to views/vendor/enso-crud/users/lists/edit-adction.blade.php. If you have custom changes, anything new into your template.

v3.1.0

Breaking - The signature of the unpack method in Yadda\Enso\Crud\Forms\FlexibleContentSection and all of the rows that extend it has now been updated to the following:

public static function unpack(Yadda\Enso\Crud\Handlers\FlexibleRow $row): ?object

You will need to update any rows that extend this class or its subclasses.

The unpack methods of the following classes were returning arrays but will now return objects. Therefore you will need to update any templates that use the result of the unpack method accordingly.

Yadda\Enso\Crud\Forms\Sections\CTASection Yadda\Enso\Crud\Forms\Sections\DividerSection Yadda\Enso\Crud\Forms\Sections\ImageSection Yadda\Enso\Crud\Forms\Sections\TextSection

v3.0.10

A enso.admin.show_not_production_warning config value should be created as follows:

/**
  * Show a message in the admin area when the environment is not production.
  *
  * This will warn admins that changes may not be visible on the live site.
  */
'show_not_production_warning' => env('ENSO_SHOW_NOT_PRODUCTION_MESSAGE', true),

v3.0.8-9

No changes required.

v3.0.7

Breaking

TextField and TextareaField now have purify_html set to false by default as this is the usual use case for these field types. You can reenable HTML purification per-field like so:

$this->setPurifyHTML(true);

v3.0.6

Breaking

If you have created any custom table cells that override the __construct method you should update their signature to match the following:

Other

public function __construct(string $name, ?Yadda\Enso\Crud\Config $config = null);

You should update config/enso/crud.php to use hard-coded strings rather than ::class syntax, making sure to include a leading slash. You will also need to update routes/web.php to remove any prepended slashes. This should make things generally cleaner and will enable using the new EnsoCrud::crudRoutes method which takes a crud name rather than a controller class.

// Before
'page' => [
    'controller'    => App\Http\Controllers\Admin\PageController::class,
    'config'        => App\Crud\Page::class,
    'model'         => App\Page::class,
],

// After
'page' => [
    'controller'    => '\App\Http\Controllers\Admin\PageController',
    'config'        => '\App\Crud\Page',
    'model'         => '\App\Page',
],

You may also want to update your routes/web.php file to use the newer, simpler syntax. This is more concise and will automatically create the publish/unpublish routes as long as your model implements the IsPublishable contract.

// Before
Route::post('admin/pages/publish', 'Admin\PagePublishController@publish')->name('admin.pages.publish');
Route::post('admin/pages/unpublish', 'Admin\PagePublishController@unpublish')->name('admin.pages.unpublish');
EnsoCrud::routes('admin/pages', "\\" . config('enso.crud.page.controller'), 'admin.pages');

// After
EnsoCrud::crudRoutes('admin/pages', 'page', 'admin.pages');
Publishing

An update to the "published" logic now require publish_at to always be populated. You should make a migration to do this.

MyModel::whereNull('publish_at')->update([
  'publish_at' => DB::raw('now()'),
]);

v2 -> v3.0.0

Install Enso Carousel

yarn add enso-carousel

Before updating, if your site is still using Bulma, you may wish to copy the flexible content row views from vendor/yadda/enso-core/resources/views/crud/flex-partials to resources/views/vendor/enso-crud/flex-partials. These templates have been updated to use TailwindCSS.

cp -r vendor/yadda/enso-core/resources/views/crud/flex-partials/* resources/views/vendor/enso-crud/flex-partials/

Update your requirements in composer.json to include "yadda/enso-core": "^3.1.0".

Analytics is now a separate package. If you require it's functionality, you should require it separately. Either way, you should remove EnsoAnalyticsServiceProvider from config/app.php if it is present.

Enso JS and CSS files are now pre-compiled. You can install them by running php artisan vendor:publish --force --tag=enso-assets.

You should also remove references to old enso assets, such as:

.js('resources/js/enso.js', 'public/js/enso-admin.js')
.sass('resources/sass/enso.scss', 'public/css/enso-admin.css')

You can also remove any requirements from package.json that are required by Enso but aren't required by your application. These may include:

bulma
gulp
jquery
lodash
moment
quill
quill-render
sweetalert
sweetalert2
vue-axios
vue-multiselect
vue-slider-component
vue-template-compiler
vue2-dropzone
vue2-leaflet
vuedraggable
vuejs-datepicker
moment-timezone
resumablejs
sass
sass-loader

You should probably run php artisan vendor:publish --tag=enso-controllers in order to get a copy of HomeController and HoldingPageController if they're missing.

Mix will now publish an svg to resources/svg/ as well as resources/svg/enso. The webpack.mix.js file that Enso publishes will allow this to happen but you may need to manually update yours to work.

If you want to use the new SiteMenu system, you should seed the database: php artisan db:seed --class Yadda\\Enso\\SiteMenus\\Database\\Seeders\\EnsoMenuSeeder.

If you're overriding the getUsername method of Yadda\Enso\Users\Models\User then you should update it the signature to include a return type of string in order to match.

Categories

If you intend to use the new Category system, update config/enso/crud.php to include the following:

'category' => [
    'controller'    => Yadda\Enso\Categories\Controllers\Admin\CategoryController::class,
    'config'        => Yadda\Enso\Categories\Crud\Category::class,
    'model'         => Yadda\Enso\Categories\Models\Category::class,
],

If you're using a custom Category class, follow the instructions on Nesting.

Crud Trait

There is now a Yadda\Enso\Crud\Traits\IsCrudModel trait for applying to Crud models. This doesn't do much at the moment but should be applied to all Crud models for future additions.