If you're going to install development version of third party modules, you should consider adding the following entries to your `composer.json` file.
```json
{
// ...
"minimum-stability": "dev",
"prefer-stable": true,
// ...
}
```
To resolve a conflict you can either:
* fork the affected module and upgrade it yourself. Don't forget to send a pull request to the original module!
* Integrate the affected module into your project's codebase
* Remove the module from your project, if it is not essential
To integrate a third party module in your project, remove it from your `composer.json` file and from your `.gitignore` file. Then track the module's codebase in your project source control. You'll need to upgrade the module's code to be compatible with SilverStripe 4.
If you're taking the time to upgrade a third party module, consider doing a pull request against the original project so other developers can benefit from your work or releasing your fork as a seperate module.
[Learn about how to publish a SilverStripe module](/developer_guides/extending/how_tos/publish_a_module)
### Finalising your dependency upgrade
Once you've resolved all conflicts in your `composer.json` file, `composer update` will be able to run without errors.
This will install your new dependencies. You'll notice many of the folders in the root of your project will disappear. That's because SilverStripe 4 modules can be installed in the vendor folder like generic PHP packages.
If you've decided to use recipes, some generic files will be copied from the recipe into your project. The `extra` attribute in your `composer.json` file will be updated to keep track of those new files.
This is a good point to commit your changes to your source control system before moving on to the next step.
## Step 2 - Update your environment configuration {#env}{#step2}
The php configuration `_ss_environment.php` file has been replaced with a non-executable
`.env` file. It follows a syntax similar to a `.ini` file for key/value pair assignment. Your `.env` file may be placed in your project root, or one level above your project root.
Read the [Environment management](/getting_started/environment_management/) documentation to learn more about configuring your project's environment.
### Automatically convert `_ss_environment.php` to `.env`
If you have installed the upgrader tool, you can use the `environment` command to generate a valid `.env` file from your existing `_ss_environment.php` file.
```bash
upgrade-code environment --write
```
If your `_ss_environment.php` file contains unusual logic (conditional statements or loops), you will get a warning. `upgrade-code` will still try to convert the file, but you should double-check the output. Omit the `--write` flag to do a dry-run.
[Continue to "Cleaning up `mysite/_config.php`"](#env-config-cleanup)
### Manually convert `_ss_environment.php` to `.env`
Create a `.env` file in the root of your project. Replace `define` statements from `_ss_environment.php` with `KEY=VALUE` pairs in `.env`.
Most SilverStripe 3 environment variables have been carried over to SilverStripe 4. See [Environment Management docs](/getting_started/environment_management/) for the full list of available variables. Your `.env` file can contain environment variables specific to your project as well.
The global array `$_FILE_TO_URL_MAPPING` has been removed and replaced with the `SS_BASE_URL` environment variable. `SS_BASE_URL` expects an absolute url with an optional protocol. The following are values would be valid entries for `SS_BASE_URL`:
* `http://localhost/`
* `https://localhost/`
* `//localhost/`
For example, take the following `_ss_environment.php` file.
```php
get('ProductService');
```
Execute the upgrade command with this command.
```bash
upgrade-code upgrade ./mysite/ --write
```
If you omit the `--write` flag you will get a preview of what change the upgrader will apply to your codebase. This can be helpful if you are tweaking your `.upgrade.yml` or if you are trying to identify areas where you should add a `@skipUpgrade` statement,
You can also tweak which rules to apply with the `--rule` flag: `code`, `config`, and `lang`. For example, the following command will only upgrade `lang` and `config` files:
```bash
upgrade-code upgrade ./mysite/ --rule=config --rule=lang
```
The `upgrade` command can alter big chunks of your codebase. While it works reasonably well in most use cases, you should not trust it blindly. You should take time to review all changes applied by the `upgrade` command and confirm you are happy with them.
[Continue to "Finalising namespace updates"](#namespace-finalise)
#### Rename Warnings
You can also show extra warnings for potentially ambiguous mappings with the `renameWarnings` property:
```yaml
renameWarnings:
- File
- Image
```
An example of an ambiguous rename would be:
```PHP
private static $has_one = [
'Image' => 'Image',
];
```
Add the `--prompt` flag to manually approve ambiguous class renames.
### Manually update namespaced references
If you decide to update your namespace references by hand, you'll need to go through the entire code base and update them all from the old non-namespaced SilverStripe classes to the new namespaced equivalent. If you are referencing classes from third party modules that have been namespaced, you'll need to update those as well.
#### Update explicit references to classes in your code
Wherever your code explicitly references a SilverStripe class, it will need to be updated to the new namespaced equivalent. You can either update the reference to use the fully qualified name of the class or you can add a `use` statement to your file.
For example take the following SilverStripe 3 class. `DataObject` and `FieldList` need to point to their namespace equivalents.
```php
'Image'
];
private static $has_many = [
'Tags' => 'BlogPost'
];
public function getShippingCost()
{
return Injector::inst('ProductService')->calculateCost($this);
}
}
```
`Image`, `BlogPost`, and `ProductService` represent classes. Those strings need to be updated to specify the full namespace.
The best way of achieving this is to use the [`::class` PHP magic class constant](http://php.net/manual/en/language.oop5.basic.php#language.oop5.basic.class.class) which will return the fully qualified name of a class.
Our example could be update to:
```php
Image::class
];
private static $has_many = [
'Tags' => BlogPost::class
];
public function getShippingCost()
{
return Injector::inst(ProductService::class)->calculateCost($this);
}
}
```
Alternatively, you can spell out the full qualified name of each class in a string. For example, `'Image'` would become `'SilverStripe\\Assets\\Image'`. Note the use of the _double backslash_ — this is necessary because the backslash is an escape character.
#### Update references to classes in your YML config
YAML configuration files can reference SilverStripe classes. Those references also need to use the fully qualified name of each class.
Take for example the following SilverStripe 3 YAML configuration file.
```yaml
Injector:
ProductService:
properties:
RoadRunnerSpeed: 99999999
CoyoteSpeed: 1
BlogPost:
extensions:
- HasOneExplosiveTennisBallExtension
Email:
admin_email: no-reply@example.com
```
In SilverStripe 4, this will become:
```yaml
SilverStripe\Core\Injector\Injector:
App\Web\ProductService:
properties:
RoadRunnerSpeed: 99999999
CoyoteSpeed: 1
SilverStripe\Blog\Model\BlogPost:
extensions:
- App\Web\Extensions\HasOneExplosiveTennisBallExtension
SilverStripe\Control\Email\Email:
admin_email: no-reply@example.com
```
#### Update references to classes in your language files
Translation keys are normally tied to classes. If you override SilverStripe's default translation or if you are localising your own project, you'll need to update those references to use the fully qualified name of each class.
For example, let's say you had the following translation file in `mysite/lang/eng.yml`.
```yaml
en:
Member:
SINGULARNAME: Coyote
RoadRunner:
SALUTATION: Beep Beep
```
In SilverStripe 4, it would become:
```yaml
en:
SilverStripe\Security\Member:
SINGULARNAME: Coyote
App\Web\RoadRunner:
SALUTATION: Beep Beep
```
### Finalising namespace updates {#namespace-finalise}
You'll need to perform the following steps manually, even if you've used the automated rewrite of namespaces.
DataObject database tables will default to use a namespaced name. For example, if you have a class under `App\Web\Products\ExplosiveTennisBall` that extends `DataObject`, the matching table in your database will be called `App_Web_Products_ExplosiveTennisBall`.
You can define a `private static $table_name` property on your DataObjects to use more convenient table names.
For example, `private static $table_name = 'ExplosiveTennisBall';`.
In your PHP code, calls to the `_t()` method should be updated to use the full namespace of the target class.
```php
'Products']);
# New SilverStripe 4
use SilverStripe\CMS\Controllers\CMSMain;
// ...
$translation = _t(CMSMain::class . '.ACCESS', "Access to '{title}' section", ['title' => 'Products']);
```
If you're calling `_t()` to retrieve a translation for the current class, you can also use `__CLASS__` or `self::class`. For example:
```php
Avoid using `static::class` or `parent::class` to retrieve translated string. It will retrieve unpredictable values bases on the class inheritance.
If your template files contain translatable strings, they also need to be updated to referenced the namespaced classes.
For example, `<%t Member.SINGULARNAME 'Member' %>` would become `<%t SilverStripe\Security\Member.SINGULARNAME 'Member' %>`.
Your codebase should now be referencing valid SilverStripe 4 classes. This means that your classes can be loaded at runtime. However, your codebase will still be using an outdated API.
This is a good point to commit your changes to your source control system before moving on to the next step.
## Step 5 - Updating your codebase to use SilverStripe 4 API {#step5}
This is the most intricate and potentially time-consuming part of the upgrade. It involves going through your entire codebase to remove references to deprecated APIs and update your project logic.
### Automatically update deprecated API references with the `inspect` command
The upgrader has an `inspect` command that can flag deprecated API usage, and in some cases, update your codebase to the SilverStripe 4 equivalent. This does require you to carefully review each change and warning to make sure the updated logic still work as intended. Even so, it is a huge time-saver compared to reviewing your code base manually.
Note that the `inspect` command loads your files with PHP interpreter. So basic syntax errors — for example, extending a class that does not exists — will cause an immediate failure. For this reason, you need to complete [Step 4 - Update codebase with references to newly namespaced classes](#step4) before running the `inspect` command.
```bash
upgrade-code inspect ./mysite/ --write
```
You can omit the `--write` flag if you just want to view the proposed changes without applying them. You can run the command on a specific subdirectory or file. This can be more manageable if you have a big project to go through.
Like the `upgrade` command, `inspect` gets its list of API changes from `.upgrade.yml` files. So you may get upgrade suggestions and substitution from third party modules. You can even include your own project specific changes in your `.upgrade.yml` if you want.
#### Sample output of the `inspect` command
Here's some sample output of what you might get back from the `inspect` command.
```bash
upgrade-code inspect ./mysite/Models/Coyote.php
Running post-upgrade on "/var/www/SS_example/mysite/code/Models/Coyote.php"
[2018-06-06 13:35:38] Applying ApiChangeWarningsRule to Coyote.php...
modified: Coyote.php
@@ -68,7 +68,7 @@
{
// Getting a reference to Coyote's list of crazy ideas
- $manyManyRelation = $this->manyManyComponent('CrazyIdeas');
+ $manyManyRelation = $this->getSchema()->manyManyComponent('CrazyIdeas');
return $manyManyRelation;
}
Warnings for Coyote.php:
- Coyote.php:20 SS_Cache: Using symfony/cache now (https://docs.silverstripe.org/en/4/changelogs/4.0.0#cache)
- Coyote.php:42 SilverStripe\Control\Director::setUrlParams(): Method removed
- Coyote.php:71 SilverStripe\ORM\DataObject->manyManyComponent(): DataObject->manyManyComponent() moved to DataObjectSchema. Access through getSchema(). You must manually add static::class as the first argument to manyManyComponent()
Changes not saved; Run with --write to commit to disk
```
### Manually update deprecated API references
SilverStripe 4 introduces many API changes. To update deprecated API references manually, you have to go through each one of your project files.
Read the changelogs for [4.0.0](/changelogs/4.0.0/) and for [subsequent minor releases](/changelogs)
### Finalising the deprecated API update
At this stage, your site should be using only SilverStripe 4 API logic.
You still have some minor clean up tasks and configuration tweaks to apply, but you're almost done.
This is a good point to commit your changes to your source control system before moving on to the next step.
## Step 6 - Update your entry point {#step6}
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`.
### Update your `index.php` file
You can get a copy of the SilverStripe 4 `index.php` file at
`vendor/silverstripe/recipe-core/public/index.php`.
If you've created your own `index.php` or modified version of `main.php`,
you'll need to reconcile those changes with the `index.php` file you got from `recipe-core`.
Otherwise, just use the generic `index.php` file `recipe-core` provides.
Copy your new `index.php` to your project's web root. Unlike SilverStripe 3, `index.php` must be present in your web root.
### Update your server configuration
If you're using a `.htaccess` file or `web.config` file to handle your server configuration, you can get the generic SilverStripe 4 version of those file from
`vendor/silverstripe/recipe-core/public`.
Just like `index.php`, if you've modified your server configuration file from the one that shipped with SilverStripe 3, you'll need to reconcile your changes into the version retrieve from `recipe-core`.
[Refer to the installation instruction for your platform](/getting_started/installation/) if your server configuration is not managed via a `.htaccess` or `web.config` file.
### Finalising the entry point upgrade
At this stage, you could in theory run your project in SilverStripe 4.
This is a good point to commit your changes to your source control system before moving on to the next step.
## Step 7 - Update project structure (optional) {#step7}
SilverStripe 4 introduces a new recommended project structure ([details](/changelogs/4.2.0#app-folder-name)).
Adopting the recommended project structure is optional, but will become mandatory in SilverStripe 5.
[Skip to Step 8](#step8)
### Automatically switch to the new structure with the `reorganise` command
The reorganise command can automatically update your project to use the new recommended structure.
It will search your code and find any occurrence of `mysite`. It won't replace those occurrences with `app` however.
```bash
upgrade-code reorganise --write
```
Omit the `--write` flag if you just want to preview your changes
### Manually switch to the new structure
Simply rename your `mysite` fold to `app`. Then rename `app/code` to `app/src`.
### Finalising the reorganise structure
If you've implemented the new PSR-4 auto-loading logic in your `composer.json` file you'll need to update your namespace mapping.
For example, let's say you had the following autoload attribute in your `composer.json`.
```json
{
// ...
"autoload": {
"classmap": [
"mysite/code/Page.php",
"mysite/code/PageController.php"
],
"psr-4": {
"App\\Web\\": "mysite/code/"
}
},
// ...
}
```
It will become this:
```json
{
// ...
"autoload": {
"classmap": [
"app/src/Page.php",
"app/src/PageController.php"
],
"psr-4": {
"App\\Web\\": "app/src/"
}
},
// ...
}
```
You'll need to update the `project` attribute for your `ModuleManifest` in your `app/src/mysite.yml` file. It should now look something like this:
```yaml
SilverStripe\Core\Manifest\ModuleManifest:
project: app
```
At this stage, your project should be functional with the recommended project structure.
Note that if you've explicitly referenced any static assets (images, css, js) under `mysite`, you'll need to rewrite those references.
This is a good point to commit your changes to your source control system before moving on to the next step.
## Step 8 - Switch to public web-root (optional){#step8}
SilverStripe 4.1 introduces the concept of _public web-root_ this allows you to move
all publicly accessible assets under a `public` folder ([details](/changelogs/4.1.0#public-folder)).
This has security benefits as it minimises the possibility that files that are not meant to be access directly get accidentally exposed.
This step is optional and requires SilverStripe 4.1 or greater. It will become mandatory in SilverStripe 5.
[Skip to Step 9](#step9)
### Automatically switch to the public web root
The `webroot` upgrader command will automatically move your files for you.
```bash
upgrade-code webroot --write
```
Omit the `--write` flag if you want to preview the change.
If you are using a modified `index.php`, `.htaccess`, or `web.config`, you will get a warning.
### Manually switch to using the public web root
* Create a `public` folder in the root of your project
* Move the following files and folder to your new public folder
* `index.php`
* `.htaccess`
* `webconfig.php`
* `assets`
* Any `favicon` files
* Other common files that should be accssible in your project webroot (example: `robots.txt`)
* Delete the root `resources` or `_resources` directories if present.
* Run the following command `composer vendor-expose` to make static assets files accessible via the `public` directory.
If you are upgrading from SilverStripe 4.0 to SilverStripe 4.1 (or above), you'll need to update `index.php` before moving it to the public folder. You can get a copy of the generic `index.php` file from `vendor/silverstripe/recipe-core/public`. If you've made modifications to your `index.php` file, you'll need to replicate those into the new `public/index.php` file.
### Finalising the web root migration
You'll need to update your server configuration to point to the public directory rather than the root of your project.
Update your `.gitignore` file so `assets` and `_resources` (or `resources` if using a pre SilverStripe 4.4 release) are still ignored when located under the `public` folder.
Your project should still be functional, although you may now be missing some static assets.
This is a good point to commit your changes to your source control system before moving on to the next step.
## Step 9 - Move away from hardcoded paths for referencing static assets {#step9}
SilverStripe 4 introduces a new way to reference static assets like images and css.
This enables innovations like moving the SilverStripe module [vendor folder](/changelogs/4.0.0#vendor-folder) or the [public web root](/changelogs/4.1.0#public-folder).
This change is mandatory if you've completed either
[step 7](#step7) (update project structure) or [step 8](#step8) (switch to public web-root).
If you have skipped these steps, it is strongly recommended, but not mandatory.
### Exposing your project static assets
If you have folders under `app` or `mysite` that need to be accessible for your project's web root, you need to say so in your `composer.json` file by adding an entry under `extra.expose`.
For example, let's say you have `scripts`, `images` and `css` folders under `app`. You can expose them by adding this content to your `composer.json` file:
```json
{
// ...
"extra": {
"branch-alias": {
"4.x-dev": "4.2.x-dev"
},
"expose": [
"app/scripts",
"app/images",
"app/css"
]
},
// ...
}
```
For the change to take affect, run the following command: `composer vendor-expose`.
### Referencing static assets in your PHP code
Wherever you would have use a hardcoded path, you can now use the `path/to/file.css` syntax. To reference a static file from a module, prefix the path with the module's name (e.g.: `silverstripe/admin:client/dist/js/bundle.js`).
To add some javascript and css files to your requirements from your PHP code, you could use this syntax:
```php
use SilverStripe\View\Requirements;
# Load your own style and scripts
Requirements::css('app/css/styles.css');
Requirements::script('app/scripts/client.css');
# Load some assets from a module.
Requirements::script('silverstripe/blog: js/main.bundle.js');
```
You can `SilverStripe\Core\Manifest\ModuleResourceLoader` to get the web path of file.
```php
ModuleResourceLoader::singleton()->resolveURL('app/images/road-runner.jpg');
ModuleResourceLoader::singleton()->resolveURL('silverstripe/blog: js/main.bundle.js');
```
You can use `SilverStripe\View\ThemeResourceLoader` to access files from your theme:
```php
$cssResourcePath = ThemeResourceLoader::inst()->findThemedResource('css/layout.css');
$relativeUrl = ModuleResourceLoader::singleton()->resolveURL($cssResourcePath);
```
For classes that expect icons, you can specify them with:
```php
class ListingPage extends \Page
{
private static $icon = 'app/images/sitetree_icon.png';
}
class MyCustomModelAdmin extends \SilverStripe\Admin\ModelAdmin
{
private static $menu_icon = 'app/images/modeladmin_icon.png';
}
```
### Referencing static assets in template files
SilverStripe template files accept a similar format for referencing static assets. You will need to go through your assets files and remove hardcoded references.
```html
)
<% require css("app: css/styles.css") %>
```
### Finalising removal of hardcoded paths for referencing static assets
All your assets should be loading properly now.
This is a good point to commit your changes to your source control system before moving on to the next step.
## Step 10 - Update database class references {#step10}
If you've updated your class names to use namespaces you will need to reflect those changes in any existing database fields. For example, if you've renamed your `HomePage` class to `App\HomePage` then the database `ClassName` column needs to be updated to point to the `App\HomePage` class, otherwise the CMS will tell you that the page is obsolete. This also applies to polymorphic relationships.
There is no automated way to do this, but you can use the list generated in .upgrade.yml and copy it to `app/_config/legacy.yml`, removing any classes that don't extend DataObject.
```
SilverStripe\ORM\DatabaseAdmin:
classname_value_remapping:
HomePage: App\HomePage
```
This will automatically update affected columns when you first build the database.
## Step 11 - Running your upgraded site for the first time {#step11}
You're almost across the finish line.
### Run a dev build
Run a `dev/build` either on the command line or in your browser.
```bash
./vendor/bin/sake dev/build
```
This should migrate your existing data (non-destructively) to the new SilverStripe 4 structure.
#### Migrating files
Since the structure of the `File` DataObject 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)).
```bash
./vendor/bin/sake dev/tasks/MigrateFileTask
```
### Any other script that needs running.
Some third party modules may include their own migration tasks. Take a minute to consult the release notes of your third party dependencies to make sure you haven't missed anything.