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 summary: What you will need to run Silverstripe CMS on a web server
--- ---
# Requirements # Requirements
Silverstripe CMS needs to be installed on a web server. Content authors and website administrators use their web browser 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
* PHP >=7.1 * PHP >=7.1
* PHP extensions: `ctype`, `dom`, `fileinfo`, `hash`, `intl`, `mbstring`, `session`, `simplexml`, `tokenizer`, `xml` * PHP extensions: `ctype`, `dom`, `fileinfo`, `hash`, `intl`, `mbstring`, `session`, `simplexml`, `tokenizer`, `xml`
* PHP configuration: `memory_limit` with at least `48M` * PHP configuration: `memory_limit` with at least `48M`
* PHP extension for image manipulation: Either `gd` or `imagick` * PHP extension for image manipulation: Either `gd` or `imagick`
* PHP extension for a database connector (e.g. `pdo` or `mysqli`) * 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. Use [phpinfo()](http://php.net/manual/en/function.phpinfo.php) to inspect your configuration.
## Database ## Database
* MySQL >=5.6 (built-in, [commercially supported](https://www.silverstripe.org/software/addons/silverstripe-commercially-supported-module-list/)) * MySQL >=5.6 (
* PostgreSQL ([third party module](https://addons.silverstripe.org/add-ons/silverstripe/postgresql), community supported) built-in, [commercially supported](https://www.silverstripe.org/software/addons/silverstripe-commercially-supported-module-list/))
* SQL Server ([third party module](https://addons.silverstripe.org/add-ons/silverstripe/mssql), community supported) * PostgreSQL ([third party module](https://addons.silverstripe.org/add-ons/silverstripe/postgresql), community
* SQLite ([third party module](https://addons.silverstripe.org/add-ons/silverstripe/sqlite3), community supported) 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 ### 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.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.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 - 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. - 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 ### 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 ## Webserver Configuration
### Overview ### Overview
SilverStripe needs to handle a variety of HTTP requests, Silverstripe needs to handle a variety of HTTP requests, and relies on the hosting environment to be configured securely
and relies on the hosting environment to be configured securely to to enforce restrictions. There are secure defaults in place for Apache, but you should be aware of the configuration
enforce restrictions. There are secure defaults in place for Apache, regardless of your webserver setup.
but you should be aware of the configuration regardless of your webserver setup.
### Public webroot ### Public webroot
The webroot of your webserver should be configured to the `public/` subfolder. The webroot of your webserver should be configured to the `public/` subfolder. Projects created prior to Silverstripe
Projects created prior to SilverStripe 4.1 might be using the main project 4.1 might be using the main project folder as the webroot. In this case, you are responsible for ensuring access to
folder as the webroot. In this case, you are responsible for ensuring system files such as configuration in `*.yml` is protected from public access. We strongly recommend switching to more
access to system files such as configuration in `*.yml` is protected secure hosting via the `public/`. See [4.1.0 upgrading guide](/changelogs/4.1.0).
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 ### Filesystem permissions
During runtime, Silverstripe needs read access for the webserver user to your base path (including your webroot). During runtime, Silverstripe needs read access for the webserver user to your base path (including your webroot). It
It also needs write access for the webserver user to the following locations: 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) * `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 * `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) [Manifests](/developer_guides/execution_pipeline/manifests), [Object Caching](/developer_guides/performance/caching)
and [Partial Template Caching](/developer_guides/templates/partial_template_caching). and [Partial Template Caching](/developer_guides/templates/partial_template_caching).
See [Environment Management](/getting_started/environment_management). See [Environment Management](/getting_started/environment_management).
If you aren't explicitly [packaging](#building-packaging-deployment) If you aren't explicitly [packaging](#building-packaging-deployment)
your Silverstripe project during your deployment process, your Silverstripe project during your deployment process, additional write access may be required to generate supporting
additional write access may be required to generate supporting files on the fly. files on the fly. This is not recommended, because it can lead to extended execution times as well as cause
This is not recommended, because it can lead to extended execution times inconsistencies between multiple server environments when manifest and cache storage isn't shared between servers.
as well as cause inconsistencies between multiple server environments
when manifest and cache storage isn't shared between servers.
### Assets ### Assets
SilverStripe allows CMS authors to upload files into the `public/assets/` folder, Silverstripe allows CMS authors to upload files into the `public/assets/` folder, which should be served by your
which should be served by your webserver. **No PHP execution should be allowed in this folder**. webserver. **No PHP execution should be allowed in this folder**. This is configured for Apache by default
This is configured for Apache by default via `public/assets/.htaccess`. via `public/assets/.htaccess`. The file is generated dynamically during the `dev/build` stage.
The file is generated dynamically during the `dev/build` stage.
Additionally, access is whitelisted by file extension through a Additionally, access is whitelisted by file extension through a dynamically generated whitelist based on
dynamically generated whitelist based on the `File.allowed_extensions` setting the `File.allowed_extensions` setting
(see [File Security](/developer_guides/files/file_security#file-types)). (see [File Security](/developer_guides/files/file_security#file-types)). This whitelist uses the same defaults
This whitelist uses the same defaults configured through file upload configured through file upload through Silverstripe, so is considered a second line of defence.
through SilverStripe, so is considered a second line of defence.
### Secure Assets {#secure-assets} ### Secure Assets {#secure-assets}
Files can be kept in draft stage, Files can be kept in draft stage, and access restricted to certain user groups. These files are stored in a
and access restricted to certain user groups. special `.protected/` folder (defaulting to `public/assets/.protected/`).
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 this folder should be denied by your webserver**.
Requests to files in the `.protected/` folder Requests to files in the `.protected/` folder are routed to PHP by default when using Apache,
are routed to PHP by default when using Apache, through `public/assets/.htaccess`. through `public/assets/.htaccess`. If you are using another webserver, please follow our guides to ensure a secure
If you are using another webserver, please follow our guides to ensure a secure setup. setup. See [Developer Guides: File Security](/developer_guides/files/file_security) for details.
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/`. For additional security, we recommend moving the `.protected/` folder out of `public/assets/`. This removes the
This removes the possibility of a misconfigured webserver accidentally exposing possibility of a misconfigured webserver accidentally exposing these files under URL paths, and forces read access via
these files under URL paths, and forces read access via PHP. PHP.
This can be configured via [.env](/getting_started/environment_management) variable, This can be configured via [.env](/getting_started/environment_management) variable, relative to the `index.php`
relative to the `index.php` location. location.
``` ```
SS_PROTECTED_ASSETS_PATH="../.protected/" 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} ### 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), It is common to build a Silverstripe application into a package on one environment (e.g. a CI server), and then deploy
and then deploy the package to a (separate) webserver environment(s). the package to a (separate) webserver environment(s). This approach relies on all auto-generated files required by
This approach relies on all auto-generated files required by SilverStripe to Silverstripe to be included in the package, or generated on the fly on each webserver environment.
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. The easiest way to ensure this is to commit auto generated files to source control. If those changes are considered too
If those changes are considered too noisy, here's some pointers for auto-generated files noisy, here's some pointers for auto-generated files to trigger and include in a deployment package:
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). via [silverstripe/vendor-plugin](https://github.com/silverstripe/vendor-plugin).
See [Templates: Requirements](/developer_guides/templates/requirements#exposing-assets-webroot). 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 * `.graphql/` and `public/_graphql/`: Schema and type definitions required by CMS and any GraphQL API endpoint.
[silverstripe/graphql v4](https://github.com/silverstripe/silverstripe-graphql). Generated through
Triggered by `dev/build`, or a [GraphQL Schema Build](/developer_guides/graphql/getting_started/building_the_schema). [silverstripe/graphql v4](https://github.com/silverstripe/silverstripe-graphql). Triggered by `dev/build`, or
* Various recipes create default files in `app/` and `public/` on `composer install` 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 and `composer update` via
[silverstripe/recipe-plugin](https://github.com/silverstripe/recipe-plugin). [silverstripe/recipe-plugin](https://github.com/silverstripe/recipe-plugin).
### Web Worker Concurrency ### Web Worker Concurrency
It's generally a good idea to run multiple workers to serve multiple HTTP requests It's generally a good idea to run multiple workers to serve multiple HTTP requests to Silverstripe concurrently. The
to SilverStripe concurrently. The exact number depends on your website needs. exact number depends on your website needs. The CMS attempts to request multiple views concurrently. It also
The CMS attempts to request multiple views concurrently. routes [protected and draft files](/developer_guides/files/file_security)
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
through SilverStripe. This can increase your concurrency requirements, draft files in the CMS.
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), When allowing upload of large files through the CMS (through PHP settings), these files might be used
these files might be used as [protected and draft files](/developer_guides/files/file_security). as [protected and draft files](/developer_guides/files/file_security). Files in this state get served by Silverstripe
Files in this state get served by SilverStripe rather than your webserver. rather than your webserver. Since the framework uses [PHP streams](https://www.php.net/manual/en/ref.stream.php), this
Since the framework uses [PHP streams](https://www.php.net/manual/en/ref.stream.php), allows serving of files larger than your PHP memory limit. Please be aware that streaming operations don't count towards
this allows serving of files larger than your PHP memory limit. PHP's [max_execution_time](https://www.php.net/manual/en/function.set-time-limit.php), which can risk exhaustion of web
Please be aware that streaming operations don't count towards worker pools for long-running downloads.
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 ### URL Rewriting
SilverStripe expects URL paths to be rewritten to `public/index.php`. Silverstripe expects URL paths to be rewritten to `public/index.php`. For Apache, this is preconfigured
For Apache, this is preconfigured through `.htaccess` files, through `.htaccess` files, and expects using the `mod_rewrite` module. By default, these files are located
and expects using the `mod_rewrite` module. in `public/.htaccess` and `public/assets/.htaccess`.
By default, these files are located in `public/.htaccess` and `public/assets/.htaccess`.
### HTTP Headers ### HTTP Headers
SilverStripe can add HTTP headers to reponses it handles directly. Silverstripe can add HTTP headers to responses it handles directly. These headers are often sensitive, for example
These headers are often sensitive, for example preventing HTTP caching for responses preventing HTTP caching for responses displaying data based on user sessions, or when serving protected assets. You need
displaying data based on user sessions, or when serving protected assets. to ensure those headers are kept in place in your webserver. For example, Apache allows this
You need to ensure those headers are kept in place in your webserver. through `Header setifempty` (see [docs](https://httpd.apache.org/docs/current/mod/mod_headers.html#header)).
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/) See [Developer Guide: Performance](/developer_guides/performance/)
and [Developer Guides: File Security](/developer_guides/files/file_security) for more details. 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, Silverstripe relies on the `Host` header to construct URLs such as "reset password" links, so you'll need to ensure that
so you'll need to ensure that the systems hosting it only allow valid values for this header. 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). See [Developer Guide: Security - Request hostname forgery](/developer_guides/security/secure_coding#request-hostname-forgery)
.
### CDNs and other Reverse Proxies ### CDNs and other Reverse Proxies
If your Silverstripe site is hosted behind multiple HTTP layers, If your Silverstripe site is hosted behind multiple HTTP layers, you're in charge of controlling which forwarded headers
you're in charge of controlling which forwarded headers are considered valid, are considered valid, and which IPs can set them.
and which IPs can set them. See [Developer Guide: Security - Request hostname forgery](/developer_guides/security/secure_coding#request-hostname-forgery). See [Developer Guide: Security - Request hostname forgery](/developer_guides/security/secure_coding#request-hostname-forgery)
.
### Symlinks ### Symlinks
SilverStripe is a modular system, with modules installed and updated Silverstripe is a modular system, with modules installed and updated via the `composer` PHP dependency manager. These
via the `composer` PHP dependency manager. These are usually stored in `vendor/`, are usually stored in `vendor/`, outside of the `public/` webroot. Since many modules rely on serving frontend assets
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
such as CSS files or images, these are mapped over to the `public/_resources/` folder automatically. supports it, this is achieved through symlinks. Depending on your hosting and deployment mechanisms, you may need to
If the filesystem supports it, this is achieved through symlinks. configure the plugin to copy files instead.
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. See [silverstripe/vendor-plugin](https://github.com/silverstripe/vendor-plugin) for details.
### Caches ### Caches
Silverstripe relies on various [caches](/developer_guides/performance/caching/) Silverstripe relies on various [caches](/developer_guides/performance/caching/)
to achieve performant responses. By default, those caches are stored in a temporary filesystem folder, to achieve performant responses. By default, those caches are stored in a temporary filesystem folder, and are not
and are not shared between multiple server instances. Alternative cache backends such as Redis can be shared between multiple server instances. Alternative cache backends such as Redis can be
[configured](/developer_guides/performance/caching/). [configured](/developer_guides/performance/caching/).
While cache objects can expire, when using filesystem caching the files are not actively pruned. While cache objects can expire, when using filesystem caching the files are not actively pruned. For long-lived server
For long-lived server instances, this can become a capacity issue over time - see instances, this can become a capacity issue over time - see
[workaround](https://github.com/silverstripe/silverstripe-framework/issues/6678). [workaround](https://github.com/silverstripe/silverstripe-framework/issues/6678).
### Error pages ### Error pages
The default installation includes [silverstripe/errorpage](https://addons.silverstripe.org/add-ons/silverstripe/errorpage), The default installation
which generates static error pages that bypass PHP execution when those pages are published in the CMS. includes [silverstripe/errorpage](https://addons.silverstripe.org/add-ons/silverstripe/errorpage), which generates
Once published, the static files are located in `public/assets/error-404.html` and `public/assets/error-500.html`. static error pages that bypass PHP execution when those pages are published in the CMS. Once published, the static files
The default `public/.htaccess` file is configured to have Apache serve those pages based on their HTTP status code. 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) ### Other webservers (Nginx, IIS, Lighttpd)
Serving through webservers other than Apache requires more manual configuration, Serving through webservers other than Apache requires more manual configuration, since the defaults configured
since the defaults configured through `.htaccess` don't apply. through `.htaccess` don't apply. Please apply the considerations above to your webserver to ensure a secure hosting
Please apply the considerations above to your webserver to ensure a secure hosting environment. environment. In particular, configure protected assets correctly to avoid exposing draft or protected files uploaded
In particular, configure protected assets correctly to avoid exposing draft or protected files uploaded through the CMS. through the CMS.
There are various community supported installation instructions for different environments. There are various community supported installation instructions for different environments. Nginx is a popular choice,
Nginx is a popular choice, see [Nginx webserver configuration](https://forum.silverstripe.org/t/nginx-webserver-configuration/2246). 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 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)). (
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 Additionally, there are community supported guides for installing Silverstripe on various environments:
on various environments:
* [Hosting via Bitnami](https://bitnami.com/stack/silverstripe/virtual-machine): In the cloud or as a locally hosted virtual machine * [Hosting via Bitnami](https://bitnami.com/stack/silverstripe/virtual-machine): In the cloud or as a locally hosted
* [Vagrant/Virtualbox with CentOS](https://forum.silverstripe.org/t/installing-via-vagrant-virtualbox-with-centos/2248) virtual machine
* [macOS with Homebrew](https://forum.silverstripe.org/t/installing-on-osx-with-homebrew/2247) * [Vagrant/Virtualbox with CentOS](https://forum.silverstripe.org/t/installing-via-vagrant-virtualbox-with-centos/2248)
* [macOS with MAMP](https://forum.silverstripe.org/t/installing-on-osx-with-mamp/2249) * [macOS with Homebrew](https://forum.silverstripe.org/t/installing-on-osx-with-homebrew/2247)
* [Windows with WAMP](https://forum.silverstripe.org/t/installing-on-windows-via-wamp/2250) * [macOS with MAMP](https://forum.silverstripe.org/t/installing-on-osx-with-mamp/2249)
* [Vagrant with silverstripe-australia/vagrant-environment](https://github.com/silverstripe-australia/vagrant-environment) * [Windows with WAMP](https://forum.silverstripe.org/t/installing-on-windows-via-wamp/2250)
* [Vagrant with BetterBrief/vagrant-skeleton](https://github.com/BetterBrief/vagrant-skeleton) * [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.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 | | | 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.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/) | | 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 ## CMS browser requirements
SilverStripe CMS supports the following web browsers: Silverstripe CMS supports the following web browsers:
* Google Chrome * Google Chrome
* Internet Explorer 11 * Internet Explorer 11
* Microsoft Edge * Microsoft Edge
* Mozilla Firefox * 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 ## 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 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 guidelines for HTML, CSS, JavaScript, and accessibility, in addition to meeting specific guide lines, such as
e-government requirements. 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 summary: What is composer and how to use it with Silverstripe CMS
--- ---
# Using SilverStripe with Composer # Using Silverstripe with Composer
## Requirements ## Requirements
[Composer](http://getcomposer.org/) is a package management tool for PHP that lets you install and upgrade SilverStripe and its modules. [Composer](http://getcomposer.org/) is a package management tool for PHP that lets you install and upgrade Silverstripe
We also have separate instructions for [installing modules with Composer](/developer_guides/extending/modules). 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. Next, [install composer](https://getcomposer.org/download/). For our documentation we assume the `composer` command is
You should now be able to run the command: installed globally. You should now be able to run the command:
``` ```
composer help composer help
@ -21,24 +24,23 @@ composer help
## Create a new site ## Create a new site
Composer can create a new site for you, using the installer as a template. Composer can create a new site for you, using the installer as a template. By default it will download the latest stable
By default it will download the latest stable version: version:
``` ```
composer create-project silverstripe/installer my-project composer create-project silverstripe/installer my-project
``` ```
If you want to get all additional fixtures for testing, such as behat and phpunit configuration, If you want to get all additional fixtures for testing, such as behat and phpunit configuration, an
an example `.env.example` file, and all documentation, then it's recommended to use `--prefer-source` example `.env.example` file, and all documentation, then it's recommended to use `--prefer-source`
to include these files. to include these files.
If you want a minimal installation with the bare essentials to get working without any additional overhead, If you want a minimal installation with the bare essentials to get working without any additional overhead, and don't
and don't plan on contributing back changes to framework, use `--prefer-dist` (default) for a more lightweight install. 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. `./my-project` should be the root directory where your site will live. For example, on OS X, you might use a
For example, on OS X, you might use a subdirectory of `~/Sites`. subdirectory of `~/Sites`. As long as your web server is up and running, this will get all the code that you need. Now
As long as your web server is up and running, this will get all the code that you need. visit the site in your web browser, and the installation process will be completed.
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: 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 composer create-project silverstripe/installer ./my-project 4.3.3
``` ```
When `create-project` is used with a release version like above, When `create-project` is used with a release version like above, it will try to get the code from archives instead of
it will try to get the code from archives instead of creating creating git repositories. If you're planning to contribute to Silverstripe,
git repositories. If you're planning to contribute to SilverStripe,
see [Using development versions](#using-development-versions). see [Using development versions](#using-development-versions).
## Adding modules to your project ## Adding modules to your project
Composer isn't only used to download SilverStripe CMS, it is also used to manage all SilverStripe modules. Composer isn't only used to download Silverstripe CMS, it is also used to manage all Silverstripe modules. You can find
You can find thousands of modules on [https://addons.silverstripe.org](https://addons.silverstripe.org). thousands of modules on [https://addons.silverstripe.org](https://addons.silverstripe.org). Installing a module can be
Installing a module can be done with the following command: done with the following command:
``` ```
composer require silverstripe/blog 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 composer require silverstripe/blog ^2
``` ```
[warning] [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] [/warning]
## Updating dependencies ## 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: 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 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 ## 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: 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
* Check `composer.lock` into your repository. necessary testing.
* Deploy your project code base, using the deployment tool of your choice. * Check `composer.lock` into your repository.
* 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. * 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 ## Composer managed modules, Git and .gitignore
Modules and themes managed by Composer should not be committed with your projects source code. Modules and themes managed by Composer should not be committed with your projects source code. Silverstripe ships with
SilverStripe ships with a [.gitignore](http://git-scm.com/docs/gitignore) file by default which prevents this. a [.gitignore](http://git-scm.com/docs/gitignore) file by default which prevents this. For more details
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). 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} ## Dev Environments for Contributing Code {#contributing}
So you want to contribute to SilverStripe? Fantastic! You can do this with composer too. So you want to contribute to Silverstripe? Fantastic! You can do this with composer too. You have to tell composer three
You have to tell composer three things in order to be able to do this: things in order to be able to do this:
- Keep the full git repository information - Keep the full git repository information
- Include dependencies marked as "developer" requirements - Include dependencies marked as "developer" requirements
- Use the development version, not the latest stable version - 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. 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 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, The process will take a bit longer, since all modules are checked out as full git repositories which you can work on.
replace `4.x-dev` with `dev-master` (more info on [composer version naming](http://getcomposer.org/doc/02-libraries.md#specifying-the-version)). 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 `--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:
SilverStripe development:
* The `behat-extension` module allows running [Behat](http://behat.org) integration tests * 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 `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 `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 Once the `create-project` command completes, you need to edit the `composer.json` in the project root and remove
and remove the `@stable` markers from the `silverstripe/cms` and `silverstripe/framework` version entries. 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. Another `composer update --dev` call will now fetch from the development branch instead. Note that you can also convert
Note that you can also convert an existing composer project with these steps. an existing composer project with these steps.
Please read the ["Contributing Code"](/contributing/code) documentation to find out how to Please read the ["Contributing Code"](/contributing/code) documentation to find out how to create forks and send pull
create forks and send pull requests. requests.
# Advanced usage # Advanced usage
## Manually editing composer.json ## 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 ```json
{ {
"name": "silverstripe/installer", "name": "silverstripe/installer",
"description": "The SilverStripe Framework Installer", "description": "The Silverstripe Framework Installer",
"require": { "require": {
"php": ">=7.3", "php": ">=7.3",
"silverstripe/cms": "^4", "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: Save your file, and then run the following command to refresh the installed packages:
@ -171,14 +188,16 @@ composer update
## Using development versions ## Using development versions
Composer will by default download the latest stable version of silverstripe/installer. Composer will by default download the latest stable version of silverstripe/installer. The `composer.json` file that
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 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 However it is relatively easy to tell composer to use development versions. Not only is this required if you want to
is this required if you want to contribute back to the SilverStripe project, it also allows you to get fixes and API changes early. 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 This is a two step process. First you get composer to start a project based on the latest unstable
the latest unstable silverstripe/installer silverstripe/installer
``` ```
composer create-project silverstripe/installer ./my-project dev-master 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 ## 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 By default, Composer will install modules listed on the Packagist site. There are a few reasons that you might not want
want to do this. For example: 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 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 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: 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 ```json
{ {
"name": "silverstripe/installer", "name": "silverstripe/installer",
"description": "The SilverStripe Framework Installer", "description": "The Silverstripe Framework Installer",
"repositories": [ "repositories": [
{ {
"type": "vcs", "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 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. 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 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 ### 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. 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 ## FAQ
### Error "The requested package silverstripe/framework 1.0.0 could not be found" ### 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. as described above, or by checking out the `silverstripe-installer` project directly from version control. In order to
In order to use Composer on archive downloads from silverstripe.org, or other unversioned sources, use Composer on archive downloads from silverstripe.org, or other unversioned sources, an advanced workaround is to set
an advanced workaround is to set the `COMPOSER_ROOT_VERSION` before every command the `COMPOSER_ROOT_VERSION` before every command
([details](http://getcomposer.org/doc/03-cli.md#composer-root-version)) ([details](http://getcomposer.org/doc/03-cli.md#composer-root-version))
### How do I convert an existing module to using Composer? ### 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
create a `composer.json`, and either commit it or send a pull request to the module author. commit it or send a pull request to the module author. Look at existing modules like
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. the ["blog" module](https://github.com/silverstripe/silverstripe-blog/blob/master/composer.json) for good examples on
It's important that the file contains a custom "type" to declare it as a 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)). `silverstripe-module` or `silverstripe-theme` (
Then register the module on [packagist.org](http://packagist.org). 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? ### 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 Follow the packagist.org advice on choosing a [unique name and vendor prefix](https://packagist.org/about). Please don't
for modules produced by SilverStripe Ltd. In order to declare that your module is use the `silverstripe/<modulename>` vendor prefix, since that's reserved for modules produced by Silverstripe Ltd. In
in fact a SilverStripe module, use the "silverstripe" tag in the composer.json file, order to declare that your module is in fact a Silverstripe module, use the "silverstripe" tag in the composer.json
and set the "type" to "silverstripe-module". file, and set the "type" to "silverstripe-module".
### What about themes? ### What about themes?
Themes are technically just "modules" which are placed in the `themes/` subdirectory. Themes are technically just "modules" which are placed in the `themes/` subdirectory. We denote a special type for them
We denote a special type for them in the `composer.json` (`"type": "silverstripe-theme"`), in the `composer.json` (`"type": "silverstripe-theme"`), which triggers their installation into the correct path.
which triggers their installation into the correct path.
### How do I convert an existing project to Composer? ### How do I convert an existing project to Composer?
Copy the `composer.json` file from a newer release, and adjust the Copy the `composer.json` file from a newer release, and adjust the version settings in the "require" section to your
version settings in the "require" section to your needs. Then refer to needs. Then refer to the [upgrading documentation](/upgrading). You'll also need to update your webserver configuration
the [upgrading documentation](/upgrading). from there (`.htaccess` or `web.config` files), in order to prevent web access to the composer-generated files.
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? ### Do I need composer on my live server?
It depends on your deployment process. If you copy or rsync files to your 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 process stays the same. If the live server hosts a git repository checkout, the live server hosts a git repository checkout, which is updated to push a newer version, you'll also need to
which is updated to push a newer version, you'll also need to run `composer install` afterwards. run `composer install` afterwards. We recommend looking
We recommend looking into [Composer "lock" files](http://getcomposer.org/doc/01-basic-usage.md#composer-lock-the-lock-file) for this purpose. 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? ### 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 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) [autoloading](http://getcomposer.org/doc/01-basic-usage.md#autoloading)
or [scripts](http://getcomposer.org/doc/articles/scripts.md) or [scripts](http://getcomposer.org/doc/articles/scripts.md)
which some modules will start relying on. which some modules will start relying on. Please check the module README for specific installation instructions.
Please check the module README for specific installation instructions.
### I don't want to get development versions of everything! ### 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 don't have to, Composer is designed to work on the constraints you set. You can declare
You can declare the ["minimum-stability"](http://getcomposer.org/doc/04-schema.md#minimum-stability) the ["minimum-stability"](http://getcomposer.org/doc/04-schema.md#minimum-stability)
on your project as suitable, or even whitelist specific modules as tracking on your project as suitable, or even whitelist specific modules as tracking a development branch while keeping others to
a development branch while keeping others to their stable release. their stable release. Read up
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. 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 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. 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 To manage environment variables, as well as other server globals, the [api:SilverStripe\Core\Environment] class provides
provides a set of APIs and helpers. a set of APIs and helpers.
## Security considerations ## Security considerations
@ -26,20 +26,23 @@ webserver.
## Managing environment variables with `.env` files ## 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 By default a file named `.env` must be placed in your project root (ie: the same folder as your `composer.json`) or the
directory. If this file exists, it will be automatically loaded by the framework and the environment variables will be parent directory. If this file exists, it will be automatically loaded by the framework and the environment variables
set. An example `.env` file is included in the default installer named `.env.example`. 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 ## Managing environment variables with Apache
You can set "real" environment variables using Apache. Please 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 ## 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 ```php
use SilverStripe\Core\Environment; 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. Environment variables cannot be used outside of Injector config as of version 4.2.
[/info] [/info]
## Including an extra `.env` file ## Including an extra `.env` file
Sometimes it may be useful to include an extra `.env` file - on a shared local development environment where all 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: 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 Note that by default variables cannot be overloaded from this file; Existing values will be preferred over values in
over values in this file. this file.
```php ```php
use SilverStripe\Core\EnvironmentLoader; use SilverStripe\Core\EnvironmentLoader;
@ -86,7 +88,7 @@ $loader->loadFile($env);
## Core environment variables ## 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 | | 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_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_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_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_DEPRECATION_ENABLED` | Enable deprecation notices for this environment.|
| `SS_ENVIRONMENT_TYPE`| The environment type: dev, test or live.| | `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_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_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_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_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. | | `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 ## 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. directories is meaningful to its logic.
## Core Structure ## Core Structure
@ -16,35 +16,32 @@ directories is meaningful to its logic.
Directory | Description Directory | Description
--------- | ----------- --------- | -----------
`public/` | Webserver public webroot `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/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). `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 `themes/` | Standard theme installation location
## Custom Code Structure ## Custom Code Structure
We're using `app/` as the default folder. We're using `app/` as the default folder. Note that until Silverstripe 4.2, this directory was named `mysite/`, and PHP
Note that until SilverStripe 4.2, this directory was named `mysite/`, code was stored in a `code/` rather than `src/` folder.
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/` | This directory contains all of your code that defines your website. |
| `app/_config` | YAML configuration specific to your application | | `app/_config` | YAML configuration specific to your application |
| `app/src` | PHP code for model and controller (subdirectories are optional) | | `app/src` | PHP code for model and controller (subdirectories are optional) |
| `app/tests` | PHP Unit tests | | `app/tests` | PHP Unit tests |
| `app/templates` | HTML [templates](/developer_guides/templates) with *.ss-extension for the `$default` theme | | `app/templates` | HTML [templates](/developer_guides/templates) with *.ss-extension for the `$default` theme |
| `app/css ` | CSS files | | `app/css ` | CSS files |
| `app/images ` | Images used in the HTML templates | | `app/images ` | Images used in the HTML templates |
| `app/javascript` | Javascript and other script files | | `app/javascript` | Javascript and other script files |
| `app/client` | More complex projects can alternatively contain frontend assets in a common `client` folder | | `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/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
Arbitrary directory-names are allowed, as long as they don't collide with "Core Structure". Here's how you would reconfigure your default folder to `myspecialapp`.
existing modules or the directories lists in "Core Structure".
Here's how you would reconfigure your default folder to `myspecialapp`.
*myspecialapp/_config/config.yml* *myspecialapp/_config/config.yml*
@ -56,73 +53,70 @@ SilverStripe\Core\Manifest\ModuleManifest:
project: 'myspecialapp' project: 'myspecialapp'
``` ```
Check our [JavaScript Coding Conventions](javascript_coding_conventions) for more details Check our [JavaScript Coding Conventions](javascript_coding_conventions) for more details on folder and file naming in
on folder and file naming in SilverStripe core modules. Silverstripe core modules.
## Themes Structure ## Themes Structure
| Directory | Description | | Directory | Description |
| ------------------ | --------------------------- | | ------------------ | --------------------------- |
| `themes/simple/` | Standard "simple" theme | | `themes/simple/` | Standard "simple" theme |
| `themes/<yourtheme>/` | Custom theme base directory | | `themes/<yourtheme>/` | Custom theme base directory |
| `themes/<yourtheme>/templates` | Theme templates | | `themes/<yourtheme>/templates` | Theme templates |
| `themes/<yourtheme>/css` | Theme CSS files | | `themes/<yourtheme>/css` | Theme CSS files |
See [themes](/developer_guides/templates/themes).
See [themes](/developer_guides/templates/themes)
## Module Structure {#module_structure} ## Module Structure {#module_structure}
Modules are commonly stored as composer packages in the `vendor/` folder. Modules are commonly stored as composer packages in the `vendor/` folder. They need to have a `_config.php` file or
They need to have a `_config.php` file or a `_config/` directory present, a `_config/` directory present, and should follow the same conventions as posed in "Custom Site Structure".
and should follow the same conventions as posed in "Custom Site Structure".
Example Forum: Example Forum:
| Directory | Description | | Directory | Description |
| --------- | ----------- | | --------- | ----------- |
| `vendor/silverstripe/blog/`| This directory contains all of your code that defines your website. | | `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/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. Note: Before Silverstripe 4.x, modules were living as top-level folders in the webroot itself. Some modules might not
Some modules might not have been upgraded to support placement in `vendor/` have been upgraded to support placement in `vendor/`.
### Module documentation ### Module documentation
Module developers can bundle developer documentation with their code by producing Module developers can bundle developer documentation with their code by producing plain text files inside a 'docs'
plain text files inside a 'docs' folder located in the module folder. These files folder located in the module folder. These files can be written with the Markdown syntax
can be written with the Markdown syntax (See [Contributing Documentation](/contributing/documentation)) (see [Contributing Documentation](/contributing/documentation))
and include media such as images or videos. and include media such as images or videos.
Inside the `docs/` folder, developers should organise the markdown files into each Inside the `docs/` folder, developers should organise the markdown files into each separate language they wish to write
separate language they wish to write documentation for (usually just `en`). Inside documentation for (usually just `en`). Inside each languages' subfolder, developers then have freedom to create whatever
each languages' subfolder, developers then have freedom to create whatever structure structure they wish for organising the documentation they wish.
they wish for organising the documentation they wish.
Example Blog Documentation: Example Blog Documentation:
| Directory | Description | | Directory | Description |
| --------- | ----------- | | --------- | ----------- |
| `vendor/silverstripe/blog/docs` | | | `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/_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/` | 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/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/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/_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/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/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 ## Autoloading
SilverStripe recursively detects classes in PHP files by building up a manifest used for autoloading, Silverstripe recursively detects classes in PHP files by building up a manifest used for autoloading, as well as
as well as respecting Composer's built-in autoloading for libraries. This means respecting Composer's built-in autoloading for libraries. This means in most cases, you don't need to worry about
in most cases, you don't need to worry about include paths or `require()` calls include paths or `require()` calls in your own code - after adding a new class, simply regenerate the manifest by using
in your own code - after adding a new class, simply regenerate the manifest a `flush=1` query parameter. See the ["Manifests" documentation](/developer_guides/execution_pipeline/manifests) for
by using a `flush=1` query parameter. See the ["Manifests" documentation](/developer_guides/execution_pipeline/manifests) for details. details.
## Best Practices ## Best Practices
### Making /assets readonly ### Making /assets readonly
See [Secure coding](/developer_guides/security/secure_coding#filesystem) 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 # 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`) - **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. - **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-core`](https://packagist.org/packages/silverstripe/recipe-core): Contains only the base
- [`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. framework, without the admin UI or CMS features.
- [`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-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 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 icon: rocket
--- ---
## Server Requirements ## Server Requirements
SilverStripe requires PHP 7.1 or newer. Silverstripe requires PHP 7.1 or newer. It runs on many webservers and databases, but is most commonly served using
It runs on many webservers and databases, Apache and MySQL/MariaDB.
but is most commonly served using Apache and MySQL/MariaDB.
If you are setting up your own environment, If you are setting up your own environment, you'll need to consider a few configuration settings such as URL rewriting
you'll need to consider a few configuration settings and protecting access to certain files. Refer to our [server requirements](server_requirements) for details.
such as URL rewriting and protecting access to certain files.
Refer to our [server requirements](server_requirements) for details.
## Quickstart Installation ## Quickstart Installation
If you're running Apache with MySQL/MariaDB already, If you're running Apache with MySQL/MariaDB already, and know your way around webservers, follow these steps to get
and know your way around webservers, follow these steps to get started. started. Silverstripe is installed via [Composer](https://getcomposer.org), a package management tool for PHP that lets
SilverStripe is installed via [Composer](https://getcomposer.org), a package management tool for PHP that you install and upgrade the framework and other modules. Assuming you've got this tool, run the following command to
lets you install and upgrade the framework and other modules. install Silverstripe:
Assuming you've got this tool, run the following command to install SilverStripe:
``` ```
composer create-project silverstripe/installer my-project 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. 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). Now create a `.env` file your project root (not the `public/` folder). It sets up the minimum
It sets up the minimum required [environment variables](environment_management). required [environment variables](environment_management). Replace the placeholders as required:
Replace the placeholders as required:
``` ```
SS_DATABASE_CLASS="MySQLDatabase" 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 vendor/bin/sake dev/build
``` ```
Your website should be available on your domain now (e.g. `http://localhost`). Your website should be available on your domain now (e.g. `http://localhost`). The CMS login can be accessed at `/admin`.
The CMS login can be accessed at `/admin`.
For more information on how to maintain your installation or install projects, For more information on how to maintain your installation or install projects, check
check out [Using SilverStripe with Composer](composer). out [Using Silverstripe with Composer](composer).
## Guided Installation ## 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 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). [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 ## Keep learning
[CHILDREN] [CHILDREN]
## Troubleshooting ## Troubleshooting
If you run into trouble, see [the Tips & Tricks forum](https://forum.silverstripe.org/c/tips) or If you run into trouble, see [the Tips & Tricks forum](https://forum.silverstripe.org/c/tips) or get help on
check our [community help options](https://www.silverstripe.org/community/). our [Slack channel](https://www.silverstripe.org/community/slack-signup/).

41
docs/en/index.md
View File

@ -1,50 +1,51 @@
--- ---
title: SilverStripe Documentation 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. 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 Before you start developing your first web application, you'll need to install the latest version of Silverstripe onto a
a web server. The [Getting Started](/getting_started) section will show you what 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 [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). and play with our [interactive demos](http://silverstripe.org/try).
## Getting support ## 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) * Join our [forum](https://forum.silverstripe.org)
* Ask technical questions on [Stack Overflow](https://stackoverflow.com/questions/tagged/silverstripe) * 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/) * 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) * 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/) * 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 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 Make sure you know the basic concepts of PHP7 before attempting to follow the tutorials. If you have not programmed with
installed and running, the following [Tutorials](http://silverstripe.org/learn/lessons) will lead through the basics and core concepts of PHP5 be sure to read
SilverStripe. 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
The [Developer Guides](/developer_guides) contain more detailed documentation on certain Silverstripe topics, 'how to'
## SilverStripe Concepts
The [Developer Guides](/developer_guides) contain more detailed documentation on certain SilverStripe topics, 'how to'
examples and reference documentation. examples and reference documentation.
[CHILDREN Folder=02_Developer_Guides] [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. contributions.
[CHILDREN Folder=05_Contributing] [CHILDREN Folder=05_Contributing]