tonyair/silverstripe-framework
1
0
Fork 0
mirror of https://github.com/silverstripe/silverstripe-framework synced 2024-10-22 14:05:37 +02:00
Code Issues Projects Releases Wiki Activity

Fix changelog anchors

Browse Source 
See https://raw.githubusercontent.com/silverstripe/silverstripe-docsviewer/f61751b19e5d22dba7e72d2c195b723376dc2b71/tests/docs/en/test.md for correct format.
This commit is contained in:
Ingo Schommer 2017-10-26 08:41:18 +13:00
parent 79a5daa0a9
commit 8725672eae
1 changed files with 69 additions and 69 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

138
docs/en/04_Changelogs/4.0.0.md
View File

@ -6,7 +6,7 @@ This version introduces many breaking changes, which in most projects can be man
of automatic upgrade processes as well as manual code review. This document reviews these changes and will 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 guide developers in preparing existing 3.x code for compatibility with 4.0
## <a name="overview"></a>Overview ## Overview {#overview}
* Minimum version dependencies have increased; PHP 5.5 and Internet Explorer 11 (or other modern browser) * Minimum version dependencies have increased; PHP 5.5 and Internet Explorer 11 (or other modern browser)
is required. is required.
@ -52,13 +52,13 @@ guide developers in preparing existing 3.x code for compatibility with 4.0
* Core modules are installed in the `vendor/` folder by default (other modules can opt-in, see [guide](/developer_guides/extending/how_tos/publish_a_module)) * Core modules are installed in the `vendor/` folder by default (other modules can opt-in, see [guide](/developer_guides/extending/how_tos/publish_a_module))
* Renamed constant for temp folder from `TEMP_FOLDER` to `TEMP_PATH` for naming consistency with other path variables and constants * Renamed constant for temp folder from `TEMP_FOLDER` to `TEMP_PATH` for naming consistency with other path variables and constants
## <a name="upgrading"></a>Upgrading Guide ## Upgrading Guide {#upgrading}
The below sections describe how to go about updating an existing site to be prepared for upgrade to 4.0. 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 Most of these upgrading tasks will involve manual code review, although in some cases there are
some automated processes that users can run. some automated processes that users can run.
### <a name="deps"></a>Composer dependency update ### Composer dependency update {#deps}
As a first step, you need to update your composer dependencies. As a first step, you need to update your composer dependencies.
The easiest way is to start with a new `composer.json` file The easiest way is to start with a new `composer.json` file
@ -126,7 +126,7 @@ you should raise an issue on the repository asking for 4.0 compatibility.
For now, you should attempt to continue the upgrade without the module For now, you should attempt to continue the upgrade without the module
and temporarily disable its functionality. and temporarily disable its functionality.
### <a name="upgrader-tool"></a>Install the upgrader tool ### Install the upgrader tool {#upgrader-tool}
A lot of upgrade work can be automated, and we've written an A lot of upgrade work can be automated, and we've written an
[upgrader tool](https://github.com/silverstripe/silverstripe-upgrader/) for this purpose. [upgrader tool](https://github.com/silverstripe/silverstripe-upgrader/) for this purpose.
@ -136,7 +136,7 @@ Install it via composer:
composer global require silverstripe/upgrader composer global require silverstripe/upgrader
``` ```
### <a name="index-php-rewrites"></a>index.php and .htaccess rewrites ### index.php and .htaccess rewrites {#index-php-rewrites}
The location of SilverStripe's "entry file" has changed. Your project and server environment will need The location of SilverStripe's "entry file" has changed. Your project and server environment will need
to adjust the path to this file from `framework/main.php` to `index.php`. to adjust the path to this file from `framework/main.php` to `index.php`.
@ -167,7 +167,7 @@ for a clean installation. If you have applied customisations to your `.htaccess`
file (e.g. a custom `main.php`, HTTP header configuration, deny file access), file (e.g. a custom `main.php`, HTTP header configuration, deny file access),
you'll need to manually reapply these to the copied default file. you'll need to manually reapply these to the copied default file.
### <a name="namespaced-classes"></a>Renamed and namespaced classes ### Renamed and namespaced classes {#namespaced-classes}
Nearly all core PHP classes have been namespaced. For example, `DataObject` is now called `SilverStripe\ORM\DataObject`. Nearly all core PHP classes have been namespaced. For example, `DataObject` is now called `SilverStripe\ORM\DataObject`.
The below tasks describe how to upgrade an existing site to remain compatible with the newly upgraded classes. The below tasks describe how to upgrade an existing site to remain compatible with the newly upgraded classes.
@ -189,7 +189,7 @@ For a full list of renamed classes, check the `.upgrade.yml` definitions in each
The rename won't affect class-based permission codes or database table names. The rename won't affect class-based permission codes or database table names.
### <a name="env"></a>`_ss_environment.php` changed to`.env` ### `_ss_environment.php` changed to`.env` {#env}
The php configuration `_ss_environment.php` file has been replaced in favour of a non-executable The php configuration `_ss_environment.php` file has been replaced in favour of a non-executable
`.env` file, which follows a syntax similar to an `.ini` file for key/value pair assignment. Like `.env` file, which follows a syntax similar to an `.ini` file for key/value pair assignment. Like
@ -255,7 +255,7 @@ To access environment variables you can use the `SilverStripe\Core\Environment::
See [Environment Management docs](/getting-started/environment_management/) for full details. See [Environment Management docs](/getting-started/environment_management/) for full details.
### <a name="migrate-file"></a>Migrate File DataObject ### Migrate File DataObject {#migrate-file}
Since the structure of `File` dataobjects has changed, a new task `MigrateFileTask` Since the structure of `File` dataobjects has changed, a new task `MigrateFileTask`
has been added to assist in migration of legacy files (see [file migration documentation](/developer_guides/files/file_migration)). has been added to assist in migration of legacy files (see [file migration documentation](/developer_guides/files/file_migration)).
@ -274,7 +274,7 @@ SilverStripe\Assets\FileMigrationHelper:
delete_invalid_files: false delete_invalid_files: false
``` ```
### <a name="inspect-hints"></a>Get upgrade tips on your code ### Get upgrade tips on your code {#inspect-hints}
While there's some code we can automatically rewrite, other uses of changed SilverStripe APIs aren't that obvious. While there's some code we can automatically rewrite, other uses of changed SilverStripe APIs aren't that obvious.
You can use our heuristics to get some hints on where you need to review code manually. You can use our heuristics to get some hints on where you need to review code manually.
@ -288,7 +288,7 @@ This task should be run *after* `upgrade-code upgrade`.
These hints only cover a part of the upgrade work, These hints only cover a part of the upgrade work,
but can serve as a good indicator for where to start. but can serve as a good indicator for where to start.
### <a name="literal-table-names"></a>Rewrite literal table names ### Rewrite literal table names {#literal-table-names}
In 3.x the class name of any DataObject matched the table name, but in 4.x all classes are namespaced, and it is In 3.x the class name of any DataObject matched the table name, but in 4.x all classes are namespaced, and it is
necessary to map between table and class for querying the database. necessary to map between table and class for querying the database.
@ -311,7 +311,7 @@ public function countDuplicates($model, $fieldToCheck)
} }
``` ```
### <a name="literal-class-names"></a>Rewrite literal class names ### Rewrite literal class names {#literal-class-names}
You'll need to update any strings that represent class names and make sure they're fully You'll need to update any strings that represent class names and make sure they're fully
qualified. In particular, relationship definitions such as `has_one` and `has_many` will need qualified. In particular, relationship definitions such as `has_one` and `has_many` will need
@ -341,7 +341,7 @@ In the context of YAML, the magic constant `::class` does not apply. Fully quali
property: value property: value
``` ```
### <a name="controllers-own-files"></a>Move controllers to their own files ### Move controllers to their own files {#controllers-own-files}
The convention for naming controllers is now `[MyPageType]Controller`, where it used to be `[MyPageType]_Controller`. This change was made to be more compatible with the PSR-2 standards. The convention for naming controllers is now `[MyPageType]Controller`, where it used to be `[MyPageType]_Controller`. This change was made to be more compatible with the PSR-2 standards.
@ -351,7 +351,7 @@ other thirdparty code that extend `PageController` are likely to assume that cla
By default, a controller for a page type *must* reside in the same namespace as its page. To use different logic, override `SiteTree::getControllerName()`. By default, a controller for a page type *must* reside in the same namespace as its page. To use different logic, override `SiteTree::getControllerName()`.
### <a name="template-locations"></a>Template locations and references ### Template locations and references {#template-locations}
Templates are now more strict about their locations. Templates are now more strict about their locations.
Case is now also checked on case-sensitive filesystems. Case is now also checked on case-sensitive filesystems.
@ -372,7 +372,7 @@ if the former is not present.
Please refer to our [template syntax](/developer_guides/templates/syntax) for details. Please refer to our [template syntax](/developer_guides/templates/syntax) for details.
### <a name="private-static"></a>Config settings should be set to `private static` ### Config settings should be set to `private static` {#private-static}
Class configuration defined as `static` properties need to be marked as `private` to take effect: Class configuration defined as `static` properties need to be marked as `private` to take effect:
@ -383,7 +383,7 @@ Class configuration defined as `static` properties need to be marked as `private
]; ];
``` ```
### <a name="module-paths"></a>Module paths can't be hardcoded ### Module paths can't be hardcoded {#module-paths}
You should no longer rely on modules being placed in a deterministic folder (e.g. `/framework`), You should no longer rely on modules being placed in a deterministic folder (e.g. `/framework`),
and use getters on the [Module](api:SilverStripe\Core\Manifest\Module) object instead. and use getters on the [Module](api:SilverStripe\Core\Manifest\Module) object instead.
@ -453,7 +453,7 @@ To ensure consistency, we've also deprecated support for path constants:
* Deprecated `THEMES_DIR` and `THEMES_PATH` * Deprecated `THEMES_DIR` and `THEMES_PATH`
* Deprecated `MODULES_PATH` and `MODULES_DIR` * Deprecated `MODULES_PATH` and `MODULES_DIR`
### <a name="vendor-folder"></a>Adapt tooling to modules in vendor folder ### Adapt tooling to modules in vendor folder {#vendor-folder}
SilverStripe modules can now be installed like any other composer package: In the `vendor/` folder SilverStripe modules can now be installed like any other composer package: In the `vendor/` folder
instead of the webroot. Modules need to opt in to this behaviour after they've ensured instead of the webroot. Modules need to opt in to this behaviour after they've ensured
@ -479,7 +479,7 @@ and this environment supports symlinks, you don't need to change anything.
If you deploy release archives, either ensure those archives can correctly extract symlinks, If you deploy release archives, either ensure those archives can correctly extract symlinks,
or explicitly switch to the "copy" mode to avoid symlinks. or explicitly switch to the "copy" mode to avoid symlinks.
### <a name="psr3-logging"></a>SS_Log replaced with PSR-3 logging ### SS_Log replaced with PSR-3 logging {#psr3-logging}
One of the great changes that comes with SilverStripe 4 is the introduction of One of the great changes that comes with SilverStripe 4 is the introduction of
[PSR-3](http://www.php-fig.org/psr/psr-3/) compatible logger interfaces. This [PSR-3](http://www.php-fig.org/psr/psr-3/) compatible logger interfaces. This
@ -532,7 +532,7 @@ SilverStripe\Core\Injector\Injector:
`WebDesignGroup\ShopSite\Logging\ErrorPageFormatter` should be a class that `WebDesignGroup\ShopSite\Logging\ErrorPageFormatter` should be a class that
implements the `Monolog\Formatter\FormatterInterface` interface. implements the `Monolog\Formatter\FormatterInterface` interface.
### <a name="config-php"></a>Upgrade `mysite/_config.php` ### Upgrade `mysite/_config.php` {#config-php}
The globals `$database` and `$databaseConfig` are deprecated. You should upgrade your The globals `$database` and `$databaseConfig` are deprecated. You should upgrade your
site `_config.php` files to use the [.env configuration](#env) site `_config.php` files to use the [.env configuration](#env)
@ -561,7 +561,7 @@ SilverStripe\Core\Manifest\ModuleManifest:
project: mysite project: mysite
``` ```
### <a name="object-replace"></a>Object class replaced by traits ### Object class replaced by traits {#object-replace}
Object has been superseded by traits. Object has been superseded by traits.
@ -630,7 +630,7 @@ Upgrade extension use
+$extensions = DataObject::get_extensions(File::class); // alternate +$extensions = DataObject::get_extensions(File::class); // alternate
``` ```
### <a name="session"></a>Session object removes static methods ### Session object removes static methods {#session}
Session object is no longer statically accessible via `Session::inst()`. Instead, Session Session object is no longer statically accessible via `Session::inst()`. Instead, Session
is a member of the current request. is a member of the current request.
@ -648,7 +648,7 @@ In some places it may still be necessary to access the session object where no r
In rare cases it is still possible to access the request of the current controller via In rare cases it is still possible to access the request of the current controller via
`Controller::curr()->getRequest()` to gain access to the current session. `Controller::curr()->getRequest()` to gain access to the current session.
### <a name="extensions-singletons"></a>Extensions are now singletons ### Extensions are now singletons {#extensions-singletons}
Extensions are now all singletons, meaning that state stored as protected vars Extensions are now all singletons, meaning that state stored as protected vars
within extensions are now shared across all object instances that use this extension. within extensions are now shared across all object instances that use this extension.
@ -707,7 +707,7 @@ class MyClass extends DataObject {
} }
``` ```
### <a name="static-asset-paths"></a>Static references to asset paths ### Static references to asset paths {#static-asset-paths}
All static files (images, javascript, stylesheets, fonts) used for the CMS and forms interfaces 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, in `framework` and `cms` have moved locations. These assets are now placed in a `client/` subfolder,
@ -781,7 +781,7 @@ framework/thirdparty/jquery/jquery.js => framework/admin/thirdparty/jquery/jquer
If you have customised the CMS UI (via JavaScript or CSS), please read our guide to If you have customised the CMS UI (via JavaScript or CSS), please read our guide to
[customise the admin interface](/developer_guides/customising_the_admin_interface/). [customise the admin interface](/developer_guides/customising_the_admin_interface/).
### <a name="template-casting"></a>Explicit text casting on template variables ### Explicit text casting on template variables {#template-casting}
Now whenever a `$Variable` is used in a template, regardless of whether any casts or methods are 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 suffixed to the reference, it will be cast to either an explicit DBField for that field, or
@ -816,7 +816,7 @@ class MyObject extends ViewableData
If you need to encode a field (such as `HTMLText`) for use in HTML attributes, use `.ATT` 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)). instead, or if used in an actual XML file use `.CDATA` (see [template casting](/developer_guides/templates/casting)).
### <a name="uploadfield"></a>Replace UploadField with injected service ### Replace UploadField with injected service {#uploadfield}
This field has been superceded by a new class provided by the This field has been superceded by a new class provided by the
[asset-admin](https://github.com/silverstripe/silverstripe-asset-admin) module, which provides a more [asset-admin](https://github.com/silverstripe/silverstripe-asset-admin) module, which provides a more
@ -844,7 +844,7 @@ class MyClass extends DataObject
} }
``` ```
### <a name="i18n"></a>i18n placeholders, plurals and i18nEntityProvider ### i18n placeholders, plurals and i18nEntityProvider {#i18n}
In many cases, localisation strings which worked in 3.x will continue to work in 4.0, however certain patterns In many cases, localisation strings which worked in 3.x will continue to work in 4.0, however certain patterns
have been deprecated and will be removed in 5.0. These include: have been deprecated and will be removed in 5.0. These include:
@ -937,7 +937,7 @@ In templates this can also be invoked as below:
<%t MyObject.PLURALS 'An item|{count} items' count=$Count %> <%t MyObject.PLURALS 'An item|{count} items' count=$Count %>
``` ```
### <a name="member-date-time-fields"></a>Removed Member.DateFormat and Member.TimeFormat database settings ### Removed Member.DateFormat and Member.TimeFormat database settings {#member-date-time-fields}
We're using [native HTML5 date and time pickers](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/date) We're using [native HTML5 date and time pickers](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/date)
in `DateField` and `TimeField` now ([discussion](https://github.com/silverstripe/silverstripe-framework/issues/6626)), in `DateField` and `TimeField` now ([discussion](https://github.com/silverstripe/silverstripe-framework/issues/6626)),
@ -950,7 +950,7 @@ Consequently, we've also removed `MemberDatetimeOptionsetField`.
the [IntlDateFormatter defaults](http://php.net/manual/en/class.intldateformatter.php) for the selected locale. the [IntlDateFormatter defaults](http://php.net/manual/en/class.intldateformatter.php) for the selected locale.
### <a name="asset-storage"></a>New asset storage mechanism ### New asset storage mechanism {#asset-storage}
File system has been abstracted into an abstract interface. By default, the out of the box filesystem 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). uses [Flysystem](http://flysystem.thephpleague.com/) with a local storage mechanism (under the assets directory).
@ -975,7 +975,7 @@ Depending on your server configuration, it may also be necessary to adjust your
permissions. Please see the [common installation problems](/getting_started/installation/common_problems) permissions. Please see the [common installation problems](/getting_started/installation/common_problems)
guide for configuration instruction. guide for configuration instruction.
### <a name="image-handling"></a>Image handling ### Image handling {#image-handling}
As all image-specific manipulations has been refactored from `Image` into an `ImageManipulations` trait, which 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 is applied to both `File` and `DBFile`. These both implement a common interface `AssetContainer`, which
@ -1015,7 +1015,7 @@ class MyObject extends SilverStripe\ORM\DataObject
} }
``` ```
### <a name="write-file-dataobject"></a>Writing to `File` dataobjects or the assets folder ### Writing to `File` dataobjects or the assets folder {#write-file-dataobject}
In the past all that was necessary to write a `File` DataObject to the database was to ensure a physical file 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. existed in the assets folder, and that the Filename of the DataObject was set to the same location.
@ -1062,7 +1062,7 @@ You can disable File versioning by adding the following to your `_config.php`
SilverStripe\Assets\File::remove_extension('Versioned'); SilverStripe\Assets\File::remove_extension('Versioned');
``` ```
### <a name="image-manipulations"></a>Custom image manipulations ### Custom image manipulations {#image-manipulations}
As file storage and handling has been refactored into the abstract interface, many other components which were 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, once specific to Image.php have now been moved into a shared `ImageManipulation` trait. Manipulations of file content,
@ -1130,7 +1130,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, 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. an `AssetStore` instance and file tuple (Filename, Hash, and Variant) rather than an Image_Backend.
### <a name="file-shortcode"></a>File or Image shortcode handler ### File or Image shortcode handler {#file-shortcode}
The `handle_shortcode` methods have been removed from the core File and Image classes The `handle_shortcode` methods have been removed from the core File and Image classes
and moved to separate classes in their own respective namespace. and moved to separate classes in their own respective namespace.
@ -1155,7 +1155,7 @@ class MyShortcodeUser extends Object
} }
``` ```
### <a name="compositedbfield"></a>Composite db fields ### Composite db fields {#compositedbfield}
The `CompositeDBField` interface has been replaced with an abstract class, `DBComposite`. In many cases, custom code 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. that handled saving of content into composite fields can be removed, as it is now handled by the base class.
@ -1181,7 +1181,7 @@ class MyAddressField extends
} }
``` ```
### <a name="dataobject-db-database-fields"></a>`DataObject::database_fields` or `DataObject::db` ### `DataObject::database_fields` or `DataObject::db` {#dataobject-db-database-fields}
These methods have been updated to include base fields (such as ID, ClassName, Created, and LastEdited), as These methods have been updated to include base fields (such as ID, ClassName, Created, and LastEdited), as
well as composite DB fields. well as composite DB fields.
@ -1197,7 +1197,7 @@ when set to true (with a field name as the first parameter), will also include t
`Table.ClassName(args)` format. `Table.ClassName(args)` format.
### <a name="sqlquery"></a>Rewrite SQLQuery to more specific classes ### Rewrite SQLQuery to more specific classes {#sqlquery}
Instead of `SQLQuery`, you should now use `SQLSelect`, `SQLUpdate`, `SQLInsert` Instead of `SQLQuery`, you should now use `SQLSelect`, `SQLUpdate`, `SQLInsert`
or `SQLDelete` - check the [3.2.0](3.2.0#sqlquery) upgrading notes for details. or `SQLDelete` - check the [3.2.0](3.2.0#sqlquery) upgrading notes for details.
@ -1215,7 +1215,7 @@ Example:
} }
``` ```
### <a name="buildtask-segment"></a>Upgrade BuildTask classes ### Upgrade BuildTask classes {#buildtask-segment}
Similarly to the `$table_name` configuration property for DataObjects, you should define a `private static $segment` for `BuildTask` Similarly to the `$table_name` configuration property for DataObjects, you should define a `private static $segment` for `BuildTask`
instances to ensure that you can still run your task via `sake dev/tasks/MyTask`. Without defining it, the default instances to ensure that you can still run your task via `sake dev/tasks/MyTask`. Without defining it, the default
@ -1230,7 +1230,7 @@ class MyTask extends BuildTask
} }
``` ```
### <a name="errorpage"></a>Moved ErrorPage into a new module ### Moved ErrorPage into a new module {#errorpage}
ErrorPage has been moved to a separate [silverstripe/errorpage module](http://addons.silverstripe.org/add-ons/silverstripe/errorpage) ErrorPage has been moved to a separate [silverstripe/errorpage module](http://addons.silverstripe.org/add-ons/silverstripe/errorpage)
to allow for alternative approaches to managing error responses. to allow for alternative approaches to managing error responses.
@ -1244,7 +1244,7 @@ By default, SilverStripe will display a plaintext "not found" message when the m
Check the [module upgrading guide](http://addons.silverstripe.org/add-ons/silverstripe/errorpage) Check the [module upgrading guide](http://addons.silverstripe.org/add-ons/silverstripe/errorpage)
for more configuration API changes on the `ErrorPage` class. for more configuration API changes on the `ErrorPage` class.
### <a name="assets-server-config"></a>Server configuration files for assets ### Server configuration files for assets {#assets-server-config}
Server configuration files for `/assets` are no longer static, and are regenerated via a set of Server configuration files for `/assets` are no longer static, and are regenerated via a set of
standard SilverStripe templates on flush. These templates include: standard SilverStripe templates on flush. These templates include:
@ -1265,7 +1265,7 @@ If upgrading from an existing installation, make sure to invoke `?flush=all` at
See our ["File Security" guide](/developer_guides/files/file_security) for more information. See our ["File Security" guide](/developer_guides/files/file_security) for more information.
### <a name="tinymce"></a>TinyMCE v4 ### TinyMCE v4 {#tinymce}
Please see the [tinymce upgrading guide](http://archive.tinymce.com/wiki.php/Tutorial:Migration_guide_from_3.x) 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 v3. to assist with upgrades to customisations to TinyMCE v3.
@ -1306,7 +1306,7 @@ $editor->setOption('charmap_append', [
]); ]);
``` ```
### <a name="dataobject-versioned"></a>DataObjects with the `Versioned` extension ### DataObjects with the `Versioned` extension {#dataobject-versioned}
In most cases, versioned models with the default versioning parameters will not need to be changed. However, 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. there are now additional restrictions on the use of custom stage names.
@ -1354,7 +1354,7 @@ These methods are deprecated:
* `Versioned::publish` Replaced by `Versioned::copyVersionToStage` * `Versioned::publish` Replaced by `Versioned::copyVersionToStage`
* `Versioned::doPublish` Replaced by `Versioned::publishRecursive` * `Versioned::doPublish` Replaced by `Versioned::publishRecursive`
### <a name="ownership"></a>New Ownership API ### New Ownership API {#ownership}
In order to support the recursive publishing of dataobjects, a new API has been developed to allow In order to support the recursive publishing of dataobjects, a new API has been developed to allow
developers to declare dependencies between objects. This is done to ensure that the published state developers to declare dependencies between objects. This is done to ensure that the published state
@ -1399,14 +1399,14 @@ setting on the child object.
For more information, see the [DataObject ownership](https://docs.silverstripe.org/en/4/developer_guides/model/versioning/#dataobject-ownership) documentation and the [versioning](/developer_guides/model/versioning) documentation For more information, see the [DataObject ownership](https://docs.silverstripe.org/en/4/developer_guides/model/versioning/#dataobject-ownership) documentation and the [versioning](/developer_guides/model/versioning) documentation
### <a name="changeset"></a>ChangeSet batch publishing ### ChangeSet batch publishing {#changeset}
ChangeSet objects have been added, which allow groups of objects to be published in ChangeSet objects have been added, which allow groups of objects to be published in
a single atomic transaction. a single atomic transaction.
This API will utilise the ownership API to ensure that changes to any object include 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. all necessary changes to owners or owned entities within the same changeset.
### <a name="image-shortcode"></a>New `[image]` shortcode in `HTMLText` fields ### New `[image]` shortcode in `HTMLText` fields {#image-shortcode}
The new Ownership API relies on relationships between objects. 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`. Many of these relationships are already made explicit through `has_one`, `has_many` and `many_many`.
@ -1416,7 +1416,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, when the field is rendered. Newly inserted images will automatically receive the shortcode and ownership tracking,
and existing `<img>` will continue to work. and existing `<img>` will continue to work.
### <a name="dbfield-rename"></a>Renamed DBField and subclasses ### Renamed DBField and subclasses {#dbfield-rename}
All `DBField` subclasses are namespaced, have a `DB` prefix, and drop any existing `SS_` prefix. All `DBField` subclasses are namespaced, have a `DB` prefix, and drop any existing `SS_` prefix.
For example, `Text` becomes `SilverStripe\ORM\FieldType\DBText`, For example, `Text` becomes `SilverStripe\ORM\FieldType\DBText`,
@ -1448,17 +1448,17 @@ class MyObject extends DataObject
} }
``` ```
### <a name="restfulservice"></a>Removed RestfulService ### Removed RestfulService {#restfulservice}
The `RestfulService` API was a (poor) attempt at a built-in HTTP client. The `RestfulService` API was a (poor) attempt at a built-in HTTP client.
We've removed it, and recommend using [Guzzle](http://docs.guzzlephp.org/en/latest/) instead. We've removed it, and recommend using [Guzzle](http://docs.guzzlephp.org/en/latest/) instead.
### <a name="oembed"></a>Removed Oembed ### Removed Oembed {#oembed}
Instead of Oembed, the framework now relies on [oscarotero/Embed](https://github.com/oscarotero/Embed) to handle getting the shortcode-data for embedding. 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 this package. If you have custom embedding-code relying on `Oembed`, please refer to the documentation provided by this package.
### <a name="admin-url"></a>Configurable Admin URL ### Configurable Admin URL {#admin-url}
The default `admin/` URL to access the CMS interface can now be changed via a custom Director routing rule for 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 `AdminRootController`. If your website or module has hard coded `admin` URLs in PHP, templates or JavaScript, make sure
@ -1466,7 +1466,7 @@ 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 [CMS architecture](/developer_guides/customising_the_admin_interface/cms-architecture#the-admin-url) for language
specific functions. specific functions.
### <a name="custom-authenticators"></a>Custom Authenticators ### Custom Authenticators {#custom-authenticators}
The methods `register()` and `unregister()` on `Authenticator` are deprecated in favour The methods `register()` and `unregister()` on `Authenticator` are deprecated in favour
of the `Config` system. This means that any custom `Authenticator` needs to be registered of the `Config` system. This means that any custom `Authenticator` needs to be registered
@ -1496,7 +1496,7 @@ which are called from the `AuthenticationHandler`.
If there is a valid `Member`, it is set on `Security::setCurrentUser()`, which defaults to `null`. If there is a valid `Member`, it is set on `Security::setCurrentUser()`, which defaults to `null`.
IdentityStores are responsible for logging members in and out (e.g. destroy cookies and sessions, or instantiate them). IdentityStores are responsible for logging members in and out (e.g. destroy cookies and sessions, or instantiate them).
### <a name="config"></a>Config is now immutable ### Config is now immutable {#config}
Performance optimisations have been made to Config which, under certain circumstances, require developer Performance optimisations have been made to Config which, under certain circumstances, require developer
care when modifying or caching config values. The top level config object is now immutable on application care when modifying or caching config values. The top level config object is now immutable on application
@ -1514,7 +1514,7 @@ One removed feature is the `Config::FIRST_SET` option. Either use uninherited co
directly, or use the inherited config lookup. As falsey values now overwrite all parent class values, it is directly, or use the inherited config lookup. As falsey values now overwrite all parent class values, it is
now generally safer to use the default inherited config, where in the past you would need to use `FIRST_SET`. now generally safer to use the default inherited config, where in the past you would need to use `FIRST_SET`.
### <a name="cache"></a>Replace Zend_Cache with symfony/cache ### Replace Zend_Cache with symfony/cache {#cache}
We have replaced the unsupported `Zend_Cache` library with [symfony/cache](https://github.com/symfony/cache). We have replaced the unsupported `Zend_Cache` library with [symfony/cache](https://github.com/symfony/cache).
This also allowed us to remove SilverStripe's `Cache` API and use dependency injection with a standard This also allowed us to remove SilverStripe's `Cache` API and use dependency injection with a standard
@ -1599,7 +1599,7 @@ SilverStripe\Core\Injector\Injector:
client: '%$MemcachedClient client: '%$MemcachedClient
``` ```
### <a name="usercode-style-upgrades"></a>User-code style upgrades ### User-code style upgrades {#usercode-style-upgrades}
Although it is not mandatory to upgrade project code to follow SilverStripe and Although it is not mandatory to upgrade project code to follow SilverStripe and
PSR-2 standard it is highly recommended to ensure that code is consistent. The below sections PSR-2 standard it is highly recommended to ensure that code is consistent. The below sections
@ -1675,7 +1675,7 @@ class GalleryPage extends Page
} }
``` ```
### <a name="class-name-remapping"></a>Class name remapping ### Class name remapping {#class-name-remapping}
If you've namespaced one of your custom page types, you may notice a message in the CMS If you've namespaced one of your custom page types, you may notice a message in the CMS
telling you it's obsolete. This is likely because the `ClassName` telling you it's obsolete. This is likely because the `ClassName`
@ -1699,7 +1699,7 @@ SilverStripe\ORM\DatabaseAdmin:
The next time you run a dev/build the class name for all `GalleryPage` pages will The next time you run a dev/build the class name for all `GalleryPage` pages will
be automatically updated to the new `WebDesignGroup\ShopSite\GalleryPage` be automatically updated to the new `WebDesignGroup\ShopSite\GalleryPage`
### <a name="psr2"></a>PSR-2 Coding Standard compliance ### PSR-2 Coding Standard compliance {#psr2}
You can use the [php codesniffer](https://github.com/squizlabs/PHP_CodeSniffer) tool You can use the [php codesniffer](https://github.com/squizlabs/PHP_CodeSniffer) tool
to not only detect and lint PSR-2 coding errors, but also do some minimal automatic to not only detect and lint PSR-2 coding errors, but also do some minimal automatic
@ -1717,7 +1717,7 @@ code style migration.
Repeat the final step and manually repair suggested changes, as necessary, Repeat the final step and manually repair suggested changes, as necessary,
until you no longer have any linting issues. until you no longer have any linting issues.
### <a name="psr4"></a>PSR-4 autoloading for project code ### PSR-4 autoloading for project code {#psr4}
While not critical to an upgrade, SilverStripe 4.0 has adopted the [PS-4 autoloading](http://www.php-fig.org/psr/psr-4/) While not critical to an upgrade, SilverStripe 4.0 has adopted the [PS-4 autoloading](http://www.php-fig.org/psr/psr-4/)
standard for the core modules, so it's probably a good idea to be consistent. standard for the core modules, so it's probably a good idea to be consistent.
@ -1751,9 +1751,9 @@ Please note that there are changes to template structure which in some cases
require templates to be in a folder location that matches the namespace of the class require templates to be in a folder location that matches the namespace of the class
that it belongs to, e.g. `themes/mytheme/templates/MyVendor/Foobar/Model/MyModel.ss`. that it belongs to, e.g. `themes/mytheme/templates/MyVendor/Foobar/Model/MyModel.ss`.
## <a name="api-changes"></a>API Changes ## API Changes {#api-changes}
### <a name="overview-general"></a>General ### General {#overview-general}
* Minimum PHP version raised to 5.6 (with support for PHP 7.x) * Minimum PHP version raised to 5.6 (with support for PHP 7.x)
* Dropped support for PHP safe mode (removed php 5.4). * Dropped support for PHP safe mode (removed php 5.4).
@ -1771,7 +1771,7 @@ that it belongs to, e.g. `themes/mytheme/templates/MyVendor/Foobar/Model/MyModel
* Admin URL can now be configured via custom Director routing rule * Admin URL can now be configured via custom Director routing rule
* `Controller::init` visibility changed to protected. Use `Controller::doInit()` instead. * `Controller::init` visibility changed to protected. Use `Controller::doInit()` instead.
* `Controller::join_links` supports an array of link sections. * `Controller::join_links` supports an array of link sections.
* <a name="object-usecustomclass"></a>`Object::useCustomClass` has been removed. You should use the config API with Injector instead. * `Object::useCustomClass` has been removed. You should use the config API with Injector instead. {#object-usecustomclass}
* `Object::invokeWithExtensions` now has the same method signature as `Object::extend` and behaves the same way. * `Object::invokeWithExtensions` now has the same method signature as `Object::extend` and behaves the same way.
* `ServiceConfigurationLocator` is now an interface not a class. * `ServiceConfigurationLocator` is now an interface not a class.
* `i18nTextCollectorTask` merge is now true by default. * `i18nTextCollectorTask` merge is now true by default.
@ -1925,7 +1925,7 @@ TrustedProxyMiddleware instead.
* Deprecated `Config::inst()->update()`. Use `Config::modify()->set()` or `Config::modify()->merge()` * Deprecated `Config::inst()->update()`. Use `Config::modify()->set()` or `Config::modify()->merge()`
instead. instead.
### <a name="overview-orm"></a>ORM ### ORM {#overview-orm}
* Deprecated `SQLQuery` in favour `SQLSelect` ([details](#sqlquery)) * Deprecated `SQLQuery` in favour `SQLSelect` ([details](#sqlquery))
* Added `DataObject.many_many` 'through' relationships now support join dataobjects in place of * Added `DataObject.many_many` 'through' relationships now support join dataobjects in place of
@ -2050,7 +2050,7 @@ usercode before invocation.
* Moved `DataObject::manyManyExtraFieldsForComponent()` to `DataObjectSchema` * Moved `DataObject::manyManyExtraFieldsForComponent()` to `DataObjectSchema`
* Deprecated `DataObject::$destroyed` * Deprecated `DataObject::$destroyed`
* Removed `DataObject::validateModelDefinitions`. Relations are now validated within `DataObjectSchema` * Removed `DataObject::validateModelDefinitions`. Relations are now validated within `DataObjectSchema`
* <a name="dataobject-has-own"></a>Removed `DataObject` methods `hasOwnTableDatabaseField`, `has_own_table_database_field` and * Removed `DataObject` methods `hasOwnTableDatabaseField`, `has_own_table_database_field` and {#dataobject-has-own}
`hasDatabaseFields` are superceded by `DataObjectSchema::fieldSpec`. `hasDatabaseFields` are superceded by `DataObjectSchema::fieldSpec`.
Use `$schema->fieldSpec($class, $field, DataObjectSchema::DB_ONLY | DataObjectSchema::UNINHERITED )`. Use `$schema->fieldSpec($class, $field, DataObjectSchema::DB_ONLY | DataObjectSchema::UNINHERITED )`.
Exclude `uninherited` option to search all tables in the class hierarchy. Exclude `uninherited` option to search all tables in the class hierarchy.
@ -2093,7 +2093,7 @@ usercode before invocation.
* Removed `Hierarchy::naturalPrev()` * Removed `Hierarchy::naturalPrev()`
* Removed `Hierarchy::markingFinished()` * Removed `Hierarchy::markingFinished()`
### <a name="overview-filesystem"></a>Filesystem ### Filesystem {#overview-filesystem}
* Image manipulations have been moved into a new `[ImageManipulation](api:SilverStripe\Assets\ImageManipulation)` trait. * Image manipulations have been moved into a new `[ImageManipulation](api:SilverStripe\Assets\ImageManipulation)` trait.
* Removed `CMSFileAddController` * Removed `CMSFileAddController`
@ -2167,7 +2167,7 @@ appropriate mime types. The following file manipulations classes and methods hav
* Removed `Filesystem::sync()` * Removed `Filesystem::sync()`
* Removed `AssetAdmin::doSync()` * Removed `AssetAdmin::doSync()`
### <a name="overview-template"></a>Templates and Form ### Templates and Form {#overview-template}
* Upgrade to TinyMCE 4.x * Upgrade to TinyMCE 4.x
* Templates now use a standard template lookup system via `SSViewer::get_templates_by_class()` * Templates now use a standard template lookup system via `SSViewer::get_templates_by_class()`
@ -2206,7 +2206,7 @@ appropriate mime types. The following file manipulations classes and methods hav
instead of a list of grouped values. The method now expectes instead of a list of grouped values. The method now expectes
a non-associative array of values (not titles) or an `SS_List`. a non-associative array of values (not titles) or an `SS_List`.
<a name="requirements"></a>The following methods and properties on `Requirements_Backend` have been renamed: The following methods and properties on `Requirements_Backend` have been renamed: {#requirements}
* Renamed `$combine_files` to `$combinedFiles` * Renamed `$combine_files` to `$combinedFiles`
* Renamed `$combine_js_with_min` to `$minifyCombinedFiles` * Renamed `$combine_js_with_min` to `$minifyCombinedFiles`
@ -2234,7 +2234,7 @@ appropriate mime types. The following file manipulations classes and methods hav
A new config `Requirements_Backend.combine_in_dev` has been added in order to allow combined files to be 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. forced on during development. If this is off, combined files is only enabled in live environments.
<a name="form-validation"></a>Form validation has been refactored significantly. A new `FormMessage` trait has been created to Form validation has been refactored significantly. A new `FormMessage` trait has been created to {#form-validation}
handle `FormField` and `Form` messages. This trait has a new`setMessage()` API to assign a message, type, and cast. handle `FormField` and `Form` messages. This trait has a new`setMessage()` API to assign a message, type, and cast.
Use `getMessage()`, `getMessageType()`, `getMessageCast()` and `getMessageCastingHelper()` to retrieve them. Use `getMessage()`, `getMessageType()`, `getMessageCast()` and `getMessageCastingHelper()` to retrieve them.
@ -2282,7 +2282,7 @@ Use `getMessage()`, `getMessageType()`, `getMessageCast()` and `getMessageCastin
* Changed constructor to remove second argument (`$message`). It now only accepts `$result`, * Changed constructor to remove second argument (`$message`). It now only accepts `$result`,
which may be a string, and optional `$code` which may be a string, and optional `$code`
<a name="datetimefield"></a>New `DatetimeField` methods replace `getConfig()` / `setConfig()`: New `DatetimeField` methods replace `getConfig()` / `setConfig()`: {#datetimefield}
* Added `getTimezone()` / `setTimezone()` * Added `getTimezone()` / `setTimezone()`
* Added `getDateTimeOrder()` / `setDateTimeOrder()` * Added `getDateTimeOrder()` / `setDateTimeOrder()`
@ -2300,7 +2300,7 @@ The `DatetimeField` has changed behaviour:
* It no longer accepts `setValue()` as an array with 'date' and 'time' keys * It no longer accepts `setValue()` as an array with 'date' and 'time' keys
* Added `getHTML5()` / `setHTML5()` * Added `getHTML5()` / `setHTML5()`
<a name="datefield"></a>New `DateField` methods replace `getConfig()` / `setConfig()`: New `DateField` methods replace `getConfig()` / `setConfig()`: {#datefield}
* Added `getDateFormat()` / `setDateFormat()` * Added `getDateFormat()` / `setDateFormat()`
* Added `getMinDate()` / `setMinDate()` * Added `getMinDate()` / `setMinDate()`
@ -2316,7 +2316,7 @@ The `DateField` has changed behavior:
* The `dmyfields` option has been replced with native HTML5 behaviour (as one single `<input type=date>`). * The `dmyfields` option has been replced with native HTML5 behaviour (as one single `<input type=date>`).
* `getClientLocale` / `setClientLocale` have been removed (handled by `DateField->locale` and browser settings) * `getClientLocale` / `setClientLocale` have been removed (handled by `DateField->locale` and browser settings)
<a name="timefield"></a>New `TimeField` methods replace `getConfig()` / `setConfig()` New `TimeField` methods replace `getConfig()` / `setConfig()` {#timefield}
* Added `getTimeFormat()` / `setTimeFormat()` * Added `getTimeFormat()` / `setTimeFormat()`
* Added `getLocale()` / `setLocale()` * Added `getLocale()` / `setLocale()`
@ -2358,7 +2358,7 @@ Further API changes:
* Removed `HTMLEditorField_Flash` * Removed `HTMLEditorField_Flash`
* Removed `HTMLEditorField_Image` * Removed `HTMLEditorField_Image`
### <a name="overview-i18n"></a>i18n ### i18n {#overview-i18n}
* Upgrade of i18n to symfony/translation * Upgrade of i18n to symfony/translation
* Localisation based on language-only (without any specific locale) is now supported * Localisation based on language-only (without any specific locale) is now supported
@ -2391,7 +2391,7 @@ Further API changes:
* Removed `i18n::get_common_locales()` * Removed `i18n::get_common_locales()`
* Removed `i18n.common_locales` * Removed `i18n.common_locales`
### <a name="overview-mailer"></a>Email ### Email {#overview-mailer}
* Changed `Mailer` to an interface * Changed `Mailer` to an interface
* `Email` re-written to be powered by [SwiftMailer](https://github.com/swiftmailer/swiftmailer) * `Email` re-written to be powered by [SwiftMailer](https://github.com/swiftmailer/swiftmailer)
@ -2400,7 +2400,7 @@ Further API changes:
* Added `Email->setPlainTemplate()` for rendering plain versions of email * Added `Email->setPlainTemplate()` for rendering plain versions of email
* Renamed `Email->populateTemplate()` to `Email->setData()` * Renamed `Email->populateTemplate()` to `Email->setData()`
### <a name="overview-testing"></a>SapphireTest ### SapphireTest {#overview-testing}
* `is_running_tests()` is no longer public and user code should not rely on this. Test-specific behaviour * `is_running_tests()` is no longer public and user code should not rely on this. Test-specific behaviour
should be implemented in `setUp()` and `tearDown()` should be implemented in `setUp()` and `tearDown()`
@ -2411,7 +2411,7 @@ Further API changes:
* Renamed `$extraDataObjects` to `$extra_dataobjects` (and made static) * Renamed `$extraDataObjects` to `$extra_dataobjects` (and made static)
* Renamed `$extraControllers` to `$extra_controllers` (and made static) * Renamed `$extraControllers` to `$extra_controllers` (and made static)
### <a name="overview-security"></a>Security ### Security {#overview-security}
* `LoginForm` now has an abstract method `getAuthenticatorName()`. If you have made subclasses of this, * `LoginForm` now has an abstract method `getAuthenticatorName()`. If you have made subclasses of this,
you will need to define this method and return a short name describing the login method. you will need to define this method and return a short name describing the login method.