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

Cleanup upgrade docs and 4.0 change logs

Browse Source
This commit is contained in:
Christopher Joe 2018-01-30 10:43:42 +13:00
parent c7e341c67d
commit 78a6b4b4c3
2 changed files with 316 additions and 243 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

182
docs/en/03_Upgrading/index.md
View File

@ -3,7 +3,8 @@ introduction: Keep your SilverStripe installations up to date with the latest fi
# Upgrading to SilverStripe 4
SilverStripe applications should be kept up to date with the latest security releases. Usually an update or upgrade to your SilverStripe installation means overwriting files, flushing the cache and updating your database schema.
SilverStripe applications should be kept up to date with the latest security releases. Usually an update or upgrade to
your SilverStripe installation means overwriting files, flushing the cache and updating your database schema.
<div class="info" markdown="1">
See our [upgrade notes and changelogs](/changelogs/4.0.0) for 4.0.0 specific information, bugfixes and API changes.
@ -11,40 +12,32 @@ See our [upgrade notes and changelogs](/changelogs/4.0.0) for 4.0.0 specific inf
## Composer
For projects managed through Composer, update the version number of `framework` and `cms` to `^4.0` in your `composer.json` file and run `composer update`.
SilverStripe CMS is becoming more modular, and
[composer is becoming the preferred way to manage your code](/getting_started/composer).
For projects managed through Composer, we recommend using `recipe-cms` in your `composer.json` file to help you keep
up to date and run `composer update`.
```json
"require": {
"silverstripe/framework": "^4.0",
"silverstripe/cms": "^4.0"
{
"require": {
"silverstripe/recipe-cms": "^1"
}
}
```
<div class="info" markdown="1">
Please note that until SilverStripe 4 is stable you will need to also add `"minimum-stability": "dev"` and `"prefer-stable": true` to your `composer.json` to be able to pull these modules.
</div>
This will also add extra dependencies, such as the `admin`, `asset-admin`, `reports`, `errorpage` and `siteconfig`
modules.
This will also add extra dependencies, the `reports` and `siteconfig` modules. SilverStripe CMS is becoming more modular, and [composer is becoming the preferred way to manage your code](/getting_started/composer).
If you want more granular control over what gets installed,
reading through the README documentation in the [recipe plugin repository](https://github.com/silverstripe/recipe-plugin)
and also checking the `composer.json` files in [recipe-core](https://github.com/silverstripe/recipe-core) and
[recipe-cms](https://github.com/silverstripe/recipe-cms).
### Asset-admin
For a description on how to handle issues with pre-existing composer installs or upgrading other modules, please read
through the [Composer dependency update section](/changelogs/4.0.0#deps)
SilverStripe 4 comes with a new asset administration module. While it is installed by default for new projects, if you are upgrading you will need to install it manually:
```
composer require silverstripe/asset-admin ^1.0
```
This will also install the `graphql` module for GraphQL API access to your SilverStripe system, which powers the `asset-admin` module.
## Migrate to dotenv
SilverStripe 4 requires the use of `.env` and "real" environment variables instead of `_ss_environment.php` for your environment configuration.
You'll need to move your constants to a new `.env` file before SilverStripe will build successfully.
If you are not able to move your webserver away from using `_ss_environment.php` files, you can use [this example file](https://gist.github.com/robbieaverill/74fbfff6f438c94f6325107e4d7b2a45) and include it at the top of your `mysite/_config.php` file. This will export your constants as environment variables.
## Manual
## Manual upgrades
* Check if any modules (e.g. `blog` or `forum`) in your installation are incompatible and need to be upgraded as well.
* Backup your database content.
@ -53,10 +46,9 @@ If you are not able to move your webserver away from using `_ss_environment.php`
* Leave custom folders like *mysite* or *themes* in place.
* Identify system folders in your webroot (`cms`, `framework` and any additional modules).
* Delete existing system folders (or move them outside of your webroot).
* Rename your `Page_Controller` class to `PageController`.
* Add a `private static $table_name = 'MyDataObject'` for any custom DataObjects in your code that are namespaced. This ensures that your database table name will be `MyDataObject` instead of `Me\MyPackage\Model\MyDataObject` (your namespace for the class).
* Ensure you add [namespaces](http://php.net/manual/en/language.namespaces.php) to any custom classes in your `mysite` folder. Your namespaces should follow the pattern of `Vendor\Package` with anything additional defined at your discretion. **Note:** The `Page` and `PageController` classes *must* be defined in the global namespace (or; without a namespace).
* Install the updated framework, CMS and any other modules you require by updating your `composer.json` configuration and running `composer update`. As of SilverStripe 4.0.0 you should also include the `asset-admin` module to power your asset management in the CMS.
* Add a `private static $table_name = 'MyDataObject'` for any custom DataObjects in your code that are namespaced. This ensures that your database table name will be `MyDataObject` instead of `Me_MyPackage_Model_MyDataObject` (converts your namespace to the table_name).
* Ensure you add [namespaces](http://php.net/manual/en/language.namespaces.php) to any custom classes in your `mysite` folder. Your namespaces should follow the pattern of `Vendor\Package` with anything additional defined at your discretion. **Note:** The `Page` and `PageController` classes *must* be defined in the global namespace (or without a namespace).
* Install the updated framework, CMS and any other modules you require by updating your `composer.json` configuration and running `composer update`. Some features have been split into their own modules, such as `asset-admin` and `errorpage`. Please refer to [`recipe-cms` composer.json](https://github.com/silverstripe/recipe-cms) and [`recipe-core` composer.json](https://github.com/silverstripe/recipe-core) for a list of recommended modules to include.
* Check if you need to adapt your code to changed PHP APIs. For more information please refer to [the changelog](/changelogs/4.0.0). There is an upgrader tool available to help you with most of the changes required (see below).
* Visit http://yoursite.com/dev/build/?flush=1 to rebuild the website database.
* Check if you have overwritten any core templates or styles which might need an update.
@ -65,20 +57,138 @@ If you are not able to move your webserver away from using `_ss_environment.php`
Never update a website on the live server without trying it on a development copy first!
</div>
## Environment variables file changed to dotenv
SilverStripe 4 requires the use of `.env` and no longer supports using `_ss_environment.php` for your
environment configuration.
You'll need to move your constants to a new `.env` file before SilverStripe will build successfully.
For further details about the `.env` migration, read through the
[`_ss_environment.php` changed to `.env` section](/changelogs/4.0.0#env)
## Using the upgrader tool
We've developed [an upgrader tool](https://github.com/silverstripe/silverstripe-upgrader) which you can use to help you with the upgrade process to SilverStripe 4. [See the upgrading notes](/changelogs/4.0.0/#a-name-upgrading-a-upgrading) in the changelog for more detailed instructions on how to use it.
We've developed [an upgrader tool](https://github.com/silverstripe/silverstripe-upgrader) which you can use to help
with the upgrade process to SilverStripe 4. See the README documentation in the repository for more detailed
instructions on how to use it.
## Quick tips
### `index.php` and `.htaccess` rewrites
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 `public/index.php`.
For more details, please read through the [`index.php` and `.htaccess` rewrites section](/changelogs/4.0.0#index-php-rewrites)
After installing, run the upgrader doctor command:
```
cd ~/my-project-root
upgrade-code doctor
```
This will ensure that your `.htaccess` and `index.php` are set to a reasonable default value for a clean installation.
### Renamed and namespaced classes
Nearly all core PHP classes in SilverStripe have been namespaced. For example, `DataObject` is now called `SilverStripe\ORM\DataObject`.
For a full list of renamed classes, check the `.upgrade.yml` definitions in each module.
After installing, run the upgrader upgrade command:
```
cd ~/my-project-root
~/.composer/vendor/bin/upgrade-code upgrade ./mysite --write
```
## Migrating files
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)).
```
$ ./vendor/bin/sake dev/tasks/MigrateFileTask
```
## Upgrade tips
While there's some code we can automatically rewrite, other uses of changed SilverStripe APIs aren't that obvious.
You can use our `inspect` to get some hints on where you need to review code manually.
Hints will generally point to more detail about a specific upgrade in this guide.
This task requires [the upgrader tool](https://github.com/silverstripe/silverstripe-upgrader).
```
~/.composer/vendor/bin/upgrade-code inspect ./mysite
```
These hints only cover a part of the upgrade work, but can serve as a good indicator for where to start.
If you've already had a look over the changelog, you will see that there are some fundamental changes that need to be implemented to upgrade from 3.x. Here's a couple of the most important ones to consider:
* PHP 5.5 is now the minimum required version (and PHP 7.x is supported!).
* All SilverStripe classes are now namespaced, and some have been renamed. Most of your modules will also have been namespaced, and you will need to consider this when updating class references (including YAML configuration) in your own code.
* PHP 5.6 is now the minimum required version (and up to PHP 7.1.x is supported!).
* CMS CSS has been re-developed using Bootstrap 4 as a base.
* SilverStripe code _should_ now be [PSR-2 compliant](http://www.php-fig.org/psr/psr-2/). While this is not a requirement, we strongly suggest you switch over now. You can use tools such as [`phpcbf`](https://github.com/squizlabs/PHP_CodeSniffer/wiki/Fixing-Errors-Automatically) to do most of it automatically.
* We've also introduced some best practices for module development. [See the Modules article](/developer_guides/extending/modules) for more information.
## Additional tips easily missed
[Object class replaced by traits](/changelogs/4.0.0#object-replace)
The `Object` class has been superceded by three traits:
- `Injectable`: Provides `MyClass::create()` and `MyClass::singleton()`
- `Configurable`: Provides `MyClass::config()`
- `Extensible`: Provides all methods related to extensions (E.g. add_extension()).
`$this->class` no longer recommended, should use `static::class` or `get_class($classObject)` instead.
[Rewrite literal table names](/changelogs/4.0.0#literal-table-names)
Use `$table = SilverStripe\ORM\DataObject::getSchema()->tableForField($model, $field)` instead of `$model` directly.
[Rewrite literal class names](/changelogs/4.0.0#literal-class-names)
For example, referencing the class name `'Member'` should be `Member::class` or if you're in YML config it should be `SilverStripe\Security\Member`.
[Template locations and references](/changelogs/4.0.0#template-locations)
Templates require the folder path inside the templates folder, and Core templates are placed in paths following the class namespace, e.g. `FormField` is now `SilverStripe/Forms/FormField`.
When using the `<% include %>` syntax, you can leave out the `Includes` folder in the path.
[Config settings should be set to `private static`](/changelogs/4.0.0#private-static)
We no longer support `public static $config_item` on classes, it now needs to be `private static $config_item`.
[Module paths can't be hardcoded](/changelogs/4.0.0#module-paths)
Modules may not be placed in a deterministic folder (e.g. `/framework`),
you should use getters on the [Module](api:SilverStripe\Core\Manifest\Module) object instead.
Please see the changelogs for more details on ways that the getters on the `Module` object could be used.
[Adapt tooling to modules in vendor folder](#vendor-folder)
SilverStripe modules are now placed in the `vendor` folder like many other composer package.
Modules need to declare which files need to be exposed via the new [vendor-plugin](https://github.com/silverstripe/vendor-plugin), using symlinks to link to files from the publically accessible `resources` folder.
[SS_Log replaced with PSR-3 logging](/changelogs/4.0.0#psr3-logging)
SilverStripe 4 introduces [PSR-3](http://www.php-fig.org/psr/psr-3/) compatible logger interfaces. Services can access the logger using the LoggerInterface::class service.
Please see the changelogs for more details on how to implement logging.
[Upgrade `mysite/_config.php`](/changelogs/4.0.0#config-php)
The globals `$database` and `$databaseConfig` are deprecated. You should upgrade your site `_config.php` files to use the [.env configuration](#env).
`conf/ConfigureFromEnv.php` is no longer used, and references to this file should be deleted.
[Session object removes static methods](/changelogs/4.0.0#session)
Session object is no longer statically accessible via `Session::inst()`. Instead, `Session` is a member of the current request.
[Extensions are now singletons](#extensions-singletons)
This means that state stored in private/protected variables are now shared across all objects which use this extension.
It is recommended to refactor the variables to be stored against the owner object.
[Explicit text casting on template variables](/changelogs/4.0.0#template-casting)
Calling `$MyField` on a DataObject in templates will by default cast MyField as `Text` which means it will be safely encoded.
You can change the casting for this by defining a casting config on the DataObject:
```php
private static $casting = [
'MyField' => 'HTMLText'
];
```
We've also introduced some best practices for module development. [See the Modules article](/developer_guides/extending/modules) for more information.
## Decision Helpers

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

@ -71,22 +71,24 @@ Backup your existing `composer.json` and overwrite it with the following content
{
"name": "myvendor/myproject",
"require": {
"silverstripe/recipe-cms": "^1"
"silverstripe/recipe-cms": "^1.0"
},
"prefer-stable": true,
"minimum-stability": "dev"
}
```
This composer file uses the new [recipe](https://github.com/silverstripe/recipe-plugin) approach
which bundles all core dependencies in a meta package. If you want more granular control over what gets installed,
check the `composer.json` files in [recipe-core](https://github.com/silverstripe/recipe-core) and [recipe-cms](https://github.com/silverstripe/recipe-cms).
This composer file uses the new [recipe](https://github.com/silverstripe/recipe-plugin) approach
which bundles all core dependencies in a meta package. If you want more granular control over what gets installed,
reading through the README documentation in the [recipe plugin repo](https://github.com/silverstripe/recipe-plugin)
and also checking the `composer.json` files in [recipe-core](https://github.com/silverstripe/recipe-core) and
[recipe-cms](https://github.com/silverstripe/recipe-cms).
Now run a `composer update`. This will remove all existing modules from your local codebase
since we replaced your project's `composer.json`. Now you can move back your modules
Now run a `composer update`. This will remove all existing modules from your local codebase
since we replaced your project's `composer.json`. Now you can move your modules back
one by one, checking for compatible versions on [packagist.org](http://packagist.org).
Note: If you have issues with a pre-existing composer install you can force a clean re-install with the
Note: If you have issues with a pre-existing composer install you can force a clean re-install with the
below commands:
```bash
@ -120,75 +122,15 @@ once the module is stable.
}
```
For modules that don't have a pre-release branch started,
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
and temporarily disable its functionality.
For modules that don't have a pre-release branch started, 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 and temporarily disable its functionality.
### Install the upgrader tool {#upgrader-tool}
### Manual upgrades
A lot of upgrade work can be automated, and we've written an
[upgrader tool](https://github.com/silverstripe/silverstripe-upgrader/) for this purpose.
Install it via composer:
Please follow
```
composer global require silverstripe/upgrader
```
### index.php and .htaccess rewrites {#index-php-rewrites}
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`.
If you are running Apache, adjust your `.htaccess` file. For other webservers,
please consult the [installation guides](getting_started/installation/).
Since 4.0, URL rewrite capabilities are required,
unless you PHP's built-in webserver through [silverstripe/serve](https://github.com/silverstripe/silverstripe-serve).
The [upgrader tool](https://github.com/silverstripe/silverstripe-upgrader/) has a task runner which
automates this process for you.
Install the upgrader:
```
export PATH=$PATH:~/.composer/vendor/bin/
composer global require silverstripe/upgrader
```
Run the upgrader:
```
cd ~/my-project-root
upgrade-code doctor
```
This will ensure that your `.htaccess` and `index.php` are set to a reasonable default value
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),
you'll need to manually reapply these to the copied default file.
### Renamed and namespaced classes {#namespaced-classes}
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.
We have developed an [upgrader tool](https://github.com/silverstripe/silverstripe-upgrader/) to (semi-)automatically
update your 3.x code to the new naming. Here's an example how to upgrade your `mysite` folder:
```
cd ~/my-project-root
~/.composer/vendor/bin/upgrade-code upgrade ./mysite --write
```
If you want to do a dry-run, omit the `--write` option to see a preview of a diff of
all changed project files.
This will resolve the majority of upgrading work, but we strongly recommend reviewing the diff
running some regression testing on your functionality. SilverStripe core classes can be referenced
in your PHP files, but also in YAML configuration and SilverStripe templates.
For a full list of renamed classes, check the `.upgrade.yml` definitions in each module.
The rename won't affect class-based permission codes or database table names.
### `_ss_environment.php` changed to`.env` {#env}
### Environment variables file changed to dotenv {#env}
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
@ -216,14 +158,14 @@ define('SS_DATABASE_SERVER', '127.0.0.1');
`.env`:
```
```bash
## Environment
SS_ENVIRONMENT_TYPE="dev"
SS_DEFAULT_ADMIN_USERNAME="admin"
SS_DEFAULT_ADMIN_PASSWORD="password"
SS_BASE_URL="http://localhost/"
### Database
## Database
SS_DATABASE_CHOOSE_NAME="true"
SS_DATABASE_CLASS="MySQLDatabase"
SS_DATABASE_USERNAME="root"
@ -251,6 +193,66 @@ To access environment variables you can use the `SilverStripe\Core\Environment::
See [Environment Management docs](/getting_started/environment_management/) for full details.
If you are not able to move your webserver away from using `_ss_environment.php` files, you can use
[this example file](https://gist.github.com/robbieaverill/74fbfff6f438c94f6325107e4d7b2a45) and include it at the top
of your `mysite/_config.php` file. This will export your constants as environment variables.
### Using the upgrader tool {#upgrader-tool}
We've developed [an upgrader tool](https://github.com/silverstripe/silverstripe-upgrader) which you can use to help
with the upgrade process to SilverStripe 4. See the README documentation in the repository for more detailed
instructions on how to use it.
### `index.php` and `.htaccess` rewrites {#index-php-rewrites}
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 `public/index.php`.
Use [`recipe-core` index.php](https://github.com/silverstripe/recipe-core) as a reference to ensure the contents of
your `index.php` file is correct.
If you are running Apache, adjust your `.htaccess` file. For other webservers,
please consult the [installation guides](getting_started/installation/).
Since 4.0, URL rewrite capabilities are required,
unless you use PHP's built-in webserver through [silverstripe/serve](https://github.com/silverstripe/silverstripe-serve).
The [upgrader tool](https://github.com/silverstripe/silverstripe-upgrader/) has a task runner which
automates this process for you.
After installing, run the upgrader:
```
cd ~/my-project-root
upgrade-code doctor
```
This will ensure that your `.htaccess` and `index.php` are set to a reasonable default value
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),
you'll need to manually reapply these to the copied default file.
### Renamed and namespaced classes {#namespaced-classes}
Nearly all core PHP classes in SilverStripe 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.
We have developed an [upgrader tool](https://github.com/silverstripe/silverstripe-upgrader/) to (semi-)automatically
update your 3.x code to the new naming. Here's an example how to upgrade your `mysite` folder:
```
cd ~/my-project-root
~/.composer/vendor/bin/upgrade-code upgrade ./mysite --write
```
If you want to do a dry-run, omit the `--write` option to see a preview of a diff of
all changed project files.
This will resolve the majority of upgrading work, but we strongly recommend reviewing the diff
running some regression testing on your functionality. SilverStripe core classes can be referenced
in your PHP files, but also in YAML configuration and SilverStripe templates.
For a full list of renamed classes, check the `.upgrade.yml` definitions in each module.
The rename won't affect class-based permission codes or database table names.
### Migrate File DataObject {#migrate-file}
Since the structure of `File` dataobjects has changed, a new task `MigrateFileTask`
@ -260,10 +262,13 @@ has been added to assist in migration of legacy files (see [file migration docum
$ ./vendor/bin/sake dev/tasks/MigrateFileTask
```
Any `File` dataobject which is not in the `File.allowed_extensions` config will be deleted
from the database during migration. Any invalid file on the filesystem will not be deleted,
but will no longer be attached to a dataobject, and should be cleaned up manually.
To disable this, set the following config:
Any `File` in the database with an extension which is not in the `File.allowed_extensions` config will be considered
invalid and deleted from the database during migration.
Any invalid file on the filesystem will not be deleted in the filesystem, but will no longer be recorded in the
database, and should be cleaned up manually.
To disable deleting from the database, set the following config:
```yaml
SilverStripe\Assets\FileMigrationHelper:
@ -284,6 +289,75 @@ This task should be run *after* `upgrade-code upgrade`.
These hints only cover a part of the upgrade work,
but can serve as a good indicator for where to start.
### Object class replaced by traits {#object-replace}
Object has been superseded by traits.
- `Injectable`: Provides `MyClass::create()` and `MyClass::singleton()`
- `Configurable`: Provides `MyClass::config()`
- `Extensible`: Provides all methods related to extensions (E.g. add_extension()).
Upgrade subclass use
```diff
-class MyClass extends Object
-{
-}
+use SilverStripe\Core\Extensible;
+use SilverStripe\Core\Injector\Injectable;
+use SilverStripe\Core\Config\Configurable;
+class MyClass
+{
+ use Extensible;
+ use Injectable;
+ use Configurable;
+}
```
Upgrade references to $this->class
```diff
-$obj->class
+get_class($obj);
-$this->class;
+static::class;
```
Upgrade parse_class_spec()
```diff
-$spec = Object::parse_class_spec($spec);
+$spec = ClassInfo::parse_class_spec($spec);
```
Upgrade create_from_string()
```diff
-$obj = Object::create_from_string('Varchar(100)');
+$obj = Injector::inst()->create('Varchar(100)');
```
Upgrade extension use
```diff
-Object::add_extension('File', 'Versioned');
+File::add_extension(Versioned::class);
+DataObject::add_extension(File::class, Versioned::class); // alternate
-$has = Object::has_extension('File', 'Versioned');
+$has = File::has_extension(Versioned::class);
+$has = DataObject::has_extension(File::class, Versioned::class); // alternate
-$extensions = Object::get_extensions('File');
+$extensions = File::get_extensions();
+$extensions = DataObject::get_extensions(File::class); // alternate
```
### 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
@ -337,7 +411,7 @@ In the context of YAML, the magic constant `::class` does not apply. Fully quali
property: value
```
### Move controllers to their own files {#controllers-own-files}
### Controllers renamed {#controllers-renamed}
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.
@ -356,12 +430,12 @@ Either include the folder in the template name (`renderWith('MyEmail.ss')` => `r
move the template into the correct directory, or both.
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
(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.
the class namespace, `SilverStripe\Forms`.
When using `<% include %>` template tag you can continue to leave out the `Includes` folder,
but this now will also search templates in the base folder if no Include can be found.
When using the `<% include %>` template tag you can continue to leave out the `Includes` folder,
but this will search templates in the base folder if no Include can be found.
`<% include Sidebar %>` will match `Includes/Sidebar.ss`, but will also match `Sidebar.ss`
if the former is not present.
@ -560,75 +634,6 @@ SilverStripe\Core\Manifest\ModuleManifest:
project: mysite
```
### Object class replaced by traits {#object-replace}
Object has been superseded by traits.
- `Injectable`: Provides `MyClass::create()` and `MyClass::singleton()`
- `Configurable`: Provides `MyClass::config()`
- `Extensible`: Provides all methods related to extensions (E.g. add_extension()).
Upgrade subclass use
```diff
-class MyClass extends Object
-{
-}
+use SilverStripe\Core\Extensible;
+use SilverStripe\Core\Injector\Injectable;
+use SilverStripe\Core\Config\Configurable;
+class MyClass
+{
+ use Extensible;
+ use Injectable;
+ use Configurable;
+}
```
Upgrade references to $this->class
```diff
-$obj->class
+get_class($obj);
-$this->class;
+static::class;
```
Upgrade parse_class_spec()
```diff
-$spec = Object::parse_class_spec($spec);
+$spec = ClassInfo::parse_class_spec($spec);
```
Upgrade create_from_string()
```diff
-$obj = Object::create_from_string('Varchar(100)');
+$obj = Injector::inst()->create('Varchar(100)');
```
Upgrade extension use
```diff
-Object::add_extension('File', 'Versioned');
+File::add_extension(Versioned::class);
+DataObject::add_extension(File::class, Versioned::class); // alternate
-$has = Object::has_extension('File', 'Versioned');
+$has = File::has_extension(Versioned::class);
+$has = DataObject::has_extension(File::class, Versioned::class); // alternate
-$extensions = Object::get_extensions('File');
+$extensions = File::get_extensions();
+$extensions = DataObject::get_extensions(File::class); // alternate
```
### Session object removes static methods {#session}
Session object is no longer statically accessible via `Session::inst()`. Instead, Session
@ -706,57 +711,12 @@ class MyClass extends DataObject {
}
```
### Static references to asset paths {#static-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,
which are also sub-folders of the modules which now reside in `vendor`.
This will affect you if you have used `Requirements::block()` on files in the `framework/` or `cms/` folder.
In order to identify resources it is preferred to use the new module-root prefixed string form when
adding requirements.
Usage in Requirements:
```diff
-Requirements::css('framework/admin/css/styles.css');
+Requirements::css('silverstripe/admin: client/dist/styles/bundle.css');
```
The location of these resources is determined from the `name` field in the `composer.json`
for each module. `silverstripe/admin:` will be mapped to the folder `vendor/silverstripe/admin`
where this module is installed, based on the `vendor/silverstripe/admin/composer.json` name
matching the prefix in `Requirements::css()`.
Care should also be taken when referencing images in these folders from your own stylesheets (`url()`),
or via SilverStripe templates (`<img>` tags).
`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 => silverstripe/admin:client/dist/
framework/javascript/lang => silverstripe/admin:client/lang/
framework/images => silverstripe/admin:client/dist/images/
framework/css => silverstripe/admin:client/dist/css/
framework/scss => silverstripe/admin:client/src/styles/
admin/javascript/ => silverstripe/admin:client/src/
admin/javascript/src/ => silverstripe/admin:client/src/legacy/ (mostly)
admin/javascript/lang/ => silverstripe/admin:client/lang/
admin/scss/ => silverstripe/admin:client/styles/legacy/
admin/css/ => silverstripe/admin:client/dist/css/
admin/css/screen.css => silverstripe/admin:client/dist/css/bundle.css
admin/images/ => silverstripe/admin:client/dist/images/
admin/images/sprites/src/ => silverstripe/admin:client/src/sprites/
admin/images/sprites/dist/ => silverstripe/admin:client/dist/sprites/
admin/font/ => silverstripe/admin:client/dist/font/
```
### Javascript files in framework/admin {#js-in-framework}
Most JavaScript files in `framework/javascript` have been removed,
and are bundled through [Webpack](http://webpack.github.io/) into a combined file instead.
If you have referenced these files elsewhere, please consider
running the ES6 source files in `admin/client/src/legacy`
running the ES6 source files in `vendor/silverstripe/admin/client/src/legacy`
through your own transpiling and bundle process.
This also includes JavaScript i18n support, and the removal of the `i18n::js_i18n`
@ -1227,6 +1187,8 @@ class MyTask extends BuildTask
### Moved ErrorPage into a new module {#errorpage}
**NOTE**: This is included automatically if you switch to using the `recipe-cms` module.
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.
The module is installed by default on new projects, but needs to be added to existing projects
@ -1588,6 +1550,7 @@ Cache::pick_backend('primary_memcached', 'any', 10);
After (`mysite/_config/config.yml`):
```yml
# setup cache
---
After:
- '#corecache'
@ -1612,13 +1575,13 @@ will assist you with bringing yourself up to speed.
Please note that before upgrading user code style it is necessary to run the standard upgrade path
to fix references and usages of framework API.
### Upgrading user-code to use namespaces
#### Upgrading user-code to use namespaces
Upgrading code to use namespaces is quite a complex process, and as such we have provided
several development tools and processes to help make the upgrade user friendly and as
automated as possible.
### Using the upgrader tool to automatically apply namespaces
#### Using the upgrader tool to automatically apply namespaces
The [upgrader tool](https://github.com/silverstripe/silverstripe-upgrader/) provides a feature
to not only automatically namespace code, but will provide automatic upgrade of other code
@ -1651,7 +1614,7 @@ This task will not do the following, and must be done manually:
Please see the following steps for more information.
### Using the upgrader tool to update references to namespaced user classes
#### Using the upgrader tool to update references to namespaced user classes
Once a project has been namespaced all newly renamed classes will have a mapping included in the `mysite/.upgrade.yml`
file. If you have any user-code that references these, you may need to run the upgrader again (as you did did
@ -1663,7 +1626,7 @@ cd ~/Project/Root
~/.composer/vendor/bin/upgrade-code upgrade ./othercode --write
```
### Updating custom dataobjects to use existing table names
#### Updating custom dataobjects to use existing table names
Once you have namespaced your user code it will be necessary to customise the `table_name` config
for your dataobjects, in order to ensure the correct table is used after upgrade. It is recommended
@ -1679,7 +1642,7 @@ class GalleryPage extends Page
}
```
### Class name remapping {#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
telling you it's obsolete. This is likely because the `ClassName`
@ -1703,7 +1666,7 @@ SilverStripe\ORM\DatabaseAdmin:
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`
### PSR-2 Coding Standard compliance {#psr2}
#### PSR-2 Coding Standard compliance {#psr2}
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
@ -1721,7 +1684,7 @@ code style migration.
Repeat the final step and manually repair suggested changes, as necessary,
until you no longer have any linting issues.
### PSR-4 autoloading for project code {#psr4}
#### 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/)
standard for the core modules, so it's probably a good idea to be consistent.