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

DOC update SilverStripe to Silverstripe

Browse Source 
- Start with Getting Started
- Apply consistent formatting (120 chars etc)
This commit is contained in:
Michael Pritchard 2021-06-22 09:41:48 +01:00
parent 5ba38520d7
commit 53ef257ff4
7 changed files with 417 additions and 385 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

267
docs/en/00_Getting_Started/00_Server_Requirements.md
View File

@ -4,7 +4,6 @@ icon: server
summary: What you will need to run Silverstripe CMS on a web server
---
# Requirements
Silverstripe CMS needs to be installed on a web server. Content authors and website administrators use their web browser
@ -13,105 +12,106 @@ the server to update templates, website logic, and perform upgrades or maintenan
## PHP
* PHP >=7.1
* PHP extensions: `ctype`, `dom`, `fileinfo`, `hash`, `intl`, `mbstring`, `session`, `simplexml`, `tokenizer`, `xml`
* PHP configuration: `memory_limit` with at least `48M`
* PHP extension for image manipulation: Either `gd` or `imagick`
* PHP extension for a database connector (e.g. `pdo` or `mysqli`)
* PHP >=7.1
* PHP extensions: `ctype`, `dom`, `fileinfo`, `hash`, `intl`, `mbstring`, `session`, `simplexml`, `tokenizer`, `xml`
* PHP configuration: `memory_limit` with at least `48M`
* PHP extension for image manipulation: Either `gd` or `imagick`
* PHP extension for a database connector (e.g. `pdo` or `mysqli`)
Use [phpinfo()](http://php.net/manual/en/function.phpinfo.php) to inspect your configuration.
## Database
* MySQL >=5.6 (built-in, [commercially supported](https://www.silverstripe.org/software/addons/silverstripe-commercially-supported-module-list/))
* PostgreSQL ([third party module](https://addons.silverstripe.org/add-ons/silverstripe/postgresql), community supported)
* SQL Server ([third party module](https://addons.silverstripe.org/add-ons/silverstripe/mssql), community supported)
* SQLite ([third party module](https://addons.silverstripe.org/add-ons/silverstripe/sqlite3), community supported)
* MySQL >=5.6 (
built-in, [commercially supported](https://www.silverstripe.org/software/addons/silverstripe-commercially-supported-module-list/))
* PostgreSQL ([third party module](https://addons.silverstripe.org/add-ons/silverstripe/postgresql), community
supported)
* SQL Server ([third party module](https://addons.silverstripe.org/add-ons/silverstripe/mssql), community supported)
* SQLite ([third party module](https://addons.silverstripe.org/add-ons/silverstripe/sqlite3), community supported)
### Default MySQL Collation
In Silverstripe CMS Recipe 4.7 and later, new projects default to the `utf8mb4_unicode_ci` collation when running against MySQL, which offers better support for multi-byte characters such as emoji. However, this may cause issues related to Varchar fields exceeding the maximum indexable size:
In Silverstripe CMS Recipe 4.7 and later, new projects default to the `utf8mb4_unicode_ci` collation when running
against MySQL, which offers better support for multi-byte characters such as emoji. However, this may cause issues
related to Varchar fields exceeding the maximum indexable size:
- MySQL 5.5 and lower cannot support indexes larger than 768 bytes (192 characters)
- MySQL 5.6 supports larger indexes (3072 bytes) if the `innodb_large_prefix` setting is enabled (but not by default)
- MySQL 5.7 and newer have `innodb_large_prefix` enabled by default
- MariaDB ~10.1 matches MySQL 5.6's behaviour, >10.2 matches 5.7's.
You can rectify this issue by upgrading MySQL, enabling the `innodb_large_prefix` setting if available, or reducing the size of affected fields. If none of these solutions are currently suitable, you can remove the new collation configuration from `app/_config/mysite.yml` to default back to the previous default collation.
You can rectify this issue by upgrading MySQL, enabling the `innodb_large_prefix` setting if available, or reducing the
size of affected fields. If none of these solutions are currently suitable, you can remove the new collation
configuration from `app/_config/mysite.yml` to default back to the previous default collation.
Existing projects that upgrade to Recipe 4.7.0 will unintentionally adopt this configuration change. Recipe 4.7.1 and later are unaffected. See [the release notes](/changelogs/4.7.0/#default-mysql-collation-updated) for more information.
Existing projects that upgrade to Recipe 4.7.0 will unintentionally adopt this configuration change. Recipe 4.7.1 and
later are unaffected. See [the release notes](/changelogs/4.7.0/#default-mysql-collation-updated) for more information.
### Connection mode (sql_mode) when using MySQL server >=5.7.5
In MySQL versions >=5.7.5, the `ANSI` sql_mode setting behaves differently and includes the `ONLY_FULL_GROUP_BY` setting. It is generally recommended to leave this setting as-is because it results in deterministic SQL. However, for some advanced cases, the sql_mode can be configured on the database connection via the configuration API (see `MySQLDatabase::$sql_mode` for more details.) This setting is only available in Silverstripe CMS 4.7 and later.
In MySQL versions >=5.7.5, the `ANSI` sql_mode setting behaves differently and includes the `ONLY_FULL_GROUP_BY`
setting. It is generally recommended to leave this setting as-is because it results in deterministic SQL. However, for
some advanced cases, the sql_mode can be configured on the database connection via the configuration API (
see `MySQLDatabase::$sql_mode` for more details.) This setting is only available in Silverstripe CMS 4.7 and later.
## Webserver Configuration
### Overview
SilverStripe needs to handle a variety of HTTP requests,
and relies on the hosting environment to be configured securely to
enforce restrictions. There are secure defaults in place for Apache,
but you should be aware of the configuration regardless of your webserver setup.
Silverstripe needs to handle a variety of HTTP requests, and relies on the hosting environment to be configured securely
to enforce restrictions. There are secure defaults in place for Apache, but you should be aware of the configuration
regardless of your webserver setup.
### Public webroot
The webroot of your webserver should be configured to the `public/` subfolder.
Projects created prior to SilverStripe 4.1 might be using the main project
folder as the webroot. In this case, you are responsible for ensuring
access to system files such as configuration in `*.yml` is protected
from public access. We strongly recommend switching to more secure
hosting via the `public/`. See [4.1.0 upgrading guide](/changelogs/4.1.0).
The webroot of your webserver should be configured to the `public/` subfolder. Projects created prior to Silverstripe
4.1 might be using the main project folder as the webroot. In this case, you are responsible for ensuring access to
system files such as configuration in `*.yml` is protected from public access. We strongly recommend switching to more
secure hosting via the `public/`. See [4.1.0 upgrading guide](/changelogs/4.1.0).
### Filesystem permissions
During runtime, Silverstripe needs read access for the webserver user to your base path (including your webroot).
It also needs write access for the webserver user to the following locations:
During runtime, Silverstripe needs read access for the webserver user to your base path (including your webroot). It
also needs write access for the webserver user to the following locations:
* `public/assets/`: Used by the CMS and other logic to [store uploads](/developer_guides/files/file_storage)
* `TEMP_PATH`: Temporary file storage used for the default filesystem-based cache adapters in
* `public/assets/`: Used by the CMS and other logic to [store uploads](/developer_guides/files/file_storage)
* `TEMP_PATH`: Temporary file storage used for the default filesystem-based cache adapters in
[Manifests](/developer_guides/execution_pipeline/manifests), [Object Caching](/developer_guides/performance/caching)
and [Partial Template Caching](/developer_guides/templates/partial_template_caching).
See [Environment Management](/getting_started/environment_management).
If you aren't explicitly [packaging](#building-packaging-deployment)
your Silverstripe project during your deployment process,
additional write access may be required to generate supporting files on the fly.
This is not recommended, because it can lead to extended execution times
as well as cause inconsistencies between multiple server environments
when manifest and cache storage isn't shared between servers.
your Silverstripe project during your deployment process, additional write access may be required to generate supporting
files on the fly. This is not recommended, because it can lead to extended execution times as well as cause
inconsistencies between multiple server environments when manifest and cache storage isn't shared between servers.
### Assets
SilverStripe allows CMS authors to upload files into the `public/assets/` folder,
which should be served by your webserver. **No PHP execution should be allowed in this folder**.
This is configured for Apache by default via `public/assets/.htaccess`.
The file is generated dynamically during the `dev/build` stage.
Silverstripe allows CMS authors to upload files into the `public/assets/` folder, which should be served by your
webserver. **No PHP execution should be allowed in this folder**. This is configured for Apache by default
via `public/assets/.htaccess`. The file is generated dynamically during the `dev/build` stage.
Additionally, access is whitelisted by file extension through a
dynamically generated whitelist based on the `File.allowed_extensions` setting
(see [File Security](/developer_guides/files/file_security#file-types)).
This whitelist uses the same defaults configured through file upload
through SilverStripe, so is considered a second line of defence.
Additionally, access is whitelisted by file extension through a dynamically generated whitelist based on
the `File.allowed_extensions` setting
(see [File Security](/developer_guides/files/file_security#file-types)). This whitelist uses the same defaults
configured through file upload through Silverstripe, so is considered a second line of defence.
### Secure Assets {#secure-assets}
Files can be kept in draft stage,
and access restricted to certain user groups.
These files are stored in a special `.protected/` folder (defaulting to `public/assets/.protected/`).
Files can be kept in draft stage, and access restricted to certain user groups. These files are stored in a
special `.protected/` folder (defaulting to `public/assets/.protected/`).
**Requests to files in this folder should be denied by your webserver**.
Requests to files in the `.protected/` folder
are routed to PHP by default when using Apache, through `public/assets/.htaccess`.
If you are using another webserver, please follow our guides to ensure a secure setup.
See [Developer Guides: File Security](/developer_guides/files/file_security) for details.
Requests to files in the `.protected/` folder are routed to PHP by default when using Apache,
through `public/assets/.htaccess`. If you are using another webserver, please follow our guides to ensure a secure
setup. See [Developer Guides: File Security](/developer_guides/files/file_security) for details.
For additional security, we recommend moving the `.protected/` folder out of `public/assets/`.
This removes the possibility of a misconfigured webserver accidentally exposing
these files under URL paths, and forces read access via PHP.
For additional security, we recommend moving the `.protected/` folder out of `public/assets/`. This removes the
possibility of a misconfigured webserver accidentally exposing these files under URL paths, and forces read access via
PHP.
This can be configured via [.env](/getting_started/environment_management) variable,
relative to the `index.php` location.
This can be configured via [.env](/getting_started/environment_management) variable, relative to the `index.php`
location.
```
SS_PROTECTED_ASSETS_PATH="../.protected/"
@ -134,128 +134,126 @@ Don't forget to include this additional folder in any syncing and backup process
### Building, Packaging and Deployment {#building-packaging-deployment}
It is common to build a SilverStripe application into a package on one environment (e.g. a CI server),
and then deploy the package to a (separate) webserver environment(s).
This approach relies on all auto-generated files required by SilverStripe to
be included in the package, or generated on the fly on each webserver environment.
It is common to build a Silverstripe application into a package on one environment (e.g. a CI server), and then deploy
the package to a (separate) webserver environment(s). This approach relies on all auto-generated files required by
Silverstripe to be included in the package, or generated on the fly on each webserver environment.
The easiest way to ensure this is to commit auto generated files to source control.
If those changes are considered too noisy, here's some pointers for auto-generated files
to trigger and include in a deployment package:
The easiest way to ensure this is to commit auto generated files to source control. If those changes are considered too
noisy, here's some pointers for auto-generated files to trigger and include in a deployment package:
* `public/_resources/`: Frontend assets copied from the (inaccessible) `vendor/` folder
* `public/_resources/`: Frontend assets copied from the (inaccessible) `vendor/` folder
via [silverstripe/vendor-plugin](https://github.com/silverstripe/vendor-plugin).
See [Templates: Requirements](/developer_guides/templates/requirements#exposing-assets-webroot).
* `.graphql/` and `public/_graphql/`: Schema and type definitions required by CMS and any GraphQL API endpoint. Generated through
[silverstripe/graphql v4](https://github.com/silverstripe/silverstripe-graphql).
Triggered by `dev/build`, or a [GraphQL Schema Build](/developer_guides/graphql/getting_started/building_the_schema).
* Various recipes create default files in `app/` and `public/` on `composer install`
* `.graphql/` and `public/_graphql/`: Schema and type definitions required by CMS and any GraphQL API endpoint.
Generated through
[silverstripe/graphql v4](https://github.com/silverstripe/silverstripe-graphql). Triggered by `dev/build`, or
a [GraphQL Schema Build](/developer_guides/graphql/getting_started/building_the_schema).
* Various recipes create default files in `app/` and `public/` on `composer install`
and `composer update` via
[silverstripe/recipe-plugin](https://github.com/silverstripe/recipe-plugin).
### Web Worker Concurrency
It's generally a good idea to run multiple workers to serve multiple HTTP requests
to SilverStripe concurrently. The exact number depends on your website needs.
The CMS attempts to request multiple views concurrently.
It also routes [protected and draft files](/developer_guides/files/file_security)
through SilverStripe. This can increase your concurrency requirements,
e.g. when authors batch upload and view dozens of draft files in the CMS.
It's generally a good idea to run multiple workers to serve multiple HTTP requests to Silverstripe concurrently. The
exact number depends on your website needs. The CMS attempts to request multiple views concurrently. It also
routes [protected and draft files](/developer_guides/files/file_security)
through Silverstripe. This can increase your concurrency requirements, e.g. when authors batch upload and view dozens of
draft files in the CMS.
When allowing upload of large files through the CMS (through PHP settings),
these files might be used as [protected and draft files](/developer_guides/files/file_security).
Files in this state get served by SilverStripe rather than your webserver.
Since the framework uses [PHP streams](https://www.php.net/manual/en/ref.stream.php),
this allows serving of files larger than your PHP memory limit.
Please be aware that streaming operations don't count towards
PHP's [max_execution_time](https://www.php.net/manual/en/function.set-time-limit.php),
which can risk exhaustion of web worker pools for long-running downloads.
When allowing upload of large files through the CMS (through PHP settings), these files might be used
as [protected and draft files](/developer_guides/files/file_security). Files in this state get served by Silverstripe
rather than your webserver. Since the framework uses [PHP streams](https://www.php.net/manual/en/ref.stream.php), this
allows serving of files larger than your PHP memory limit. Please be aware that streaming operations don't count towards
PHP's [max_execution_time](https://www.php.net/manual/en/function.set-time-limit.php), which can risk exhaustion of web
worker pools for long-running downloads.
### URL Rewriting
SilverStripe expects URL paths to be rewritten to `public/index.php`.
For Apache, this is preconfigured through `.htaccess` files,
and expects using the `mod_rewrite` module.
By default, these files are located in `public/.htaccess` and `public/assets/.htaccess`.
Silverstripe expects URL paths to be rewritten to `public/index.php`. For Apache, this is preconfigured
through `.htaccess` files, and expects using the `mod_rewrite` module. By default, these files are located
in `public/.htaccess` and `public/assets/.htaccess`.
### HTTP Headers
SilverStripe can add HTTP headers to reponses it handles directly.
These headers are often sensitive, for example preventing HTTP caching for responses
displaying data based on user sessions, or when serving protected assets.
You need to ensure those headers are kept in place in your webserver.
For example, Apache allows this through `Header setifempty` (see [docs](https://httpd.apache.org/docs/current/mod/mod_headers.html#header)).
Silverstripe can add HTTP headers to responses it handles directly. These headers are often sensitive, for example
preventing HTTP caching for responses displaying data based on user sessions, or when serving protected assets. You need
to ensure those headers are kept in place in your webserver. For example, Apache allows this
through `Header setifempty` (see [docs](https://httpd.apache.org/docs/current/mod/mod_headers.html#header)).
See [Developer Guide: Performance](/developer_guides/performance/)
and [Developer Guides: File Security](/developer_guides/files/file_security) for more details.
Silverstripe relies on the `Host` header to construct URLs such as "reset password" links,
so you'll need to ensure that the systems hosting it only allow valid values for this header.
See [Developer Guide: Security - Request hostname forgery](/developer_guides/security/secure_coding#request-hostname-forgery).
Silverstripe relies on the `Host` header to construct URLs such as "reset password" links, so you'll need to ensure that
the systems hosting it only allow valid values for this header.
See [Developer Guide: Security - Request hostname forgery](/developer_guides/security/secure_coding#request-hostname-forgery)
.
### CDNs and other Reverse Proxies
If your Silverstripe site is hosted behind multiple HTTP layers,
you're in charge of controlling which forwarded headers are considered valid,
and which IPs can set them. See [Developer Guide: Security - Request hostname forgery](/developer_guides/security/secure_coding#request-hostname-forgery).
If your Silverstripe site is hosted behind multiple HTTP layers, you're in charge of controlling which forwarded headers
are considered valid, and which IPs can set them.
See [Developer Guide: Security - Request hostname forgery](/developer_guides/security/secure_coding#request-hostname-forgery)
.
### Symlinks
SilverStripe is a modular system, with modules installed and updated
via the `composer` PHP dependency manager. These are usually stored in `vendor/`,
outside of the `public/` webroot. Since many modules rely on serving frontend assets
such as CSS files or images, these are mapped over to the `public/_resources/` folder automatically.
If the filesystem supports it, this is achieved through symlinks.
Depending on your hosting and deployment mechanisms,
you may need to configure the plugin to copy files instead.
Silverstripe is a modular system, with modules installed and updated via the `composer` PHP dependency manager. These
are usually stored in `vendor/`, outside of the `public/` webroot. Since many modules rely on serving frontend assets
such as CSS files or images, these are mapped over to the `public/_resources/` folder automatically. If the filesystem
supports it, this is achieved through symlinks. Depending on your hosting and deployment mechanisms, you may need to
configure the plugin to copy files instead.
See [silverstripe/vendor-plugin](https://github.com/silverstripe/vendor-plugin) for details.
### Caches
Silverstripe relies on various [caches](/developer_guides/performance/caching/)
to achieve performant responses. By default, those caches are stored in a temporary filesystem folder,
and are not shared between multiple server instances. Alternative cache backends such as Redis can be
to achieve performant responses. By default, those caches are stored in a temporary filesystem folder, and are not
shared between multiple server instances. Alternative cache backends such as Redis can be
[configured](/developer_guides/performance/caching/).
While cache objects can expire, when using filesystem caching the files are not actively pruned.
For long-lived server instances, this can become a capacity issue over time - see
While cache objects can expire, when using filesystem caching the files are not actively pruned. For long-lived server
instances, this can become a capacity issue over time - see
[workaround](https://github.com/silverstripe/silverstripe-framework/issues/6678).
### Error pages
The default installation includes [silverstripe/errorpage](https://addons.silverstripe.org/add-ons/silverstripe/errorpage),
which generates static error pages that bypass PHP execution when those pages are published in the CMS.
Once published, the static files are located in `public/assets/error-404.html` and `public/assets/error-500.html`.
The default `public/.htaccess` file is configured to have Apache serve those pages based on their HTTP status code.
The default installation
includes [silverstripe/errorpage](https://addons.silverstripe.org/add-ons/silverstripe/errorpage), which generates
static error pages that bypass PHP execution when those pages are published in the CMS. Once published, the static files
are located in `public/assets/error-404.html` and `public/assets/error-500.html`. The default `public/.htaccess` file is
configured to have Apache serve those pages based on their HTTP status code.
### Other webservers (Nginx, IIS, Lighttpd)
Serving through webservers other than Apache requires more manual configuration,
since the defaults configured through `.htaccess` don't apply.
Please apply the considerations above to your webserver to ensure a secure hosting environment.
In particular, configure protected assets correctly to avoid exposing draft or protected files uploaded through the CMS.
Serving through webservers other than Apache requires more manual configuration, since the defaults configured
through `.htaccess` don't apply. Please apply the considerations above to your webserver to ensure a secure hosting
environment. In particular, configure protected assets correctly to avoid exposing draft or protected files uploaded
through the CMS.
There are various community supported installation instructions for different environments.
Nginx is a popular choice, see [Nginx webserver configuration](https://forum.silverstripe.org/t/nginx-webserver-configuration/2246).
There are various community supported installation instructions for different environments. Nginx is a popular choice,
see [Nginx webserver configuration](https://forum.silverstripe.org/t/nginx-webserver-configuration/2246).
SilverStripe is known to work with Microsoft IIS, and generates `web.config` files by default
(see [Microsoft IIS and SQL Server configuration](https://forum.silverstripe.org/t/microsoft-iis-webserver-and-sql-server-support/2245)).
Silverstripe is known to work with Microsoft IIS, and generates `web.config` files by default
(
see [Microsoft IIS and SQL Server configuration](https://forum.silverstripe.org/t/microsoft-iis-webserver-and-sql-server-support/2245))
.
Additionally, there are community supported guides for installing SilverStripe
on various environments:
Additionally, there are community supported guides for installing Silverstripe on various environments:
* [Hosting via Bitnami](https://bitnami.com/stack/silverstripe/virtual-machine): In the cloud or as a locally hosted virtual machine
* [Vagrant/Virtualbox with CentOS](https://forum.silverstripe.org/t/installing-via-vagrant-virtualbox-with-centos/2248)
* [macOS with Homebrew](https://forum.silverstripe.org/t/installing-on-osx-with-homebrew/2247)
* [macOS with MAMP](https://forum.silverstripe.org/t/installing-on-osx-with-mamp/2249)
* [Windows with WAMP](https://forum.silverstripe.org/t/installing-on-windows-via-wamp/2250)
* [Vagrant with silverstripe-australia/vagrant-environment](https://github.com/silverstripe-australia/vagrant-environment)
* [Vagrant with BetterBrief/vagrant-skeleton](https://github.com/BetterBrief/vagrant-skeleton)
* [Hosting via Bitnami](https://bitnami.com/stack/silverstripe/virtual-machine): In the cloud or as a locally hosted
virtual machine
* [Vagrant/Virtualbox with CentOS](https://forum.silverstripe.org/t/installing-via-vagrant-virtualbox-with-centos/2248)
* [macOS with Homebrew](https://forum.silverstripe.org/t/installing-on-osx-with-homebrew/2247)
* [macOS with MAMP](https://forum.silverstripe.org/t/installing-on-osx-with-mamp/2249)
* [Windows with WAMP](https://forum.silverstripe.org/t/installing-on-windows-via-wamp/2250)
* [Vagrant with silverstripe-australia/vagrant-environment](https://github.com/silverstripe-australia/vagrant-environment)
* [Vagrant with BetterBrief/vagrant-skeleton](https://github.com/BetterBrief/vagrant-skeleton)
## PHP Requirements for older SilverStripe releases {#php-support}
## PHP Requirements for older Silverstripe releases {#php-support}
SilverStripe's PHP support has changed over time and if you are looking to upgrade PHP on your SilverStripe site, this table may be of use:
Silverstripe's PHP support has changed over time and if you are looking to upgrade PHP on your Silverstripe site, this
table may be of use:
| SilverStripe Version | PHP Version | More information |
| Silverstripe Version | PHP Version | More information |
| -------------------- | ----------- | ---------------- |
| 3.0 - 3.5 | 5.3 - 5.6 | [requirements docs](https://docs.silverstripe.org/en/3.4/getting_started/server_requirements/)
| 3.6 | 5.3 - 7.1 | |
@ -263,20 +261,21 @@ SilverStripe's PHP support has changed over time and if you are looking to upgra
| 4.0 - 4.4 | 5.6+ | |
| 4.5+ | 7.1+ | [blog post](https://www.silverstripe.org/blog/our-plan-for-ending-php-5-6-support-in-silverstripe-4/) |
## CMS browser requirements
SilverStripe CMS supports the following web browsers:
Silverstripe CMS supports the following web browsers:
* Google Chrome
* Internet Explorer 11
* Microsoft Edge
* Mozilla Firefox
We aim to provide satisfactory experiences in Apple Safari. SilverStripe CMS works well across Windows, Linux, and Mac operating systems.
We aim to provide satisfactory experiences in Apple Safari. Silverstripe CMS works well across Windows, Linux, and Mac
operating systems.
## End user requirements
SilverStripe CMS is designed to make excellent, standards-compliant websites that are compatible with a wide range of
Silverstripe CMS is designed to make excellent, standards-compliant websites that are compatible with a wide range of
industry standard browsers and operating systems. A competent developer is able to produce websites that meet W3C
guidelines for HTML, CSS, JavaScript, and accessibility, in addition to meeting specific guide lines, such as
e-government requirements.

258
docs/en/00_Getting_Started/02_Composer.md
View File

@ -3,17 +3,20 @@ title: Composer
summary: What is composer and how to use it with Silverstripe CMS
---
# Using SilverStripe with Composer
# Using Silverstripe with Composer
## Requirements
[Composer](http://getcomposer.org/) is a package management tool for PHP that lets you install and upgrade SilverStripe and its modules.
We also have separate instructions for [installing modules with Composer](/developer_guides/extending/modules).
[Composer](http://getcomposer.org/) is a package management tool for PHP that lets you install and upgrade Silverstripe
and its modules. We also have separate instructions
for [installing modules with Composer](/developer_guides/extending/modules).
Before installing Composer you should ensure your system has the version control system, [Git installed](http://git-scm.com/book/en/v2/Getting-Started-Installing-Git). Composer uses Git to check out the code dependancies you need to run your SilverStripe CMS website from the code repositories maintained on GitHub.
Before installing Composer you should ensure your system has the version control
system, [Git installed](http://git-scm.com/book/en/v2/Getting-Started-Installing-Git). Composer uses Git to check out
the code dependancies you need to run your Silverstripe CMS website from the code repositories maintained on GitHub.
Next, [install composer](https://getcomposer.org/download/). For our documentation we assume the `composer` command is installed globally.
You should now be able to run the command:
Next, [install composer](https://getcomposer.org/download/). For our documentation we assume the `composer` command is
installed globally. You should now be able to run the command:
```
composer help
@ -21,24 +24,23 @@ composer help
## Create a new site
Composer can create a new site for you, using the installer as a template.
By default it will download the latest stable version:
Composer can create a new site for you, using the installer as a template. By default it will download the latest stable
version:
```
composer create-project silverstripe/installer my-project
```
If you want to get all additional fixtures for testing, such as behat and phpunit configuration,
an example `.env.example` file, and all documentation, then it's recommended to use `--prefer-source`
If you want to get all additional fixtures for testing, such as behat and phpunit configuration, an
example `.env.example` file, and all documentation, then it's recommended to use `--prefer-source`
to include these files.
If you want a minimal installation with the bare essentials to get working without any additional overhead,
and don't plan on contributing back changes to framework, use `--prefer-dist` (default) for a more lightweight install.
If you want a minimal installation with the bare essentials to get working without any additional overhead, and don't
plan on contributing back changes to framework, use `--prefer-dist` (default) for a more lightweight install.
`./my-project` 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.
Now visit the site in your web browser, and the installation process will be completed.
`./my-project` 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. 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 `4.3.3` release:
@ -46,34 +48,38 @@ You can also specify a version to download that version explicitly, i.e. this wi
composer create-project silverstripe/installer ./my-project 4.3.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,
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,
see [Using development versions](#using-development-versions).
## Adding modules to your project
Composer isn't only used to download SilverStripe CMS, it is also used to manage all SilverStripe modules.
You can find thousands of modules on [https://addons.silverstripe.org](https://addons.silverstripe.org).
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. You can find
thousands of modules on [https://addons.silverstripe.org](https://addons.silverstripe.org). Installing a module can be
done with the following command:
```
composer require silverstripe/blog
```
This will install the `silverstripe/blog` module in the latest compatible version. If you know the specific version you want to install already (such as `^2`), you can add it after the package name as a [version constraint](http://getcomposer.org/doc/01-basic-usage.md#the-require-key):
This will install the `silverstripe/blog` module in the latest compatible version. If you know the specific version you
want to install already (such as `^2`), you can add it after the package name as
a [version constraint](http://getcomposer.org/doc/01-basic-usage.md#the-require-key):
```
composer require silverstripe/blog ^2
```
[warning]
**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`.
**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`.
[/warning]
## 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:
@ -81,35 +87,43 @@ To get the latest updates of the modules in your project, run this command:
composer update
```
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.
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`. 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!
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:
* 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. 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.
* 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. 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
Modules and themes managed by Composer should not be committed with your projects source code.
SilverStripe ships with a [.gitignore](http://git-scm.com/docs/gitignore) file by default which prevents this.
For more details read [Should I commit the dependencies in my vendor directory?](https://getcomposer.org/doc/faqs/should-i-commit-the-dependencies-in-my-vendor-directory.md).
Modules and themes managed by Composer should not be committed with your projects source code. Silverstripe ships with
a [.gitignore](http://git-scm.com/docs/gitignore) file by default which prevents this. For more details
read [Should I commit the dependencies in my vendor directory?](https://getcomposer.org/doc/faqs/should-i-commit-the-dependencies-in-my-vendor-directory.md)
.
## Dev Environments for Contributing Code {#contributing}
So you want to contribute to SilverStripe? Fantastic! You can do this with composer too.
You have to tell composer three things in order to be able to do this:
So you want to contribute to Silverstripe? Fantastic! You can do this with composer too. You have to tell composer three
things in order to be able to do this:
- Keep the full git repository information
- Include dependencies marked as "developer" requirements
- Use the development version, not the latest stable version
- Keep the full git repository information
- Include dependencies marked as "developer" requirements
- Use the development version, not the latest stable version
The first two steps are done as part of the initial create project using additional arguments.
@ -117,36 +131,38 @@ The first two steps are done as part of the initial create project using additio
composer create-project --keep-vcs --dev silverstripe/installer ./my-project 4.x-dev --prefer-source
```
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.x release line. To check out from master instead,
replace `4.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.x release line. To check out from master instead, replace `4.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
SilverStripe development:
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
* The `docsviewer` module will let you preview changes to the project documentation
* The `buildtools` module which adds [phing](http://phing.info) tasks for creating SilverStripe releases
* The `behat-extension` module allows running [Behat](http://behat.org) integration tests
* The `docsviewer` module will let you preview changes to the project documentation
* The `buildtools` module which adds [phing](http://phing.info) tasks for creating Silverstripe releases
Once the `create-project` command completes, you need to edit the `composer.json` in the project root
and remove the `@stable` markers from the `silverstripe/cms` and `silverstripe/framework` version entries.
Another `composer update --dev` call will now fetch from the development branch instead.
Note that you can also convert an existing composer project with these steps.
Once the `create-project` command completes, you need to edit the `composer.json` in the project root and remove
the `@stable` markers from the `silverstripe/cms` and `silverstripe/framework` version entries.
Another `composer update --dev` call will now fetch from the development branch instead. Note that you can also convert
an existing composer project with these steps.
Please read the ["Contributing Code"](/contributing/code) documentation to find out how to
create forks and send pull requests.
Please read the ["Contributing Code"](/contributing/code) documentation to find out how to create forks and send pull
requests.
# Advanced usage
## 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:
```json
{
"name": "silverstripe/installer",
"description": "The SilverStripe Framework Installer",
"description": "The Silverstripe Framework Installer",
"require": {
"php": ">=7.3",
"silverstripe/cms": "^4",
@ -161,7 +177,8 @@ To remove dependencies, or if you prefer seeing all your dependencies in a text
}
```
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!
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:
@ -171,14 +188,16 @@ composer update
## Using development versions
Composer will by default download the latest stable version of silverstripe/installer.
The `composer.json` file that comes with silverstripe/installer may also explicitly state it requires the stable version of cms and framework - this is to ensure that when developers are getting started, running `composer update` won't upgrade their project to an unstable version
Composer will by default download the latest stable version of silverstripe/installer. The `composer.json` file that
comes with silverstripe/installer may also explicitly state it requires the stable version of cms and framework - this
is to ensure that when developers are getting started, running `composer update` won't upgrade their project to an
unstable version
However it is relatively easy to tell composer to use development versions. Not only
is this required if you want to contribute back to the SilverStripe project, it also allows you to get fixes and API changes early.
However it is relatively easy to tell composer to use development versions. Not only is this required if you want to
contribute back to the Silverstripe project, it also allows you to get fixes and API changes early.
This is a two step process. First you get composer to start a project based on
the latest unstable silverstripe/installer
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-project dev-master
@ -192,24 +211,28 @@ composer create-project silverstripe/installer ./my-project 4.0.x-dev
## Working with project forks and unreleased modules
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:
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.
* 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.
There are many ways that you can address this, but this is one that we recommend, because it minimises the changes you would need to make to switch to an official version in the future.
There are many ways that you can address this, but this is one that we recommend, because it minimises the changes you
would need to make to switch to an official version in the future.
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:
```json
{
"name": "silverstripe/installer",
"description": "The SilverStripe Framework Installer",
"description": "The Silverstripe Framework Installer",
"repositories": [
{
"type": "vcs",
@ -219,13 +242,16 @@ This is how you do it:
}
```
* **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.
* **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 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`.
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.
@ -234,15 +260,21 @@ 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).
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 4.0, then call the branch `4.0`, not `4.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 `4.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.
@ -257,72 +289,74 @@ Open `composer.json`, and find the module's `require`. Then put `as (core versio
}
```
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.
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).
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).
This is not the only way to set things up in Composer. For more information on this topic, read the ["Aliases" chapter of the Composer documentation](http://getcomposer.org/doc/articles/aliases.md).
This is not the only way to set things up in Composer. For more information on this topic, read
the ["Aliases" chapter of the Composer documentation](http://getcomposer.org/doc/articles/aliases.md).
## FAQ
### 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`
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
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
([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),
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
`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).
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
`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).
### How should I name my module?
Follow the packagist.org advice on choosing a [unique name and vendor prefix](https://packagist.org/about). Please don't use the `silverstripe/<modulename>` vendor prefix, since that's reserved
for modules produced by SilverStripe Ltd. In order to declare that your module is
in fact a SilverStripe module, use the "silverstripe" tag in the composer.json file,
and set the "type" to "silverstripe-module".
Follow the packagist.org advice on choosing a [unique name and vendor prefix](https://packagist.org/about). Please don't
use the `silverstripe/<modulename>` vendor prefix, since that's reserved for modules produced by Silverstripe Ltd. In
order to declare that your module is in fact a Silverstripe module, use the "silverstripe" tag in the composer.json
file, and set the "type" to "silverstripe-module".
### What about themes?
Themes are technically just "modules" which are placed in the `themes/` subdirectory.
We denote a special type for them in the `composer.json` (`"type": "silverstripe-theme"`),
which triggers their installation into the correct path.
Themes are technically just "modules" which are placed in the `themes/` subdirectory. We denote a special type for them
in the `composer.json` (`"type": "silverstripe-theme"`), which triggers their installation into the correct path.
### How do I convert an existing project to Composer?
Copy the `composer.json` file from a newer release, and adjust the
version settings in the "require" section to your needs. Then refer to
the [upgrading documentation](/upgrading).
You'll also need to update your webserver configuration
from there (`.htaccess` or `web.config` files), in order to prevent
web access to the composer-generated files.
Copy the `composer.json` file from a newer release, and adjust the version settings in the "require" section to your
needs. Then refer to the [upgrading documentation](/upgrading). You'll also need to update your webserver configuration
from there (`.htaccess` or `web.config` files), in order to prevent web access to the composer-generated files.
### Do I need composer on my live server?
It depends on your deployment process. If you copy or rsync files to your live server,
the process stays the same. If the live server hosts a git repository checkout,
which is updated to push a newer version, you'll also need to run `composer install` afterwards.
We recommend looking into [Composer "lock" files](http://getcomposer.org/doc/01-basic-usage.md#composer-lock-the-lock-file) for this purpose.
It depends on your deployment process. If you copy or rsync files to your live server, the process stays the same. If
the live server hosts a git repository checkout, which is updated to push a newer version, you'll also need to
run `composer install` afterwards. We recommend looking
into [Composer "lock" files](http://getcomposer.org/doc/01-basic-usage.md#composer-lock-the-lock-file) for this purpose.
### Can I keep using Downloads, Subversion Externals or Git Submodules?
Composer is more than just a file downloader. It 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.
which some modules will start relying on. Please check the module README for specific installation instructions.
### I don't want to get development versions of everything!
You don't have to, Composer is designed to work on the constraints you set.
You can declare the ["minimum-stability"](http://getcomposer.org/doc/04-schema.md#minimum-stability)
on your project as suitable, or even whitelist specific modules as tracking
a development branch while keeping others to their stable release.
Read up on [Composer "lock" files](http://getcomposer.org/doc/01-basic-usage.md#composer-lock-the-lock-file) on how this all fits together.
You don't have to, Composer is designed to work on the constraints you set. You can declare
the ["minimum-stability"](http://getcomposer.org/doc/04-schema.md#minimum-stability)
on your project as suitable, or even whitelist specific modules as tracking a development branch while keeping others to
their stable release. Read up
on [Composer "lock" files](http://getcomposer.org/doc/01-basic-usage.md#composer-lock-the-lock-file) on how this all
fits together.

30
docs/en/00_Getting_Started/03_Environment_Management.md
View File

@ -12,8 +12,8 @@ server.
For each of these environments we may require slightly different configurations for our servers. This could be our debug
level, caching backends, or - of course - sensitive information such as database credentials.
To manage environment variables, as well as other server globals, the [api:SilverStripe\Core\Environment] class
provides a set of APIs and helpers.
To manage environment variables, as well as other server globals, the [api:SilverStripe\Core\Environment] class provides
a set of APIs and helpers.
## Security considerations
@ -26,20 +26,23 @@ webserver.
## Managing environment variables with `.env` files
By default a file named `.env` must be placed in your project root (ie: the same folder as your `composer.json`) or the parent
directory. If this file exists, it will be automatically loaded by the framework and the environment variables will be
set. An example `.env` file is included in the default installer named `.env.example`.
By default a file named `.env` must be placed in your project root (ie: the same folder as your `composer.json`) or the
parent directory. If this file exists, it will be automatically loaded by the framework and the environment variables
will be set. An example `.env` file is included in the default installer named `.env.example`.
**Note:** The file must be named exactly `.env` and not any variation (such as `mysite.env` or `.env.mysite`) or it will not be detected automatically. If you wish to load environment variables from a file with a different name, you will need to do so manually. See the [Including an extra `.env` file](#including-an-extra-env-file) section below for more information.
**Note:** The file must be named exactly `.env` and not any variation (such as `mysite.env` or `.env.mysite`) or it will
not be detected automatically. If you wish to load environment variables from a file with a different name, you will
need to do so manually. See the [Including an extra `.env` file](#including-an-extra-env-file) section below for more
information.
## Managing environment variables with Apache
You can set "real" environment variables using Apache. Please
[see the Apache docs for more information](https://httpd.apache.org/docs/current/env.html)
[see the Apache docs for more information](https://httpd.apache.org/docs/current/env.html).
## How to access the environment variables
Accessing the environment varaibles should be done via the `Environment::getEnv()` method
Accessing the environment variables should be done via the `Environment::getEnv()` method.
```php
use SilverStripe\Core\Environment;
@ -68,14 +71,13 @@ SilverStripe\Core\Injector\Injector:
Environment variables cannot be used outside of Injector config as of version 4.2.
[/info]
## Including an extra `.env` file
Sometimes it may be useful to include an extra `.env` file - on a shared local development environment where all
database credentials could be the same. To do this, you can add this snippet to your `app/_config.php` file:
Note that by default variables cannot be overloaded from this file; Existing values will be preferred
over values in this file.
Note that by default variables cannot be overloaded from this file; Existing values will be preferred over values in
this file.
```php
use SilverStripe\Core\EnvironmentLoader;
@ -86,7 +88,7 @@ $loader->loadFile($env);
## Core environment variables
SilverStripe core environment variables are listed here, though you're free to define any you need for your application.
Silverstripe core environment variables are listed here, though you're free to define any you need for your application.
| Name | Description |
| ---- | ----------- |
@ -99,12 +101,12 @@ SilverStripe core environment variables are listed here, though you're free to d
| `SS_DATABASE_PREFIX`| A prefix to add to the database name.|
| `SS_DATABASE_TIMEZONE`| Set the database timezone to something other than the system timezone.
| `SS_DATABASE_NAME` | Set the database name. Assumes the `$database` global variable in your config is missing or empty. |
| `SS_DATABASE_CHOOSE_NAME`| Boolean/Int. If defined, then the system will choose a default database name for you if one isn't give in the $database variable. The database name will be "SS_" followed by the name of the folder into which you have installed SilverStripe. If this is enabled, it means that the phpinstaller will work out of the box without the installer needing to alter any files. This helps prevent accidental changes to the environment. If `SS_DATABASE_CHOOSE_NAME` is an integer greater than one, then an ancestor folder will be used for the database name. This is handy for a site that's hosted from /sites/examplesite/www or /buildbot/allmodules-2.3/build. If it's 2, the parent folder will be chosen; if it's 3 the grandparent, and so on.|
| `SS_DATABASE_CHOOSE_NAME`| Boolean/Int. If defined, then the system will choose a default database name for you if one isn't give in the $database variable. The database name will be "SS_" followed by the name of the folder into which you have installed Silverstripe. If this is enabled, it means that the phpinstaller will work out of the box without the installer needing to alter any files. This helps prevent accidental changes to the environment. If `SS_DATABASE_CHOOSE_NAME` is an integer greater than one, then an ancestor folder will be used for the database name. This is handy for a site that's hosted from /sites/examplesite/www or /buildbot/allmodules-2.3/build. If it's 2, the parent folder will be chosen; if it's 3 the grandparent, and so on.|
| `SS_DEPRECATION_ENABLED` | Enable deprecation notices for this environment.|
| `SS_ENVIRONMENT_TYPE`| The environment type: dev, test or live.|
| `SS_DEFAULT_ADMIN_USERNAME`| The username of the default admin. This is a user with administrative privileges.|
| `SS_DEFAULT_ADMIN_PASSWORD`| The password of the default admin. This will not be stored in the database.|
| `SS_USE_BASIC_AUTH`| Baseline protection for requests handled by SilverStripe. Usually requires additional security measures for comprehensive protection. See [Environment Types](/developer_guides/debugging/environment_types) for caveats.|
| `SS_USE_BASIC_AUTH`| Baseline protection for requests handled by Silverstripe. Usually requires additional security measures for comprehensive protection. See [Environment Types](/developer_guides/debugging/environment_types) for caveats.|
| `SS_SEND_ALL_EMAILS_TO`| If you define this constant, all emails will be redirected to this address.|
| `SS_SEND_ALL_EMAILS_FROM`| If you define this constant, all emails will be sent from this address.|
| `SS_ERROR_LOG` | Relative path to the log file. |

116
docs/en/00_Getting_Started/04_Directory_Structure.md
View File

@ -8,7 +8,7 @@ icon: sitemap
## Introduction
The directory-structure in SilverStripe is built on "convention over configuration", so the placement of some files and
The directory-structure in Silverstripe is built on "convention over configuration", so the placement of some files and
directories is meaningful to its logic.
## Core Structure
@ -16,35 +16,32 @@ directories is meaningful to its logic.
Directory | Description
--------- | -----------
`public/` | Webserver public webroot
`public/assets/` | Images and other files uploaded via the SilverStripe CMS. You can also place your own content inside it, and link to it from within the content area of the CMS.
`public/assets/` | Images and other files uploaded via the Silverstripe CMS. You can also place your own content inside it, and link to it from within the content area of the CMS.
`public/assets/.protected/` | Default location for [protected assets](/developer_guides/files/file_security)
`public/_resources/` | Exposed public files added from modules. Folders within this parent will match that of the source root location (this can be altered by configuration).
`vendor/` | SilverStripe modules and other supporting libraries (the framework is in `vendor/silverstripe/framework`)
`vendor/` | Silverstripe modules and other supporting libraries (the framework is in `vendor/silverstripe/framework`)
`themes/` | Standard theme installation location
## Custom Code Structure
We're using `app/` as the default folder.
Note that until SilverStripe 4.2, this directory was named `mysite/`,
and PHP code was stored in a `code/` rather than `src/` folder.
We're using `app/` as the default folder. Note that until Silverstripe 4.2, this directory was named `mysite/`, and PHP
code was stored in a `code/` rather than `src/` folder.
| Directory | Description |
| Directory | Description |
| --------- | ----------- |
| `app/` | This directory contains all of your code that defines your website. |
| `app/_config` | YAML configuration specific to your application |
| `app/src` | PHP code for model and controller (subdirectories are optional) |
| `app/tests` | PHP Unit tests |
| `app/templates` | HTML [templates](/developer_guides/templates) with *.ss-extension for the `$default` theme |
| `app/css ` | CSS files |
| `app/images ` | Images used in the HTML templates |
| `app/javascript` | Javascript and other script files |
| `app/client` | More complex projects can alternatively contain frontend assets in a common `client` folder |
| `app/themes/<yourtheme>` | Custom nested themes (note: theme structure is described below) |
| `app/` | This directory contains all of your code that defines your website. |
| `app/_config` | YAML configuration specific to your application |
| `app/src` | PHP code for model and controller (subdirectories are optional) |
| `app/tests` | PHP Unit tests |
| `app/templates` | HTML [templates](/developer_guides/templates) with *.ss-extension for the `$default` theme |
| `app/css ` | CSS files |
| `app/images ` | Images used in the HTML templates |
| `app/javascript` | Javascript and other script files |
| `app/client` | More complex projects can alternatively contain frontend assets in a common `client` folder |
| `app/themes/<yourtheme>` | Custom nested themes (note: theme structure is described below) |
Arbitrary directory-names are allowed, as long as they don't collide with
existing modules or the directories lists in "Core Structure".
Here's how you would reconfigure your default folder to `myspecialapp`.
Arbitrary directory-names are allowed, as long as they don't collide with existing modules or the directories lists in
"Core Structure". Here's how you would reconfigure your default folder to `myspecialapp`.
*myspecialapp/_config/config.yml*
@ -56,73 +53,70 @@ SilverStripe\Core\Manifest\ModuleManifest:
project: 'myspecialapp'
```
Check our [JavaScript Coding Conventions](javascript_coding_conventions) for more details
on folder and file naming in SilverStripe core modules.
Check our [JavaScript Coding Conventions](javascript_coding_conventions) for more details on folder and file naming in
Silverstripe core modules.
## Themes Structure
| Directory | Description |
| Directory | Description |
| ------------------ | --------------------------- |
| `themes/simple/` | Standard "simple" theme |
| `themes/<yourtheme>/` | Custom theme base directory |
| `themes/<yourtheme>/templates` | Theme templates |
| `themes/<yourtheme>/css` | Theme CSS files |
| `themes/simple/` | Standard "simple" theme |
| `themes/<yourtheme>/` | Custom theme base directory |
| `themes/<yourtheme>/templates` | Theme templates |
| `themes/<yourtheme>/css` | Theme CSS files |
See [themes](/developer_guides/templates/themes)
See [themes](/developer_guides/templates/themes).
## Module Structure {#module_structure}
Modules are commonly stored as composer packages in the `vendor/` folder.
They need to have a `_config.php` file or a `_config/` directory present,
and should follow the same conventions as posed in "Custom Site Structure".
Modules are commonly stored as composer packages in the `vendor/` folder. They need to have a `_config.php` file or
a `_config/` directory present, and should follow the same conventions as posed in "Custom Site Structure".
Example Forum:
| Directory | Description |
| Directory | Description |
| --------- | ----------- |
| `vendor/silverstripe/blog/`| This directory contains all of your code that defines your website. |
| `vendor/silverstripe/blog/code` | PHP code for model and controller (subdirectories are optional) |
| ... | ... |
| `vendor/silverstripe/blog/`| This directory contains all of your code that defines your website. |
| `vendor/silverstripe/blog/code` | PHP code for model and controller (subdirectories are optional) |
| ... | ... |
Note: Before SilverStripe 4.x, modules were living as top-level folders in the webroot itself.
Some modules might not have been upgraded to support placement in `vendor/`
Note: Before Silverstripe 4.x, modules were living as top-level folders in the webroot itself. Some modules might not
have been upgraded to support placement in `vendor/`.
### Module documentation
Module developers can bundle developer documentation with their code by producing
plain text files inside a 'docs' folder located in the module folder. These files
can be written with the Markdown syntax (See [Contributing Documentation](/contributing/documentation))
Module developers can bundle developer documentation with their code by producing plain text files inside a 'docs'
folder located in the module folder. These files can be written with the Markdown syntax
(see [Contributing Documentation](/contributing/documentation))
and include media such as images or videos.
Inside the `docs/` folder, developers should organise the markdown files into each
separate language they wish to write documentation for (usually just `en`). Inside
each languages' subfolder, developers then have freedom to create whatever structure
they wish for organising the documentation they wish.
Inside the `docs/` folder, developers should organise the markdown files into each separate language they wish to write
documentation for (usually just `en`). Inside each languages' subfolder, developers then have freedom to create whatever
structure they wish for organising the documentation they wish.
Example Blog Documentation:
| Directory | Description |
| Directory | Description |
| --------- | ----------- |
| `vendor/silverstripe/blog/docs` | |
| `vendor/silverstripe/blog/docs/_manifest_exclude` | Empty file to signify that SilverStripe does not need to load classes from this folder |
| `vendor/silverstripe/blog/docs/en/` | English documentation |
| `vendor/silverstripe/blog/docs/en/index.md` | Documentation homepage. Should provide an introduction and links to remaining docs |
| `vendor/silverstripe/blog/docs/en/Getting_Started.md` | Documentation page. Naming convention is Uppercase and underscores. |
| `vendor/silverstripe/blog/docs/en/_images/` | Folder to store any images or media |
| `vendor/silverstripe/blog/docs/en/Some_Topic/` | You can organise documentation into nested folders. Naming convention is Uppercase and underscores. |
| `vendor/silverstripe/blog/docs/en/04_Some_Topic/00_Getting_Started.md`|Structure is created by use of numbered prefixes. This applies to nested folders and documentations pages, index.md should not have a prefix.|
| `vendor/silverstripe/blog/docs` | |
| `vendor/silverstripe/blog/docs/_manifest_exclude` | Empty file to signify that Silverstripe does not need to load classes from this folder |
| `vendor/silverstripe/blog/docs/en/` | English documentation |
| `vendor/silverstripe/blog/docs/en/index.md` | Documentation homepage. Should provide an introduction and links to remaining docs |
| `vendor/silverstripe/blog/docs/en/Getting_Started.md` | Documentation page. Naming convention is Uppercase and underscores. |
| `vendor/silverstripe/blog/docs/en/_images/` | Folder to store any images or media |
| `vendor/silverstripe/blog/docs/en/Some_Topic/` | You can organise documentation into nested folders. Naming convention is Uppercase and underscores. |
| `vendor/silverstripe/blog/docs/en/04_Some_Topic/00_Getting_Started.md`|Structure is created by use of numbered prefixes. This applies to nested folders and documentations pages, index.md should not have a prefix.|
## Autoloading
SilverStripe recursively detects classes in PHP files by building up a manifest used for autoloading,
as well as respecting Composer's built-in autoloading for libraries. This means
in most cases, you don't need to worry about include paths or `require()` calls
in your own code - after adding a new class, simply regenerate the manifest
by using a `flush=1` query parameter. See the ["Manifests" documentation](/developer_guides/execution_pipeline/manifests) for details.
Silverstripe recursively detects classes in PHP files by building up a manifest used for autoloading, as well as
respecting Composer's built-in autoloading for libraries. This means in most cases, you don't need to worry about
include paths or `require()` calls in your own code - after adding a new class, simply regenerate the manifest by using
a `flush=1` query parameter. See the ["Manifests" documentation](/developer_guides/execution_pipeline/manifests) for
details.
## Best Practices
### Making /assets readonly
See [Secure coding](/developer_guides/security/secure_coding#filesystem)

21
docs/en/00_Getting_Started/05_Recipes.md
View File

@ -6,15 +6,24 @@ icon: clipboard
# Recipes
Silverstripe CMS is powered by a system of components in the form of Composer packages. It consists of two types of package:
Silverstripe CMS is powered by a system of components in the form of Composer packages. It consists of two types of
package:
- **Modules**, which provide pieces of functionality (such as `silverstripe/cms` and `silverstripe/framework`)
- **Recipes**, which group related Modules together to make them easier to install and release.
When we announce a new version of Silverstripe CMS and publish a changelog for it, we refer to a new set of _Recipe_ versions, which include new versions of some or all of their associated Modules. The easiest way to keep up to date with new Silverstripe CMS releases is to depend on one of the core Recipes:
When we announce a new version of Silverstripe CMS and publish a changelog for it, we refer to a new set of _Recipe_
versions, which include new versions of some or all of their associated Modules. The easiest way to keep up to date with
new Silverstripe CMS releases is to depend on one of the core Recipes:
- [`silverstripe/recipe-core`](https://packagist.org/packages/silverstripe/recipe-core): Contains only the base framework, without the admin UI or CMS features.
- [`silverstripe/recipe-cms`](https://packagist.org/packages/silverstripe/recipe-cms): Includes `recipe-core`, and adds the admin UI and CMS features. We recommend specifying this recipe in your dependencies.
- [`silverstripe/installer`](https://packagist.org/packages/silverstripe/installer): Includes `recipe-cms`, and adds a default theme for the front-end of your site. We recommend creating new projects based on this recipe (via `composer create-project silverstripe/installer myproject ^4`)
- [`silverstripe/recipe-core`](https://packagist.org/packages/silverstripe/recipe-core): Contains only the base
framework, without the admin UI or CMS features.
- [`silverstripe/recipe-cms`](https://packagist.org/packages/silverstripe/recipe-cms): Includes `recipe-core`, and adds
the admin UI and CMS features. We recommend specifying this recipe in your dependencies.
- [`silverstripe/installer`](https://packagist.org/packages/silverstripe/installer): Includes `recipe-cms`, and adds a
default theme for the front-end of your site. We recommend creating new projects based on this recipe (
via `composer create-project silverstripe/installer myproject ^4`).
When determining whether you are running the latest version of Silverstripe CMS, it is easier to refer to the Recipe version than the individual Module versions, which may not align with Recipe versions. You can use Packagist to find detailed information on what versions of individual modules are contained in each Recipe release.
When determining whether you are running the latest version of Silverstripe CMS, it is easier to refer to the Recipe
version than the individual Module versions, which may not align with Recipe versions. You can use Packagist to find
detailed information on what versions of individual modules are contained in each Recipe release.

41
docs/en/00_Getting_Started/index.md
View File

@ -1,27 +1,24 @@
---
title: Getting Started
introduction: SilverStripe is a web application. This means that you will need to have a webserver and database. We will take you through the setup of the server environment as well the application itself.
introduction: Silverstripe is a web application. This means that you will need to have a
webserver and database. We will take you through the setup of the server environment as well the application itself.
icon: rocket
---
## Server Requirements
SilverStripe requires PHP 7.1 or newer.
It runs on many webservers and databases,
but is most commonly served using Apache and MySQL/MariaDB.
Silverstripe requires PHP 7.1 or newer. It runs on many webservers and databases, but is most commonly served using
Apache and MySQL/MariaDB.
If you are setting up your own environment,
you'll need to consider a few configuration settings
such as URL rewriting and protecting access to certain files.
Refer to our [server requirements](server_requirements) for details.
If you are setting up your own environment, you'll need to consider a few configuration settings such as URL rewriting
and protecting access to certain files. Refer to our [server requirements](server_requirements) for details.
## Quickstart Installation
If you're running Apache with MySQL/MariaDB already,
and know your way around webservers, follow these steps to get started.
SilverStripe is installed via [Composer](https://getcomposer.org), a package management tool for PHP that
lets you install and upgrade the framework and other modules.
Assuming you've got this tool, run the following command to install SilverStripe:
If you're running Apache with MySQL/MariaDB already, and know your way around webservers, follow these steps to get
started. Silverstripe is installed via [Composer](https://getcomposer.org), a package management tool for PHP that lets
you install and upgrade the framework and other modules. Assuming you've got this tool, run the following command to
install Silverstripe:
```
composer create-project silverstripe/installer my-project
@ -29,9 +26,8 @@ composer create-project silverstripe/installer my-project
Within the newly created `my-project` folder, point your webserver at the `public/` folder.
Now create a `.env` file your project root (not the `public/` folder).
It sets up the minimum required [environment variables](environment_management).
Replace the placeholders as required:
Now create a `.env` file your project root (not the `public/` folder). It sets up the minimum
required [environment variables](environment_management). Replace the placeholders as required:
```
SS_DATABASE_CLASS="MySQLDatabase"
@ -50,11 +46,10 @@ Now you should be able to build your database by running this command:
vendor/bin/sake dev/build
```
Your website should be available on your domain now (e.g. `http://localhost`).
The CMS login can be accessed at `/admin`.
Your website should be available on your domain now (e.g. `http://localhost`). The CMS login can be accessed at `/admin`.
For more information on how to maintain your installation or install projects,
check out [Using SilverStripe with Composer](composer).
For more information on how to maintain your installation or install projects, check
out [Using Silverstripe with Composer](composer).
## Guided Installation
@ -62,14 +57,12 @@ If you are unsure on how this all works, please jump on our [lessons](https://ww
Webserver setup is covered in
[Lesson 4: Setting up a local dev environment](https://www.silverstripe.org/learn/lessons/v4/up-and-running-setting-up-a-local-silverstripe-dev-environment-1).
## Keep learning
[CHILDREN]
## Troubleshooting
If you run into trouble, see [the Tips & Tricks forum](https://forum.silverstripe.org/c/tips) or
check our [community help options](https://www.silverstripe.org/community/).
If you run into trouble, see [the Tips & Tricks forum](https://forum.silverstripe.org/c/tips) or get help on
our [Slack channel](https://www.silverstripe.org/community/slack-signup/).

41
docs/en/index.md
View File

@ -1,50 +1,51 @@
---
title: SilverStripe Documentation
summary: Welcome to the SilverStripe Developer Documentation. This website is aimed at website developers looking to learn how to build and manage web applications with the SilverStripe Framework.
title: Silverstripe Documentation
summary: Welcome to the Silverstripe Developer Documentation. This website is aimed at website developers looking to learn how to build and manage web applications with the Silverstripe Framework.
---
## Getting Started with SilverStripe
## Getting Started with Silverstripe
Before you start developing your first web application, you'll need to install the latest version of SilverStripe onto
a web server. The [Getting Started](/getting_started) section will show you what
Before you start developing your first web application, you'll need to install the latest version of Silverstripe onto a
web server. The [Getting Started](/getting_started) section will show you what
[server requirements](/getting_started/server_requirements) you will need to meet and how to
[install SilverStripe with Composer](/getting_started/composer).
[install Silverstripe with Composer](/getting_started/composer).
To check out the features that SilverStripe offers without installing it, read the [Feature Overview](http://www.silverstripe.org/software/)
To check out the features that Silverstripe offers without installing it, read
the [Feature Overview](http://www.silverstripe.org/software/)
and play with our [interactive demos](http://silverstripe.org/try).
## Getting support
SilverStripe has an wide range of options for getting support:
Silverstripe has a wide range of options for getting support:
* Get help on our [Slack channel](https://www.silverstripe.org/community/slack-signup/)
* Join our [forum](https://forum.silverstripe.org)
* Ask technical questions on [Stack Overflow](https://stackoverflow.com/questions/tagged/silverstripe)
* Get help on our [Slack channel](https://www.silverstripe.org/community/slack-signup/)
* Read the technical reference in our [API Documentation](http://api.silverstripe.org/)
* Get a user-focused overview of the CMS features in our [User Help](http://userhelp.silverstripe.com)
* Discuss new features, API changes and the development [roadmap](http://www.silverstripe.org/software/roadmap/)
on the ["feature ideas" category](https://forum.silverstripe.org/c/feature-ideas) in our forums
## Building your first Silverstripe Web application
## Building your first SilverStripe Web application
Once you have completed the [Getting Started](/getting_started) guide and have got Silverstripe installed and running,
the following [Tutorials](http://silverstripe.org/learn/lessons) will lead through the basics and core concepts of
Silverstripe.
Once you have completed the [Getting Started](/getting_started) guide and have got SilverStripe
installed and running, the following [Tutorials](http://silverstripe.org/learn/lessons) will lead through the basics and core concepts of
SilverStripe.
Make sure you know the basic concepts of PHP7 before attempting to follow the tutorials. If you have not programmed with
PHP5 be sure to read
the [Introduction to PHP5 (zend.com)](http://devzone.zend.com/6/php-101--php-for-the-absolute-beginner).
Make sure you know the basic concepts of PHP5 before attempting to follow the tutorials. If you have not programmed with PHP5 be sure to read the [Introduction to PHP5 (zend.com)](http://devzone.zend.com/6/php-101--php-for-the-absolute-beginner).
## Silverstripe Concepts
## SilverStripe Concepts
The [Developer Guides](/developer_guides) contain more detailed documentation on certain SilverStripe topics, 'how to'
The [Developer Guides](/developer_guides) contain more detailed documentation on certain Silverstripe topics, 'how to'
examples and reference documentation.
[CHILDREN Folder=02_Developer_Guides]
## Contributing to SilverStripe
## Contributing to Silverstripe
The SilverStripe Framework, Content Management System and related websites are open source and welcome community
The Silverstripe Framework, Content Management System and related websites are open source and welcome community
contributions.
[CHILDREN Folder=05_Contributing]