mirror of
https://github.com/silverstripe/silverstripe-framework
synced 2024-10-22 14:05:37 +02:00
Merge pull request #6559 from robbieaverill/feature/4.0-upgrade-guide
DOCS Add 4.0 upgrade guide, update "composer" and "modules" to include 4.x recommended practices
This commit is contained in:
Daniel Hensby
GitHub
commit
90072e27e3
@ -1,6 +1,6 @@
|
||||
# Installing and Upgrading with Composer
|
||||
|
||||
Composer is a package management tool for PHP that lets you install and upgrade SilverStripe and its modules. Although installing Composer is one extra step, it will give you much more flexibility than just downloading the file from silverstripe.org. This is our recommended way of downloading SilverStripe and managing your code.
|
||||
Composer is a package management tool for PHP that lets you install and upgrade SilverStripe and its modules. Although installing Composer is one extra step, it will give you much more flexibility than just downloading the file from silverstripe.org. This is our recommended way of downloading SilverStripe and managing your code.
|
||||
|
||||
For more information about Composer, visit [its website](http://getcomposer.org/).
|
||||
We also have separate instructions for [installing modules with Composer](/developer_guides/extending/modules).
|
||||
@ -15,38 +15,46 @@ Next, [install composer](https://getcomposer.org/download/). For our documentati
|
||||
|
||||
You can then run Composer commands by calling `composer`. For example:
|
||||
|
||||
composer help
|
||||
```
|
||||
composer help
|
||||
```
|
||||
|
||||
<div class="hint" markdown="1">
|
||||
It is also possible to keep `composer.phar` out of your path, for example, to put it in your project root. Every command would then start with `php composer.phar` instead of `composer`. This is handy if need to keep your installation isolated from the rest of your computer's set-up, but we recommend putting composer into the path for most people.
|
||||
</div>
|
||||
</div>
|
||||
|
||||
#### Updating composer
|
||||
|
||||
If you already have composer installed you can update it by running:
|
||||
|
||||
sudo composer self-update
|
||||
|
||||
```
|
||||
sudo composer self-update
|
||||
```
|
||||
|
||||
Composer updates regularly, so you should run this command fairly often. These instructions assume you are running the latest version.
|
||||
|
||||
## Installing Composer on Windows WAMP
|
||||
For those that use WAMP as a development environment, [detailed information is available on installing using Composer.](/getting_started/installation/windows)
|
||||
For those that use WAMP as a development environment, [detailed information is available on installing using Composer.](/getting_started/installation/windows)
|
||||
|
||||
## Create a new site
|
||||
|
||||
Composer can create a new site for you, using the installer as a template (by default composer will download the latest stable version):
|
||||
|
||||
composer create-project silverstripe/installer ./my/website/folder
|
||||
```
|
||||
composer create-project silverstripe/installer ./my/website/folder
|
||||
```
|
||||
|
||||
`./my/website/folder` should be the root directory where your site will live.
|
||||
For example, on OS X, you might use a subdirectory of `~/Sites`.
|
||||
As long as your web server is up and running, this will get all the code that you need.
|
||||
As long as your web server is up and running, this will get all the code that you need.
|
||||
Now visit the site in your web browser, and the installation process will be completed.
|
||||
|
||||
You can also specify a version to download that version explicitly, i.e. this will download the older `3.0.3` release:
|
||||
You can also specify a version to download that version explicitly, i.e. this will download the older `3.5.0` release:
|
||||
|
||||
```
|
||||
composer create-project silverstripe/installer ./my/website/folder 3.5.0
|
||||
```
|
||||
|
||||
composer create-project silverstripe/installer ./my/website/folder 3.0.3
|
||||
|
||||
When `create-project` is used with a release version like above,
|
||||
it will try to get the code from archives instead of creating
|
||||
git repositories. If you're planning to contribute to SilverStripe,
|
||||
@ -54,53 +62,64 @@ see [Using development versions](#using-development-versions).
|
||||
|
||||
## Adding modules to your project
|
||||
|
||||
Composer isn't only used to download SilverStripe CMS, it can also be used to manage all SilverStripe modules. Installing a module can be done with the following command:
|
||||
Composer isn't only used to download SilverStripe CMS, it is also used to manage all SilverStripe modules. Installing a module can be done with the following command:
|
||||
|
||||
composer require "silverstripe/forum:*"
|
||||
```
|
||||
composer require silverstripe/forum
|
||||
```
|
||||
|
||||
This will install the forum module in the latest compatible version. If you know the specific version you want to install already (such as `^0.8`), you can add it after the package name. For more information, read the [Composer documentation](http://getcomposer.org/doc/01-basic-usage.md#the-require-key):
|
||||
|
||||
```
|
||||
composer require silverstripe/forum ^0.8
|
||||
```
|
||||
|
||||
This will install the forum module in the latest compatible version.
|
||||
By default, Composer updates other existing modules (like `framework` and `cms`),
|
||||
and installs "dev" dependencies like PHPUnit. In case you don't need those dependencies,
|
||||
use the following command instead:
|
||||
|
||||
composer require --no-update "silverstripe/forum:*"
|
||||
composer update --no-dev
|
||||
```
|
||||
composer require --no-update silverstripe/forum
|
||||
composer update --no-dev
|
||||
```
|
||||
|
||||
The `require` command has two parts. First is `silverstripe/forum`. This is the name of the package.
|
||||
The `require` command has two parts. First is `silverstripe/forum`. This is the name of the package.
|
||||
You can find other packages with the following command:
|
||||
|
||||
composer search silverstripe
|
||||
```
|
||||
composer search silverstripe
|
||||
```
|
||||
|
||||
This will return a list of package names of the forum `vendor/package`. If you prefer, you can search for packages on [packagist.org](https://packagist.org/search/?q=silverstripe).
|
||||
|
||||
The second part after the colon, `*`, is a version string. `*` is a good default: it will give you the latest version that works with the other modules you have installed. Alternatively, you can specificy a specific version, or a constraint such as `>=3.0`. For more information, read the [Composer documentation](http://getcomposer.org/doc/01-basic-usage.md#the-require-key).
|
||||
|
||||
<div class="warning" markdown="1">
|
||||
`master` is not a legal version string - it's a branch name. These are different things. The version string that would get you the branch is `dev-master`. The version string that would get you a numeric branch is a little different. The version string for the `3.0` branch is `3.0.x-dev`.
|
||||
**Version constraints:** `master` is not a legal version string - it's a branch name. These are different things. The version string that would get you the branch is `dev-master`. The version string that would get you a numeric branch is a little different. The version string for the `4` branch is `4.x-dev`.
|
||||
</div>
|
||||
|
||||
## Updating dependencies
|
||||
|
||||
Except for the control code of the Voyager space probe, every piece of code in the universe gets updated from time to time. SilverStripe modules are no exception.
|
||||
Except for the control code of the Voyager space probe, every piece of code in the universe gets updated from time to time. SilverStripe modules are no exception.
|
||||
|
||||
To get the latest updates of the modules in your project, run this command:
|
||||
|
||||
composer update --no-dev
|
||||
```
|
||||
composer update --no-dev
|
||||
```
|
||||
|
||||
Updates to the required modules will be installed, and the `composer.lock` file will get updated with the specific commits of each of those.
|
||||
Updates to the required modules will be installed, and the `composer.lock` file will get updated with the specific commits and version constraints for each of them.
|
||||
|
||||
## Deploying projects with Composer
|
||||
|
||||
When deploying projects with composer, you could just push the code and run `composer update`. However, this is risky. In particular, if you were referencing development dependencies and a change was made between your testing and your depoyment to production, you would end up deploying untested code. Not cool!
|
||||
When deploying projects with composer, you could just push the code and run `composer update`. This, however, is risky. In particular, if you were referencing development dependencies and a change was made between your testing and your deployment to production, you would end up deploying untested code. Not cool!
|
||||
|
||||
The `composer.lock` file helps with this. It references the specific commits that have been checked out, rather than the version string. You can run `composer install` to install dependencies from this rather than `composer.json`.
|
||||
The `composer.lock` file helps with this. It references the specific commits that have been checked out, rather than the version string. You can run `composer install` to install dependencies from this rather than `composer.json`.
|
||||
|
||||
So, your deployment process, as it relates to Composer, should be as follows:
|
||||
So your deployment process, as it relates to Composer, should be as follows:
|
||||
|
||||
* Run `composer update` on your development version before you start whatever testing you have planned. Perform all the necessary testing.
|
||||
* Run `composer update` on your development version before you start whatever testing you have planned. Perform all the necessary testing.
|
||||
* Check `composer.lock` into your repository.
|
||||
* Deploy your project code base, using the deployment tool of your choice.
|
||||
* Run `composer install --no-dev -o` on your production version.
|
||||
* Run `composer install --no-dev -o` on your production version. In this command, the `--no-dev` command tells Composer not to install your development-only dependencies, and `-o` is an alias for `--optimise-autoloader`, which will convert your PSR-0 and PSR-4 autoloader definitions into a classmap to improve the speed of the autoloader.
|
||||
|
||||
## Composer managed modules, Git and .gitignore
|
||||
|
||||
@ -110,18 +129,20 @@ Since SilverStripe modules are installed into their own folder, you have to mana
|
||||
|
||||
Here is the default SilverStripe [.gitignore](http://git-scm.com/docs/gitignore) with the forum module ignored
|
||||
|
||||
assets/*
|
||||
_ss_environment.php
|
||||
tools/phing-metadata
|
||||
silverstripe-cache
|
||||
.buildpath
|
||||
.project
|
||||
.settings
|
||||
.idea
|
||||
.DS_Store
|
||||
vendor/
|
||||
# Don't include the forum module, as this will be installed with composer
|
||||
forum
|
||||
```
|
||||
assets/*
|
||||
_ss_environment.php
|
||||
tools/phing-metadata
|
||||
silverstripe-cache
|
||||
.buildpath
|
||||
.project
|
||||
.settings
|
||||
.idea
|
||||
.DS_Store
|
||||
vendor/
|
||||
# Don't include the forum module, as this will be installed with composer
|
||||
forum
|
||||
```
|
||||
|
||||
In large projects it can get difficult to manage your [.gitignore](http://git-scm.com/docs/gitignore) and ensure it contains all composer managed modules and themes.
|
||||
|
||||
@ -132,13 +153,17 @@ This package will maintain your [.gitignore](http://git-scm.com/docs/gitignore)
|
||||
|
||||
Include the package in your project by running this command
|
||||
|
||||
composer require gdmedia/ss-auto-git-ignore --dev
|
||||
```
|
||||
composer require gdmedia/ss-auto-git-ignore --dev
|
||||
```
|
||||
|
||||
Edit your composer.json and insert
|
||||
Edit your `composer.json` and insert:
|
||||
|
||||
"scripts": {
|
||||
"post-update-cmd": "GDM\\SSAutoGitIgnore\\UpdateScript::Go"
|
||||
}
|
||||
```json
|
||||
"scripts": {
|
||||
"post-update-cmd": "GDM\\SSAutoGitIgnore\\UpdateScript::Go"
|
||||
}
|
||||
```
|
||||
|
||||
This will instruct composer to run SSAutoGitIgnore after every update. SSAutoGitIgnore will then ensure composer managed models and themes are correctly added to your [.gitignore](http://git-scm.com/docs/gitignore).
|
||||
For more information about SSAutoGitIgnore, see the [SSAutoGitIgnore home page](https://github.com/guru-digital/SSAutoGitIgnore/).
|
||||
@ -146,25 +171,27 @@ For more information about post-updated-cmd and scripts, read the ["Scripts" cha
|
||||
|
||||
Full example of composer.json with the SSAutoGitIgnore installed and enabled
|
||||
|
||||
{
|
||||
"name": "silverstripe/installer",
|
||||
"description": "The SilverStripe Framework Installer",
|
||||
"require": {
|
||||
"php": ">=5.3.2",
|
||||
"silverstripe/cms": "3.0.*",
|
||||
"silverstripe/framework": "3.0.*",
|
||||
"silverstripe-themes/simple": "*"
|
||||
},
|
||||
"require-dev": {
|
||||
"silverstripe/compass": "*",
|
||||
"silverstripe/docsviewer": "*",
|
||||
"gdmedia/ss-auto-git-ignore": "*"
|
||||
},
|
||||
"scripts": {
|
||||
"post-update-cmd": "GDM\\SSAutoGitIgnore\\UpdateScript::Go"
|
||||
},
|
||||
"minimum-stability": "dev"
|
||||
}
|
||||
```json
|
||||
{
|
||||
"name": "silverstripe/installer",
|
||||
"description": "The SilverStripe Framework Installer",
|
||||
"require": {
|
||||
"php": ">=5.5.0",
|
||||
"silverstripe/cms": "^4.0",
|
||||
"silverstripe/framework": "^4.0",
|
||||
"silverstripe-themes/simple": "~3.2.0"
|
||||
},
|
||||
"require-dev": {
|
||||
"silverstripe/docsviewer": "^3.0",
|
||||
"gdmedia/ss-auto-git-ignore": "^1.0"
|
||||
},
|
||||
"scripts": {
|
||||
"post-update-cmd": "GDM\\SSAutoGitIgnore\\UpdateScript::Go"
|
||||
},
|
||||
"minimum-stability": "dev",
|
||||
"prefer-stable": true
|
||||
}
|
||||
```
|
||||
|
||||
# Dev Environments for Contributing Code {#contributing}
|
||||
|
||||
@ -177,15 +204,16 @@ You have to tell composer three things in order to be able to do this:
|
||||
|
||||
The first two steps are done as part of the initial create project using additional arguments.
|
||||
|
||||
```
|
||||
composer create-project --keep-vcs --dev silverstripe/installer ./my/website/folder 4.0.x-dev
|
||||
```
|
||||
|
||||
composer create-project --keep-vcs --dev silverstripe/installer ./my/website/folder 3.0.x-dev
|
||||
|
||||
The process will take a bit longer, since all modules are checked out as full git repositories which you can work on. The command checks out from the 3.0 release line. To check out from master instead,
|
||||
replace `3.0.x-dev` with `dev-master` (more info on [composer version naming](http://getcomposer.org/doc/02-libraries.md#specifying-the-version)).
|
||||
The process will take a bit longer, since all modules are checked out as full git repositories which you can work on. The command checks out from the 4.0 release line. To check out from master instead,
|
||||
replace `4.0.x-dev` with `dev-master` (more info on [composer version naming](http://getcomposer.org/doc/02-libraries.md#specifying-the-version)).
|
||||
|
||||
The `--keep-vcs` flag will make sure you have access to the git history of the installer and the requirements
|
||||
|
||||
The `--dev` flag is optional, and can be used to add a couple modules which are useful for
|
||||
The `--dev` flag is optional, and can be used to add a couple modules which are useful for
|
||||
SilverStripe development:
|
||||
|
||||
* The `behat-extension` module allows running [Behat](http://behat.org) integration tests
|
||||
@ -204,29 +232,33 @@ create forks and send pull requests.
|
||||
|
||||
## Manually editing composer.json
|
||||
|
||||
To remove dependencies, or if you prefer seeing all your dependencies in a text file, you can edit the `composer.json` file. It will appear in your project root, and by default, it will look something like this:
|
||||
To remove dependencies, or if you prefer seeing all your dependencies in a text file, you can edit the `composer.json` file. It will appear in your project root, and by default, it will look something like this:
|
||||
|
||||
{
|
||||
"name": "silverstripe/installer",
|
||||
"description": "The SilverStripe Framework Installer",
|
||||
"require": {
|
||||
"php": ">=5.3.2",
|
||||
"silverstripe/cms": "3.0.*",
|
||||
"silverstripe/framework": "3.0.*",
|
||||
"silverstripe-themes/simple": "*"
|
||||
},
|
||||
"require-dev": {
|
||||
"silverstripe/compass": "*",
|
||||
"silverstripe/docsviewer": "*"
|
||||
},
|
||||
"minimum-stability": "dev"
|
||||
}
|
||||
|
||||
To add modules, you should add more entries into the `"require"` section. For example, we might add the blog and forum modules. Be careful with the commas at the end of the lines!
|
||||
```json
|
||||
{
|
||||
"name": "silverstripe/installer",
|
||||
"description": "The SilverStripe Framework Installer",
|
||||
"require": {
|
||||
"php": ">=5.5.0",
|
||||
"silverstripe/cms": "^4.0",
|
||||
"silverstripe/framework": "^4.0",
|
||||
"silverstripe-themes/simple": "~3.2.0"
|
||||
},
|
||||
"require-dev": {
|
||||
"silverstripe/docsviewer": "^3.0"
|
||||
},
|
||||
"minimum-stability": "dev",
|
||||
"prefer-stable": true
|
||||
}
|
||||
```
|
||||
|
||||
To add modules, you should add more entries into the `"require"` section. For example, we might add the blog and forum modules. Be careful with the commas at the end of the lines!
|
||||
|
||||
Save your file, and then run the following command to refresh the installed packages:
|
||||
|
||||
composer update
|
||||
```
|
||||
composer update
|
||||
```
|
||||
|
||||
## Using development versions
|
||||
|
||||
@ -239,16 +271,20 @@ is this required if you want to contribute back to the SilverStripe project, it
|
||||
This is a two step process. First you get composer to start a project based on
|
||||
the latest unstable silverstripe/installer
|
||||
|
||||
composer create-project silverstripe/installer ./my/website/folder master-dev
|
||||
```
|
||||
composer create-project silverstripe/installer ./my/website/folder dev-master
|
||||
```
|
||||
|
||||
Or for the latest development version in the 3.0.x series
|
||||
|
||||
composer create-project silverstripe/installer ./my/website/folder 3.0.x-dev
|
||||
```
|
||||
composer create-project silverstripe/installer ./my/website/folder 4.0.x-dev
|
||||
```
|
||||
|
||||
## Working with project forks and unreleased modules
|
||||
|
||||
By default, Composer will install modules listed on the packagist site. There a few reasons that you might not
|
||||
want to do this. For example:
|
||||
By default, Composer will install modules listed on the Packagist site. There are a few reasons that you might not
|
||||
want to do this. For example:
|
||||
|
||||
* You may have your own fork of a module, either specific to a project, or because you are working on a pull request
|
||||
* You may have a module that hasn't been released to the public.
|
||||
@ -257,58 +293,63 @@ There are many ways that you can address this, but this is one that we recommend
|
||||
|
||||
This is how you do it:
|
||||
|
||||
* **Ensure that all of your fork repositories have correct composer.json files.** Set up the project forks as you would a distributed package. If you have cloned a repository that already has a composer.json file, then there's nothing you need to do, but if not, you will need to create one yourself.
|
||||
* **Ensure that all of your fork repositories have correct composer.json files.** Set up the project forks as you would a distributed package. If you have cloned a repository that already has a composer.json file, then there's nothing you need to do, but if not, you will need to create one yourself.
|
||||
|
||||
* **List all your fork repositories in your project's composer.json files.** You do this in a `repositories` section. Set the `type` to `vcs`, and `url` to the URL of the repository. The result will look something like this:
|
||||
* **List all your fork repositories in your project's composer.json files.** You do this in a `repositories` section. Set the `type` to `vcs`, and `url` to the URL of the repository. The result will look something like this:
|
||||
|
||||
{
|
||||
"name": "silverstripe/installer",
|
||||
"description": "The SilverStripe Framework Installer",
|
||||
```json
|
||||
{
|
||||
"name": "silverstripe/installer",
|
||||
"description": "The SilverStripe Framework Installer",
|
||||
|
||||
"repositories": [
|
||||
{
|
||||
"type": "vcs",
|
||||
"url": "git@github.com:sminnee/silverstripe-cms.git"
|
||||
}
|
||||
],
|
||||
...
|
||||
}
|
||||
"repositories": [
|
||||
{
|
||||
"type": "vcs",
|
||||
"url": "git@github.com:sminnee/silverstripe-cms.git"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
* **Install the module as you would normally.** Use the regular composer function - there are no special flags to use a fork. Your fork will be used in place of the package version.
|
||||
|
||||
composer require silverstripe/cms
|
||||
```
|
||||
composer require silverstripe/cms
|
||||
```
|
||||
|
||||
Composer will scan all of the repositories you list, collect meta-data about the packages within them, and use them in favour of the packages listed on packagist. To switch back to using the mainline version of the package, just remove the `repositories` section from `composer.json` and run `composer update`.
|
||||
|
||||
Now add an "upstream" remote to the original repository location so you can rebase or merge your fork as required.
|
||||
|
||||
cd cms
|
||||
git remote add -f upstream git://github.com/silverstripe/silverstripe-cms.git
|
||||
```
|
||||
cd cms
|
||||
git remote add -f upstream git://github.com/silverstripe/silverstripe-cms.git
|
||||
```
|
||||
|
||||
For more information, read the ["Repositories" chapter of the Composer documentation](http://getcomposer.org/doc/05-repositories.md).
|
||||
|
||||
### Forks and branch names
|
||||
|
||||
Generally, you should keep using the same pattern of branch names as the main repositories does. If your version is a fork of 3.0, then call the branch `3.0`, not `3.0-myproj` or `myproj`. Otherwise, the dependency resolution gets confused.
|
||||
Generally, you should keep using the same pattern of branch names as the main repositories does. If your version is a fork of 4.0, then call the branch `4.0`, not `4.0-myproj` or `myproj`. Otherwise, the dependency resolution gets confused.
|
||||
|
||||
Sometimes, however, this isn't feasible. For example, you might have a number of project forks stored in a single repository, such as your personal github fork of a project. Or you might be testing/developing a feature branch. Or it might just be confusing to other team members to call the branch of your modified version `3.0`.
|
||||
Sometimes, however, this isn't feasible. For example, you might have a number of project forks stored in a single repository, such as your personal GitHub fork of a project. Or you might be testing/developing a feature branch. Or it might just be confusing to other team members to call the branch of your modified version `4.0`.
|
||||
|
||||
In this case, you need to use Composer's aliasing feature to specify how you want the project branch to be treated, when it comes to dependency resolution.
|
||||
In this case, you need to use Composer's aliasing feature to specify how you want the project branch to be treated, when it comes to dependency resolution.
|
||||
|
||||
Open `composer.json`, and find the module's `require`. Then put `as (core version name)` on the end.
|
||||
Open `composer.json`, and find the module's `require`. Then put `as (core version name)` on the end.
|
||||
|
||||
{
|
||||
...
|
||||
"require": {
|
||||
"php": ">=5.3.2",
|
||||
"silverstripe/cms": "3.0.2.1",
|
||||
"silverstripe/framework": "dev-myproj as 3.0.x-dev",
|
||||
"silverstripe-themes/simple": "*"
|
||||
},
|
||||
...
|
||||
```json
|
||||
{
|
||||
"require": {
|
||||
"php": ">=5.5.0",
|
||||
"silverstripe/cms": "3.5.1.2",
|
||||
"silverstripe/framework": "dev-myproj as 4.0.x-dev",
|
||||
"silverstripe-themes/simple": "~3.2.0"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
What this means is that when the `myproj` branch is checked out into a project, this will satisfy any dependencies that 3.0.x-dev would meet. So, if another module has `"silverstripe/framework": ">=3.0.0"` in its dependency list, it won't get a conflict.
|
||||
What this means is that when the `myproj` branch is checked out into a project, this will satisfy any dependencies that `4.0.x-dev` would meet. So, if another module has `"silverstripe/framework": "^4.0.0"` in its dependency list, it won't get a conflict.
|
||||
|
||||
Both the version and the alias are specified as Composer versions, not branch names. For the relationship between branch/tag names and Composer versions, read [the relevant Composer documentation](http://getcomposer.org/doc/02-libraries.md#specifying-the-version).
|
||||
|
||||
@ -318,18 +359,18 @@ This is not the only way to set things up in Composer. For more information on t
|
||||
|
||||
### Error "The requested package silverstripe/framework 1.0.0 could not be found"
|
||||
|
||||
Composer needs hints about the base package version, either by using `composer create-project`
|
||||
Composer needs hints about the base package version, either by using `composer create-project`
|
||||
as described above, or by checking out the `silverstripe-installer` project directly from version control.
|
||||
In order to use Composer on archive downloads from silverstripe.org, or other unversioned sources,
|
||||
an advanced workaround is to set the `COMPOSER_ROOT_VERSION` before every command
|
||||
an advanced workaround is to set the `COMPOSER_ROOT_VERSION` before every command
|
||||
([details](http://getcomposer.org/doc/03-cli.md#composer-root-version))
|
||||
|
||||
### How do I convert an existing module to using Composer?
|
||||
|
||||
Simply decide on a [unique name and vendor prefix](https://packagist.org/about),
|
||||
Simply decide on a [unique name and vendor prefix](https://packagist.org/about),
|
||||
create a `composer.json`, and either commit it or send a pull request to the module author.
|
||||
Look at existing modules like the ["blog" module](https://github.com/silverstripe/silverstripe-blog/blob/master/composer.json) for good examples on what this file should contain.
|
||||
It's important that the file contains a custom "type" to declare it as a
|
||||
It's important that the file contains a custom "type" to declare it as a
|
||||
`silverstripe-module` or `silverstripe-theme` (see [custom installers](http://getcomposer.org/doc/articles/custom-installers.md)).
|
||||
Then register the module on [packagist.org](http://packagist.org).
|
||||
|
||||
@ -364,9 +405,9 @@ We recommend looking into [Composer "lock" files](http://getcomposer.org/doc/01-
|
||||
|
||||
### Can I keep using Downloads, Subversion Externals or Git Submodules?
|
||||
|
||||
Yes and no. Composer comes with additional features such as
|
||||
[autoloading](http://getcomposer.org/doc/01-basic-usage.md#autoloading)
|
||||
or [scripts](http://getcomposer.org/doc/articles/scripts.md)
|
||||
Yes and no. Composer comes with additional features such as
|
||||
[autoloading](http://getcomposer.org/doc/01-basic-usage.md#autoloading)
|
||||
or [scripts](http://getcomposer.org/doc/articles/scripts.md)
|
||||
which some modules will start relying on.
|
||||
Please check the module README for specific installation instructions.
|
||||
|
||||
|
||||
@ -6,30 +6,32 @@ summary: Extend core functionality with modules.
|
||||
SilverStripe is designed to be a modular application system - even the CMS is simply a module that plugs into the core
|
||||
framework.
|
||||
|
||||
A module is a collection of classes, templates, and other resources that is loaded into a top-level directory such as
|
||||
the `framework`, `cms` or `mysite` folders. The only thing that identifies a folder as a SilverStripe module is the
|
||||
A module is a collection of classes, templates, and other resources that is loaded into a top-level directory such as
|
||||
the `framework`, `cms` or `mysite` folders. The only thing that identifies a folder as a SilverStripe module is the
|
||||
existence of a `_config` directory or `_config.php` at the top level of the directory.
|
||||
|
||||
mysite/
|
||||
|
|
||||
+-- _config/
|
||||
+-- code/
|
||||
+-- ..
|
||||
|
|
||||
my_custom_module/
|
||||
|
|
||||
+-- _config/
|
||||
+-- ...
|
||||
```
|
||||
mysite/
|
||||
|
|
||||
+-- _config/
|
||||
+-- src/
|
||||
+-- ..
|
||||
|
|
||||
my_custom_module/
|
||||
|
|
||||
+-- _config/
|
||||
+-- ...
|
||||
```
|
||||
|
||||
SilverStripe will automatically include any PHP classes and templates from within your module when you next flush your
|
||||
cache.
|
||||
|
||||
<div class="info" markdown="1">
|
||||
In a default SilverStripe installation, even resources in `framework` and `mysite` are treated in exactly the same as
|
||||
<div class="info" markdown="1">
|
||||
In a default SilverStripe installation, even resources in `framework` and `mysite` are treated in exactly the same as
|
||||
every other module. Order of priority is usually alphabetical unless stated.
|
||||
</div>
|
||||
|
||||
Creating a module is a good way to re-use abstract code and templates across multiple projects. SilverStripe already
|
||||
Creating a module is a good way to re-use abstract code and templates across multiple projects. SilverStripe already
|
||||
has certain modules included, for example the `cms` module and core functionality such as commenting and spam protection
|
||||
are also abstracted into modules allowing developers the freedom to choose what they want.
|
||||
|
||||
@ -38,7 +40,7 @@ are also abstracted into modules allowing developers the freedom to choose what
|
||||
|
||||
* [Official module list on silverstripe.org](http://addons.silverstripe.org/)
|
||||
* [Packagist.org "silverstripe" tag](https://packagist.org/search/?tags=silverstripe)
|
||||
* [Github.com "silverstripe" search](https://github.com/search?q=silverstripe&ref=commandbar)
|
||||
* [GitHub.com "silverstripe" search](https://github.com/search?q=silverstripe)
|
||||
|
||||
## Installation
|
||||
|
||||
@ -50,49 +52,51 @@ The root directory is the one containing the *framework* and *mysite* subdirecto
|
||||
</div>
|
||||
|
||||
<div class="notice" markdown="1">
|
||||
After you add or remove modules make sure you rebuild the database by going to http://yoursite.com/dev/build?flush=1
|
||||
After you add or remove modules, make sure you rebuild the database, class and configuration manifests by going to http://yoursite.com/dev/build?flush=1
|
||||
</div>
|
||||
|
||||
### From Composer
|
||||
|
||||
Our preferred way to manage module dependencies is through the [Composer](http://getcomposer.org) package manager. It
|
||||
enables you to install modules from specific versions, checking for compatibilities between modules and even allowing
|
||||
Our preferred way to manage module dependencies is through the [Composer](http://getcomposer.org) package manager. It
|
||||
enables you to install modules from specific versions, checking for compatibilities between modules and even allowing
|
||||
to track development branches of them. To install modules using this method, you will first need to setup SilverStripe
|
||||
with [Composer](../../getting_started/composer).
|
||||
|
||||
Each module has a unique identifier, consisting of a vendor prefix and name. For example, the "blog" module has the
|
||||
identifier `silverstripe/blog` as it is published by *silverstripe*. To install, use the following command executed in
|
||||
Each module has a unique identifier, consisting of a vendor prefix and name. For example, the "blog" module has the
|
||||
identifier `silverstripe/blog` as it is published by *silverstripe*. To install, use the following command executed in
|
||||
the root folder:
|
||||
|
||||
:::bash
|
||||
composer require "silverstripe/blog" "*@stable"
|
||||
|
||||
```bash
|
||||
composer require silverstripe/blog *@stable
|
||||
```
|
||||
|
||||
This will fetch the latest compatible stable version of the module. To install a specific version of the module give the
|
||||
tag name.
|
||||
|
||||
:::bash
|
||||
composer require "silverstripe/blog" "1.1.0"
|
||||
```bash
|
||||
composer require silverstripe/blog 1.1.0
|
||||
```
|
||||
|
||||
<div class="info" markdown="1">
|
||||
To lock down to a specific version, branch or commit, read up on
|
||||
For more information on using Composer version constraints, please [see here](https://getcomposer.org/doc/articles/versions.md). To lock down to a specific version, branch or commit, read up on
|
||||
[Composer "lock" files](http://getcomposer.org/doc/01-basic-usage.md#composer-lock-the-lock-file).
|
||||
</div>
|
||||
|
||||
## From an Archive Download
|
||||
|
||||
<div class="alert" markdown="1">
|
||||
Some modules might not work at all with this approach since they rely on the
|
||||
Composer [autoloader](http://getcomposer.org/doc/01-basic-usage.md#autoloading), additional modules or post-install
|
||||
Some modules might not work at all with this approach since they rely on the
|
||||
Composer [autoloader](http://getcomposer.org/doc/01-basic-usage.md#autoloading), additional modules or post-install
|
||||
hooks, so we recommend using Composer.
|
||||
</div>
|
||||
|
||||
Alternatively, you can download the archive file from the [modules page](http://www.silverstripe.org/modules) and
|
||||
Alternatively, you can download the archive file from the [modules page](http://www.silverstripe.org/modules) and
|
||||
extract it to the root folder mentioned above.
|
||||
|
||||
<div class="notice" markdown="1">
|
||||
The main folder extracted from the archive might contain the version number or additional "container" folders above the
|
||||
actual module codebase. You need to make sure the folder name is the correct name of the module (e.g. "blog/" rather
|
||||
than "silverstripe-blog/"). This folder should contain a `_config/` directory. While the module might register and
|
||||
The main folder extracted from the archive might contain the version number or additional "container" folders above the
|
||||
actual module codebase. You need to make sure the folder name is the correct name of the module (e.g. "blog/" rather
|
||||
than "silverstripe-blog/"). This folder should contain a `_config/` directory. While the module might register and
|
||||
operate in other structures, paths to static files such as CSS or JavaScript won't work.
|
||||
</div>
|
||||
|
||||
@ -107,20 +111,21 @@ The SilverStripe module standard defines a set of conventions that high-quality
|
||||
|
||||
### Coding Guidelines
|
||||
|
||||
* Declaration of level of support is provided for each module (either via README.md or composer) including the below.
|
||||
* Declaration of level of support is provided for each module (either via README.md or composer) including the following:
|
||||
* Level of support provided.
|
||||
* Supporting user(s) and/or organisation(s).
|
||||
* Complies to a well defined module directory structure and coding standards:
|
||||
* templates (for ss templates)
|
||||
* code (for php files)
|
||||
* tests (for php test files) and
|
||||
* _config (for yml config)
|
||||
* `templates/` (for `.ss` templates)
|
||||
* `src/` (for `.php` files)
|
||||
* `tests/` (for `*Test.php` test files), and;
|
||||
* `_config/` (for `.yml` config files)
|
||||
* The module is a Composer package.
|
||||
* All Composer dependencies are bound to a single major release (e.g. ^3.1 not >=3.1).
|
||||
* All Composer dependencies are bound to a single major release (e.g. `^4.0` not `>=4` or `*`).
|
||||
* There is a level of test coverage.
|
||||
* A clear public API documented in the docblock tags.
|
||||
* Recommend the use of [PSR-1](http://www.php-fig.org/psr/psr-1/) and [PSR-2](http://www.php-fig.org/psr/psr-2/).
|
||||
* .gitattributes will be used to exclude non-essential files from the distribution. At a minimum tests, docs, and IDE/dev-tool config should be excluded.
|
||||
* Code follows [PSR-1](http://www.php-fig.org/psr/psr-1/) and [PSR-2](http://www.php-fig.org/psr/psr-2/) style guidelines.
|
||||
* `.gitattributes` will be used to exclude non-essential files from the distribution. At a minimum tests, docs, and IDE/dev-tool config should be excluded.
|
||||
* Add a [PSR-4 compatible autoload reference](https://getcomposer.org/doc/04-schema.md#psr-4) for your module.
|
||||
|
||||
### Documentation Guidelines
|
||||
|
||||
@ -129,14 +134,14 @@ Documentation will use the following format:
|
||||
* README.md provides:
|
||||
* Links or badges to CI and code quality tools.
|
||||
* A short summary of the module, end-user.
|
||||
* Installation instructions
|
||||
* Testing/development instructions and a link to contrib instructions.
|
||||
* Installation instructions.
|
||||
* Testing/development instructions and a link to contributing instructions.
|
||||
* How to report security vulnerabilities. Note that PSR-9 / PSR-10 may be recommended once released.
|
||||
* Security, license, links to more detailed docs.
|
||||
* CONTRIBUTING.md explaining terms of contribution.
|
||||
* A changelog CHANGELOG.md (may link to other more detailed docs or GitHub releases if you want). You could [use a changelog generator](https://github.com/skywinder/Github-Changelog-Generator) to help create this.
|
||||
* A changelog: CHANGELOG.md (may link to other more detailed docs or GitHub releases if you want). You could [use a changelog generator](https://github.com/skywinder/Github-Changelog-Generator) to help create this.
|
||||
* Has a licence (LICENSE.md file) - for SilverStripe supported this needs to be BSD.
|
||||
* Detailed documentation in /docs/en as a nested set of GitHub-compatible Markdown files.
|
||||
* Detailed documentation in `/docs/en` as a nested set of GitHub-compatible Markdown files.
|
||||
* It is suggested to use a documentation page named `userguide.md` in `docs/en/` that includes documentation of module features that have CMS user functionality (if applicable). For modules with large userguides, this should be in a directory named `userguide` with an `index.md` linking to any other userguide pages.
|
||||
* Links and image references are relative, and are able to be followed in viewers such as GitHub.
|
||||
* Markdown may include non-visible comments or meta-data.
|
||||
@ -146,7 +151,7 @@ Documentation will cover:
|
||||
* Installation
|
||||
* Configuration
|
||||
* Usage guides for key features; screenshots are recommended.
|
||||
* A committers guide, covering PR-merging and release guidelines.
|
||||
* A committers guide, covering pull request merging and release guidelines.
|
||||
|
||||
## Related
|
||||
|
||||
|
||||
@ -1,52 +1,83 @@
|
||||
title: Upgrading
|
||||
introduction: Keep your SilverStripe installations up to date with the latest fixes, security patches and new features.
|
||||
|
||||
# Upgrading to SilverStripe 3.2
|
||||
# Upgrading to SilverStripe 4
|
||||
|
||||
SilverStripe applications should be kept up to date with the latest security releases. Usually an update or upgrade to your SilverStripe installation means overwriting files, flushing the cache and updating your database-schema.
|
||||
SilverStripe applications should be kept up to date with the latest security releases. Usually an update or upgrade to your SilverStripe installation means overwriting files, flushing the cache and updating your database schema.
|
||||
|
||||
<div class="info" markdown="1">
|
||||
See our [upgrade notes and changelogs](/changelogs/3.2.0) for 3.2.0 specific information, bugfixes and API changes.
|
||||
See our [upgrade notes and changelogs](/changelogs/4.0.0) for 4.0.0 specific information, bugfixes and API changes.
|
||||
</div>
|
||||
|
||||
## Composer
|
||||
## Composer
|
||||
|
||||
For projects managed through Composer, update the version number of `framework` and `cms` to `^3.2` in your `composer.json` file and run `composer update`.
|
||||
For projects managed through Composer, update the version number of `framework` and `cms` to `^4.0` in your `composer.json` file and run `composer update`.
|
||||
|
||||
```json
|
||||
"require": {
|
||||
"silverstripe/framework": "^3.2",
|
||||
"silverstripe/cms": "^3.2"
|
||||
}
|
||||
"require": {
|
||||
"silverstripe/framework": "^4.0",
|
||||
"silverstripe/cms": "^4.0"
|
||||
}
|
||||
```
|
||||
|
||||
<div class="info" markdown="1">
|
||||
Please note that until SilverStripe 4 is stable you will need to also add `"minimum-stability": "dev"` and `"prefer-stable": true` to your `composer.json` to be able to pull these modules.</div>
|
||||
|
||||
This will also add extra dependencies, the `reports` and `siteconfig` modules. SilverStripe CMS is becoming more modular, and [composer is becoming the preferred way to manage your code](/getting_started/composer).
|
||||
|
||||
### Asset-admin
|
||||
|
||||
SilverStripe 4 comes with a new asset administration module. While it is installed by default for new projects, if you are upgrading you will need to install it manually:
|
||||
|
||||
```
|
||||
composer require silverstripe/asset-admin ^1.0
|
||||
```
|
||||
|
||||
This will also install the `graphql` module for GraphQL API access to your SilverStripe system, which powers the `asset-admin` module.
|
||||
|
||||
## Manual
|
||||
|
||||
* 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 *mysite* or *themes* in place.
|
||||
* Identify system folders in your webroot (`cms`, `framework` and any additional modules).
|
||||
* Delete existing system folders (or move them outside of your webroot)
|
||||
* Extract and replace system folders from your download (Deleting instead of "copying over" existing folders ensures that files removed from the new SilverStripe release are not persisting in your installation).
|
||||
* As of SilverStripe CMS 3.2.0 you will also need to include the `reports` and `siteconfig` modules to ensure feature parity with previous versions of the CMS.
|
||||
* Visit http://yoursite.com/dev/build/?flush=1 to rebuild the website database.
|
||||
* Check if you need to adapt your code to changed PHP APIs
|
||||
* Check if you have overwritten any core templates or styles which might need an update.
|
||||
* 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 *mysite* or *themes* in place.
|
||||
* Identify system folders in your webroot (`cms`, `framework` and any additional modules).
|
||||
* Delete existing system folders (or move them outside of your webroot).
|
||||
* Rename your `Page_Controller` class to `PageController`.
|
||||
* Add a `private static $table_name = 'MyDataObject'` for any custom DataObjects in your code that are namespaced. This ensures that your database table name will be `MyDataObject` instead of `Me\MyPackage\Model\MyDataObject` (your namespace for the class).
|
||||
* Ensure you add [namespaces](http://php.net/manual/en/language.namespaces.php) to any custom classes in your `mysite` folder. Your namespaces should follow the pattern of `Vendor\Package` with anything additional defined at your discretion. **Note:** The `Page` and `PageController` classes *must* be defined in the global namespace (or; without a namespace).
|
||||
* Install the updated framework, CMS and any other modules you require by updating your `composer.json` configuration and running `composer update`. As of SilverStripe 4.0.0 you should also include the `asset-admin` module to power your asset management in the CMS.
|
||||
* 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.
|
||||
|
||||
<div class="warning" markdown="1">
|
||||
Never update a website on the live server without trying it on a development copy first.
|
||||
Never update a website on the live server without trying it on a development copy first!
|
||||
</div>
|
||||
|
||||
## Decision Helpers
|
||||
## Using the upgrader tool
|
||||
|
||||
How easy will it be to update my project? It's a fair question, and sometimes a difficult one to answer.
|
||||
We've developed [an upgrader tool](https://github.com/silverstripe/silverstripe-upgrader) which you can use to help you with the upgrade process to SilverStripe 4. [See the upgrading notes](/changelogs/4.0.0/#a-name-upgrading-a-upgrading) in the changelog for more detailed instructions on how to use it.
|
||||
|
||||
## Quick tips
|
||||
|
||||
If you've already had a look over the changelog, you will see that there are some fundamental changes that need to be implemented to upgrade from 3.x. Here's a couple of the most important ones to consider:
|
||||
|
||||
* PHP 5.5 is now the minimum required version (and PHP 7.x is supported!).
|
||||
* All SilverStripe classes are now namespaced, and some have been renamed. Most of your modules will also have been namespaced, and you will need to consider this when updating class references (including YAML configuration) in your own code.
|
||||
* 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.
|
||||
|
||||
## 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.
|
||||
* 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
|
||||
|
||||
Loading…
Reference in New Issue
Block a user