From c23ce32f885344967f6e59587cbb84e740bbc249 Mon Sep 17 00:00:00 2001 From: Maxime Rainville Date: Tue, 29 May 2018 12:11:06 +1200 Subject: [PATCH 1/9] Rewrite upgrading guide :construction: Original upgrading doc. I'm keeping it around just so I know what content hasn't been restructured. :construction: Setting outline of new upgrading guide. I'm just outlining the TOC here. https://github.com/silverstripe/silverstripe-upgrader/issues/72 :construction: Typo correction. :construction: Move most of original content into new structure. :memo: Documenting how to recompose your dependencies. :memo: Finish documenting the reorganise command. :memo: Add a conlusion to upgrade :memo: Drafting environment upgrade doc Move environment upgrade doc out of change log and integrating it into the upgrading guide. :memo: Document how to namespace project :construction: Working on step 4. :memo: Adding doc for the upgrade step. Finalise first draft of the upgrade guide. Remove typo Implementing feedback on the doc. Implementing upgrade guide feedback.wq Add refrence to upgrade guide into change log. Implement specific upgrade guide peer review suggestion. Wording tweaks. Remove reference to ACME and rewrite overview. The end of the upgrading guide tweaks ... I think. --- docs/en/03_Upgrading/index.md | 1200 +++++++++++++++++++++++++++++--- docs/en/04_Changelogs/4.0.0.md | 165 +---- docs/en/04_Changelogs/4.1.0.md | 2 + docs/en/04_Changelogs/4.2.0.md | 2 + 4 files changed, 1111 insertions(+), 258 deletions(-) diff --git a/docs/en/03_Upgrading/index.md b/docs/en/03_Upgrading/index.md index b20a97673..b350fa5e3 100644 --- a/docs/en/03_Upgrading/index.md +++ b/docs/en/03_Upgrading/index.md @@ -1,5 +1,5 @@ title: Upgrading -introduction: Keep your SilverStripe installations up to date with the latest fixes, security patches and new features. +introduction: Upgrade your project SilverStripe 4 and keep it up to date with the latest fixes, security patches and new features. # Upgrading to SilverStripe 4 @@ -10,11 +10,77 @@ your SilverStripe installation means overwriting files, flushing the cache and u See our [upgrade notes and changelogs](/changelogs/4.0.0) for 4.0.0 specific information, bugfixes and API changes. -## Composer +## Understanding and planning your upgrade {#planning} -SilverStripe CMS is a modular system, and [Composer](http://getcomposer.org) -is the default way to manage your modules ([instructions](/getting_started/composer)). -We recommend using `recipe-cms` in your `composer.json` file to help you keep +How easy will it be to update my project? It's a fair question, and sometimes a difficult one to answer. + +* SilverStripe follows _semantic versioning_ (see our [release process](/contributing/release_process) for details). + * "Major" releases introduces API change that may break your application. + * "Minor" releases (x.y) introduces API changes in a backward compatible way and can mark some API as deprecated. + * "Patch" releases (x.y.z) fix bugs without introducing any API changes. +* If you've made custom branches of SilverStripe core, or any thirdparty module, it's going to be harder to upgrade. +* The more custom features you have, the harder it will be to upgrade. You will have to re-test all of those features, and adapt to API changes in core. +* Customizations of a well defined type - such as custom page types or custom blog widgets - are going to be easier to upgrade than customisations that modify deep system internals like rewriting SQL queries. + +### Overview of changes + +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.6 is now the minimum required version and up to PHP 7.2.x is supported. +* SilverStripe is now even more modular which allows you to remove functionality your project might not need. +* Common functionality sets can now be installed via SilverStripe _recipes_. +* SilverStripe modules can now be installed in the vendor folder along with your regular PHP packages. +* The SilverStripe codebase is now completely namespaced. +* SilverStripe 4 makes usage of PHP _traits_ making it easy to apply common patterns to your classes. +* Publicly facing files can now be served from a public webroot for added security. +* The concept of `ChangeSet` has been added to versioning along with version ownership. +* GraphQL is now the favourite way of creating web services with SilverStripe. +* Asset management has been completely redone with a brand new react-based UI and the introduction of versioned files. +* Parts of the CMS UI are now build in react and entwine is in the process of being faded out. +* SilverStripe 4 now supports PSR-4 auto-loading for modules and for your main project. + +[Learn more about major API changes introduced by SilverStripe 4](#list-of-major-api-changes) + +### Using recipes instead of requiring individual modules +The SilverStripe CMS and SilverStripe Framework are becoming more modular. Many of the secondary features contained in SilverStripe CMS 3 and SilverStripe Framework 3 have been moved to separate modules. + +SilverStripe 4 introduces the concept of _recipes_. Recipes are a combination of modules to achieve a common pattern. + +Read the [Switching to recipes](#switching-to-recipes) section of this guide for more information about how recipes work. + +### Automating your upgrades using the SilverStripe 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. The upgrader is unlikely to completely upgrade your project to SilverStripe 4, however it can take care of the most tedious part of the upgrade. + +It can also be use to upgrade your existing SilverStripe 4 to a newer minor release. + +Each step in this upgrade guide explains how to use + +[Learn how to install the upgrader tool](#install-the-upgrader-tool-(optional)) + +## Step 0 - Pre-requisites and background work {#step0} + +Before you begin the upgrade process, make sure you meat these pre-requisites + +### Back up your files and database + +* Set up your project in your development environment. +* Backup your database content. +* Backup your webroot files. + +
+Never update a website on the live server. Get it working on a development copy first! +
+ +### Install composer + +Most of the steps in this guide assume you are tracking your project dependencies through composer. + +While it is possible to upgrade to SilverStripe 4 without using composer, you will save a lot of time if you do. + +[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 @@ -36,123 +102,1069 @@ and also checking the `composer.json` files in [recipe-core](https://github.com/ 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) -## Manual upgrades +### Install the upgrader tool (optional) +Using the upgrader is not mandatory, but it can speed up the upgrade process. To install the upgrader globally run this command. -* 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. -* Backup your webroot files. -* Download the new release and uncompress it to a temporary folder. -* Leave custom folders like *themes* in place. -* Rename `app/code` folder to `app/src`, updating your `app/_config/app.yml` config to set the new project name. -* Identify system folders in your webroot (`cms`, `framework` and any additional modules). -* Delete existing system folders (or move them outside of your webroot). -* 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 `app/` 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. +```bash +composer global require silverstripe/upgrader +``` -
-Never update a website on the live server without trying it on a development copy first! +Add your global composer bin directory to your path. On *nix system, this directory is normally located at `$HOME/.composer/vendor/bin`. On Windows system, this directory is normally located at `C:\Users\\AppData\Roaming\Composer\vendor\bin`. You can find the exact location by running this command: +```bash +composer global config bin-dir +``` + +On *nix system, the following command will add your global composer bin directory to your path if `bash` is your default shell environment: +```bash +echo 'export PATH=$PATH:~/.composer/vendor/bin/' >> ~/.bash_profile +``` + +Each command in the upgrader has somewhat different arguments. However, most of them accept these two options: +* `--write` which tells the upgrader to apply changes to your code base +* `-d` which can be use to explicitly specify the root of your project — if not specified the current working directory is assume to be the root of the project. + +You can run `upgrade-code help` to get more information about the upgrader or `upgrade-code help command-name` to information about a specific command. + + +
+Sample upgrader commands in this guide assume your working directory is the root of your SilverStripe project. You'll need to use the `-d` flag if that's not the case.
-## Environment variables file changed to dotenv +### Running all the upgrader commands in this guide in on line -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) - -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. +The upgrader comes with an `all-in-one` command. This command will attempt to run all the upgrader commands in the same order as this guide. This is unlikely to work on your first try, but can be a good way to get started without going through this entire guide. +```bash +upgrade-code all-in-one --recipe-core-constraint=1.1 --namespace="App\\Web" ``` -cd ~/my-project-root + +* `--recipe-core-constraint` defined your target version of `silverstripe/recipe-core`. +* `--namespace` allows you to specify what will be the main namespace of your project. +* `--skip-namespace` allows you to skip the `add-namespace` command. +* `--skip-webroot` allows you to skip the `webroot` command. + +### Branching your project + +Setting a dedicated branch in your source control system to track your upgrade work can help you manage your upgrade. If you're upgrading a big project, you should consider creating individual branches for each step. + +## Step 1 - Upgrade your dependencies + +The first step is to update your dependencies' constraints in your `composer.json` file to require the latest version of the SilverStripe modules. + +### Automatically upgrade dependencies with the `recompose` upgrader command + +If you've installed the upgrader, you can use the `recompose` command to help you upgrade your dependencies. This command will try to: +* upgrade your PHP constraint +* upgrade core SilverStripe modules to their version 4 equivalent +* switch to recipes where possible +* find SilverStripe 4 compatible versions of third party modules. + +Take for example the following SilverStripe 3 `composer.json` file. +```json +{ + "name": "app/cms-website", + "description": "The Example website project.", + "license": "BSD-3", + "require": { + "php": ">=5.3.3", + "silverstripe/cms": "3.6.5@stable", + "silverstripe/framework": "3.6.5@stable", + "silverstripe/reports": "3.6.5@stable", + "silverstripe/siteconfig": "3.6.5@stable", + "dnadesign/silverstripe-elemental": "^1.8.0" + } +} +``` + +You can upgrade the `composer.json` file with this command: +```bash +upgrade-code recompose --recipe-core-constraint=1.1 --write +``` + +The `--recipe-core-constraint` flag can be use to target a specific version of `silverstripe/recipe-core`. If this flag is omitted, the project will be upgraded to the latest stable version. You can use the `--strict` option if you want to use more conservative version constraints. Omit the `--write` flag to preview your changes. + +Your upgraded `composer.json` file will look like this. +```json +{ + "name": "app/cms-website", + "description": "The Example website project.", + "license": "BSD-3", + "require": { + "dnadesign/silverstripe-elemental": "^2.1", + "php": ">=5.6", + "silverstripe/recipe-cms": "^1.1" + } +} +``` + +If the `recompose` command can't find a SilverStripe 4 compatible version for one of your module, it will keep this dependency in your `composer.json` file with its existing constraint. + +### Manually upgrading your dependencies + +The instruction in this section assumed you'll be editing your `composer.json` file in a text editor. + +#### Switching to recipes + +Where possible, we recommend you use recipes. + +If your SilverStripe 3 project requires the `silverstripe/cms` module, replace that dependency with `silverstripe/recipe-cms`. Set the version constraint for `silverstripe/recipe-cms` to: +* `~1.0.0` to upgrade to SilverStripe 4.0 +* `~1.1.0` to upgrade to SilverStripe 4.1 +* `~1.2.0` to upgrade to SilverStripe 4.2 +* and so on. + +If your SilverStripe 3 project requires the `silverstripe/framework` module without `silverstripe/cms`, replace `silverstripe/framework` with `silverstripe/recipe-core`. Set the version constraint for `silverstripe/recipe-core` to: +* `~1.0.0` to upgrade to SilverStripe 4.0 +* `~1.1.0` to upgrade to SilverStripe 4.1 +* `~1.2.0` to upgrade to SilverStripe 4.2 +* and so on. + +The following modules are implicitly required by `silverstripe/recipe-core`. They can be removed from your `composer.json` dependencies if you are using `silverstripe/recipe-core` or `silverstripe/recipe-cms`. +* `sivlerstripe/framework` +* `silverstripe/config` +* `silverstripe/assets` + +The following modules are implicitly required by `silverstripe/recipe-cms`. They can be removed from your `composer.json` dependencies if you are using `silverstripe/recipe-cms`. +* `silverstripe/admin` +* `silverstripe/asset-admin` +* `silverstripe/campaign-admin` +* `silverstripe/cms` +* `silverstripe/errorpage` +* `silverstripe/reports` +* `silverstripe/graphql` +* `silverstripe/siteconfig` +* `silverstripe/versioned` +* `silverstripe/recipe-core` + +Take for example the following SilverStripe 3 `composer.json`. +```json +{ + "name": "app/cms-website", + "require": { + "silverstripe/cms": "3.6.5@stable", + "silverstripe/framework": "3.6.5@stable", + "silverstripe/reports": "3.6.5@stable", + "silverstripe/siteconfig": "3.6.5@stable" + } +} +``` + +After switching to SilverStripe 4 recipes, the `composer.json` file should look like this. +```json +{ + "name": "app/cms-website", + "require": { + "silverstripe/recipe-cms": "~1.1.0" + } +} +``` + +#### Explicitly defining your dependencies +If you would rather explicitly define your dependencies, you can do so. Update the `silverstripe/framework` constraint and `silverstripe/cms` constraint to match your targeted minor version of SilverStripe 4. If you use `silverstripe/reports` and `silverstripe/siteconfig`, update their constraints as well. + +In most cases, you'll also want to require the same modules as the equivalent recipes. If you don't, your users will likely lose some features after the upgrade is completed. + +Take for example the following SilverStripe 3 `composer.json`. +```json +{ + "name": "app/cms-website", + "require": { + "silverstripe/cms": "3.6.5@stable", + "silverstripe/framework": "3.6.5@stable", + "silverstripe/reports": "3.6.5@stable", + "silverstripe/siteconfig": "3.6.5@stable" + } +} +``` + +After switching to SilverStripe 4 and explicitly defining your dependencies, the `composer.json` file should look like this. +```json +{ + "name": "app/cms-website", + "require": { + "silverstripe/cms": "~4.1.0", + "silverstripe/framework": "~4.1.0", + "silverstripe/reports": "~4.1.0", + "silverstripe/siteconfig": "~4.1.0", + "silverstripe/admin": "~1.1.0", + "silverstripe/asset-admin": "~1.1.0", + "silverstripe/campaign-admin": "~1.1.0", + "silverstripe/errorpage": "~1.1.0", + "silverstripe/graphql": "~1.1.0", + "silverstripe/versioned": "~1.1.0" + } +} +``` + +#### Updating third party dependencies +If you project requires third party modules, you'll need to adjust their associated constraint. This will allow you to retrieve a SilverStripe 4 compatible version of the module. + +[Look up the module on Packagist](https://packagist.org/) to see if a SilverStripe 4 version is provided. + +Take for example the following SilverStripe 3 `composer.json`. +```json +{ + "name": "app/cms-website", + "require": { + "silverstripe/framework": "3.6.5@stable", + "silverstripe/cms": "3.6.5@stable", + "dnadesign/silverstripe-elemental": "^1.8.0" + } +} +``` + +Looking at the [Packagist entry for `dnadesign/silverstripe-elemental`](https://packagist.org/packages/dnadesign/silverstripe-elemental#2.0.0), you can see that versions 2.0.0 and above of this module are compatible with SilverStripe 4. So you can update that constraint to `^2.0.0`. + +Alternatively, you can set a very permissive constraint and let composer find a SilverStripe 4 compatible version. After you're done updating your dependencies, make sure you adjust your constraints to be more specific. + +Once you've updated your third-party modules constraints, try updating your dependencies by running `composer update`. If composer can't resolve all your dependencies it will throw an error. + +### Resolving conflicts + +You'll likely have some conflicts to resolve, whether you've updated your dependencies with the upgrader or manually. + +Running a `composer update` will tell you which modules are conflicted and suggested alternative combinations of modules that might work. + +The most typical reason for a conflict is that the maintainer of a module hasn't released a version compatible with SilverStripe 4. + +If the maintainer of the module is in the process of upgrading to SilverStripe 4, a development version of the module might be available. In some cases, it can be worthwhile to look up the repository of the module or to reach out to the maintainer. + +
+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: +* remove the module from your project, if it is not essential +* integrate the affected module into your project's codebase +* fork the affected module and maintain it yourself. + +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 in favour of a non-executable +`.env` file, which 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. + +### 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 ``` -Read the [upgrader `environment` command documentation](https://github.com/silverstripe/silverstripe-upgrader/blob/master/docs/en/environment.md) -for more details. +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. -## Using the upgrader tool +Omit the `--write` flag to do a dry-run. -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. +### 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`. -### `index.php` and `.htaccess` rewrites +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 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`. +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 more details, please read through the [`index.php` and `.htaccess` rewrites section](/changelogs/4.0.0#index-php-rewrites) +For example, take the following `_ss_environment.php` file. +```php +get('ProductService'); +``` + +#### Running the `upgrade` command + +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 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. There's 3 options that can be provided: `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 case, 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. + +### 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 +You'll need to perform the following steps manually, even if you've used the automated rewrite of namespaces previously. + +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 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 of small and big API changes. To update deprecated API references manually, you have to go through each one of your project files. + +[Read the SilverStripe 4 change logs](/changelogs/4.0.0/) for a comprehensive list of what has changed. + +### 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 are upgrading to SilverStripe 4.1 or above +* `vendor/silverstripe/recipe-core/index.php` if you are upgrading to SilverStripe 4.0 + +If you've modified your SilverStripe 3 `index.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` if you are upgrading to SilverStripe 4.1 or above +* `vendor/silverstripe/recipe-core/` if you are upgrading to SilverStripe 4.0 + +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. Adopting the recommended project structure is optional, but will become mandatory in SilverStripe 5. + +You may skip this step if you want. + +### 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 occurrence 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 reference 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. 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. + +### 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` directory 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` 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 enable innovations like moving SilverStripe module vendor folder or the public web root. + +This change is mandatory if you've completed either: +* Step 7 - Update project structure +* Step 8 - Switch to public web-root + +Otherwise, 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 an hardcoded path, you can now use the `projectname: path/to/file.css` syntax. + +`projectname` is controlled by the `project` property of `SilverStripe\Core\Manifest\ModuleManifest` in your YML configuration. This configuration file should look like this: + ```yaml + SilverStripe\Core\Manifest\ModuleManifest: + project: app + ``` + +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\ModuleLoader` to get the web path of file. +```php +ModuleLoader::getModule('app')->getResource('images/road-runner.jpg')->getRelativePath(); +``` + +You can use `SilverStripe\View\ThemeResourceLoader` to access files from your theme: +```php +$themeFolderPath = ThemeResourceLoader::inst()->getPath('simple'); +$themesFilePath = ThemeResourceLoader::inst()->findThemedResource('css/styles.css'); +``` + +For classes that expect icons, you can specify theme 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 +SS template files accept a similar format for referencing static assets. 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 - Running your upgraded site for the first time {#step10} + +You're almost across the finish line. + +### Run a dev build +Rnn a `dev/build` either on the command line or in your browser. + +```bash +./vendor/bin/sake dev/build +``` + +This should migrate your existing data 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)). -``` -$ ./vendor/bin/sake dev/tasks/MigrateFileTask +```bash +./vendor/bin/sake dev/tasks/MigrateFileTask ``` -## Upgrade tips +### Any other script that needs running. -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). +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 have miss anything. -``` -~/.composer/vendor/bin/upgrade-code inspect ./mysite -``` +## List of Major API Changes -These hints only cover a part of the upgrade work, but can serve as a good indicator for where to start. +This is a list of the most common API changes that might affect you. -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.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 +Read the changelogs for a comprehensive list of everything that is new in SilverStripe 4: +* (SilverStripe 4.0.0 change logs)[/changelogs/4.0.0/] +* (SilverStripe 4.1.0 change logs)[/changelogs/4.1.0/] +* (SilverStripe 4.2.0 change logs)[/changelogs/4.2.0/]. [Object class replaced by traits](/changelogs/4.0.0#object-replace) The `Object` class has been superceded by three traits: @@ -209,19 +1221,3 @@ You can change the casting for this by defining a casting config on the DataObje 'MyField' => 'HTMLText' ]; ``` - - -## Decision Helpers - -How easy will it be to update my project? It's a fair question, and sometimes a difficult one to answer. - -* "Micro" releases (x.y.z) are explicitly backwards compatible, "minor" and "major" releases can deprecate features and change APIs (see our [release process](/contributing/release_process) for details) -* If you've made custom branches of SilverStripe core, or any thirdparty module, it's going to be harder to upgrade. -* The more custom features you have, the harder it will be to upgrade. You will have to re-test all of those features, and adapt to API changes in core. -* Customizations of a well defined type - such as custom page types or custom blog widgets - are going to be easier to upgrade than customisations that modify deep system internals like rewriting SQL queries. - -## Related - -* [Release Announcements](http://groups.google.com/group/silverstripe-announce/) -* [Blog posts about releases on silverstripe.org](http://silverstripe.org/blog/tag/release) -* [Release Process](../contributing/release_process) diff --git a/docs/en/04_Changelogs/4.0.0.md b/docs/en/04_Changelogs/4.0.0.md index e01c0a80c..e678c82e2 100644 --- a/docs/en/04_Changelogs/4.0.0.md +++ b/docs/en/04_Changelogs/4.0.0.md @@ -3,15 +3,18 @@ ## Introduction This version introduces many breaking changes, which in most projects can be managed through a combination -of automatic upgrade processes as well as manual code review. This document reviews these changes and will -guide developers in preparing existing 3.x code for compatibility with 4.0 +of automatic upgrade processes as well as manual code review. This changelogs described all API changes in detail. -For users upgrading to 4.1.0 please see the specific [4.1.0 upgrading guide](4.1.0.md). +[Read _Upgrading to SilverStripe 4_](/upgrading/) for a detailed step-by-step guide on upgrading your SilverStripe 3 project to SilverStripe 4.0 + +For users upgrading to 4.1.0 please see the specific [4.1.0 changelogs](4.1.0.md). + + ## Overview {#overview} -* Minimum version dependencies have increased; PHP 5.5 and Internet Explorer 11 (or other modern browser) - is required. +* Minimum version dependencies have increased; PHP 5.6 and Internet Explorer 11 (or other modern browser) + are required. * All code earlier marked as deprecated for 4.0 has now been removed (check our [deprecation process](/contributing/release_process)) * **4.1.0 only** Support for public webroot folder `public/` ([details](4.1.0#public-folder)) @@ -45,7 +48,7 @@ For users upgrading to 4.1.0 please see the specific [4.1.0 upgrading guide](4.1 * Removed module path constants (e.g. `FRAMEWORK_PATH`) and support for hardcoded file paths (e.g. `mysite/css/styles.css`) ([details](#module-paths)) * Replaced Zend_Translate with symfony/translation ([details](#i18n)) * Replaced `Zend_Cache` and the `Cache` API with a PSR-16 implementation (symfony/cache) ([details](#cache)) -* `_ss_environment.php` files have been removed in favour of `.env` and "real" environment variables ([details](#env)). +* `_ss_environment.php` files have been removed in favour of `.env` and "real" environment variables ([details](/upgrading/#env)). * Behat support updated to v3 ( [details](https://github.com/silverstripe/silverstripe-behat-extension)) * The `GDBackend` and `ImagickBackend` classes have been replaced by a unified `InterventionBackend` which uses the @@ -129,76 +132,6 @@ For modules that don't have a pre-release branch started, you should raise an is compatibility. For now, you should attempt to continue the upgrade without the module and temporarily disable its functionality. -### Manual upgrades - -Please follow - -### 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 -the old php file, `.env` may be placed in either the web root, or one level above. - -For example, if you have the below `_ss_environment.php` file, your `.env` would be rewritten as follows: - -`_ss_environment.php`: - - -```php -// Environment -define('SS_ENVIRONMENT_TYPE', 'dev'); -define('SS_DEFAULT_ADMIN_USERNAME', 'admin'); -define('SS_DEFAULT_ADMIN_PASSWORD', 'password'); -$_FILE_TO_URL_MAPPING[__DIR__] = 'http://localhost'; - -// Database -define('SS_DATABASE_CHOOSE_NAME', true); -define('SS_DATABASE_CLASS', 'MySQLDatabase'); -define('SS_DATABASE_USERNAME', 'root'); -define('SS_DATABASE_PASSWORD', ''); -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 -SS_DATABASE_CHOOSE_NAME="true" -SS_DATABASE_CLASS="MySQLDatabase" -SS_DATABASE_USERNAME="root" -SS_DATABASE_PASSWORD="" -SS_DATABASE_SERVER="127.0.0.1" -``` - -The removal of the `_ss_environment.php` file means that conditional logic is no longer available in the environment -variable set-up process. This generally encouraged bad practice and should be avoided. If you still require conditional -logic early in the bootstrap, this is best placed in the `_config.php` files. - -Note also that `$_FILE_TO_URL_MAPPING` has been removed and replaced with `SS_BASE_URL` env var. -This url must be an absolute url with an optional protocol. The following are valid, for example: - -``` -SS_BASE_URL="http://localhost/" -SS_BASE_URL="https://localhost/" -SS_BASE_URL="//localhost/" -``` - -The global values `$database` and `$databaseConfig` have been deprecated, as has `ConfigureFromEnv.php` -which is no longer necessary. - -To access environment variables you can use the `SilverStripe\Core\Environment::getEnv()` method. - -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} @@ -234,28 +167,6 @@ 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` @@ -618,14 +529,6 @@ implements the `Monolog\Formatter\FormatterInterface` interface. ### Upgrade `mysite/_config.php` {#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. - -If you need to configure database details in PHP you should configure these details via `.env` file, -or alternatively (but less recommended) use the new `DB::setConfig()` api. - The global `$project` is deprecated in favour of the configuration setting `SilverStripe\Core\Manifest\ModuleManifest.project`. @@ -1640,56 +1543,6 @@ 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 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 - -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 -references to those classes. - -Use the below to setup upgrader, and apply a namespace to a given code folder. - -``` -composer global require silverstripe/upgrader -cd ~/Project/Root -~/.composer/vendor/bin/upgrade-code add-namespace "WebDesignGroup\ShopSite" ./mysite/code --recursive --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 task will do the following: - - - Add the given namespace to all files in the code class, and subdirectories. - - Sub-namespaces will be applied based on directory structure - - All references to classes in any namespaced files will be safely retained with additional `use` directives - added as necessary. - - Register all namespaced classese in a mysite/.upgrade.yml file for migration of other code - -This task will not do the following, and must be done manually: - - - Adding `table_name` to any namespaced classes - - Upgrade other references to namespaced classes outside of this folder - - Migrate any database table records - -Please see the following steps for more information. - -#### 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 -to upgrade your project to namespaced framework classe). - -``` -composer global require silverstripe/upgrader -cd ~/Project/Root -~/.composer/vendor/bin/upgrade-code upgrade ./othercode --write -``` #### Updating custom dataobjects to use existing table names diff --git a/docs/en/04_Changelogs/4.1.0.md b/docs/en/04_Changelogs/4.1.0.md index ee61f0e10..29ac00984 100644 --- a/docs/en/04_Changelogs/4.1.0.md +++ b/docs/en/04_Changelogs/4.1.0.md @@ -7,6 +7,8 @@ ## Upgrading +[Read _Upgrading to SilverStripe 4_](/upgrading/) for a detailed step-by-step guide on upgrading your SilverStripe project to SilverStripe 4.1 + Note: if you receive an error message about an undefined constant while upgrading with `composer`, re-running the command should solve the issue. diff --git a/docs/en/04_Changelogs/4.2.0.md b/docs/en/04_Changelogs/4.2.0.md index cdde4a46b..922fbe49e 100644 --- a/docs/en/04_Changelogs/4.2.0.md +++ b/docs/en/04_Changelogs/4.2.0.md @@ -7,6 +7,8 @@ ## Upgrading {#upgrading} +[Read _Upgrading to SilverStripe 4_](/upgrading/) for a detailed step-by-step guide on upgrading your SilverStripe project to SilverStripe 4.1 + ### App folder name The standard 'mysite' code naming convention has changed in 4.2. Although existing sites can continue From 3ceed740f4da93eeefa9d32d2e1663d0e8256045 Mon Sep 17 00:00:00 2001 From: Maxime Rainville Date: Wed, 13 Jun 2018 13:44:01 +1200 Subject: [PATCH 2/9] Rename `skip-namespace` argument. --- docs/en/03_Upgrading/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/en/03_Upgrading/index.md b/docs/en/03_Upgrading/index.md index b350fa5e3..09f1c102f 100644 --- a/docs/en/03_Upgrading/index.md +++ b/docs/en/03_Upgrading/index.md @@ -140,7 +140,7 @@ upgrade-code all-in-one --recipe-core-constraint=1.1 --namespace="App\\Web" * `--recipe-core-constraint` defined your target version of `silverstripe/recipe-core`. * `--namespace` allows you to specify what will be the main namespace of your project. -* `--skip-namespace` allows you to skip the `add-namespace` command. +* `--skip-add-namespace` allows you to skip the `add-namespace` command. * `--skip-webroot` allows you to skip the `webroot` command. ### Branching your project From c8b688858241873d331e15599d074ef2887195e4 Mon Sep 17 00:00:00 2001 From: Maxime Rainville Date: Wed, 13 Jun 2018 17:38:25 +1200 Subject: [PATCH 3/9] Update the doc about the `all` command. --- docs/en/03_Upgrading/index.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/en/03_Upgrading/index.md b/docs/en/03_Upgrading/index.md index 09f1c102f..a60176f29 100644 --- a/docs/en/03_Upgrading/index.md +++ b/docs/en/03_Upgrading/index.md @@ -132,15 +132,17 @@ Sample upgrader commands in this guide assume your working directory is the root ### Running all the upgrader commands in this guide in on line -The upgrader comes with an `all-in-one` command. This command will attempt to run all the upgrader commands in the same order as this guide. This is unlikely to work on your first try, but can be a good way to get started without going through this entire guide. +The upgrader comes with an `all` command. This command will attempt to run all the upgrader commands in the same order as this guide. This is unlikely to work on your first try, but can be a good way to get started without going through this entire guide. ```bash -upgrade-code all-in-one --recipe-core-constraint=1.1 --namespace="App\\Web" +upgrade-code all --recipe-core-constraint=1.1 --namespace="App\\Web" --psr4 ``` * `--recipe-core-constraint` defined your target version of `silverstripe/recipe-core`. * `--namespace` allows you to specify what will be the main namespace of your project. +* `--psr4` allows you to specify that your project structure respect the PSR-4 standard and to use sub-namespaces. * `--skip-add-namespace` allows you to skip the `add-namespace` command. +* `--skip-reorganise` allows you to skip the `reorganise` command. * `--skip-webroot` allows you to skip the `webroot` command. ### Branching your project From e80d3a8ff109118f4b85929350ca3108882e5b6f Mon Sep 17 00:00:00 2001 From: Maxime Rainville Date: Thu, 14 Jun 2018 10:14:55 +1200 Subject: [PATCH 4/9] Remove the bits that said composer usage was optional. --- docs/en/03_Upgrading/index.md | 9 +++------ 1 file changed, 3 insertions(+), 6 deletions(-) diff --git a/docs/en/03_Upgrading/index.md b/docs/en/03_Upgrading/index.md index a60176f29..e27457a56 100644 --- a/docs/en/03_Upgrading/index.md +++ b/docs/en/03_Upgrading/index.md @@ -74,14 +74,11 @@ Never update a website on the live server. Get it working on a development copy ### Install composer -Most of the steps in this guide assume you are tracking your project dependencies through composer. +SilverStripe 4 requires the use of composer for dependency management. -While it is possible to upgrade to SilverStripe 4 without using composer, you will save a lot of time if you do. +[Learn how to use composer with SilverStripe](/getting_started/composer) -[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`. +We recommend using `recipe-cms` in your `composer.json` file to help you keep up to date and run `composer update`. ```json { From 4fb30da80eb0f2de32903b3e1edd0b64e3e47e4e Mon Sep 17 00:00:00 2001 From: Maxime Rainville Date: Fri, 15 Jun 2018 11:17:18 +1200 Subject: [PATCH 5/9] Update recipe-core and recipe-cms versions Update recipe-core and recipe-cms version to use the retag 4.x releases. --- docs/en/03_Upgrading/index.md | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/docs/en/03_Upgrading/index.md b/docs/en/03_Upgrading/index.md index e27457a56..9e11d27b0 100644 --- a/docs/en/03_Upgrading/index.md +++ b/docs/en/03_Upgrading/index.md @@ -83,7 +83,7 @@ We recommend using `recipe-cms` in your `composer.json` file to help you keep up ```json { "require": { - "silverstripe/recipe-cms": "^1" + "silverstripe/recipe-cms": "^4" } } ``` @@ -177,7 +177,7 @@ Take for example the following SilverStripe 3 `composer.json` file. You can upgrade the `composer.json` file with this command: ```bash -upgrade-code recompose --recipe-core-constraint=1.1 --write +upgrade-code recompose --recipe-core-constraint=4.1 --write ``` The `--recipe-core-constraint` flag can be use to target a specific version of `silverstripe/recipe-core`. If this flag is omitted, the project will be upgraded to the latest stable version. You can use the `--strict` option if you want to use more conservative version constraints. Omit the `--write` flag to preview your changes. @@ -191,7 +191,7 @@ Your upgraded `composer.json` file will look like this. "require": { "dnadesign/silverstripe-elemental": "^2.1", "php": ">=5.6", - "silverstripe/recipe-cms": "^1.1" + "silverstripe/recipe-cms": "^4.1" } } ``` @@ -206,16 +206,16 @@ The instruction in this section assumed you'll be editing your `composer.json` f Where possible, we recommend you use recipes. -If your SilverStripe 3 project requires the `silverstripe/cms` module, replace that dependency with `silverstripe/recipe-cms`. Set the version constraint for `silverstripe/recipe-cms` to: -* `~1.0.0` to upgrade to SilverStripe 4.0 -* `~1.1.0` to upgrade to SilverStripe 4.1 -* `~1.2.0` to upgrade to SilverStripe 4.2 +If your SilverStripe 3 project requires the `silverstripe/cms` module, replace that dependency with `silverstripe/recipe-cms`. The version constraint for `silverstripe/recipe-cms` must match your targeted version of SilverStripe: +* `~4.0.0` to upgrade to SilverStripe 4.0 +* `~4.1.0` to upgrade to SilverStripe 4.1 +* `~4.2.0` to upgrade to SilverStripe 4.2 * and so on. -If your SilverStripe 3 project requires the `silverstripe/framework` module without `silverstripe/cms`, replace `silverstripe/framework` with `silverstripe/recipe-core`. Set the version constraint for `silverstripe/recipe-core` to: -* `~1.0.0` to upgrade to SilverStripe 4.0 -* `~1.1.0` to upgrade to SilverStripe 4.1 -* `~1.2.0` to upgrade to SilverStripe 4.2 +If your SilverStripe 3 project requires the `silverstripe/framework` module without `silverstripe/cms`, replace `silverstripe/framework` with `silverstripe/recipe-core`. The version constraint for `silverstripe/recipe-core` must match your targeted version of SilverStripe: +* `~4.0.0` to upgrade to SilverStripe 4.0 +* `~4.1.0` to upgrade to SilverStripe 4.1 +* `~4.2.0` to upgrade to SilverStripe 4.2 * and so on. The following modules are implicitly required by `silverstripe/recipe-core`. They can be removed from your `composer.json` dependencies if you are using `silverstripe/recipe-core` or `silverstripe/recipe-cms`. @@ -253,7 +253,7 @@ After switching to SilverStripe 4 recipes, the `composer.json` file should look { "name": "app/cms-website", "require": { - "silverstripe/recipe-cms": "~1.1.0" + "silverstripe/recipe-cms": "~4.1.0" } } ``` From 580999b570ac7c0ff80040ef97b962b2403b8174 Mon Sep 17 00:00:00 2001 From: Maxime Rainville Date: Mon, 25 Jun 2018 15:57:33 +1200 Subject: [PATCH 6/9] Correcting typo. --- docs/en/03_Upgrading/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/en/03_Upgrading/index.md b/docs/en/03_Upgrading/index.md index 9e11d27b0..1eb09539c 100644 --- a/docs/en/03_Upgrading/index.md +++ b/docs/en/03_Upgrading/index.md @@ -219,7 +219,7 @@ If your SilverStripe 3 project requires the `silverstripe/framework` module with * and so on. The following modules are implicitly required by `silverstripe/recipe-core`. They can be removed from your `composer.json` dependencies if you are using `silverstripe/recipe-core` or `silverstripe/recipe-cms`. -* `sivlerstripe/framework` +* `silverstripe/framework` * `silverstripe/config` * `silverstripe/assets` From 1b06be1a6456e12131f9a370daaf58ca107054e0 Mon Sep 17 00:00:00 2001 From: Ingo Schommer Date: Tue, 26 Jun 2018 11:40:46 +1200 Subject: [PATCH 7/9] Consistent upgrading crosslinks in changelogs --- docs/en/03_Upgrading/index.md | 4 ---- docs/en/04_Changelogs/4.0.0.md | 9 ++++----- docs/en/04_Changelogs/4.1.0.md | 10 +++++----- docs/en/04_Changelogs/4.2.0.md | 8 ++++++-- 4 files changed, 15 insertions(+), 16 deletions(-) diff --git a/docs/en/03_Upgrading/index.md b/docs/en/03_Upgrading/index.md index 1eb09539c..5deb97e1b 100644 --- a/docs/en/03_Upgrading/index.md +++ b/docs/en/03_Upgrading/index.md @@ -6,10 +6,6 @@ introduction: Upgrade your project SilverStripe 4 and keep it up to date with th 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. -
-See our [upgrade notes and changelogs](/changelogs/4.0.0) for 4.0.0 specific information, bugfixes and API changes. -
- ## Understanding and planning your upgrade {#planning} How easy will it be to update my project? It's a fair question, and sometimes a difficult one to answer. diff --git a/docs/en/04_Changelogs/4.0.0.md b/docs/en/04_Changelogs/4.0.0.md index e678c82e2..754e7fa36 100644 --- a/docs/en/04_Changelogs/4.0.0.md +++ b/docs/en/04_Changelogs/4.0.0.md @@ -5,11 +5,10 @@ This version introduces many breaking changes, which in most projects can be managed through a combination of automatic upgrade processes as well as manual code review. This changelogs described all API changes in detail. -[Read _Upgrading to SilverStripe 4_](/upgrading/) for a detailed step-by-step guide on upgrading your SilverStripe 3 project to SilverStripe 4.0 - -For users upgrading to 4.1.0 please see the specific [4.1.0 changelogs](4.1.0.md). - - +[Read _Upgrading to SilverStripe 4_](/upgrading/) for a detailed step-by-step guide on upgrading your SilverStripe 3 project to SilverStripe 4. +It describes how to use an automated [upgrader tool](https://github.com/silverstripe/silverstripe-upgrader) +to make the job easier. +For users upgrading to later versions, please see the specific [4.1.0](4.1.0) and [4.2.0](4.2.0) changelogs. ## Overview {#overview} diff --git a/docs/en/04_Changelogs/4.1.0.md b/docs/en/04_Changelogs/4.1.0.md index 29ac00984..4ed2029f5 100644 --- a/docs/en/04_Changelogs/4.1.0.md +++ b/docs/en/04_Changelogs/4.1.0.md @@ -7,12 +7,12 @@ ## Upgrading -[Read _Upgrading to SilverStripe 4_](/upgrading/) for a detailed step-by-step guide on upgrading your SilverStripe project to SilverStripe 4.1 +[Read _Upgrading to SilverStripe 4_](/upgrading/) for a detailed step-by-step guide on upgrading your SilverStripe 3 project to SilverStripe 4. +It describes how to use an automated [upgrader tool](https://github.com/silverstripe/silverstripe-upgrader) +to make the job easier. +Please also note the [4.0.0](4.0.0) and [4.2.0](4.2.0) changelogs for a complete list of changes. -Note: if you receive an error message about an undefined constant while -upgrading with `composer`, re-running the command should solve the issue. - -### Upgrade `public/` folder (optional) {#public-folder} +### Use `public/` folder (optional) {#public-folder} This release allows the maintenance of a public webroot folder which separates all web-accessible files from protected project files (like the vendor folder diff --git a/docs/en/04_Changelogs/4.2.0.md b/docs/en/04_Changelogs/4.2.0.md index 922fbe49e..f87222f60 100644 --- a/docs/en/04_Changelogs/4.2.0.md +++ b/docs/en/04_Changelogs/4.2.0.md @@ -7,7 +7,10 @@ ## Upgrading {#upgrading} -[Read _Upgrading to SilverStripe 4_](/upgrading/) for a detailed step-by-step guide on upgrading your SilverStripe project to SilverStripe 4.1 +[Read _Upgrading to SilverStripe 4_](/upgrading/) for a detailed step-by-step guide on upgrading your SilverStripe 3 project to SilverStripe 4. +It describes how to use an automated [upgrader tool](https://github.com/silverstripe/silverstripe-upgrader) +to make the job easier. +Please also note the [4.0.0](4.0.0) and [4.1.0](4.1.0) changelogs for a complete list of changes. ### App folder name @@ -50,7 +53,8 @@ SilverStripe\Core\Manifest\ModuleManifest: - Ensure you flush your site with `?flush=all` -Note: In 5.0 the app folder will be fixed to `app` and cannot be soft-coded via `mysite.yml` +Follow our [step-by-step upgrading guide](/upgrading) to perform this change automatically through our `upgrade-code` tool. +In 5.0 the app folder will be fixed to `app` and cannot be soft-coded via `mysite.yml` ### Disable session-based stage setting From 9b6fb70c5d3b54a576fea76a66e6909e13980715 Mon Sep 17 00:00:00 2001 From: Ingo Schommer Date: Tue, 26 Jun 2018 11:41:30 +1200 Subject: [PATCH 8/9] Removed "overview of changes" upgrading docs duplication --- docs/en/03_Upgrading/index.md | 65 ---------------------------------- docs/en/04_Changelogs/4.0.0.md | 38 ++++++++++++++++++++ 2 files changed, 38 insertions(+), 65 deletions(-) diff --git a/docs/en/03_Upgrading/index.md b/docs/en/03_Upgrading/index.md index 5deb97e1b..4b372f7b4 100644 --- a/docs/en/03_Upgrading/index.md +++ b/docs/en/03_Upgrading/index.md @@ -1151,68 +1151,3 @@ has been added to assist in migration of legacy files (see [file migration docum ### 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 have miss anything. - -## List of Major API Changes - -This is a list of the most common API changes that might affect you. - -Read the changelogs for a comprehensive list of everything that is new in SilverStripe 4: -* (SilverStripe 4.0.0 change logs)[/changelogs/4.0.0/] -* (SilverStripe 4.1.0 change logs)[/changelogs/4.1.0/] -* (SilverStripe 4.2.0 change logs)[/changelogs/4.2.0/]. - -[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 `app/_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' - ]; -``` diff --git a/docs/en/04_Changelogs/4.0.0.md b/docs/en/04_Changelogs/4.0.0.md index 754e7fa36..dc8d52a00 100644 --- a/docs/en/04_Changelogs/4.0.0.md +++ b/docs/en/04_Changelogs/4.0.0.md @@ -12,6 +12,44 @@ For users upgrading to later versions, please see the specific [4.1.0](4.1.0) an ## Overview {#overview} +### For Content Authors + +### For Developers + + + * [Object class replaced by traits](/changelogs/4.0.0#object-replace) + `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. + * [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. + * [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. + * Minimum version dependencies have increased; PHP 5.6 and Internet Explorer 11 (or other modern browser) are required. * All code earlier marked as deprecated for 4.0 has now been removed (check our From f7c001eaf8ce9f069da01df574eff48aa5e00f1b Mon Sep 17 00:00:00 2001 From: Ingo Schommer Date: Tue, 26 Jun 2018 11:42:13 +1200 Subject: [PATCH 9/9] Removed duplicate upgrade instructions They're already present in the new upgrading guide Folded upgrading "list of changes" into 4.0.0 guide They duplicate each other, and create confusion in the upgrading doc because there's *both* an "overview" of changes at the top, and "important changes" at the bottom - why are they at the bottom when they're important? Added "skip" and "continue" anchor links [ci skip] --- docs/en/03_Upgrading/index.md | 199 +++++++++++------------- docs/en/04_Changelogs/4.0.0.md | 268 +++++++++------------------------ docs/en/04_Changelogs/4.1.0.md | 2 +- docs/en/04_Changelogs/4.2.0.md | 6 +- 4 files changed, 168 insertions(+), 307 deletions(-) diff --git a/docs/en/03_Upgrading/index.md b/docs/en/03_Upgrading/index.md index 4b372f7b4..78ac5c66b 100644 --- a/docs/en/03_Upgrading/index.md +++ b/docs/en/03_Upgrading/index.md @@ -14,28 +14,31 @@ How easy will it be to update my project? It's a fair question, and sometimes a * "Major" releases introduces API change that may break your application. * "Minor" releases (x.y) introduces API changes in a backward compatible way and can mark some API as deprecated. * "Patch" releases (x.y.z) fix bugs without introducing any API changes. -* If you've made custom branches of SilverStripe core, or any thirdparty module, it's going to be harder to upgrade. -* The more custom features you have, the harder it will be to upgrade. You will have to re-test all of those features, and adapt to API changes in core. -* Customizations of a well defined type - such as custom page types or custom blog widgets - are going to be easier to upgrade than customisations that modify deep system internals like rewriting SQL queries. +* If you've made custom branches of SilverStripe core, or any thirdparty module, upgrades are going to be more complex. +* More custom features mean more work to re-test all of those features, and adapt to API changes in core. +* Customisations of a well defined type - such as custom page types or custom blog widgets - + are going to be easier to upgrade than customisations that modify deep system internals like rewriting SQL queries. ### Overview of changes -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. +There are some fundamental changes in SilverStripe 4: -* PHP 5.6 is now the minimum required version and up to PHP 7.2.x is supported. +* PHP 5.6 is now the minimum required version and up to PHP 7.2 is supported. * SilverStripe is now even more modular which allows you to remove functionality your project might not need. * Common functionality sets can now be installed via SilverStripe _recipes_. -* SilverStripe modules can now be installed in the vendor folder along with your regular PHP packages. -* The SilverStripe codebase is now completely namespaced. -* SilverStripe 4 makes usage of PHP _traits_ making it easy to apply common patterns to your classes. -* Publicly facing files can now be served from a public webroot for added security. -* The concept of `ChangeSet` has been added to versioning along with version ownership. +* SilverStripe modules can now be installed in the `vendor/` folder along with your regular PHP packages. +* All classes are namespaced: You have to use these, but can decide if you namespace your project code. +* PHP _traits_ replace a few core classes (e.g. `Object`) and make it easy to apply common patterns +* Public files can now be served from a `public/` webroot for added security. +* Versioning is more powerful through an "ownership" concept, and available for all DataObject classes. +* Changes across objects can be collected in a "campaign" for batch publication. * GraphQL is now the favourite way of creating web services with SilverStripe. -* Asset management has been completely redone with a brand new react-based UI and the introduction of versioned files. -* Parts of the CMS UI are now build in react and entwine is in the process of being faded out. -* SilverStripe 4 now supports PSR-4 auto-loading for modules and for your main project. +* Asset management has been completely redone with a brand new React-based UI, protected draft files and versioning. +* Parts of the CMS UI are now build in React and Bootstrap instead of Entwine and custom CSS. +* PSR-4 auto-loading is supported for modules and for your project code. -[Learn more about major API changes introduced by SilverStripe 4](#list-of-major-api-changes) +[Learn more about major API changes introduced by SilverStripe 4](#list-of-major-api-changes), +and dig into the changelogs for [4.0.0](/changelogs/4.0.0), [4.1.0](/changelogs/4.1.0) and [4.2.0](/changelogs/4.2.0). ### Using recipes instead of requiring individual modules The SilverStripe CMS and SilverStripe Framework are becoming more modular. Many of the secondary features contained in SilverStripe CMS 3 and SilverStripe Framework 3 have been moved to separate modules. @@ -46,23 +49,18 @@ Read the [Switching to recipes](#switching-to-recipes) section of this guide for ### Automating your upgrades using the SilverStripe 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. The upgrader is unlikely to completely upgrade your project to SilverStripe 4, however it can take care of the most tedious part of the upgrade. - -It can also be use to upgrade your existing SilverStripe 4 to a newer minor release. - -Each step in this upgrade guide explains how to use - -[Learn how to install the upgrader tool](#install-the-upgrader-tool-(optional)) +with the upgrade process. The upgrader is unlikely to completely upgrade your project, however it can take care of the most tedious part of the upgrade. +It can also be use to upgrade your existing SilverStripe 4 project to a newer minor release. ## Step 0 - Pre-requisites and background work {#step0} -Before you begin the upgrade process, make sure you meat these pre-requisites +Before you begin the upgrade process, make sure you meet these pre-requisites. ### Back up your files and database -* Set up your project in your development environment. +* Set up your codebase in your development environment. * Backup your database content. -* Backup your webroot files. +* Backup your codebase (use version control if possible).
Never update a website on the live server. Get it working on a development copy first! @@ -70,10 +68,7 @@ Never update a website on the live server. Get it working on a development copy ### Install composer -SilverStripe 4 requires the use of composer for dependency management. - -[Learn how to use composer with SilverStripe](/getting_started/composer) - +SilverStripe 4 requires the use of [Composer](http://getcomposer.org) for dependency management ([details](/getting_started/composer)). We recommend using `recipe-cms` in your `composer.json` file to help you keep up to date and run `composer update`. ```json @@ -88,15 +83,17 @@ This will also add extra dependencies, such as the `admin`, `asset-admin`, `repo modules. 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 +check out the [recipe plugin repository](https://github.com/silverstripe/recipe-plugin) +as well as the `composer.json` files in [recipe-core](https://github.com/silverstripe/recipe-core) and [recipe-cms](https://github.com/silverstripe/recipe-cms). 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) ### Install the upgrader tool (optional) -Using the upgrader is not mandatory, but it can speed up the upgrade process. To install the upgrader globally run this command. +Using the upgrader is not mandatory, but it can speed up the process. +Although SilverStripe 4 can run in both PHP 5.6 and PHP 7, the upgrader itself requires PHP 7. +To install the upgrader globally run this command. ```bash composer global require silverstripe/upgrader @@ -114,13 +111,12 @@ echo 'export PATH=$PATH:~/.composer/vendor/bin/' >> ~/.bash_profile Each command in the upgrader has somewhat different arguments. However, most of them accept these two options: * `--write` which tells the upgrader to apply changes to your code base -* `-d` which can be use to explicitly specify the root of your project — if not specified the current working directory is assume to be the root of the project. +* `--root-dir` which can be use to explicitly specify the root of your project — if not specified the current working directory is assume to be the root of the project. You can run `upgrade-code help` to get more information about the upgrader or `upgrade-code help command-name` to information about a specific command. -
-Sample upgrader commands in this guide assume your working directory is the root of your SilverStripe project. You'll need to use the `-d` flag if that's not the case. +Sample upgrader commands in this guide assume your working directory is the root of your SilverStripe project. You'll need to use the `--root-dir` flag if that's not the case.
### Running all the upgrader commands in this guide in on line @@ -128,11 +124,11 @@ Sample upgrader commands in this guide assume your working directory is the root The upgrader comes with an `all` command. This command will attempt to run all the upgrader commands in the same order as this guide. This is unlikely to work on your first try, but can be a good way to get started without going through this entire guide. ```bash -upgrade-code all --recipe-core-constraint=1.1 --namespace="App\\Web" --psr4 +upgrade-code all --namespace="App\\Web" --psr4 ``` -* `--recipe-core-constraint` defined your target version of `silverstripe/recipe-core`. -* `--namespace` allows you to specify what will be the main namespace of your project. +* `--recipe-core-constraint` defines your SilverStripe release version (optional, will default to the most recent stable release). +* `--namespace` allows you to specify how your project will be namespaced (optional). * `--psr4` allows you to specify that your project structure respect the PSR-4 standard and to use sub-namespaces. * `--skip-add-namespace` allows you to skip the `add-namespace` command. * `--skip-reorganise` allows you to skip the `reorganise` command. @@ -140,11 +136,11 @@ upgrade-code all --recipe-core-constraint=1.1 --namespace="App\\Web" --psr4 ### Branching your project -Setting a dedicated branch in your source control system to track your upgrade work can help you manage your upgrade. If you're upgrading a big project, you should consider creating individual branches for each step. +Setting a dedicated branch in your source control system to track your upgrade work can help you manage your upgrade. If you're upgrading a big project, you should consider creating individual branches or commits for each step. -## Step 1 - Upgrade your dependencies +## Step 1 - Upgrade your dependencies {#step1} -The first step is to update your dependencies' constraints in your `composer.json` file to require the latest version of the SilverStripe modules. +The first step is to update your dependencies' constraints in your `composer.json` file to require the latest version of modules. ### Automatically upgrade dependencies with the `recompose` upgrader command @@ -173,10 +169,10 @@ Take for example the following SilverStripe 3 `composer.json` file. You can upgrade the `composer.json` file with this command: ```bash -upgrade-code recompose --recipe-core-constraint=4.1 --write +upgrade-code recompose --write ``` -The `--recipe-core-constraint` flag can be use to target a specific version of `silverstripe/recipe-core`. If this flag is omitted, the project will be upgraded to the latest stable version. You can use the `--strict` option if you want to use more conservative version constraints. Omit the `--write` flag to preview your changes. +You can add a `--recipe-core-constraint` flag to target a specific version of `silverstripe/recipe-core`. By default, the project will be upgraded to the latest stable version. You can use the `--strict` option if you want to use more conservative version constraints. Omit the `--write` flag to preview your changes. Your upgraded `composer.json` file will look like this. ```json @@ -192,7 +188,9 @@ Your upgraded `composer.json` file will look like this. } ``` -If the `recompose` command can't find a SilverStripe 4 compatible version for one of your module, it will keep this dependency in your `composer.json` file with its existing constraint. +If the `recompose` command can't find a compatible version for one of your module, it will keep this dependency in your `composer.json` file with its existing constraint. + +[Continue to Step 2](#step2) ### Manually upgrading your dependencies @@ -338,9 +336,9 @@ If you're going to install development version of third party modules, you shoul
To resolve a conflict you can either: -* remove the module from your project, if it is not essential -* integrate the affected module into your project's codebase -* fork the affected module and maintain it yourself. +* 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. @@ -362,8 +360,8 @@ This is a good point to commit your changes to your source control system before ## Step 2 - Update your environment configuration {#env}{#step2} -The php configuration `_ss_environment.php` file has been replaced in favour of a non-executable -`.env` file, which 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. +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 ([details](/getting_started/environment_management/)) ### Automatically convert `_ss_environment.php` to `.env` @@ -373,9 +371,9 @@ If you have installed the upgrader tool, you can use the `environment` command t 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. +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. -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` @@ -421,9 +419,10 @@ SS_DATABASE_PASSWORD="" SS_DATABASE_SERVER="127.0.0.1" ``` -### Cleaning up `mysite/_config.php` after your environment configuration upgrade +### Cleaning up `mysite/_config.php` after your environment configuration upgrade {#env-config-cleanup} -You'll need to clean up your `mysite/_config.php` file after upgrading your environment file. +Regardless if you've used the automated or manual path, +you'll need to clean up your `mysite/_config.php` file after upgrading your environment file. The global values `$database` and `$databaseConfig` have been deprecated. Your database configuration details should be stored in your `.env` file. If you want to keep your database configuration in `_config.php`, you can use the new `DB::setConfig()` api, however this is discouraged. @@ -437,24 +436,19 @@ To access environment variables, use the `SilverStripe\Core\Environment::getEnv( ### Finalising your environment upgrade It's inadvisable to track your `.env` file in your source control system as it might contain sensitive information. -You should ignore the `.env` file by adding an entry to your `.gitignore` file. You can create a sample environment configuration by duplicating your `.env` file as `.env.sample`, and removing sensitive information from it. - -You can safely delete your legacy `_ss_environement.php` if you want. +You should ignore the `.env` file by adding an entry to your `.gitignore` file. You can create a sample environment configuration by duplicating your `.env` file as `.env.sample`, and removing sensitive information from it. You can safely delete your legacy `_ss_environement.php` if you want. This is a good point to commit your changes to your source control system before moving on to the next step. ## Step 3 - Namespacing your project (optional) {#step3} Namespacing your code is an optional step. It is recommended and will help future-proof your code base. - -To learn more about PHP namespace: -* Read the [official Namespace PHP documentation](http://php.net/manual/en/language.namespaces.php) -* Read the [PSR-4: Autoloader standard](https://www.php-fig.org/psr/psr-4/). +Read more about [PHP Namespaces](http://php.net/manual/en/language.namespaces.php) +and the [PSR-4 Autoloader Standard](https://www.php-fig.org/psr/psr-4/). ### Before you start namespacing your codebase You need to choose a root namespace for your project. We recommend following the `Vendor\Package` pattern. - The `Page` and `PageController` classes *must* be defined in the global namespace (or without a namespace). If you want your codebase to comply with the PSR-4 standard, make sure sub-directories of your code folder are using the _UpperCamelCase_ naming convention. For example, `mysite/code/page_types` should be renamed to `mysite/code/PageTypes`. @@ -464,22 +458,19 @@ If you want your codebase to comply with the PSR-4 standard, make sure sub-direc The `add-namespace` command of the [upgrader tool](https://github.com/silverstripe/silverstripe-upgrader/) provides a feature to namespace your codebase and to automatic update references to those classes. -``` -composer global require silverstripe/upgrader +```bash upgrade-code add-namespace "App\\Web" ./mysite/code --recursive --write ``` This task will do the following: * Add the given namespace to all files in the code class, and subdirectories * All references to classes in any namespaced files will be safely retained with additional `use` directives added as necessary -* A `mysite/.upgrade.yml` file be created/updated to record the new fully qualified name of each class. +* A `mysite/.upgrade.yml` file will be created/updated to record the new fully qualified name of each class. + This will be used in later steps to update references to the outdated class names in your own project code. -`.upgrade.yml` will be used in later steps to update references to the old non-namespaced classes. - -If you want to do a dry-run, omit the `--write` option to see a preview of all changed project files. - -By default, the same namespace will be applied to all your classes regardless of which directory they are in. If you want to apply different namespaces to different folders to be compliant with PSR-4, combine the `--recursive` with the `--psr4`. Your folder structure has to be PSR4 compliant for this to work. +By default, the same namespace will be applied to all your classes regardless of which directory they are in. If you want to apply different namespaces to different folders to be compliant with PSR-4, combine the `--recursive` with the `--psr4`. Your folder structure has to be PSR4 compliant for this to work. If you want to do a dry-run, omit the `--write` option to see a preview of all changed project files. +[Continue to Step 4](#step4) ### Manually namespacing your codebase @@ -529,7 +520,6 @@ class ProductService ### Enable PSR-4 auto-loading in your `composer.json` file If you have namespaced your project and followed the PSR-4 convention, you have the option to enable PSR-4 auto-loading in your composer.json file. - Enabling PSR-4 auto-loading is optional. It will provide better auto-loading of your classes in your development environment and will future proof your code. For example, let's say you have defined the following namespaces for the following folders: @@ -570,7 +560,6 @@ This is a good point to commit your changes to your source control system before ## Step 4 - Update codebase with references to newly namespaced classes {#step4} All core PHP classes in SilverStripe 4 have been namespaced. For example, `DataObject` is now called `SilverStripe\ORM\DataObject`. Your project codebase, config files and language files need be updated to reference those newly namespaced classes. This will include explicit references in your PHP code, but also string that contain the name of a class. - If you've opted to namespace your own code in the previous step, those references will need to be updated as well. ### Automatically update namespaced references with the `upgrade` command @@ -579,10 +568,7 @@ If you've installed the upgrader, you can use the `upgrade` command to update re The `upgrade` command will update PHP files, YML configuration files, and YML language files. -#### Before running the `upgrade` command -Each core SilverStripe 4 module includes a `.upgrade.yml` that defines the equivalent fully qualified name of each class. Most third party SilverStripe modules that have been upgraded to be compatible with SilverStripe 4, also include a `.upgrade.yml`. - -If you've namespaced your own project, you'll need to provide your own `.upgrade.yml` file . If you've used the upgrader to namespace your project, that file will have been created for you. +Each core SilverStripe 4 module includes a `.upgrade.yml` that defines the equivalent fully qualified name of each class. Most third party SilverStripe modules that have been upgraded to be compatible with SilverStripe 4, also include a `.upgrade.yml`. If you've namespaced your own project, you'll need to provide your own `.upgrade.yml` file . If you've used the upgrader to namespace your project, that file will have been created for you. The `upgrade` command will try to update some strings that reference the old name of some classes. In some cases this might not be what you want. You can tell the upgrader to skip specific strings by using the `@skipUpgrade` flag in your PHPDoc comment. For example: @@ -591,8 +577,6 @@ The `upgrade` command will try to update some strings that reference the old nam return Injector::inst()->get('ProductService'); ``` -#### Running the `upgrade` command - Execute the upgrade command with this command. ```bash @@ -601,13 +585,15 @@ 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 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. There's 3 options that can be provided: `code`, `config`, and `lang`. For example, the following command will only upgrade `lang` and `config` files: +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 case, 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) + ### 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. @@ -789,12 +775,12 @@ en: SALUTATION: Beep Beep ``` -### Finalising namespace updates -You'll need to perform the following steps manually, even if you've used the automated rewrite of namespaces previously. +### 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';`. +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. @@ -832,11 +818,9 @@ Avoid using `static::class` or `parent::class` to retrieve translated string. It 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} @@ -883,9 +867,9 @@ Changes not saved; Run with --write to commit to disk ### Manually update deprecated API references -SilverStripe 4 introduces many of small and big API changes. To update deprecated API references manually, you have to go through each one of your project files. - -[Read the SilverStripe 4 change logs](/changelogs/4.0.0/) for a comprehensive list of what has changed. +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/), [4.1.0](/changelogs/4.1.0/) and [4.2.0](/changelogs/4.2.0/) +for a comprehensive overview. ### Finalising the deprecated API update At this stage, your site should be using only SilverStripe 4 API logic. @@ -899,18 +883,18 @@ The location of SilverStripe's _entry file_ has changed. Your project and server 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 are upgrading to SilverStripe 4.1 or above -* `vendor/silverstripe/recipe-core/index.php` if you are upgrading to SilverStripe 4.0 +You can get a copy of the SilverStripe 4 `index.php` file at +`vendor/silverstripe/recipe-core/public/index.php`. -If you've modified your SilverStripe 3 `index.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. +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` if you are upgrading to SilverStripe 4.1 or above -* `vendor/silverstripe/recipe-core/` if you are upgrading to SilverStripe 4.0 +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`. @@ -923,9 +907,10 @@ 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. Adopting the recommended project structure is optional, but will become mandatory in SilverStripe 5. +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. -You may skip this step if you want. +[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. @@ -987,17 +972,20 @@ SilverStripe\Core\Manifest\ModuleManifest: ``` At this stage, your project should be functional with the recommended project structure. - Note, that if you've explicitly reference 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. This has security benefits as it minimises the possibility that files that are not meant to be access directly get accidentally exposed. +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. @@ -1026,22 +1014,19 @@ If you are upgrading from SilverStripe 4.0 to SilverStripe 4.1 (or above), you'l ### 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` 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 enable innovations like moving SilverStripe module vendor folder or the public web root. +SilverStripe 4 introduces a new way to reference static assets like images and css. +This enable innovations like moving 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 - Update project structure -* Step 8 - Switch to public web-root - -Otherwise, it is strongly recommended, but not mandatory. +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`. @@ -1131,13 +1116,13 @@ This is a good point to commit your changes to your source control system before You're almost across the finish line. ### Run a dev build -Rnn a `dev/build` either on the command line or in your browser. +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 to the new SilverStripe 4 structure. +This should migrate your existing data (non-destructively) to the new SilverStripe 4 structure. #### Migrating files diff --git a/docs/en/04_Changelogs/4.0.0.md b/docs/en/04_Changelogs/4.0.0.md index dc8d52a00..a9e003e98 100644 --- a/docs/en/04_Changelogs/4.0.0.md +++ b/docs/en/04_Changelogs/4.0.0.md @@ -5,177 +5,105 @@ This version introduces many breaking changes, which in most projects can be managed through a combination of automatic upgrade processes as well as manual code review. This changelogs described all API changes in detail. -[Read _Upgrading to SilverStripe 4_](/upgrading/) for a detailed step-by-step guide on upgrading your SilverStripe 3 project to SilverStripe 4. +Read [Upgrading to SilverStripe 4](/upgrading/) for a detailed step-by-step guide on upgrading your SilverStripe 3 project to SilverStripe 4. It describes how to use an automated [upgrader tool](https://github.com/silverstripe/silverstripe-upgrader) to make the job easier. For users upgrading to later versions, please see the specific [4.1.0](4.1.0) and [4.2.0](4.2.0) changelogs. ## Overview {#overview} -### For Content Authors +### General -### For Developers +* Minimum version dependencies have increased; PHP 5.6 and Internet Explorer 11 (or other modern browser) + are required. +* All code has been migrated to follow the PSR-2 coding standard. Most significantly, all SilverStripe + classes are now namespaced, and some have been renamed. This has major implications for + arrangement of templates, as well as other references to classes via string literals or configuration. +* All code earlier marked as deprecated for 4.0 has now been removed (check our + [deprecation process](/contributing/release_process)) +* 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)) +* **4.1.0 only** Support for public webroot folder `public/` ([details](4.1.0#public-folder)) +### ORM - * [Object class replaced by traits](/changelogs/4.0.0#object-replace) +* [Better core support for Versioning](#changeset): Addition of campaigns to allow batches of related + or inter-dependent objects to be published as a single "changeset". +* [Record ownership and Campaigns](#ownership): Dependencies between versioned objects can be + declared using the new ownership API, so that developers can ensure that relational consistency is + maintained during publishing + This new system can be managed via the new "Campaigns" CMS section ([blog post](https://www.silverstripe.org/blog/campaigns-in-silverstripe-4/)) +* [Rewrite literal table names](#literal-table-names): + Use `$table = SilverStripe\ORM\DataObject::getSchema()->tableForField($model, $field)` instead of `$model` directly. + +### Assets + +* Asset storage has been abstracted, and a new concept of `DBFile` references via database column references + now exists in addition to references via the existing `File` dataobject. File security and protected files + are now a core feature ([details](#asset-storage)) +* Asset admin has been replaced with a purely ReactJS powered upgrade, and split out + module called [asset-admin](https://github.com/silverstripe/silverstripe-asset-admin/). + +### Framework + +* [Object class replaced by traits](#object-replace): `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) +* [Rewrite literal class names](#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) +* [Config settings should be set to `private static`](#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) +* [Module paths can't be hardcoded](#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. - * [Adapt tooling to modules in vendor folder](#vendor-folder) +* [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) +* [SS_Log replaced with PSR-3 logging](#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. - * [Upgrade `mysite/_config.php`](/changelogs/4.0.0#config-php) +* [Upgrade `mysite/_config.php`](#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 removes static methods](#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) +* [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. +* [Removed module path constants](#module-paths) (e.g. `FRAMEWORK_PATH`) and support for hardcoded file paths (e.g. `mysite/css/styles.css`) +* [Replaced Zend_Translate](#i18n) with symfony/translation +* [Replaced `Zend_Cache`](#cache) and the `Cache` API with a PSR-16 implementation (symfony/cache) +* [`_ss_environment.php` files](/upgrading/#env) have been removed in favour of `.env` and "real" environment variables +* [Behat support updated to v3](https://github.com/silverstripe/silverstripe-behat-extension) +* Dependencies can managed via [recipe-plugin](https://github.com/silverstripe/recipe-plugin). See [recipe-core](https://github.com/silverstripe/recipe-core) and [recipe-cms](https://github.com/silverstripe/recipe-cms) as examples. +* [Authentication](#custom-authenticators) has been upgraded to a modular approach using re-usable interfaces and easier to hook in to LoginHandlers +* Renamed constant for temp folder from `TEMP_FOLDER` to `TEMP_PATH` for naming consistency with other path variables and constants + + +### View + +* [Template locations and references](#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. +* 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. +* [Explicit text casting on template variables](#template-casting) + Calling `$MyField` on a DataObject in templates will by default cast MyField as `Text` which means it will be safely encoded. +* Template variable casting (e.g. `

$Title

`) is enforced by default, which will ensure safe HTML encode + unless explicitly opted out ([details](#template-casting)) +* Themes are now configured to cascade, where you can specify a list of themes, and have the template engine + search programatically through a prioritised list when resolving template and CSS file paths. +* The `GDBackend` and `ImagickBackend` classes have been replaced by a unified `InterventionBackend` which uses the + [intervention/image](https://github.com/intervention/image) library to power manipualations. + +### CMS -* Minimum version dependencies have increased; PHP 5.6 and Internet Explorer 11 (or other modern browser) - are required. -* All code earlier marked as deprecated for 4.0 has now been removed (check our - [deprecation process](/contributing/release_process)) -* **4.1.0 only** Support for public webroot folder `public/` ([details](4.1.0#public-folder)) -* All code has been migrated to follow the PSR-2 coding standard. Most significantly, all SilverStripe - classes are now namespaced, and some have been renamed. This has major implications for - arrangement of templates, as well as other references to classes via string literals or configuration. - Automatic upgrading tools have been developed to cope with the bulk of these changes (see - [upgrading notes](#upgrading)). -* Object class has been replaced with traits ([details](#object-replace)). -* Asset storage has been abstracted, and a new concept of `DBFile` references via database column references - now exists in addition to references via the existing `File` dataobject. File security and protected files - are now a core feature ([details](#asset-storage)) * A new front-end development process has been developed for the construction of javascript based components, prominently featuring ReactJS to develop highly functional CMS content areas. A new standard form schema API has been developed to allow back-end PHP constructed forms to scaffold themselves within ReactJS powered sections. * CMS CSS has been re-developed using Bootstrap v4 as a base ([blog post](https://www.silverstripe.org/blog/a-frameworks-framework-why-silverstripe-4-will-use-bootstrap/)) -* Asset admin has been replaced with a purely ReactJS powered upgrade, and split out - module called [asset-admin](https://github.com/silverstripe/silverstripe-asset-admin/). -* Versioning is now a much more powerful feature, with the addition of campaigns to allow batches of related - or inter-dependent objects to be published as a single "changeset" ([details](#changeset)). -* Dependencies between versioned objects can be - declared using the new ownership API, so that developers can ensure that relational consistency is - maintained during publishing ([details](#ownership)) - This new system can be managed via the new "Campaigns" CMS section ([blog post](https://www.silverstripe.org/blog/campaigns-in-silverstripe-4/)) -* Template variable casting (e.g. `

$Title

`) is enforced by default, which will ensure safe HTML encode - unless explicitly opted out ([details](#template-casting)) -* Themes are now configured to cascade, where you can specify a list of themes, and have the template engine - search programatically through a prioritised list when resolving template and CSS file paths. -* Removed module path constants (e.g. `FRAMEWORK_PATH`) and support for hardcoded file paths (e.g. `mysite/css/styles.css`) ([details](#module-paths)) -* Replaced Zend_Translate with symfony/translation ([details](#i18n)) -* Replaced `Zend_Cache` and the `Cache` API with a PSR-16 implementation (symfony/cache) ([details](#cache)) -* `_ss_environment.php` files have been removed in favour of `.env` and "real" environment variables ([details](/upgrading/#env)). -* Behat support updated to v3 ( - [details](https://github.com/silverstripe/silverstripe-behat-extension)) -* The `GDBackend` and `ImagickBackend` classes have been replaced by a unified `InterventionBackend` which uses the - [intervention/image](https://github.com/intervention/image) library to power manipualations. -* Dependencies can managed via [recipe-plugin](https://github.com/silverstripe/recipe-plugin). See [recipe-core](https://github.com/silverstripe/recipe-core) and [recipe-cms](https://github.com/silverstripe/recipe-cms) as examples. -* Authentication has been upgraded to a modular approach using re-usable interfaces and easier to hook in to LoginHandlers ([details](#custom-authenticators)). -* 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 - -## Upgrading Guide {#upgrading} - -The below sections describe how to go about updating an existing site to be prepared for upgrade to 4.0. -Most of these upgrading tasks will involve manual code review, although in some cases there are -some automated processes that users can run. - -### Composer dependency update {#deps} - -As a first step, you need to update your composer dependencies. -The easiest way is to start with a new `composer.json` file -and gradually move over settings from your old one. -This way you don't get dependency conflicts with potentially incompatible modules. - -Backup your existing `composer.json` and overwrite it with the following content: - -```json -{ - "name": "myvendor/myproject", - "require": { - "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, -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 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 -below commands: - -```bash -rm -rf vendor/composer -rm composer.lock -composer update -``` - -For modules with stable releases, simply set your composer constraints to the new version -(with a [next significant release](https://getcomposer.org/doc/articles/versions.md#next-significant-release-operators) operator). - -```diff -{ - "require": { -- "myvendor/compatible-module": "~2.0", -+ "myvendor/compatible-module": "~3.0", - } -} -``` - -For modules with a compatible pre-release, use an explicit [stability constraints](https://getcomposer.org/doc/articles/versions.md#stability-constraints). -This can be changed to a [next significant release](https://getcomposer.org/doc/articles/versions.md#next-significant-release-operators) operator -once the module is stable. - -```diff -{ - "require": { -- "myvendor/prerelease-module": "~2.0", -+ "myvendor/prerelease-module": "~3.0@dev", - } -} -``` - -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. - - -### 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. +## Detailed Changes ### `index.php` and `.htaccess` rewrites {#index-php-rewrites} @@ -189,57 +117,6 @@ 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. - -### Migrate File DataObject {#migrate-file} - -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 -``` - -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: - delete_invalid_files: false -``` - -### 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. -You can use our heuristics 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 should be run *after* `upgrade-code upgrade`. - -``` -~/.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. - ### Object class replaced by traits {#object-replace} Object has been superseded by traits. @@ -248,7 +125,7 @@ Object has been superseded by traits. - `Configurable`: Provides `MyClass::config()` - `Extensible`: Provides all methods related to extensions (E.g. add_extension()). -Upgrade subclass use +Upgrade subclass use: ```diff @@ -267,7 +144,7 @@ Upgrade subclass use ``` -Upgrade references to $this->class +Upgrade references to `$this->class`: ```diff -$obj->class @@ -277,14 +154,14 @@ Upgrade references to $this->class +static::class; ``` -Upgrade parse_class_spec() +Upgrade `parse_class_spec()`: ```diff -$spec = Object::parse_class_spec($spec); +$spec = ClassInfo::parse_class_spec($spec); ``` -Upgrade create_from_string() +Upgrade `create_from_string()`: ```diff @@ -564,7 +441,7 @@ SilverStripe\Core\Injector\Injector: `WebDesignGroup\ShopSite\Logging\ErrorPageFormatter` should be a class that implements the `Monolog\Formatter\FormatterInterface` interface. -### Upgrade `mysite/_config.php` {#config-php} +### Replace $project with YAML config {#config-php} The global `$project` is deprecated in favour of the configuration setting `SilverStripe\Core\Manifest\ModuleManifest.project`. @@ -598,7 +475,6 @@ public function httpSubmission($data, $form, $request) } ``` - In some places it may still be necessary to access the session object where no request is available. 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. diff --git a/docs/en/04_Changelogs/4.1.0.md b/docs/en/04_Changelogs/4.1.0.md index 4ed2029f5..9a0e79a99 100644 --- a/docs/en/04_Changelogs/4.1.0.md +++ b/docs/en/04_Changelogs/4.1.0.md @@ -7,7 +7,7 @@ ## Upgrading -[Read _Upgrading to SilverStripe 4_](/upgrading/) for a detailed step-by-step guide on upgrading your SilverStripe 3 project to SilverStripe 4. +Read [Upgrading to SilverStripe 4](/upgrading/) for a detailed step-by-step guide on upgrading your SilverStripe 3 project to SilverStripe 4. It describes how to use an automated [upgrader tool](https://github.com/silverstripe/silverstripe-upgrader) to make the job easier. Please also note the [4.0.0](4.0.0) and [4.2.0](4.2.0) changelogs for a complete list of changes. diff --git a/docs/en/04_Changelogs/4.2.0.md b/docs/en/04_Changelogs/4.2.0.md index f87222f60..643ae17c3 100644 --- a/docs/en/04_Changelogs/4.2.0.md +++ b/docs/en/04_Changelogs/4.2.0.md @@ -7,15 +7,15 @@ ## Upgrading {#upgrading} -[Read _Upgrading to SilverStripe 4_](/upgrading/) for a detailed step-by-step guide on upgrading your SilverStripe 3 project to SilverStripe 4. +Read [Upgrading to SilverStripe 4](/upgrading/) for a detailed step-by-step guide on upgrading your SilverStripe 3 project to SilverStripe 4. It describes how to use an automated [upgrader tool](https://github.com/silverstripe/silverstripe-upgrader) to make the job easier. Please also note the [4.0.0](4.0.0) and [4.1.0](4.1.0) changelogs for a complete list of changes. ### App folder name -The standard 'mysite' code naming convention has changed in 4.2. Although existing sites can continue -to use 'app/code` to store their base project code, the recommendation and new default is to +The standard 'mysite' code naming convention has changed. Although existing sites can continue +to use 'mysite/code` to store their base project code, the recommendation and new default is to store code in `app/src`. Additionally, we reinforce the recommendation to use psr-4 autoloading in your project to speed up