mirror of
https://github.com/silverstripe/silverstripe-framework
synced 2024-10-22 14:05:37 +02:00
Merge pull request #5968 from open-sausages/pulls/4.0/upgrade-guide
Restructure 4.0.0.md
This commit is contained in:
Ingo Schommer
GitHub
commit
484b6f6c62
@ -1,426 +1,64 @@
|
||||
# 4.0.0 (unreleased)
|
||||
|
||||
## Overview
|
||||
|
||||
### Framework
|
||||
|
||||
* Minimum PHP version raised to 5.5.0
|
||||
* Minimum CMS browser requirement raised from Internet Explorer 8 to Internet Explorer 10
|
||||
* Deprecate `SQLQuery` in favour `SQLSelect`
|
||||
* `DataList::filter` by null now internally generates "IS NULL" or "IS NOT NULL" conditions appropriately on queries
|
||||
* `DataObject` constructor now has an additional parameter, which must be included in subclasses.
|
||||
* `DataObject::database_fields` now returns all fields on that table.
|
||||
* `DataObject::db` now returns composite fields.
|
||||
* `DataObject::ClassName` field has been refactored into a `DBClassName` type field.
|
||||
* Image manipulations have been moved into a new `[api:ImageManipulation]` trait.
|
||||
* `Controller::init` visibility changed to protected. Use `Controller::doInit()` instead.
|
||||
* `CMSFileAddController` removed.
|
||||
* `UploadField::setAllowedFileCategories('image')` now excludes non-resizeable images. 'unresizeable_image' is
|
||||
can be used to validate these types.
|
||||
* `Image_Backend` API now loads and saves from `AssetContainer` instances rather than local files.
|
||||
* The following File categories have been renamed: 'zip' to 'archive', 'doc' to 'document', and 'mov' to 'video'
|
||||
* `File::updateLinks` no longer takes urls as parameters. All file links are now identified either by
|
||||
the `DataObject::ID` in a `data-fileid` property, or via shortcodes. This is necessary because file
|
||||
urls are no longer able to identify assets.
|
||||
* Extension point `HtmlEditorField::processImage` has been removed, and moved to `Image::regenerateImageHTML`
|
||||
* `Upload::load` now stores assets directly without saving into a `File` dataobject.
|
||||
* Protected file storage is now a core Framework API. See [/developer_guides/files/file_security] for
|
||||
more information.
|
||||
* `Object::useCustomClass` has been removed. You should use the config API with Injector instead.
|
||||
* Upgrade of TinyMCE to version 4.
|
||||
* `File` is now versioned, and should be published before they can be used on the frontend.
|
||||
See section on [Migrating File DataObject from 3.x to 4.0](#migrating-file-dataobject-from-3x-to-40)
|
||||
below for upgrade notes.
|
||||
* Removed `RegenerateCachedImagesTask`
|
||||
* Removed `dev/tests/` controller in favour of standard `vendor/bin/phpunit` command
|
||||
* Updated PHPUnit from 3.7 to 4.8 ([upgrade notes](https://github.com/sebastianbergmann/phpunit/wiki/Release-Announcement-for-PHPUnit-4.0.0#backwards-compatibility-issues)).
|
||||
Please remove any PHPUnit related `require_once()` calls (e.g. in `FeatureContext`
|
||||
definitions of the [behat-extension](https://github.com/silverstripe-labs/silverstripe-behat-extension) module).
|
||||
Run `composer require --dev 'phpunit/phpunit:~4.8'` on existing projects to pull in the new dependency.
|
||||
* `Object::invokeWithExtensions` now has the same method signature as `Object::extend` and behaves the same way.
|
||||
* `CMSMain` model actions have been changed:
|
||||
* `CMSBatchAction_Delete` and `CMSMain::delete` are no longer deprecated.
|
||||
* `CMSBatchAction_DeleteFromLive` is removed.
|
||||
* `CMSMain.enabled_legacy_actions` config is removed.
|
||||
* `DataObject::can` has new method signature with `$context` parameter.
|
||||
* `SiteTree.alternatePreviewLink` is deprecated. Use `updatePreviewLink` instead.
|
||||
* `Injector` dependencies no longer automatically inherit from parent classes.
|
||||
* `default_cast` is now enforced on all template variables. See upgrading notes below.
|
||||
* `HTMLText` no longer enables shortcodes by default. You can specify the `db` option for
|
||||
html fields as `HTMLText(['whitelist=meta,link'])`, or use a `ShortcodeHTMLText` as
|
||||
a shorthand substitute.
|
||||
* `FormField->dontEscape` has been removed. Escaping is now managed on a class by class basis.
|
||||
* `HeaderField` requires a `$name` constructor argument (`new HeaderField('MyName', 'My Title')`
|
||||
* `DBString->LimitWordCountXML` removed. Use `LimitWordCount` for XML safe version.
|
||||
* `$module` parameter in `themedCSS` and `themedJavascript` removed.
|
||||
* Theme selector has been removed from SiteConfig. Please use `SSViewer.themes` config instead.
|
||||
* `CMSMain::buildbrokenlinks()` action is removed.
|
||||
* `Folder_UnusedAssetsField` is removed.
|
||||
* `UpgradeSiteTreePermissionSchemaTask` is removed.
|
||||
* `$action` parameter to `Controller::Link()` method is standardised.
|
||||
* Removed `UpgradeSiteTreePermissionSchemaTask`
|
||||
* Removed `DataList::applyFilterContext` private method
|
||||
* Search filter classes (e.g. `ExactMatchFilter`) are now registered with `Injector`
|
||||
via a new `DataListFilter.` prefix convention.
|
||||
see [search filter documentation](/developer_guides/model/searchfilters) for more information.
|
||||
* FormField templates no longer look in the 'forms' folder for templates.
|
||||
* Removed `TabularStyle`
|
||||
* Removed `NestedForm`
|
||||
* Removed `Config_LRU`
|
||||
* Removed `SilverStripeInjectionCreator`
|
||||
* Removed `i18n::get_translatable_modules`
|
||||
* Removed `i18nTextCollector_Writer_Php`
|
||||
* Removed `i18nSSLegacyAdapter`
|
||||
* Removed `FunctionalTest::stat`
|
||||
* Removed `LeftAndMainMarkingFilter`
|
||||
* Removed `Controller::getFormOwner`
|
||||
* Removed `EncryptAllPasswordsTask`
|
||||
* `ServiceConfigurationLocator` is now an interface now a class.
|
||||
* `i18nTextCollectorTask` merge is now true by default.
|
||||
* Removed `FieldList` methods:
|
||||
* `getTabPathRewrites`
|
||||
* `setTabPathRewrites`
|
||||
* `rewriteTabPath`
|
||||
* Removed `Form` methods:
|
||||
* `transformTo`
|
||||
* `callfieldmethod`
|
||||
* `single_field_required`
|
||||
* `current_action`
|
||||
* `set_current_action`
|
||||
* Removed `PermissionCheckboxSetField::getAssignedPermissionCodes()` (never implemented)
|
||||
* Removed `ReportAdminForm.ss` template
|
||||
* Removed `DataList::applyFilterContext` private method
|
||||
|
||||
## New API
|
||||
|
||||
* New filesystem abstraction including new `DBFile` database field to hold file references.
|
||||
* `ShortcodeHandler` interface to help generate standard handlers for HTML shortcodes in the editor.
|
||||
* `AssetNameGenerator` interface, including a `DefaultAssetNameGenerator` implementation, which is used to generate
|
||||
renaming suggestions based on an original given filename in order to resolve file duplication issues.
|
||||
* `GeneratedAssetHandler` API now used to store and manage generated files (such as those used for error page
|
||||
cache or combined files).
|
||||
* `Requirements_Minifier` API can be used to declare any new mechanism for minifying combined required files.
|
||||
By default this api is provided by the `JSMinifier` class, but user code can substitute their own.
|
||||
* `AssetField` formfield to provide an `UploadField` style uploader for the new `DBFile` database field.
|
||||
* `AssetControlExtension` is applied by default to all DataObjects, in order to support the management
|
||||
of linked assets and file protection.
|
||||
* `ProtectedFileController` class is used to serve up protected assets.
|
||||
* `Object` has been broken up into various traits, each of which can be added to other objects independently:
|
||||
* `Configurable` Provides Config API helper methods
|
||||
* `Injectable` Provides Injector API helper methods
|
||||
* `Extensible` Allows extensions to be applied
|
||||
* Removed ability to run tests via web requests (`http://mydomain.com/dev/tests`), use the standard CLI command instead (`vendor/bin/phpunit`)
|
||||
* Removed `dev/jstests/` controller (no replacement)
|
||||
* Moved test database cleanup task from `sake dev/tests/cleanupdb` to `sake dev/tasks/CleanupTestDatabasesTask`
|
||||
* Removed `TestRunner` and `JSTestRunner` APIs
|
||||
* Removed `PhpUnitWrapper`, `PhpUnitWrapper_3_4`, `PhpUnitWrapper_3_5`, `PhpUnitWrapper_Generic`, `SapphireTestSuite` APIs
|
||||
* Removed `SapphireTest->skipTest`, use `markTestSkipped()` in a `setUp()` method instead
|
||||
* `HtmlEditorConfig` is now an abstract class, with a default implementation `TinyMCEConfig` for the built in
|
||||
TinyMCE editor.
|
||||
* `HtmlEditorField::setEditorConfig` may now take an instance of a `HtmlEditorConfig` class, as well as a
|
||||
standard config identifier name.
|
||||
* A lot of standard versioned API has been refactored from `SiteTree` into `Versioned` extension. Now
|
||||
all versioned DataObjects have `canPublish()`, `canArchive()`, `canUnpublish()`, `doPublish()`, `doArchive()`
|
||||
`doUnpublish()`, `isPublished()` and `isonDraft()` out of the box. However, `do*()` methods will no longer
|
||||
automatically check `can*()` permissions, and must be done by usercode before invocation.
|
||||
* GridField edit form now has improved support for versioned DataObjects, with basic publishing
|
||||
actions available when editing records.
|
||||
* `Versioned` API has some breaking changes:
|
||||
* Versioned constructor now only allows a single string to declare whether staging is enabled or not. The
|
||||
number of names of stages are no longer able to be specified. See below for upgrading notes for models
|
||||
with custom stages.
|
||||
* `reading_stage` is now `set_stage` and throws an error if setting an invalid stage.
|
||||
* `current_stage` is now `get_stage`
|
||||
* `getVersionedStages` is gone.
|
||||
* `get_live_stage` is removed. Use the `Versioned::LIVE` constant instead.
|
||||
* `getDefaultStage` is removed. Use the `Versioned::DRAFT` constant instead.
|
||||
* `$versionableExtensions` is now `private static` instead of `protected static`
|
||||
* `hasStages` is addded to check if an object has a given stage.
|
||||
* `stageTable` is added to get the table for a given class and stage.
|
||||
* Any extension declared via `versionableExtensions` config on Versioned dataobject must now
|
||||
`VersionableExtension` interface at a minimum. `Translatable` has been removed from default
|
||||
`versionableExtensions`
|
||||
* `ChangeSet` and `ChangeSetItem` have been added for batch publishing of versioned dataobjects.
|
||||
* `FormAction::setValidationExempt` can be used to turn on or off form validation for individual actions
|
||||
* `DataObject.table_name` config can now be used to customise the database table for any record.
|
||||
* `DataObjectSchema` class added to assist with mapping between classes and tables.
|
||||
* Changes to `DBString` formatting:
|
||||
* `NoHTML` is renamed to `Plain`
|
||||
* `LimitWordCountXML` is removed. Use `LimitWordCount` instead.
|
||||
* `BigSummary` is removed. Use `Summary` instead.
|
||||
* Most limit methods on `DBHTMLText` now plain text rather than attempt to manipulate the underlying HTML.
|
||||
* `FormField::Title` and `FormField::RightTitle` are now cast as plain text by default (but can be overridden).
|
||||
* `PopoverField` added to provide popup-menu behaviour in react forms (currently not available for
|
||||
non-react forms).
|
||||
* Admin URL can now be configured via custom Director routing rule
|
||||
* Templates now use a standard template lookup system via `SSViewer::get_templates_by_class`
|
||||
which builds a candidate list for a given class. Actual resolution of existing templates
|
||||
for any list of candidates is actually performed by `SSViewer::chooseTemplate`
|
||||
|
||||
### Front-end build tooling for CMS interface
|
||||
|
||||
* Management of CMS JavaScript dependencies via [npm](https://www.npmjs.com/)
|
||||
* ES6 is now available in all core JavaScript files via [Babel](https://babeljs.io/)
|
||||
* Bundling of core JavaScript via [Browserify](http://browserify.org/)
|
||||
* CMS build tasks managed by [Gulp](http://gulpjs.com/)
|
||||
|
||||
If you're planning to contribute to SilverStripe core,
|
||||
you should learn how to [use the build tooling](/developer_guides/customising_the_admin_interface/cms_architecture)
|
||||
and [work with client-side dependencies](../contributing/code#working-with-client-side-dependencies).
|
||||
Note that you don't need any of these tools for running SilverStripe or developing your own website.
|
||||
|
||||
### Added new front-end UI libraries
|
||||
|
||||
* Added the following npm libraries:
|
||||
* [react](https://www.npmjs.com/package/react)
|
||||
* [redux](https://www.npmjs.com/package/redux)
|
||||
* [react-router](https://github.com/reactjs/react-router)
|
||||
* [react-router-redux](https://github.com/reactjs/react-router-redux)
|
||||
* [react-redux](https://www.npmjs.com/package/react-redux)
|
||||
* [react-dom](https://www.npmjs.com/package/react-dom)
|
||||
* [isomorphic-fetch](https://www.npmjs.com/package/isomorphic-fetch)
|
||||
* [redux-thunk](https://www.npmjs.com/package/redux-thunk)
|
||||
* [react-addons-test-utils](https://www.npmjs.com/package/react-addons-test-utils)
|
||||
* Added SilverStripeComponent base class for building React UIs
|
||||
|
||||
### Compiling CSS
|
||||
|
||||
[Compass](http://compass-style.org/) has been removed and css/sprite compilation is now handled with [gulp](http://gulpjs.com/) (see [Markup and Style Conventions](../developer_guides/customising_the_admin_interface/cms_architecture/#markup-and-style-conventions)).
|
||||
|
||||
### Bootstrap CSS
|
||||
|
||||
Bootstrap 4 Alpha.2 CSS is available in `admin/css/bootstrap`.
|
||||
|
||||
### Changed paths of static assets
|
||||
|
||||
All static files (images, javascript, stylesheets, fonts) used for the CMS and forms interfaces
|
||||
in `framework` and `cms` have moved locations. These assets are now placed in a `client/` subfolder,
|
||||
to account for a structural change where both javascript and styles are co-located in component-specific folders.
|
||||
This will affect you if you have used `Requirements::block()` on files in the `framework/` or `cms/` folder.
|
||||
Care should also be taken when referencing images in these folders from your own stylesheets.
|
||||
|
||||
```
|
||||
framework/javascript => framework/client/dist/
|
||||
framework/javascript/lang => framework/client/lang/
|
||||
framework/images => framework/client/dist/images/
|
||||
framework/css => framework/client/dist/css/
|
||||
framework/scss => framework/client/src/styles/
|
||||
admin/javascript/ => admin/client/src/
|
||||
admin/javascript/src/ => admin/client/src/legacy/ (mostly)
|
||||
admin/javascript/lang/ => admin/client/lang/
|
||||
admin/scss/ => admin/client/styles/legacy/
|
||||
admin/css/ => admin/client/dist/css/
|
||||
admin/css/screen.css => admin/client/dist/css/bundle.css
|
||||
admin/images/ => admin/client/dist/images/
|
||||
admin/images/sprites/src/ => admin/client/src/sprites/
|
||||
admin/images/sprites/dist/ => admin/client/dist/sprites/
|
||||
admin/font/ => admin/client/dist/font/
|
||||
```
|
||||
|
||||
## Deprecated classes/methods
|
||||
|
||||
### Core
|
||||
* Added the following npm libraries:
|
||||
* Page.js
|
||||
|
||||
* Removed the following JavaScript libraries:
|
||||
* History.js
|
||||
|
||||
* `debugmethods` querystring argument has been removed from debugging.
|
||||
|
||||
* The following ClassInfo methods are now deprecated:
|
||||
* `ClassInfo::baseDataClass` - Use `DataObject::getSchema()->baseDataClass()` instead.
|
||||
* `ClassInfo::table_for_object_field` - Use `DataObject::getSchema()->tableForField()` instead
|
||||
|
||||
### ORM
|
||||
|
||||
* `DataList::getRelation` is removed, as it was mutable. Use `DataList::applyRelation` instead, which is immutable.
|
||||
|
||||
### ErrorPage
|
||||
|
||||
* `ErrorPage.static_filepath` config has been removed.
|
||||
* `ErrorPage::get_filepath_for_errorcode` has been removed
|
||||
* `ErrorPage::alternateFilepathForErrorcode` extension point has been removed
|
||||
|
||||
See notes below on upgrading extensions to the ErrorPage class
|
||||
|
||||
### Member
|
||||
|
||||
* `Member` Field 'RememberLoginToken' removed, replaced with 'RememberLoginHashes' has_many relationship
|
||||
|
||||
### Assets and Filesystem
|
||||
|
||||
The following image manipulations previously deprecated has been removed:
|
||||
|
||||
* `Image::SetRatioSize` superceded by `Fit`
|
||||
* `Image::SetWidth` superceded by `ScaleWidth`
|
||||
* `Image::SetHeight` superceded by `ScaleHeight`
|
||||
* `Image::SetSize` superceded by `Pad`
|
||||
* `Image::PaddedImage` superceded by `Pad`
|
||||
* `Image::CroppedImage` superceded by `Fill`
|
||||
* `Image::AssetLibraryPreview` superceded by `PreviewThumbnail`
|
||||
* `Image::AssetLibraryThumbnail` superceded by `CMSThumbnail`
|
||||
|
||||
The following `File` methods have been removed. Since there is no longer any assumed local path for any file,
|
||||
methods which dealt with such paths may no longer be relied on.
|
||||
|
||||
* `File::deletedatabaseOnly`
|
||||
* `File::link_shortcode_handler` renamed to `handle_shortcode`
|
||||
* `File::setParentID`
|
||||
* `File::getFullPath`
|
||||
* `File::getRelativePath`
|
||||
* `File::Content` database field is removed
|
||||
|
||||
Image manipulations have been moved out of Image.php and now available to any File or DBFile which has the
|
||||
appropriate mime types. The following file manipulations classes and methods have been removed:
|
||||
|
||||
* `CleanImageManipulationCache` class
|
||||
* `Image_Cached` class
|
||||
* `Image::regenerateFormattedImages`
|
||||
* `Image::getGeneratedImages`
|
||||
* `Image::deleteFormattedImages`
|
||||
* `AssetAdmin::deleteunusedthumbnails`
|
||||
* `AssetAdmin::getUnusedThumbnails`
|
||||
|
||||
Many `Folder` methods have also been removed:
|
||||
|
||||
* `Folder::syncChildren`
|
||||
* `Folder::constructChild`
|
||||
* `Folder::addUploadToFolder`
|
||||
|
||||
The following filesystem synchronisation methods are also removed
|
||||
|
||||
* `Filesystem::sync`
|
||||
* `AssetAdmin::doSync`
|
||||
|
||||
The Spyc YAML library has been removed from /thirdparty. Please load it yourself, or use the Symfony YAML component that’s automatically installed by composer.
|
||||
|
||||
### Requirements
|
||||
|
||||
The following methods and properties on `Requirements_Backend` have been renamed:
|
||||
|
||||
* `Requirements_Backund::$combine_files` made protected and renamed `$combinedFiles`
|
||||
* `Requirements_Backend::$combine_js_with_min` made protected and renamed `$minifyCombinedFiles`
|
||||
* `Requirements_Backend::$write_header_comments` made protected and renamed `$writeHeaderComment`
|
||||
* `Requirements_Backend::$write_js_to_body` made protected and renamed to `$writeJavascriptToBody`
|
||||
* `Requirements_Backend::$force_js_to_bottom` renamed to `$forceJSToBottom`
|
||||
* `get_combined_files_enabled` renamed to `getCombinedFilesEnabled`
|
||||
* `set_combined_files_enabled` renamed to `setCombinedFilesEnabled`
|
||||
* `get_suffix_requirements` renamed to `getSuffixRequirements`
|
||||
* `set_suffix_requirements` renamed to `setSuffixRequirements`
|
||||
* `get_custom_scripts` renamed to `getCustomScripts`
|
||||
* `unblock_all` renamed to `unblockAll`
|
||||
* `include_in_response` renamed to `includeInResponse`
|
||||
* `combine_files` renamed to `combineFiles`
|
||||
* `get_combine_files` renamed to `getCombinedFiles`
|
||||
* `clear_combined_files` renamed to `clearCombinedFiles`
|
||||
* `process_combined_files` renamed to `processCombinedFiles`
|
||||
* `set_write_js_to_body` renamed to `setWriteJavascriptToBody`
|
||||
* `set_force_js_to_bottom` renamed to `setForceJSToBottom`
|
||||
|
||||
New methods on `Requirements` are added to access these:
|
||||
|
||||
* `get_minify_combined_js_files`
|
||||
* `set_minify_combined_js_files`
|
||||
* `get_force_js_to_bottom`
|
||||
* `get_write_js_to_body`
|
||||
|
||||
Some methods on `Requirements` have had their method signatures changed:
|
||||
|
||||
* `includeInHTML` has had the first parameter $template removed as it was previously deprecated.
|
||||
|
||||
And some methods on `Requirements` and `Requirements_Backend` have been removed as they are obsolete.
|
||||
|
||||
* `delete_combined_files` (both classes)
|
||||
|
||||
A new config `Requirements_Backend.combine_in_dev` has been added in order to allow combined files to be
|
||||
forced on during development. If this is off, combined files is only enabled in live environments.
|
||||
|
||||
In addition, a new API for javascript files has been added to support front-end tools
|
||||
such as [browserify](http://browserify.org/) that pre-combine scripts. You can specify
|
||||
a 'provides' option to the second parameter of `Requirements::javascript` to declare
|
||||
included files.
|
||||
|
||||
E.g.
|
||||
|
||||
|
||||
:::php
|
||||
Requirements::javascript('mysite/js/dist/bundle.js', ['provides' => [
|
||||
'mysite/js/jquery.js'
|
||||
'mysite/js/src/main.js',
|
||||
'mysite/js/src/functions.js'
|
||||
]]);
|
||||
|
||||
### RestfulService
|
||||
|
||||
* `RestfulService` has been removed. Use Guzzle instead. See Upgrading notes.
|
||||
|
||||
### Oembed
|
||||
|
||||
* Our self-maintained `Oembed` implementation has been removed, in favour of introducing [oscarotero/Embed](https://github.com/oscarotero/Embed) as a dependency.
|
||||
|
||||
|
||||
## Upgrading
|
||||
|
||||
### Explicit text casting is now enforced on all template variables
|
||||
|
||||
Now whenever a `$Variable` is used in a template, regardless of whether any casts or methods are
|
||||
suffixed to the reference, it will be cast to either an explicit DBField for that field, or
|
||||
the value declared by the `default_cast` on the parent object.
|
||||
|
||||
The default value of `default_cast` is `Text`, meaning that now many cases where a field was
|
||||
left un-uncoded, this will now be safely encoded via `Convert::raw2xml`. In cases where
|
||||
un-cast fields were used to place raw HTML into templates, this will now encode this until
|
||||
explicitly cast for that field.
|
||||
|
||||
You can resolve this in your model by adding an explicit cast to HTML for those fields.
|
||||
|
||||
|
||||
Before:
|
||||
|
||||
|
||||
:::ss
|
||||
<div>
|
||||
$SomeHTML
|
||||
</div>
|
||||
|
||||
|
||||
:::php
|
||||
class MyObject extends ViewableData {
|
||||
public function getSomeHTML {
|
||||
$title = Convert::raw2xml($this->Title);
|
||||
return "<h1>{$title}</h1>";
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
After:
|
||||
|
||||
|
||||
:::ss
|
||||
<div>
|
||||
$SomeHTML
|
||||
</div>
|
||||
|
||||
|
||||
:::php
|
||||
class MyObject extends ViewableData {
|
||||
private static $casting = [
|
||||
'SomeHTML' => 'HTMLText'
|
||||
];
|
||||
|
||||
public function getSomeHTML {
|
||||
$title = Convert::raw2xml($this->Title);
|
||||
return "<h1>{$title}</h1>";
|
||||
}
|
||||
}
|
||||
|
||||
If you need to encode a field (such as HTMLText) for use in html attributes, use `.ATT`
|
||||
instead, or if used in an actual XML file use `.CDATA`.
|
||||
|
||||
See the [Template casting](/developer_guides/templates/casting) section for specific details.
|
||||
|
||||
### Automatically upgrading
|
||||
## Introduction
|
||||
|
||||
This version introduces many breaking changes, which in most projects can be managed through a combination
|
||||
of automatic upgrade processes as well as manual code review. This document reviews these changes and will
|
||||
guide developers in preparing existing 3.x code for compatibility with 4.0
|
||||
|
||||
* [Highlights of Major Changes](#overview)
|
||||
* [Upgrading Guide](#upgrading)
|
||||
* [Standard Upgrade](#upgrading-primary)
|
||||
* [API Specific Upgrades](#upgrading-specifics)
|
||||
* [API Changes](#api-changes)
|
||||
* [General and Core API](#overview-general)
|
||||
* [ORM API](#overview-orm)
|
||||
* [Filesystem API](#overview-filesystem)
|
||||
* [Template and Form API](#overview-template)
|
||||
* [Commit History](#commit-history)
|
||||
|
||||
## <a name="overview"></a>Highlights of major changes
|
||||
|
||||
* Minimum version dependencies have increased; PHP 5.5 and Internet Explorer 10 (or other modern browser)
|
||||
is required.
|
||||
* All code earlier marked as deprecated for 4.0 has now been removed. See
|
||||
[deprecation documentation](/contributing/release_process) for information on code deprecation.
|
||||
* All SilverStripe classes are now namespaced, and some have been renamed. This has major implications for
|
||||
arrangement of templates, as well as other references to classes via string literals or configuration.
|
||||
Automatic upgrading tools have been developed to cope with the bulk of these changes (see
|
||||
[upgrading notes](#upgrading)).
|
||||
* Asset storage has been abstracted, and a new concept of `DBFile` references via database column references
|
||||
now exists in addition to references via the existing `File` dataobject. File security and protected files
|
||||
are now a core feature.
|
||||
* A new front-end development process has been developed for the construction of javascript based components,
|
||||
prominently featuring ReactJS to develop highly functional CMS content areas. A new standard form schema
|
||||
API has been developed to allow back-end PHP constructed forms to scaffold themselves within ReactJS
|
||||
powered sections.
|
||||
* CMS CSS has been re-developed using bootstrap 4 as a base
|
||||
([blog post](https://www.silverstripe.org/blog/a-frameworks-framework-why-silverstripe-4-will-use-bootstrap/))
|
||||
* Asset admin has been replaced with a purely ReactJS powered upgrade, and split out
|
||||
module called [asset-admin](https://github.com/silverstripe/silverstripe-asset-admin/). You'll need to add this to your `composer.json` to retain file management capabilities for your CMS authors.
|
||||
* Versioning is now a much more powerful feature, with the addition of campaigns to allow batches of related
|
||||
or inter-dependent objects to be published as a single act. Dependencies between versioned objects can be
|
||||
declared using the new ownership API, so that developers can ensure that relational consistency is
|
||||
maintained during publishing. This new system can be managed via the new "Campaigns" CMS section ([blog post](https://www.silverstripe.org/blog/campaigns-in-silverstripe-4/))
|
||||
* Template variable casting (e.g. `<h1>$Title</h1>`) is enforced by default, which will ensure safe HTML encode
|
||||
unless explicitly opted out.
|
||||
* Themes are now configured to cascade, where you can specify a list of themes, and have the template engine
|
||||
search programatically through a prioritised list when resolving template and CSS file paths.
|
||||
|
||||
## <a name="upgrading"></a>Upgrading
|
||||
|
||||
The below sections describe how to go about updating an existing site to be prepared for upgrade to 4.0.
|
||||
Most of these upgrading tasks will involve manual code review, although in some cases there are
|
||||
some automated processes that users can run to
|
||||
|
||||
### <a name="upgrading-primary"></a>Standard Upgrade
|
||||
|
||||
This section describes the processes which every project upgrading to 4.0 should follow. This should be followed
|
||||
as a standard first point of upgrade.
|
||||
|
||||
#### Upgrade references to renamed and namespaced classes
|
||||
|
||||
4.0 moves many classes to namespaces, and renames many methods.
|
||||
A tool is available to (semi-)automatically update your 3.x code to the new 4.0 names.
|
||||
@ -440,7 +78,7 @@ all changed project files.
|
||||
This will resolve the majority of upgrading work, but for specific changes that will
|
||||
require manual intervention, please see the below upgrading notes.
|
||||
|
||||
### Make sure templates are in correct locations
|
||||
#### Upgrade template locations and references
|
||||
|
||||
Templates are now much more strict about their locations. You can no longer put a template in an arbitrary
|
||||
folder and have it be found. Case is now also checked on case-sensitive filesystems.
|
||||
@ -452,15 +90,109 @@ When using `<% include %>` template tag you should continue to leave out the `In
|
||||
`<% include Sidebar %>` will match only match `Includes/Sidebar.ss`, not `Sidebar.ss`.
|
||||
Please refer to our [template syntax](/developer_guides/templates/syntax) for details.
|
||||
|
||||
The `forms` template folder is no longer used to lookup templates for `FormField` instances.
|
||||
Core template locations have moved - if you're including or overriding these
|
||||
(e.g. for FormField templates) please adjust to the new paths. The `forms` folder
|
||||
no longer exists, and instead template locations will be placed in paths that match
|
||||
the `SilverStripe\Forms` namespace.
|
||||
|
||||
### Update code that uses SQLQuery
|
||||
### <a name="upgrading-specifics"></a>API Specific Upgrades
|
||||
|
||||
Where your code once used SQLQuery you should now use SQLSelect in all cases, as this has been removed.
|
||||
The below sections deal with upgrades to specific parts of various API. Projects which rely on certain
|
||||
API should be upgraded as appropriate using any of the relevant processes documented below.
|
||||
|
||||
See the [3.2.0](3.2.0) upgrading notes for details on how existing code should be upgraded.
|
||||
#### Compatibility with the new front-end building tools
|
||||
|
||||
### New asset storage mechanism
|
||||
If you are using Requirements from 3.x then your scripts should continue to work as they did before.
|
||||
The new front-end tooling is intended only for those wishing to customise the CMS look and feel, or behaviour.
|
||||
|
||||
Those wishing to customise the CMS should read about how to
|
||||
[customise the admin interface](/developer_guides/customising_the_admin_interface/).
|
||||
|
||||
#### Upgrade static references to asset paths
|
||||
|
||||
All static files (images, javascript, stylesheets, fonts) used for the CMS and forms interfaces
|
||||
in `framework` and `cms` have moved locations. These assets are now placed in a `client/` subfolder,
|
||||
to account for a structural change where both javascript and styles are co-located in component-specific folders.
|
||||
This will affect you if you have used `Requirements::block()` on files in the `framework/` or `cms/` folder.
|
||||
Care should also be taken when referencing images in these folders from your own stylesheets.
|
||||
|
||||
`Requirements` now throws an exception then a file is not found, rather than
|
||||
failing silently, so check your `Requirements` are pointing to files that exist.
|
||||
|
||||
```
|
||||
framework/javascript => framework/client/dist/
|
||||
framework/javascript/lang => framework/client/lang/
|
||||
framework/images => framework/client/dist/images/
|
||||
framework/css => framework/client/dist/css/
|
||||
framework/scss => framework/client/src/styles/
|
||||
admin/javascript/ => admin/client/src/
|
||||
admin/javascript/src/ => admin/client/src/legacy/ (mostly)
|
||||
admin/javascript/lang/ => admin/client/lang/
|
||||
admin/scss/ => admin/client/styles/legacy/
|
||||
admin/css/ => admin/client/dist/css/
|
||||
admin/css/screen.css => admin/client/dist/css/bundle.css
|
||||
admin/images/ => admin/client/dist/images/
|
||||
admin/images/sprites/src/ => admin/client/src/sprites/
|
||||
admin/images/sprites/dist/ => admin/client/dist/sprites/
|
||||
admin/font/ => admin/client/dist/font/
|
||||
```
|
||||
|
||||
If you're not doing this already, we suggest looking into a JavaScript bundler
|
||||
like [Browserify](http://browserify.org/), to combine JavaScript files. SilverStripe
|
||||
core is moving away from `Requirements::combine_files` in favour of Browserify as of
|
||||
4.0 and `Requirements::combine_files` is being considered for deprecation in future
|
||||
versions.
|
||||
|
||||
#### Explicit text casting is now enforced on all template variables
|
||||
|
||||
Now whenever a `$Variable` is used in a template, regardless of whether any casts or methods are
|
||||
suffixed to the reference, it will be cast to either an explicit DBField for that field, or
|
||||
the value declared by the `default_cast` on the parent object.
|
||||
|
||||
The default value of `default_cast` is `Text`, meaning that now many cases where a field was
|
||||
left un-uncoded, this will now be safely encoded via `Convert::raw2xml`. In cases where
|
||||
un-cast fields were used to place raw HTML into templates, this will now encode this until
|
||||
explicitly cast for that field.
|
||||
|
||||
You can resolve this in your model by adding an explicit cast to HTML for those fields.
|
||||
|
||||
|
||||
Before:
|
||||
|
||||
|
||||
:::php
|
||||
class MyObject extends ViewableData {
|
||||
public function getSomeHTML {
|
||||
$title = Convert::raw2xml($this->Title);
|
||||
return "<h1>{$title}</h1>";
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
After:
|
||||
|
||||
|
||||
:::php
|
||||
class MyObject extends ViewableData {
|
||||
private static $casting = [
|
||||
'SomeHTML' => 'HTMLText'
|
||||
];
|
||||
|
||||
public function getSomeHTML {
|
||||
$title = Convert::raw2xml($this->Title);
|
||||
return "<h1>{$title}</h1>";
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
If you need to encode a field (such as HTMLText) for use in html attributes, use `.ATT`
|
||||
instead, or if used in an actual XML file use `.CDATA` (see [template casting](/developer_guides/templates/casting)).
|
||||
|
||||
#### Upgrade code that uses SQLQuery
|
||||
|
||||
Where your code once used SQLQuery you should now use SQLSelect in all cases, as this has been removed (check the [3.2.0](3.2.0) upgrading notes).
|
||||
|
||||
#### New asset storage mechanism
|
||||
|
||||
File system has been abstracted into an abstract interface. By default, the out of the box filesystem
|
||||
uses [Flysystem](http://flysystem.thephpleague.com/) with a local storage mechanism (under the assets directory).
|
||||
@ -478,9 +210,9 @@ Note that this will not allow you to utilise certain file versioning features in
|
||||
legacy_paths: true
|
||||
|
||||
|
||||
See [/developer_guides/files/file_management] for more information on how the new system works.
|
||||
See our ["File Management" guide](/developer_guides/files/file_management) for more information.
|
||||
|
||||
### Migrating File DataObject from 3.x to 4.0
|
||||
#### Migrating File DataObject from 3.x to 4.0
|
||||
|
||||
Since the structure of `File` dataobjects has changed, a new task `MigrateFileTask` has been added to assist
|
||||
in migration of legacy files. Migration can be invoked by either this task, or can be configured to automatically
|
||||
@ -501,7 +233,12 @@ that previously visible assets remain visible to the public site.
|
||||
If additional security or visibility rules should be applied to File dataobjects, then
|
||||
make sure to correctly extend `canView` via extensions.
|
||||
|
||||
### Upgrade code which acts on `Image`
|
||||
Note that pre-existing security solutions for 3.x (such as
|
||||
[secure assets module](https://github.com/silverstripe/silverstripe-secureassets))
|
||||
are incompatible with core file security.
|
||||
|
||||
|
||||
#### Upgrade code which acts on `Image`
|
||||
|
||||
As all image-specific manipulations has been refactored from `Image` into an `ImageManipulations` trait, which
|
||||
is applied to both `File` and `DBFile`. These both implement a common interface `AssetContainer`, which
|
||||
@ -551,7 +288,7 @@ E.g.
|
||||
}
|
||||
|
||||
|
||||
### Upgrading code that writes to `File` dataobjects, or writes files to the 'assets' folder
|
||||
#### Upgrading code that writes to `File` dataobjects, or writes files to the 'assets' folder
|
||||
|
||||
In the past all that was necessary to write a `File` DataObject to the database was to ensure a physical file
|
||||
existed in the assets folder, and that the Filename of the DataObject was set to the same location.
|
||||
@ -559,7 +296,6 @@ existed in the assets folder, and that the Filename of the DataObject was set to
|
||||
Since the storage of physical files is no longer a standard location, it's necessary to delegate the writing of such
|
||||
files to the asset persistence layer. As a wrapper for an individual file, you can use any of the `setFrom*`
|
||||
methods to assign content from a local (e.g. temporary) file, a stream, or a string of content.
|
||||
|
||||
You would need to upgrade your code as below.
|
||||
|
||||
Before:
|
||||
@ -607,7 +343,7 @@ You can disable File versioning by adding the following to your _config.php
|
||||
File::remove_extension('Versioned');
|
||||
|
||||
|
||||
### Upgrading code performs custom image manipulations
|
||||
#### Upgrading code performs custom image manipulations
|
||||
|
||||
As file storage and handling has been refactored into the abstract interface, many other components which were
|
||||
once specific to Image.php have now been moved into a shared `ImageManipulation` trait. Manipulations of file content,
|
||||
@ -615,7 +351,6 @@ which are used to generate what are now called "variants" of assets, is now a ge
|
||||
and `DBFile` classes through this trait.
|
||||
|
||||
Custom manipulations, applied via extensions, must be modified to use the new API.
|
||||
|
||||
For instance, code which sizes images to a fixed width should be updated as below:
|
||||
|
||||
Before:
|
||||
@ -636,9 +371,7 @@ Before:
|
||||
Image::add_extension('MyImageExtension');
|
||||
|
||||
|
||||
Now image manipulations are implemented with a single method via a callback generator.
|
||||
|
||||
After:
|
||||
Now image manipulations are implemented with a single method via a callback generator:
|
||||
|
||||
|
||||
:::php
|
||||
@ -672,7 +405,7 @@ There are a few differences in this new API:
|
||||
A generic `manipulate` method may be used, although the callback for this method both is given, and should return,
|
||||
an `AssetStore` instance and file tuple (Filename, Hash, and Variant) rather than an Image_Backend.
|
||||
|
||||
### Upgrading code that uses composite db fields.
|
||||
#### Upgrading code that uses composite db fields.
|
||||
|
||||
The `CompositeDBField` interface has been replaced with an abstract class, `DBComposite`. In many cases, custom code
|
||||
that handled saving of content into composite fields can be removed, as it is now handled by the base class.
|
||||
@ -696,14 +429,13 @@ The below describes the minimum amount of effort required to implement a composi
|
||||
}
|
||||
|
||||
|
||||
### Upgrading code that references `DataObject::database_fields` or `DataObject::db`
|
||||
#### Upgrading code that references `DataObject::database_fields` or `DataObject::db`
|
||||
|
||||
These methods have been updated to include base fields (such as ID, ClassName, Created, and LastEdited), as
|
||||
well as composite DB fields.
|
||||
|
||||
`DataObject::database_fields` does not have a second parameter anymore, and can be called directly on an object
|
||||
or class. E.g. `Member::database_fields()`
|
||||
|
||||
or class. E.g. `Member::database_fields()`.
|
||||
If user code requires the list of fields excluding base fields, then use custom_database_fields instead, or
|
||||
make sure to call `unset($fields['ID']);` if this field should be excluded.
|
||||
|
||||
@ -713,7 +445,7 @@ when set to true (with a field name as the first parameter), will also include t
|
||||
`Table.ClassName(args)` format.
|
||||
|
||||
|
||||
### Update code that uses SQLQuery
|
||||
#### Upgrade code that uses SQLQuery
|
||||
|
||||
SQLQuery is still implemented, but now extends the new SQLSelect class and has some methods
|
||||
deprecated. Previously this class was used for both selecting and deleting, but these
|
||||
@ -724,7 +456,7 @@ these references should be replaced with `SQLSelect`. Legacy code which generate
|
||||
`SQLQuery` can still communicate with new code that expects `SQLSelect` as it is a
|
||||
subclass of `SQLSelect`, but the inverse is not true.
|
||||
|
||||
### Update code that references table names
|
||||
#### Upgrade code that references table names
|
||||
|
||||
A major change in 4.0.0 is that now tables and class names can differ from model to model. In order to
|
||||
fix a table name, to prevent it being changed (for instance, when applying a namespace to a model)
|
||||
@ -739,7 +471,7 @@ the `table_name` config can be applied to any DataObject class.
|
||||
|
||||
|
||||
In order to ensure you are using the correct table for any class a new [api:DataObjectSchema] service
|
||||
is available to manage these mappings.
|
||||
is available to manage these mappings (see [versioned documentation](/developer_guides/model/data_model_and_orm)).
|
||||
|
||||
|
||||
:::php
|
||||
@ -752,15 +484,11 @@ is available to manage these mappings.
|
||||
}
|
||||
|
||||
|
||||
See [versioned documentation](/developer_guides/model/data_model_and_orm) for more information.
|
||||
|
||||
### Update implementations of augmentSQL
|
||||
#### Upgrade implementations of augmentSQL
|
||||
|
||||
Since this method now takes a `SQLSelect` as a first parameter, existing code referencing the deprecated `SQLQuery`
|
||||
type will raise a PHP error.
|
||||
|
||||
E.g.
|
||||
|
||||
Before:
|
||||
|
||||
:::php
|
||||
@ -785,7 +513,7 @@ After:
|
||||
}
|
||||
|
||||
|
||||
### Update code that modifies the behaviour of ErrorPage
|
||||
#### Upgrade code that modifies the behaviour of ErrorPage
|
||||
|
||||
ErrorPage has been updated to use a configurable asset backend, similar to the `AssetStore` described above.
|
||||
This replaces the `ErrorPage.static_filepath` config that was used to write local files.
|
||||
@ -805,8 +533,6 @@ In case that user code must customise this filename, such as for extensions whic
|
||||
for any error page, the extension point `updateErrorFilename` can be used. This extension point should
|
||||
also be used to replace any `alternateFilepathForErrorcode` used.
|
||||
|
||||
E.g.
|
||||
|
||||
|
||||
:::php
|
||||
class MyErrorPageExtension extends SiteTreeExtension {
|
||||
@ -826,7 +552,7 @@ E.g.
|
||||
extensions:
|
||||
- MyErrorPageExtension
|
||||
|
||||
### Upgrading asset web.config, .htaccess, or other server configuration
|
||||
#### Upgrading asset web.config, .htaccess, or other server configuration
|
||||
|
||||
Server configuration files for `/assets` are no longer static, and are regenerated via a set of
|
||||
standard silverstripe templates on flush. These templates include:
|
||||
@ -841,9 +567,9 @@ configuration customisation is done via overriding these templates.
|
||||
|
||||
If upgrading from an existing installation, make sure to invoke `?flush=all` at least once.
|
||||
|
||||
See [/developer_guides/files/file_security] for more information.
|
||||
See our ["File Security" guide](/developer_guides/files/file_security) for more information.
|
||||
|
||||
### `ListboxField` is now multiple-only
|
||||
#### `ListboxField` is now multiple-only
|
||||
|
||||
Previously, this field would operate as either a single select (default) or multi-select by setting
|
||||
`setMultiple` to either true or false.
|
||||
@ -851,21 +577,13 @@ Previously, this field would operate as either a single select (default) or mult
|
||||
Now this field should only be used for multi-selection. Single-selection should be done using
|
||||
a regular `DropdownField`.
|
||||
|
||||
### `GroupedDropdownField::setDisabled` now only accepts a list of values.
|
||||
#### `GroupedDropdownField::setDisabled` now only accepts a list of values.
|
||||
|
||||
Where previously you could specify a list of grouped values in the same way as `setSource`, this
|
||||
method now only accepts either a non-associative array of values (not titles) or an `SS_List`
|
||||
of items to disable.
|
||||
|
||||
### Upgrading Requirements file paths
|
||||
|
||||
`Requirements` now throws an exception then a file is not found, rather than failing silently, so check your `Requirements` are pointing to files that exist.
|
||||
|
||||
Core JavaScript files paths have changed, so if you're referencing these, you'll have to update your file paths. Files previously in `admin/javascript` are now located in `admin/javascript/dist` and files previously located in `javascript` are now locatied in `javascript/dist`.
|
||||
|
||||
If you're not doing this already, we suggest looking into a JavaScript bundler like [Browserify](http://browserify.org/), to combine JavaScript files. SilverStripe core is moving away from `Requirements::combine_files` in favour of Browserify as of 4.0 and `Requirements::combine_files` is being considered for deprecation in future versions.
|
||||
|
||||
### Upgrading TinyMCE to 4.0
|
||||
#### Upgrading TinyMCE to 4.0
|
||||
|
||||
Please see the [tinymce upgrading guide](http://archive.tinymce.com/wiki.php/Tutorial:Migration_guide_from_3.x)
|
||||
to assist with upgrades to customisations to tinymce 3.
|
||||
@ -907,7 +625,7 @@ has been removed from core. You can configure the built-in `charmap` plugin inst
|
||||
For more information on available options and plugins please refer to the
|
||||
[tinymce documentation](https://www.tinymce.com/docs/configure/)
|
||||
|
||||
### Upgrading DataObjects with the `Versioned` extension
|
||||
#### Upgrading DataObjects with the `Versioned` extension
|
||||
|
||||
In most cases, versioned models with the default versioning parameters will not need to be changed. However,
|
||||
there are now additional restrictions on the use of custom stage names.
|
||||
@ -916,8 +634,6 @@ Rather than declaring the list of stages a model has, the constructor for `Versi
|
||||
parameter, which declares whether or not the model is versioned and has a draft and live stage, or alternatively
|
||||
if it only has versioning without staging.
|
||||
|
||||
For instance:
|
||||
|
||||
|
||||
:::php
|
||||
/**
|
||||
@ -950,7 +666,7 @@ These methods are deprecated:
|
||||
* `Versioned::publish` Replaced by `Versioned::copyVersionToStage`
|
||||
* `Versioned::doPublish` Replaced by `Versioned::publishRecursive`
|
||||
|
||||
### Implementation of ownership API
|
||||
#### Implementation of ownership API
|
||||
|
||||
In order to support the recursive publishing of dataobjects, a new API has been developed to allow
|
||||
developers to declare dependencies between objects. See the
|
||||
@ -958,15 +674,14 @@ developers to declare dependencies between objects. See the
|
||||
|
||||
By default all versioned dataobjects will automatically publish objects that they own.
|
||||
|
||||
### ChangeSet batch publishing
|
||||
#### ChangeSet batch publishing
|
||||
|
||||
ChangeSet objects have been added, which allow groups of objects to be published in
|
||||
a single atomic transaction.
|
||||
|
||||
This API will utilise the ownership API to ensure that changes to any object include
|
||||
all necessary changes to owners or owned entities within the same changeset.
|
||||
|
||||
### New `[image]` shortcode in `HTMLText` fields
|
||||
#### New `[image]` shortcode in `HTMLText` fields
|
||||
|
||||
The new Ownership API relies on relationships between objects.
|
||||
Many of these relationships are already made explicit through `has_one`, `has_many` and `many_many`.
|
||||
@ -976,7 +691,7 @@ of the `Image` record rather than its path on the filesystem. The shortcode will
|
||||
when the field is rendered. Newly inserted images will automatically receive the shortcode and ownership tracking,
|
||||
and existing `<img>` will continue to work.
|
||||
|
||||
### Upgrading references to DBField and subclasses
|
||||
#### Upgrading references to DBField and subclasses
|
||||
|
||||
A major change in 4.0 is the introduction of namespaced DBField subclasses. Now as a standard, all DBField subclasses have a `DB` prefix, are namespaced, and have an associative alias which omits the DB prefix.
|
||||
|
||||
@ -984,7 +699,7 @@ This means that for the most part, code that worked in 3.0 won't need to be chan
|
||||
|
||||
An exception to this is any classes which once had the `SS_` prefix, which will now be instead prefixed with `DB`, and have an un-aliased prefix. For example `SS_Datetime` is now `DBDateTime`, and has the alias `DateTime` which may be used in config.
|
||||
|
||||
For example:
|
||||
Before:
|
||||
|
||||
class MyObject extends DataObject {
|
||||
private static $db = array(
|
||||
@ -1001,7 +716,7 @@ For example:
|
||||
}
|
||||
}
|
||||
|
||||
Will become:
|
||||
After:
|
||||
|
||||
use SilverStripe\ORM\FieldType\DBVarchar;
|
||||
|
||||
@ -1022,7 +737,7 @@ Will become:
|
||||
|
||||
Note that string references to SS_Datetime passed to injector, or used in config values, will still work, and will refer to the updated class names.
|
||||
|
||||
### Upgrading from deprecated RestfulService
|
||||
#### Upgrading from deprecated RestfulService
|
||||
|
||||
Install Guzzle to get an API consuming library.
|
||||
`composer require guzzlehttp/guzzle` or add `guzzlehttp/guzzle: "^6.0"` to your composer.json.
|
||||
@ -1031,16 +746,297 @@ For information on how to use Guzzle, please see the extensive [Guzzle documenta
|
||||
|
||||
In case you want to keep using RestfulService, you can use `Firesphere/silverstripe-restfulservice`, but it is unmaintained and deprecated.
|
||||
|
||||
### Upgrading from deprecated Oembed
|
||||
#### Upgrading from deprecated Oembed
|
||||
|
||||
Instead of Oembed, the framework now relies on [oscarotero/Embed](https://github.com/oscarotero/Embed) to handle getting the shortcode-data for embedding.
|
||||
|
||||
If you have custom embedding-code relying on Oembed, please refer to the documentation provided by oscarotero.
|
||||
|
||||
### Admin URL can now be configured via custom Director routing rule
|
||||
#### Admin URL can now be configured via custom Director routing rule
|
||||
|
||||
The default `admin/` URL to access the CMS interface can now be changed via a custom Director routing rule for
|
||||
`AdminRootController`. If your website or module has hard coded `admin` URLs in PHP, templates or JavaScript, make sure
|
||||
to update those with the appropriate function or config call. See
|
||||
[CMS architecture](/developer_guides/customising_the_admin_interface/cms-architecture#the-admin-url) for language
|
||||
specific functions.
|
||||
|
||||
## <a name="api-changes"></a>API Changes
|
||||
|
||||
### <a name="overview-general"></a>General and Core API
|
||||
|
||||
#### <a name="overview-general-api"></a>General and Core API Additions / Changes
|
||||
|
||||
* Minimum PHP version raised to 5.5.0
|
||||
* Minimum CMS browser requirement raised from Internet Explorer 8 to Internet Explorer 10
|
||||
* Updated PHPUnit from 3.7 to 4.8 ([upgrade notes](https://github.com/sebastianbergmann/phpunit/wiki/Release-Announcement-for-PHPUnit-4.0.0#backwards-compatibility-issues)).
|
||||
Please remove any PHPUnit related `require_once()` calls (e.g. in `FeatureContext`
|
||||
definitions of the [behat-extension](https://github.com/silverstripe-labs/silverstripe-behat-extension) module).
|
||||
Run `composer require --dev 'phpunit/phpunit:~4.8'` on existing projects to pull in the new dependency.
|
||||
* Admin URL can now be configured via custom Director routing rule
|
||||
* `Controller::init` visibility changed to protected. Use `Controller::doInit()` instead.
|
||||
* `Object::useCustomClass` has been removed. You should use the config API with Injector instead.
|
||||
* `Object::invokeWithExtensions` now has the same method signature as `Object::extend` and behaves the same way.
|
||||
* `ServiceConfigurationLocator` is now an interface not a class.
|
||||
* `i18nTextCollectorTask` merge is now true by default.
|
||||
* `Object` has been broken up into various traits, each of which can be added to other objects independently:
|
||||
* `Configurable` Provides Config API helper methods
|
||||
* `Injectable` Provides Injector API helper methods
|
||||
* `Extensible` Allows extensions to be applied
|
||||
* `SiteTree.alternatePreviewLink` is deprecated. Use `updatePreviewLink` instead.
|
||||
* `Injector` dependencies no longer automatically inherit from parent classes.
|
||||
* `$action` parameter to `Controller::Link()` method is standardised.
|
||||
* Moved test database cleanup task from `sake dev/tests/cleanupdb` to `sake dev/tasks/CleanupTestDatabasesTask`
|
||||
|
||||
#### <a name="overview-general-removed"></a>General and Core Removed API
|
||||
|
||||
* `CMSMain::buildbrokenlinks()` action is removed.
|
||||
* `SS_Log::add_writer()` method is removed.
|
||||
* Removed `CMSBatchAction_Delete`
|
||||
* Removed `CMSBatchAction_DeleteFromLive`
|
||||
* Removed `CMSMain.enabled_legacy_actions` config.
|
||||
* Removed ability to run tests via web requests (`http://mydomain.com/dev/tests`), use the standard CLI
|
||||
command instead (`vendor/bin/phpunit`).
|
||||
* Removed `dev/jstests/` controller (no replacement)
|
||||
* Removed `TestRunner` and `JSTestRunner` APIs
|
||||
* Removed `PhpUnitWrapper`, `PhpUnitWrapper_3_4`, `PhpUnitWrapper_3_5`, `PhpUnitWrapper_Generic`, `SapphireTestSuite` APIs
|
||||
* Removed `SapphireTest::skipTest()`, use `markTestSkipped()` in a `setUp()` method instead
|
||||
* Removed the `History.js` javascript library.
|
||||
* `debugmethods` querystring argument has been removed from debugging.
|
||||
* `ErrorPage.static_filepath` config has been removed.
|
||||
* `ErrorPage::get_filepath_for_errorcode` has been removed
|
||||
* `ErrorPage::alternateFilepathForErrorcode` extension point has been removed
|
||||
* Removed `Config_LRU`
|
||||
* Removed `SilverStripeInjectionCreator`
|
||||
* Removed `i18n::get_translatable_modules` method.
|
||||
* Removed `i18nTextCollector_Writer_Php`
|
||||
* Removed `i18nSSLegacyAdapter`
|
||||
* Removed `FunctionalTest::stat`
|
||||
* Removed `LeftAndMainMarkingFilter`
|
||||
* Removed `Controller::getFormOwner`
|
||||
* The Spyc YAML library has been removed from /thirdparty. Please load it yourself, or use the
|
||||
Symfony YAML component that’s automatically installed by composer.
|
||||
* `RestfulService` has been removed. Use Guzzle instead. See Upgrading notes.
|
||||
* Our self-maintained `Oembed` implementation has been removed, in favour of introducing
|
||||
[oscarotero/Embed](https://github.com/oscarotero/Embed) as a dependency.
|
||||
|
||||
#### <a name="overview-general-deprecated"></a>General and Core Deprecated API
|
||||
|
||||
A very small number of methods were chosen for deprecation, and will be removed in 5.0 rather than 4.0
|
||||
|
||||
* `ClassInfo::baseDataClass` - Use `DataObject::getSchema()->baseDataClass()` instead.
|
||||
* `ClassInfo::table_for_object_field` - Use `DataObject::getSchema()->tableForField()` instead
|
||||
|
||||
### <a name="overview-orm"></a>ORM API
|
||||
|
||||
#### <a name="overview-orm-api"></a>ORM API Additions / Changes
|
||||
|
||||
* Deprecate `SQLQuery` in favour `SQLSelect`
|
||||
* `DataList::filter` by null now internally generates "IS NULL" or "IS NOT NULL" conditions appropriately on queries
|
||||
* `DataObject` constructor now has an additional parameter, which must be included in subclasses.
|
||||
* `DataObject::database_fields` now returns all fields on that table.
|
||||
* `DataObject::db` now returns composite fields.
|
||||
* `DataObject::ClassName` field has been refactored into a `DBClassName` type field.
|
||||
* `DataObject::can` has new method signature with `$context` parameter.
|
||||
* `DBHTMLText` no longer enables shortcodes by default. Two injector aliases have been created for this
|
||||
class which can be used to select the correct behaviour:
|
||||
* `HTMLText`: `DBHTMLText` with shortcodes enabled
|
||||
* `HTMLFragment`: `DBHTMLText` without shortcodes enabled (as default)
|
||||
* Changes to `DBString` formatting:
|
||||
* `NoHTML` is renamed to `Plain`
|
||||
* `LimitWordCountXML` is removed. Use `LimitWordCount` instead.
|
||||
* `BigSummary` is removed. Use `Summary` instead.
|
||||
* Most limit methods on `DBHTMLText` now plain text rather than attempt to manipulate the underlying HTML.
|
||||
* `FormField::Title` and `FormField::RightTitle` are now cast as plain text by default (but can be overridden).
|
||||
* Removed `DataList::applyFilterContext` private method
|
||||
* Search filter classes (e.g. `ExactMatchFilter`) are now registered with `Injector`
|
||||
via a new `DataListFilter.` prefix convention.
|
||||
see [search filter documentation](/developer_guides/model/searchfilters) for more information.
|
||||
* `Versioned` API has some breaking changes:
|
||||
* Versioned constructor now only allows a single string to declare whether staging is enabled or not. The
|
||||
number of names of stages are no longer able to be specified. See below for upgrading notes for models
|
||||
with custom stages.
|
||||
* `reading_stage` is now `set_stage` and throws an error if setting an invalid stage.
|
||||
* `current_stage` is now `get_stage`
|
||||
* `getVersionedStages` is gone.
|
||||
* `get_live_stage` is removed. Use the `Versioned::LIVE` constant instead.
|
||||
* `getDefaultStage` is removed. Use the `Versioned::DRAFT` constant instead.
|
||||
* `$versionableExtensions` is now `private static` instead of `protected static`
|
||||
* `hasStages` is addded to check if an object has a given stage.
|
||||
* `stageTable` is added to get the table for a given class and stage.
|
||||
* Any extension declared via `versionableExtensions` config on Versioned dataobject must now
|
||||
`VersionableExtension` interface at a minimum. `Translatable` has been removed from default
|
||||
`versionableExtensions`
|
||||
* A lot of standard versioned API has been refactored from `SiteTree` into `Versioned` extension. Now
|
||||
all versioned DataObjects have `canPublish()`, `canArchive()`, `canUnpublish()`, `doPublish()`, `doArchive()`
|
||||
`doUnpublish()`, `isPublished()` and `isonDraft()` out of the box. However, `do*()` methods will no longer
|
||||
automatically check `can*()` permissions, and must be done by usercode before invocation.
|
||||
* `ChangeSet` and `ChangeSetItem` have been added for batch publishing of versioned dataobjects.
|
||||
* `DataObject.table_name` config can now be used to customise the database table for any record.
|
||||
* `DataObjectSchema` class added to assist with mapping between classes and tables.
|
||||
|
||||
#### <a name="overview-orm-removed"></a>ORM Removed API
|
||||
|
||||
* Removed `DataList::getRelation`, as it was mutable. Use `DataList::applyRelation` instead, which is immutable.
|
||||
* Removed `DataList::applyFilterContext` private method
|
||||
* `Member` Field 'RememberLoginToken' removed, replaced with 'RememberLoginHashes' has_many relationship
|
||||
* Removed `UpgradeSiteTreePermissionSchemaTask`
|
||||
* Removed `EncryptAllPasswordsTask`
|
||||
* Removed `DBString::LimitWordCountXML()` method. Use `LimitWordCount` for XML safe version.
|
||||
|
||||
### <a name="overview-filesystem"></a>Filesystem API
|
||||
|
||||
#### <a name="overview-filesystem-api"></a>Filesystem API Additions / Changes
|
||||
|
||||
* Image manipulations have been moved into a new `[api:ImageManipulation]` trait.
|
||||
* `CMSFileAddController` removed.
|
||||
* `UploadField::setAllowedFileCategories('image')` now excludes non-resizeable images. 'unresizeable_image' is
|
||||
can be used to validate these types.
|
||||
* `Image_Backend` API now loads and saves from `AssetContainer` instances rather than local files.
|
||||
* The following File categories have been renamed: 'zip' to 'archive', 'doc' to 'document', and 'mov' to 'video'
|
||||
* `File::updateLinks` no longer takes urls as parameters. All file links are now identified either by
|
||||
the `DataObject::ID` in a `data-fileid` property, or via shortcodes. This is necessary because file
|
||||
urls are no longer able to identify assets.
|
||||
* Extension point `HtmlEditorField::processImage` has been removed, and moved to `Image::regenerateImageHTML`
|
||||
* `Upload::load` now stores assets directly without saving into a `File` dataobject.
|
||||
* Protected file storage is now a core Framework API. See [/developer_guides/files/file_security] for
|
||||
more information.
|
||||
* `File` is now versioned, and should be published before they can be used on the frontend.
|
||||
See section on [Migrating File DataObject from 3.x to 4.0](#migrating-file-dataobject-from-3x-to-40)
|
||||
below for upgrade notes.
|
||||
* New filesystem abstraction including new `DBFile` database field to hold file references.
|
||||
* `ShortcodeHandler` interface to help generate standard handlers for HTML shortcodes in the editor.
|
||||
* `AssetNameGenerator` interface, including a `DefaultAssetNameGenerator` implementation, which is used to generate
|
||||
renaming suggestions based on an original given filename in order to resolve file duplication issues.
|
||||
* `GeneratedAssetHandler` API now used to store and manage generated files (such as those used for error page
|
||||
cache or combined files).
|
||||
* `Requirements_Minifier` API can be used to declare any new mechanism for minifying combined required files.
|
||||
By default this api is provided by the `JSMinifier` class, but user code can substitute their own.
|
||||
* `AssetField` formfield to provide an `UploadField` style uploader for the new `DBFile` database field.
|
||||
* `AssetControlExtension` is applied by default to all DataObjects, in order to support the management
|
||||
of linked assets and file protection.
|
||||
* `ProtectedFileController` class is used to serve up protected assets.
|
||||
|
||||
#### <a name="overview-filesystem-removed"></a>Filesystem removed API
|
||||
|
||||
The following image manipulations previously deprecated has been removed:
|
||||
|
||||
* `Image::SetRatioSize` superceded by `Fit`
|
||||
* `Image::SetWidth` superceded by `ScaleWidth`
|
||||
* `Image::SetHeight` superceded by `ScaleHeight`
|
||||
* `Image::SetSize` superceded by `Pad`
|
||||
* `Image::PaddedImage` superceded by `Pad`
|
||||
* `Image::CroppedImage` superceded by `Fill`
|
||||
* `Image::AssetLibraryPreview` superceded by `PreviewThumbnail`
|
||||
* `Image::AssetLibraryThumbnail` superceded by `CMSThumbnail`
|
||||
|
||||
The following `File` methods have been removed. Since there is no longer any assumed local path for any file,
|
||||
methods which dealt with such paths may no longer be relied on.
|
||||
|
||||
* `File::deletedatabaseOnly`
|
||||
* `File::link_shortcode_handler` renamed to `handle_shortcode`
|
||||
* `File::setParentID`
|
||||
* `File::getFullPath`
|
||||
* `File::getRelativePath`
|
||||
* `File::Content` database field is removed
|
||||
|
||||
Image manipulations have been moved out of Image.php and now available to any File or DBFile which has the
|
||||
appropriate mime types. The following file manipulations classes and methods have been removed:
|
||||
|
||||
* `Image_Cached` class
|
||||
* `Image::regenerateFormattedImages` method
|
||||
* `Image::getGeneratedImages` method
|
||||
* `Image::deleteFormattedImages` method
|
||||
* `AssetAdmin::deleteunusedthumbnails` method
|
||||
* `AssetAdmin::getUnusedThumbnails` method
|
||||
|
||||
Many `Folder` api have also been removed:
|
||||
|
||||
* `Folder_UnusedAssetsField` class
|
||||
* `Folder::syncChildren` method
|
||||
* `Folder::constructChild` method
|
||||
* `Folder::addUploadToFolder` method
|
||||
|
||||
The following filesystem synchronisation methods and tasks are also removed
|
||||
|
||||
* `RegenerateCachedImagesTask` class
|
||||
* `CleanImageManipulationCache` class
|
||||
* `Filesystem::sync` method
|
||||
* `AssetAdmin::doSync` method
|
||||
|
||||
### <a name="overview-template"></a>Template and Form API
|
||||
|
||||
#### <a name="overview-template-api"></a>Template and Form API Additions / Changes
|
||||
|
||||
* Upgrade of TinyMCE to version 4.
|
||||
* Templates now use a standard template lookup system via `SSViewer::get_templates_by_class`
|
||||
which builds a candidate list for a given class. Actual resolution of existing templates
|
||||
for any list of candidates is actually performed by `SSViewer::chooseTemplate`
|
||||
* `HtmlEditorConfig` is now an abstract class, with a default implementation `TinyMCEConfig` for the built in
|
||||
TinyMCE editor.
|
||||
* `HtmlEditorField::setEditorConfig` may now take an instance of a `HtmlEditorConfig` class, as well as a
|
||||
standard config identifier name.
|
||||
* `HeaderField` requires a `$name` constructor argument (`new HeaderField('MyName', 'My Title')`
|
||||
* `default_cast` is now enforced on all template variables. See upgrading notes below.
|
||||
* FormField templates no longer look in the 'forms' folder for templates. As all form fields are
|
||||
now namespaced, the path for these templates will now match the namespace of the given class instead.
|
||||
* `$module` parameter in `themedCSS` and `themedJavascript` removed.
|
||||
* Theme selector has been removed from SiteConfig. Please use `SSViewer.themes` config instead.
|
||||
* `FormAction::setValidationExempt` can be used to turn on or off form validation for individual actions
|
||||
* GridField edit form now has improved support for versioned DataObjects, with basic publishing
|
||||
actions available when editing records.
|
||||
* `PopoverField` added to provide popup-menu behaviour in react forms (currently not available for
|
||||
non-react forms).
|
||||
|
||||
The following methods and properties on `Requirements_Backend` have been renamed:
|
||||
|
||||
* `Requirements_Backund::$combine_files` made protected and renamed `$combinedFiles`
|
||||
* `Requirements_Backend::$combine_js_with_min` made protected and renamed `$minifyCombinedFiles`
|
||||
* `Requirements_Backend::$write_header_comments` made protected and renamed `$writeHeaderComment`
|
||||
* `Requirements_Backend::$write_js_to_body` made protected and renamed to `$writeJavascriptToBody`
|
||||
* `Requirements_Backend::$force_js_to_bottom` renamed to `$forceJSToBottom`
|
||||
* `get_combined_files_enabled` renamed to `getCombinedFilesEnabled`
|
||||
* `set_combined_files_enabled` renamed to `setCombinedFilesEnabled`
|
||||
* `get_suffix_requirements` renamed to `getSuffixRequirements`
|
||||
* `set_suffix_requirements` renamed to `setSuffixRequirements`
|
||||
* `get_custom_scripts` renamed to `getCustomScripts`
|
||||
* `unblock_all` renamed to `unblockAll`
|
||||
* `include_in_response` renamed to `includeInResponse`
|
||||
* `combine_files` renamed to `combineFiles`
|
||||
* `get_combine_files` renamed to `getCombinedFiles`
|
||||
* `clear_combined_files` renamed to `clearCombinedFiles`
|
||||
* `process_combined_files` renamed to `processCombinedFiles`
|
||||
* `set_write_js_to_body` renamed to `setWriteJavascriptToBody`
|
||||
* `set_force_js_to_bottom` renamed to `setForceJSToBottom`
|
||||
|
||||
New methods on `Requirements` are added to access these:
|
||||
|
||||
* `get_minify_combined_js_files`
|
||||
* `set_minify_combined_js_files`
|
||||
* `get_force_js_to_bottom`
|
||||
* `get_write_js_to_body`
|
||||
|
||||
Some methods on `Requirements` have had their method signatures changed:
|
||||
|
||||
* `includeInHTML` has had the first parameter $template removed as it was previously deprecated.
|
||||
|
||||
A new config `Requirements_Backend.combine_in_dev` has been added in order to allow combined files to be
|
||||
forced on during development. If this is off, combined files is only enabled in live environments.
|
||||
|
||||
#### <a name="overview-template-removed"></a>Template and Form Removed API
|
||||
|
||||
* Removed `TabularStyle`
|
||||
* Removed `NestedForm`
|
||||
* Removed `FieldList` methods:
|
||||
* `getTabPathRewrites`
|
||||
* `setTabPathRewrites`
|
||||
* `rewriteTabPath`
|
||||
* Removed `Form` methods:
|
||||
* `transformTo`
|
||||
* `callfieldmethod`
|
||||
* `single_field_required`
|
||||
* `current_action`
|
||||
* `set_current_action`
|
||||
* Removed `ReportAdminForm.ss` template
|
||||
* `FormField::dontEscape()` has been removed. Escaping is now managed on a class by class basis.
|
||||
* Removed `PermissionCheckboxSetField::getAssignedPermissionCodes()` (never implemented)
|
||||
* `Requirements::delete_combined_files()` and `Requirements::delete_combined_files()` methods have been removed
|
||||
as they are obsolete.
|
||||
|
||||
Loading…
Reference in New Issue
Block a user