mirror of
https://github.com/silverstripe/silverstripe-framework
synced 2024-10-22 14:05:37 +02:00
DOC update SilverStripe to Silverstripe
- Start with Getting Started - Apply consistent formatting (120 chars etc)
This commit is contained in:
parent
5ba38520d7
commit
53ef257ff4
@ -4,7 +4,6 @@ icon: server
|
||||
summary: What you will need to run Silverstripe CMS on a web server
|
||||
---
|
||||
|
||||
|
||||
# Requirements
|
||||
|
||||
Silverstripe CMS needs to be installed on a web server. Content authors and website administrators use their web browser
|
||||
@ -13,105 +12,106 @@ the server to update templates, website logic, and perform upgrades or maintenan
|
||||
|
||||
## PHP
|
||||
|
||||
* PHP >=7.1
|
||||
* PHP extensions: `ctype`, `dom`, `fileinfo`, `hash`, `intl`, `mbstring`, `session`, `simplexml`, `tokenizer`, `xml`
|
||||
* PHP configuration: `memory_limit` with at least `48M`
|
||||
* PHP extension for image manipulation: Either `gd` or `imagick`
|
||||
* PHP extension for a database connector (e.g. `pdo` or `mysqli`)
|
||||
* PHP >=7.1
|
||||
* PHP extensions: `ctype`, `dom`, `fileinfo`, `hash`, `intl`, `mbstring`, `session`, `simplexml`, `tokenizer`, `xml`
|
||||
* PHP configuration: `memory_limit` with at least `48M`
|
||||
* PHP extension for image manipulation: Either `gd` or `imagick`
|
||||
* PHP extension for a database connector (e.g. `pdo` or `mysqli`)
|
||||
|
||||
Use [phpinfo()](http://php.net/manual/en/function.phpinfo.php) to inspect your configuration.
|
||||
|
||||
## Database
|
||||
|
||||
* MySQL >=5.6 (built-in, [commercially supported](https://www.silverstripe.org/software/addons/silverstripe-commercially-supported-module-list/))
|
||||
* PostgreSQL ([third party module](https://addons.silverstripe.org/add-ons/silverstripe/postgresql), community supported)
|
||||
* SQL Server ([third party module](https://addons.silverstripe.org/add-ons/silverstripe/mssql), community supported)
|
||||
* SQLite ([third party module](https://addons.silverstripe.org/add-ons/silverstripe/sqlite3), community supported)
|
||||
* MySQL >=5.6 (
|
||||
built-in, [commercially supported](https://www.silverstripe.org/software/addons/silverstripe-commercially-supported-module-list/))
|
||||
* PostgreSQL ([third party module](https://addons.silverstripe.org/add-ons/silverstripe/postgresql), community
|
||||
supported)
|
||||
* SQL Server ([third party module](https://addons.silverstripe.org/add-ons/silverstripe/mssql), community supported)
|
||||
* SQLite ([third party module](https://addons.silverstripe.org/add-ons/silverstripe/sqlite3), community supported)
|
||||
|
||||
### Default MySQL Collation
|
||||
|
||||
In Silverstripe CMS Recipe 4.7 and later, new projects default to the `utf8mb4_unicode_ci` collation when running against MySQL, which offers better support for multi-byte characters such as emoji. However, this may cause issues related to Varchar fields exceeding the maximum indexable size:
|
||||
In Silverstripe CMS Recipe 4.7 and later, new projects default to the `utf8mb4_unicode_ci` collation when running
|
||||
against MySQL, which offers better support for multi-byte characters such as emoji. However, this may cause issues
|
||||
related to Varchar fields exceeding the maximum indexable size:
|
||||
|
||||
- MySQL 5.5 and lower cannot support indexes larger than 768 bytes (192 characters)
|
||||
- MySQL 5.6 supports larger indexes (3072 bytes) if the `innodb_large_prefix` setting is enabled (but not by default)
|
||||
- MySQL 5.7 and newer have `innodb_large_prefix` enabled by default
|
||||
- MariaDB ~10.1 matches MySQL 5.6's behaviour, >10.2 matches 5.7's.
|
||||
|
||||
You can rectify this issue by upgrading MySQL, enabling the `innodb_large_prefix` setting if available, or reducing the size of affected fields. If none of these solutions are currently suitable, you can remove the new collation configuration from `app/_config/mysite.yml` to default back to the previous default collation.
|
||||
You can rectify this issue by upgrading MySQL, enabling the `innodb_large_prefix` setting if available, or reducing the
|
||||
size of affected fields. If none of these solutions are currently suitable, you can remove the new collation
|
||||
configuration from `app/_config/mysite.yml` to default back to the previous default collation.
|
||||
|
||||
Existing projects that upgrade to Recipe 4.7.0 will unintentionally adopt this configuration change. Recipe 4.7.1 and later are unaffected. See [the release notes](/changelogs/4.7.0/#default-mysql-collation-updated) for more information.
|
||||
Existing projects that upgrade to Recipe 4.7.0 will unintentionally adopt this configuration change. Recipe 4.7.1 and
|
||||
later are unaffected. See [the release notes](/changelogs/4.7.0/#default-mysql-collation-updated) for more information.
|
||||
|
||||
### Connection mode (sql_mode) when using MySQL server >=5.7.5
|
||||
|
||||
In MySQL versions >=5.7.5, the `ANSI` sql_mode setting behaves differently and includes the `ONLY_FULL_GROUP_BY` setting. It is generally recommended to leave this setting as-is because it results in deterministic SQL. However, for some advanced cases, the sql_mode can be configured on the database connection via the configuration API (see `MySQLDatabase::$sql_mode` for more details.) This setting is only available in Silverstripe CMS 4.7 and later.
|
||||
In MySQL versions >=5.7.5, the `ANSI` sql_mode setting behaves differently and includes the `ONLY_FULL_GROUP_BY`
|
||||
setting. It is generally recommended to leave this setting as-is because it results in deterministic SQL. However, for
|
||||
some advanced cases, the sql_mode can be configured on the database connection via the configuration API (
|
||||
see `MySQLDatabase::$sql_mode` for more details.) This setting is only available in Silverstripe CMS 4.7 and later.
|
||||
|
||||
## Webserver Configuration
|
||||
|
||||
### Overview
|
||||
|
||||
SilverStripe needs to handle a variety of HTTP requests,
|
||||
and relies on the hosting environment to be configured securely to
|
||||
enforce restrictions. There are secure defaults in place for Apache,
|
||||
but you should be aware of the configuration regardless of your webserver setup.
|
||||
Silverstripe needs to handle a variety of HTTP requests, and relies on the hosting environment to be configured securely
|
||||
to enforce restrictions. There are secure defaults in place for Apache, but you should be aware of the configuration
|
||||
regardless of your webserver setup.
|
||||
|
||||
### Public webroot
|
||||
|
||||
The webroot of your webserver should be configured to the `public/` subfolder.
|
||||
Projects created prior to SilverStripe 4.1 might be using the main project
|
||||
folder as the webroot. In this case, you are responsible for ensuring
|
||||
access to system files such as configuration in `*.yml` is protected
|
||||
from public access. We strongly recommend switching to more secure
|
||||
hosting via the `public/`. See [4.1.0 upgrading guide](/changelogs/4.1.0).
|
||||
The webroot of your webserver should be configured to the `public/` subfolder. Projects created prior to Silverstripe
|
||||
4.1 might be using the main project folder as the webroot. In this case, you are responsible for ensuring access to
|
||||
system files such as configuration in `*.yml` is protected from public access. We strongly recommend switching to more
|
||||
secure hosting via the `public/`. See [4.1.0 upgrading guide](/changelogs/4.1.0).
|
||||
|
||||
### Filesystem permissions
|
||||
|
||||
During runtime, Silverstripe needs read access for the webserver user to your base path (including your webroot).
|
||||
It also needs write access for the webserver user to the following locations:
|
||||
During runtime, Silverstripe needs read access for the webserver user to your base path (including your webroot). It
|
||||
also needs write access for the webserver user to the following locations:
|
||||
|
||||
* `public/assets/`: Used by the CMS and other logic to [store uploads](/developer_guides/files/file_storage)
|
||||
* `TEMP_PATH`: Temporary file storage used for the default filesystem-based cache adapters in
|
||||
[Manifests](/developer_guides/execution_pipeline/manifests), [Object Caching](/developer_guides/performance/caching)
|
||||
and [Partial Template Caching](/developer_guides/templates/partial_template_caching).
|
||||
See [Environment Management](/getting_started/environment_management).
|
||||
* `public/assets/`: Used by the CMS and other logic to [store uploads](/developer_guides/files/file_storage)
|
||||
* `TEMP_PATH`: Temporary file storage used for the default filesystem-based cache adapters in
|
||||
[Manifests](/developer_guides/execution_pipeline/manifests), [Object Caching](/developer_guides/performance/caching)
|
||||
and [Partial Template Caching](/developer_guides/templates/partial_template_caching).
|
||||
See [Environment Management](/getting_started/environment_management).
|
||||
|
||||
If you aren't explicitly [packaging](#building-packaging-deployment)
|
||||
your Silverstripe project during your deployment process,
|
||||
additional write access may be required to generate supporting files on the fly.
|
||||
This is not recommended, because it can lead to extended execution times
|
||||
as well as cause inconsistencies between multiple server environments
|
||||
when manifest and cache storage isn't shared between servers.
|
||||
your Silverstripe project during your deployment process, additional write access may be required to generate supporting
|
||||
files on the fly. This is not recommended, because it can lead to extended execution times as well as cause
|
||||
inconsistencies between multiple server environments when manifest and cache storage isn't shared between servers.
|
||||
|
||||
### Assets
|
||||
|
||||
SilverStripe allows CMS authors to upload files into the `public/assets/` folder,
|
||||
which should be served by your webserver. **No PHP execution should be allowed in this folder**.
|
||||
This is configured for Apache by default via `public/assets/.htaccess`.
|
||||
The file is generated dynamically during the `dev/build` stage.
|
||||
Silverstripe allows CMS authors to upload files into the `public/assets/` folder, which should be served by your
|
||||
webserver. **No PHP execution should be allowed in this folder**. This is configured for Apache by default
|
||||
via `public/assets/.htaccess`. The file is generated dynamically during the `dev/build` stage.
|
||||
|
||||
Additionally, access is whitelisted by file extension through a
|
||||
dynamically generated whitelist based on the `File.allowed_extensions` setting
|
||||
(see [File Security](/developer_guides/files/file_security#file-types)).
|
||||
This whitelist uses the same defaults configured through file upload
|
||||
through SilverStripe, so is considered a second line of defence.
|
||||
Additionally, access is whitelisted by file extension through a dynamically generated whitelist based on
|
||||
the `File.allowed_extensions` setting
|
||||
(see [File Security](/developer_guides/files/file_security#file-types)). This whitelist uses the same defaults
|
||||
configured through file upload through Silverstripe, so is considered a second line of defence.
|
||||
|
||||
### Secure Assets {#secure-assets}
|
||||
|
||||
Files can be kept in draft stage,
|
||||
and access restricted to certain user groups.
|
||||
These files are stored in a special `.protected/` folder (defaulting to `public/assets/.protected/`).
|
||||
Files can be kept in draft stage, and access restricted to certain user groups. These files are stored in a
|
||||
special `.protected/` folder (defaulting to `public/assets/.protected/`).
|
||||
**Requests to files in this folder should be denied by your webserver**.
|
||||
|
||||
Requests to files in the `.protected/` folder
|
||||
are routed to PHP by default when using Apache, through `public/assets/.htaccess`.
|
||||
If you are using another webserver, please follow our guides to ensure a secure setup.
|
||||
See [Developer Guides: File Security](/developer_guides/files/file_security) for details.
|
||||
Requests to files in the `.protected/` folder are routed to PHP by default when using Apache,
|
||||
through `public/assets/.htaccess`. If you are using another webserver, please follow our guides to ensure a secure
|
||||
setup. See [Developer Guides: File Security](/developer_guides/files/file_security) for details.
|
||||
|
||||
For additional security, we recommend moving the `.protected/` folder out of `public/assets/`.
|
||||
This removes the possibility of a misconfigured webserver accidentally exposing
|
||||
these files under URL paths, and forces read access via PHP.
|
||||
For additional security, we recommend moving the `.protected/` folder out of `public/assets/`. This removes the
|
||||
possibility of a misconfigured webserver accidentally exposing these files under URL paths, and forces read access via
|
||||
PHP.
|
||||
|
||||
This can be configured via [.env](/getting_started/environment_management) variable,
|
||||
relative to the `index.php` location.
|
||||
This can be configured via [.env](/getting_started/environment_management) variable, relative to the `index.php`
|
||||
location.
|
||||
|
||||
```
|
||||
SS_PROTECTED_ASSETS_PATH="../.protected/"
|
||||
@ -134,128 +134,126 @@ Don't forget to include this additional folder in any syncing and backup process
|
||||
|
||||
### Building, Packaging and Deployment {#building-packaging-deployment}
|
||||
|
||||
It is common to build a SilverStripe application into a package on one environment (e.g. a CI server),
|
||||
and then deploy the package to a (separate) webserver environment(s).
|
||||
This approach relies on all auto-generated files required by SilverStripe to
|
||||
be included in the package, or generated on the fly on each webserver environment.
|
||||
It is common to build a Silverstripe application into a package on one environment (e.g. a CI server), and then deploy
|
||||
the package to a (separate) webserver environment(s). This approach relies on all auto-generated files required by
|
||||
Silverstripe to be included in the package, or generated on the fly on each webserver environment.
|
||||
|
||||
The easiest way to ensure this is to commit auto generated files to source control.
|
||||
If those changes are considered too noisy, here's some pointers for auto-generated files
|
||||
to trigger and include in a deployment package:
|
||||
The easiest way to ensure this is to commit auto generated files to source control. If those changes are considered too
|
||||
noisy, here's some pointers for auto-generated files to trigger and include in a deployment package:
|
||||
|
||||
* `public/_resources/`: Frontend assets copied from the (inaccessible) `vendor/` folder
|
||||
via [silverstripe/vendor-plugin](https://github.com/silverstripe/vendor-plugin).
|
||||
See [Templates: Requirements](/developer_guides/templates/requirements#exposing-assets-webroot).
|
||||
* `.graphql/` and `public/_graphql/`: Schema and type definitions required by CMS and any GraphQL API endpoint. Generated through
|
||||
[silverstripe/graphql v4](https://github.com/silverstripe/silverstripe-graphql).
|
||||
Triggered by `dev/build`, or a [GraphQL Schema Build](/developer_guides/graphql/getting_started/building_the_schema).
|
||||
* Various recipes create default files in `app/` and `public/` on `composer install`
|
||||
and `composer update` via
|
||||
[silverstripe/recipe-plugin](https://github.com/silverstripe/recipe-plugin).
|
||||
* `public/_resources/`: Frontend assets copied from the (inaccessible) `vendor/` folder
|
||||
via [silverstripe/vendor-plugin](https://github.com/silverstripe/vendor-plugin).
|
||||
See [Templates: Requirements](/developer_guides/templates/requirements#exposing-assets-webroot).
|
||||
* `.graphql/` and `public/_graphql/`: Schema and type definitions required by CMS and any GraphQL API endpoint.
|
||||
Generated through
|
||||
[silverstripe/graphql v4](https://github.com/silverstripe/silverstripe-graphql). Triggered by `dev/build`, or
|
||||
a [GraphQL Schema Build](/developer_guides/graphql/getting_started/building_the_schema).
|
||||
* Various recipes create default files in `app/` and `public/` on `composer install`
|
||||
and `composer update` via
|
||||
[silverstripe/recipe-plugin](https://github.com/silverstripe/recipe-plugin).
|
||||
|
||||
### Web Worker Concurrency
|
||||
|
||||
It's generally a good idea to run multiple workers to serve multiple HTTP requests
|
||||
to SilverStripe concurrently. The exact number depends on your website needs.
|
||||
The CMS attempts to request multiple views concurrently.
|
||||
It also routes [protected and draft files](/developer_guides/files/file_security)
|
||||
through SilverStripe. This can increase your concurrency requirements,
|
||||
e.g. when authors batch upload and view dozens of draft files in the CMS.
|
||||
It's generally a good idea to run multiple workers to serve multiple HTTP requests to Silverstripe concurrently. The
|
||||
exact number depends on your website needs. The CMS attempts to request multiple views concurrently. It also
|
||||
routes [protected and draft files](/developer_guides/files/file_security)
|
||||
through Silverstripe. This can increase your concurrency requirements, e.g. when authors batch upload and view dozens of
|
||||
draft files in the CMS.
|
||||
|
||||
When allowing upload of large files through the CMS (through PHP settings),
|
||||
these files might be used as [protected and draft files](/developer_guides/files/file_security).
|
||||
Files in this state get served by SilverStripe rather than your webserver.
|
||||
Since the framework uses [PHP streams](https://www.php.net/manual/en/ref.stream.php),
|
||||
this allows serving of files larger than your PHP memory limit.
|
||||
Please be aware that streaming operations don't count towards
|
||||
PHP's [max_execution_time](https://www.php.net/manual/en/function.set-time-limit.php),
|
||||
which can risk exhaustion of web worker pools for long-running downloads.
|
||||
When allowing upload of large files through the CMS (through PHP settings), these files might be used
|
||||
as [protected and draft files](/developer_guides/files/file_security). Files in this state get served by Silverstripe
|
||||
rather than your webserver. Since the framework uses [PHP streams](https://www.php.net/manual/en/ref.stream.php), this
|
||||
allows serving of files larger than your PHP memory limit. Please be aware that streaming operations don't count towards
|
||||
PHP's [max_execution_time](https://www.php.net/manual/en/function.set-time-limit.php), which can risk exhaustion of web
|
||||
worker pools for long-running downloads.
|
||||
|
||||
### URL Rewriting
|
||||
|
||||
SilverStripe expects URL paths to be rewritten to `public/index.php`.
|
||||
For Apache, this is preconfigured through `.htaccess` files,
|
||||
and expects using the `mod_rewrite` module.
|
||||
By default, these files are located in `public/.htaccess` and `public/assets/.htaccess`.
|
||||
Silverstripe expects URL paths to be rewritten to `public/index.php`. For Apache, this is preconfigured
|
||||
through `.htaccess` files, and expects using the `mod_rewrite` module. By default, these files are located
|
||||
in `public/.htaccess` and `public/assets/.htaccess`.
|
||||
|
||||
### HTTP Headers
|
||||
|
||||
SilverStripe can add HTTP headers to reponses it handles directly.
|
||||
These headers are often sensitive, for example preventing HTTP caching for responses
|
||||
displaying data based on user sessions, or when serving protected assets.
|
||||
You need to ensure those headers are kept in place in your webserver.
|
||||
For example, Apache allows this through `Header setifempty` (see [docs](https://httpd.apache.org/docs/current/mod/mod_headers.html#header)).
|
||||
Silverstripe can add HTTP headers to responses it handles directly. These headers are often sensitive, for example
|
||||
preventing HTTP caching for responses displaying data based on user sessions, or when serving protected assets. You need
|
||||
to ensure those headers are kept in place in your webserver. For example, Apache allows this
|
||||
through `Header setifempty` (see [docs](https://httpd.apache.org/docs/current/mod/mod_headers.html#header)).
|
||||
See [Developer Guide: Performance](/developer_guides/performance/)
|
||||
and [Developer Guides: File Security](/developer_guides/files/file_security) for more details.
|
||||
|
||||
Silverstripe relies on the `Host` header to construct URLs such as "reset password" links,
|
||||
so you'll need to ensure that the systems hosting it only allow valid values for this header.
|
||||
See [Developer Guide: Security - Request hostname forgery](/developer_guides/security/secure_coding#request-hostname-forgery).
|
||||
Silverstripe relies on the `Host` header to construct URLs such as "reset password" links, so you'll need to ensure that
|
||||
the systems hosting it only allow valid values for this header.
|
||||
See [Developer Guide: Security - Request hostname forgery](/developer_guides/security/secure_coding#request-hostname-forgery)
|
||||
.
|
||||
|
||||
### CDNs and other Reverse Proxies
|
||||
|
||||
If your Silverstripe site is hosted behind multiple HTTP layers,
|
||||
you're in charge of controlling which forwarded headers are considered valid,
|
||||
and which IPs can set them. See [Developer Guide: Security - Request hostname forgery](/developer_guides/security/secure_coding#request-hostname-forgery).
|
||||
If your Silverstripe site is hosted behind multiple HTTP layers, you're in charge of controlling which forwarded headers
|
||||
are considered valid, and which IPs can set them.
|
||||
See [Developer Guide: Security - Request hostname forgery](/developer_guides/security/secure_coding#request-hostname-forgery)
|
||||
.
|
||||
|
||||
### Symlinks
|
||||
|
||||
SilverStripe is a modular system, with modules installed and updated
|
||||
via the `composer` PHP dependency manager. These are usually stored in `vendor/`,
|
||||
outside of the `public/` webroot. Since many modules rely on serving frontend assets
|
||||
such as CSS files or images, these are mapped over to the `public/_resources/` folder automatically.
|
||||
If the filesystem supports it, this is achieved through symlinks.
|
||||
Depending on your hosting and deployment mechanisms,
|
||||
you may need to configure the plugin to copy files instead.
|
||||
Silverstripe is a modular system, with modules installed and updated via the `composer` PHP dependency manager. These
|
||||
are usually stored in `vendor/`, outside of the `public/` webroot. Since many modules rely on serving frontend assets
|
||||
such as CSS files or images, these are mapped over to the `public/_resources/` folder automatically. If the filesystem
|
||||
supports it, this is achieved through symlinks. Depending on your hosting and deployment mechanisms, you may need to
|
||||
configure the plugin to copy files instead.
|
||||
See [silverstripe/vendor-plugin](https://github.com/silverstripe/vendor-plugin) for details.
|
||||
|
||||
### Caches
|
||||
|
||||
Silverstripe relies on various [caches](/developer_guides/performance/caching/)
|
||||
to achieve performant responses. By default, those caches are stored in a temporary filesystem folder,
|
||||
and are not shared between multiple server instances. Alternative cache backends such as Redis can be
|
||||
to achieve performant responses. By default, those caches are stored in a temporary filesystem folder, and are not
|
||||
shared between multiple server instances. Alternative cache backends such as Redis can be
|
||||
[configured](/developer_guides/performance/caching/).
|
||||
|
||||
While cache objects can expire, when using filesystem caching the files are not actively pruned.
|
||||
For long-lived server instances, this can become a capacity issue over time - see
|
||||
While cache objects can expire, when using filesystem caching the files are not actively pruned. For long-lived server
|
||||
instances, this can become a capacity issue over time - see
|
||||
[workaround](https://github.com/silverstripe/silverstripe-framework/issues/6678).
|
||||
|
||||
### Error pages
|
||||
|
||||
The default installation includes [silverstripe/errorpage](https://addons.silverstripe.org/add-ons/silverstripe/errorpage),
|
||||
which generates static error pages that bypass PHP execution when those pages are published in the CMS.
|
||||
Once published, the static files are located in `public/assets/error-404.html` and `public/assets/error-500.html`.
|
||||
The default `public/.htaccess` file is configured to have Apache serve those pages based on their HTTP status code.
|
||||
The default installation
|
||||
includes [silverstripe/errorpage](https://addons.silverstripe.org/add-ons/silverstripe/errorpage), which generates
|
||||
static error pages that bypass PHP execution when those pages are published in the CMS. Once published, the static files
|
||||
are located in `public/assets/error-404.html` and `public/assets/error-500.html`. The default `public/.htaccess` file is
|
||||
configured to have Apache serve those pages based on their HTTP status code.
|
||||
|
||||
### Other webservers (Nginx, IIS, Lighttpd)
|
||||
|
||||
Serving through webservers other than Apache requires more manual configuration,
|
||||
since the defaults configured through `.htaccess` don't apply.
|
||||
Please apply the considerations above to your webserver to ensure a secure hosting environment.
|
||||
In particular, configure protected assets correctly to avoid exposing draft or protected files uploaded through the CMS.
|
||||
Serving through webservers other than Apache requires more manual configuration, since the defaults configured
|
||||
through `.htaccess` don't apply. Please apply the considerations above to your webserver to ensure a secure hosting
|
||||
environment. In particular, configure protected assets correctly to avoid exposing draft or protected files uploaded
|
||||
through the CMS.
|
||||
|
||||
There are various community supported installation instructions for different environments.
|
||||
Nginx is a popular choice, see [Nginx webserver configuration](https://forum.silverstripe.org/t/nginx-webserver-configuration/2246).
|
||||
There are various community supported installation instructions for different environments. Nginx is a popular choice,
|
||||
see [Nginx webserver configuration](https://forum.silverstripe.org/t/nginx-webserver-configuration/2246).
|
||||
|
||||
SilverStripe is known to work with Microsoft IIS, and generates `web.config` files by default
|
||||
(see [Microsoft IIS and SQL Server configuration](https://forum.silverstripe.org/t/microsoft-iis-webserver-and-sql-server-support/2245)).
|
||||
Silverstripe is known to work with Microsoft IIS, and generates `web.config` files by default
|
||||
(
|
||||
see [Microsoft IIS and SQL Server configuration](https://forum.silverstripe.org/t/microsoft-iis-webserver-and-sql-server-support/2245))
|
||||
.
|
||||
|
||||
Additionally, there are community supported guides for installing SilverStripe
|
||||
on various environments:
|
||||
Additionally, there are community supported guides for installing Silverstripe on various environments:
|
||||
|
||||
* [Hosting via Bitnami](https://bitnami.com/stack/silverstripe/virtual-machine): In the cloud or as a locally hosted virtual machine
|
||||
* [Vagrant/Virtualbox with CentOS](https://forum.silverstripe.org/t/installing-via-vagrant-virtualbox-with-centos/2248)
|
||||
* [macOS with Homebrew](https://forum.silverstripe.org/t/installing-on-osx-with-homebrew/2247)
|
||||
* [macOS with MAMP](https://forum.silverstripe.org/t/installing-on-osx-with-mamp/2249)
|
||||
* [Windows with WAMP](https://forum.silverstripe.org/t/installing-on-windows-via-wamp/2250)
|
||||
* [Vagrant with silverstripe-australia/vagrant-environment](https://github.com/silverstripe-australia/vagrant-environment)
|
||||
* [Vagrant with BetterBrief/vagrant-skeleton](https://github.com/BetterBrief/vagrant-skeleton)
|
||||
* [Hosting via Bitnami](https://bitnami.com/stack/silverstripe/virtual-machine): In the cloud or as a locally hosted
|
||||
virtual machine
|
||||
* [Vagrant/Virtualbox with CentOS](https://forum.silverstripe.org/t/installing-via-vagrant-virtualbox-with-centos/2248)
|
||||
* [macOS with Homebrew](https://forum.silverstripe.org/t/installing-on-osx-with-homebrew/2247)
|
||||
* [macOS with MAMP](https://forum.silverstripe.org/t/installing-on-osx-with-mamp/2249)
|
||||
* [Windows with WAMP](https://forum.silverstripe.org/t/installing-on-windows-via-wamp/2250)
|
||||
* [Vagrant with silverstripe-australia/vagrant-environment](https://github.com/silverstripe-australia/vagrant-environment)
|
||||
* [Vagrant with BetterBrief/vagrant-skeleton](https://github.com/BetterBrief/vagrant-skeleton)
|
||||
|
||||
## PHP Requirements for older SilverStripe releases {#php-support}
|
||||
## PHP Requirements for older Silverstripe releases {#php-support}
|
||||
|
||||
SilverStripe's PHP support has changed over time and if you are looking to upgrade PHP on your SilverStripe site, this table may be of use:
|
||||
Silverstripe's PHP support has changed over time and if you are looking to upgrade PHP on your Silverstripe site, this
|
||||
table may be of use:
|
||||
|
||||
| SilverStripe Version | PHP Version | More information |
|
||||
| Silverstripe Version | PHP Version | More information |
|
||||
| -------------------- | ----------- | ---------------- |
|
||||
| 3.0 - 3.5 | 5.3 - 5.6 | [requirements docs](https://docs.silverstripe.org/en/3.4/getting_started/server_requirements/)
|
||||
| 3.6 | 5.3 - 7.1 | |
|
||||
@ -263,20 +261,21 @@ SilverStripe's PHP support has changed over time and if you are looking to upgra
|
||||
| 4.0 - 4.4 | 5.6+ | |
|
||||
| 4.5+ | 7.1+ | [blog post](https://www.silverstripe.org/blog/our-plan-for-ending-php-5-6-support-in-silverstripe-4/) |
|
||||
|
||||
|
||||
## CMS browser requirements
|
||||
|
||||
SilverStripe CMS supports the following web browsers:
|
||||
Silverstripe CMS supports the following web browsers:
|
||||
|
||||
* Google Chrome
|
||||
* Internet Explorer 11
|
||||
* Microsoft Edge
|
||||
* Mozilla Firefox
|
||||
|
||||
We aim to provide satisfactory experiences in Apple Safari. SilverStripe CMS works well across Windows, Linux, and Mac operating systems.
|
||||
We aim to provide satisfactory experiences in Apple Safari. Silverstripe CMS works well across Windows, Linux, and Mac
|
||||
operating systems.
|
||||
|
||||
## End user requirements
|
||||
|
||||
SilverStripe CMS is designed to make excellent, standards-compliant websites that are compatible with a wide range of
|
||||
Silverstripe CMS is designed to make excellent, standards-compliant websites that are compatible with a wide range of
|
||||
industry standard browsers and operating systems. A competent developer is able to produce websites that meet W3C
|
||||
guidelines for HTML, CSS, JavaScript, and accessibility, in addition to meeting specific guide lines, such as
|
||||
e-government requirements.
|
||||
|
@ -3,17 +3,20 @@ title: Composer
|
||||
summary: What is composer and how to use it with Silverstripe CMS
|
||||
---
|
||||
|
||||
# Using SilverStripe with Composer
|
||||
# Using Silverstripe with Composer
|
||||
|
||||
## Requirements
|
||||
|
||||
[Composer](http://getcomposer.org/) is a package management tool for PHP that lets you install and upgrade SilverStripe and its modules.
|
||||
We also have separate instructions for [installing modules with Composer](/developer_guides/extending/modules).
|
||||
[Composer](http://getcomposer.org/) is a package management tool for PHP that lets you install and upgrade Silverstripe
|
||||
and its modules. We also have separate instructions
|
||||
for [installing modules with Composer](/developer_guides/extending/modules).
|
||||
|
||||
Before installing Composer you should ensure your system has the version control system, [Git installed](http://git-scm.com/book/en/v2/Getting-Started-Installing-Git). Composer uses Git to check out the code dependancies you need to run your SilverStripe CMS website from the code repositories maintained on GitHub.
|
||||
Before installing Composer you should ensure your system has the version control
|
||||
system, [Git installed](http://git-scm.com/book/en/v2/Getting-Started-Installing-Git). Composer uses Git to check out
|
||||
the code dependancies you need to run your Silverstripe CMS website from the code repositories maintained on GitHub.
|
||||
|
||||
Next, [install composer](https://getcomposer.org/download/). For our documentation we assume the `composer` command is installed globally.
|
||||
You should now be able to run the command:
|
||||
Next, [install composer](https://getcomposer.org/download/). For our documentation we assume the `composer` command is
|
||||
installed globally. You should now be able to run the command:
|
||||
|
||||
```
|
||||
composer help
|
||||
@ -21,24 +24,23 @@ composer help
|
||||
|
||||
## Create a new site
|
||||
|
||||
Composer can create a new site for you, using the installer as a template.
|
||||
By default it will download the latest stable version:
|
||||
Composer can create a new site for you, using the installer as a template. By default it will download the latest stable
|
||||
version:
|
||||
|
||||
```
|
||||
composer create-project silverstripe/installer my-project
|
||||
```
|
||||
|
||||
If you want to get all additional fixtures for testing, such as behat and phpunit configuration,
|
||||
an example `.env.example` file, and all documentation, then it's recommended to use `--prefer-source`
|
||||
If you want to get all additional fixtures for testing, such as behat and phpunit configuration, an
|
||||
example `.env.example` file, and all documentation, then it's recommended to use `--prefer-source`
|
||||
to include these files.
|
||||
|
||||
If you want a minimal installation with the bare essentials to get working without any additional overhead,
|
||||
and don't plan on contributing back changes to framework, use `--prefer-dist` (default) for a more lightweight install.
|
||||
If you want a minimal installation with the bare essentials to get working without any additional overhead, and don't
|
||||
plan on contributing back changes to framework, use `--prefer-dist` (default) for a more lightweight install.
|
||||
|
||||
`./my-project` should be the root directory where your site will live.
|
||||
For example, on OS X, you might use a subdirectory of `~/Sites`.
|
||||
As long as your web server is up and running, this will get all the code that you need.
|
||||
Now visit the site in your web browser, and the installation process will be completed.
|
||||
`./my-project` should be the root directory where your site will live. For example, on OS X, you might use a
|
||||
subdirectory of `~/Sites`. As long as your web server is up and running, this will get all the code that you need. Now
|
||||
visit the site in your web browser, and the installation process will be completed.
|
||||
|
||||
You can also specify a version to download that version explicitly, i.e. this will download the older `4.3.3` release:
|
||||
|
||||
@ -46,34 +48,38 @@ You can also specify a version to download that version explicitly, i.e. this wi
|
||||
composer create-project silverstripe/installer ./my-project 4.3.3
|
||||
```
|
||||
|
||||
When `create-project` is used with a release version like above,
|
||||
it will try to get the code from archives instead of creating
|
||||
git repositories. If you're planning to contribute to SilverStripe,
|
||||
When `create-project` is used with a release version like above, it will try to get the code from archives instead of
|
||||
creating git repositories. If you're planning to contribute to Silverstripe,
|
||||
see [Using development versions](#using-development-versions).
|
||||
|
||||
## Adding modules to your project
|
||||
|
||||
Composer isn't only used to download SilverStripe CMS, it is also used to manage all SilverStripe modules.
|
||||
You can find thousands of modules on [https://addons.silverstripe.org](https://addons.silverstripe.org).
|
||||
Installing a module can be done with the following command:
|
||||
Composer isn't only used to download Silverstripe CMS, it is also used to manage all Silverstripe modules. You can find
|
||||
thousands of modules on [https://addons.silverstripe.org](https://addons.silverstripe.org). Installing a module can be
|
||||
done with the following command:
|
||||
|
||||
```
|
||||
composer require silverstripe/blog
|
||||
```
|
||||
|
||||
This will install the `silverstripe/blog` module in the latest compatible version. If you know the specific version you want to install already (such as `^2`), you can add it after the package name as a [version constraint](http://getcomposer.org/doc/01-basic-usage.md#the-require-key):
|
||||
This will install the `silverstripe/blog` module in the latest compatible version. If you know the specific version you
|
||||
want to install already (such as `^2`), you can add it after the package name as
|
||||
a [version constraint](http://getcomposer.org/doc/01-basic-usage.md#the-require-key):
|
||||
|
||||
```
|
||||
composer require silverstripe/blog ^2
|
||||
```
|
||||
|
||||
[warning]
|
||||
**Version constraints:** `master` is not a legal version string - it's a branch name. These are different things. The version string that would get you the branch is `dev-master`. The version string that would get you a numeric branch is a little different. The version string for the `4` branch is `4.x-dev`.
|
||||
**Version constraints:** `master` is not a legal version string - it's a branch name. These are different things. The
|
||||
version string that would get you the branch is `dev-master`. The version string that would get you a numeric branch is
|
||||
a little different. The version string for the `4` branch is `4.x-dev`.
|
||||
[/warning]
|
||||
|
||||
## Updating dependencies
|
||||
|
||||
Except for the control code of the Voyager space probe, every piece of code in the universe gets updated from time to time. SilverStripe modules are no exception.
|
||||
Except for the control code of the Voyager space probe, every piece of code in the universe gets updated from time to
|
||||
time. Silverstripe modules are no exception.
|
||||
|
||||
To get the latest updates of the modules in your project, run this command:
|
||||
|
||||
@ -81,35 +87,43 @@ To get the latest updates of the modules in your project, run this command:
|
||||
composer update
|
||||
```
|
||||
|
||||
Updates to the required modules will be installed, and the `composer.lock` file will get updated with the specific commits and version constraints for each of them.
|
||||
Updates to the required modules will be installed, and the `composer.lock` file will get updated with the specific
|
||||
commits and version constraints for each of them.
|
||||
|
||||
## Deploying projects with Composer
|
||||
|
||||
When deploying projects with composer, you could just push the code and run `composer update`. This, however, is risky. In particular, if you were referencing development dependencies and a change was made between your testing and your deployment to production, you would end up deploying untested code. Not cool!
|
||||
When deploying projects with composer, you could just push the code and run `composer update`. This, however, is risky.
|
||||
In particular, if you were referencing development dependencies and a change was made between your testing and your
|
||||
deployment to production, you would end up deploying untested code. Not cool!
|
||||
|
||||
The `composer.lock` file helps with this. It references the specific commits that have been checked out, rather than the version string. You can run `composer install` to install dependencies from this rather than `composer.json`.
|
||||
The `composer.lock` file helps with this. It references the specific commits that have been checked out, rather than the
|
||||
version string. You can run `composer install` to install dependencies from this rather than `composer.json`.
|
||||
|
||||
So your deployment process, as it relates to Composer, should be as follows:
|
||||
|
||||
* Run `composer update` on your development version before you start whatever testing you have planned. Perform all the necessary testing.
|
||||
* Check `composer.lock` into your repository.
|
||||
* Deploy your project code base, using the deployment tool of your choice.
|
||||
* Run `composer install --no-dev -o` on your production version. In this command, the `--no-dev` command tells Composer not to install your development-only dependencies, and `-o` is an alias for `--optimise-autoloader`, which will convert your PSR-0 and PSR-4 autoloader definitions into a classmap to improve the speed of the autoloader.
|
||||
* Run `composer update` on your development version before you start whatever testing you have planned. Perform all the
|
||||
necessary testing.
|
||||
* Check `composer.lock` into your repository.
|
||||
* Deploy your project code base, using the deployment tool of your choice.
|
||||
* Run `composer install --no-dev -o` on your production version. In this command, the `--no-dev` command tells Composer
|
||||
not to install your development-only dependencies, and `-o` is an alias for `--optimise-autoloader`, which will
|
||||
convert your PSR-0 and PSR-4 autoloader definitions into a classmap to improve the speed of the autoloader.
|
||||
|
||||
## Composer managed modules, Git and .gitignore
|
||||
|
||||
Modules and themes managed by Composer should not be committed with your projects source code.
|
||||
SilverStripe ships with a [.gitignore](http://git-scm.com/docs/gitignore) file by default which prevents this.
|
||||
For more details read [Should I commit the dependencies in my vendor directory?](https://getcomposer.org/doc/faqs/should-i-commit-the-dependencies-in-my-vendor-directory.md).
|
||||
Modules and themes managed by Composer should not be committed with your projects source code. Silverstripe ships with
|
||||
a [.gitignore](http://git-scm.com/docs/gitignore) file by default which prevents this. For more details
|
||||
read [Should I commit the dependencies in my vendor directory?](https://getcomposer.org/doc/faqs/should-i-commit-the-dependencies-in-my-vendor-directory.md)
|
||||
.
|
||||
|
||||
## Dev Environments for Contributing Code {#contributing}
|
||||
|
||||
So you want to contribute to SilverStripe? Fantastic! You can do this with composer too.
|
||||
You have to tell composer three things in order to be able to do this:
|
||||
So you want to contribute to Silverstripe? Fantastic! You can do this with composer too. You have to tell composer three
|
||||
things in order to be able to do this:
|
||||
|
||||
- Keep the full git repository information
|
||||
- Include dependencies marked as "developer" requirements
|
||||
- Use the development version, not the latest stable version
|
||||
- Keep the full git repository information
|
||||
- Include dependencies marked as "developer" requirements
|
||||
- Use the development version, not the latest stable version
|
||||
|
||||
The first two steps are done as part of the initial create project using additional arguments.
|
||||
|
||||
@ -117,36 +131,38 @@ The first two steps are done as part of the initial create project using additio
|
||||
composer create-project --keep-vcs --dev silverstripe/installer ./my-project 4.x-dev --prefer-source
|
||||
```
|
||||
|
||||
The process will take a bit longer, since all modules are checked out as full git repositories which you can work on. The command checks out from the 4.x release line. To check out from master instead,
|
||||
replace `4.x-dev` with `dev-master` (more info on [composer version naming](http://getcomposer.org/doc/02-libraries.md#specifying-the-version)).
|
||||
The process will take a bit longer, since all modules are checked out as full git repositories which you can work on.
|
||||
The command checks out from the 4.x release line. To check out from master instead, replace `4.x-dev`
|
||||
with `dev-master` (more info
|
||||
on [composer version naming](http://getcomposer.org/doc/02-libraries.md#specifying-the-version)).
|
||||
|
||||
The `--keep-vcs` flag will make sure you have access to the git history of the installer and the requirements
|
||||
|
||||
The `--dev` flag is optional, and can be used to add a couple modules which are useful for
|
||||
SilverStripe development:
|
||||
The `--dev` flag is optional, and can be used to add a couple modules which are useful for Silverstripe development:
|
||||
|
||||
* The `behat-extension` module allows running [Behat](http://behat.org) integration tests
|
||||
* The `docsviewer` module will let you preview changes to the project documentation
|
||||
* The `buildtools` module which adds [phing](http://phing.info) tasks for creating SilverStripe releases
|
||||
* The `behat-extension` module allows running [Behat](http://behat.org) integration tests
|
||||
* The `docsviewer` module will let you preview changes to the project documentation
|
||||
* The `buildtools` module which adds [phing](http://phing.info) tasks for creating Silverstripe releases
|
||||
|
||||
Once the `create-project` command completes, you need to edit the `composer.json` in the project root
|
||||
and remove the `@stable` markers from the `silverstripe/cms` and `silverstripe/framework` version entries.
|
||||
Another `composer update --dev` call will now fetch from the development branch instead.
|
||||
Note that you can also convert an existing composer project with these steps.
|
||||
Once the `create-project` command completes, you need to edit the `composer.json` in the project root and remove
|
||||
the `@stable` markers from the `silverstripe/cms` and `silverstripe/framework` version entries.
|
||||
Another `composer update --dev` call will now fetch from the development branch instead. Note that you can also convert
|
||||
an existing composer project with these steps.
|
||||
|
||||
Please read the ["Contributing Code"](/contributing/code) documentation to find out how to
|
||||
create forks and send pull requests.
|
||||
Please read the ["Contributing Code"](/contributing/code) documentation to find out how to create forks and send pull
|
||||
requests.
|
||||
|
||||
# Advanced usage
|
||||
|
||||
## Manually editing composer.json
|
||||
|
||||
To remove dependencies, or if you prefer seeing all your dependencies in a text file, you can edit the `composer.json` file. It will appear in your project root, and by default, it will look something like this:
|
||||
To remove dependencies, or if you prefer seeing all your dependencies in a text file, you can edit the `composer.json`
|
||||
file. It will appear in your project root, and by default, it will look something like this:
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "silverstripe/installer",
|
||||
"description": "The SilverStripe Framework Installer",
|
||||
"description": "The Silverstripe Framework Installer",
|
||||
"require": {
|
||||
"php": ">=7.3",
|
||||
"silverstripe/cms": "^4",
|
||||
@ -161,7 +177,8 @@ To remove dependencies, or if you prefer seeing all your dependencies in a text
|
||||
}
|
||||
```
|
||||
|
||||
To add modules, you should add more entries into the `"require"` section. For example, we might add the blog and forum modules. Be careful with the commas at the end of the lines!
|
||||
To add modules, you should add more entries into the `"require"` section. For example, we might add the blog and forum
|
||||
modules. Be careful with the commas at the end of the lines!
|
||||
|
||||
Save your file, and then run the following command to refresh the installed packages:
|
||||
|
||||
@ -171,14 +188,16 @@ composer update
|
||||
|
||||
## Using development versions
|
||||
|
||||
Composer will by default download the latest stable version of silverstripe/installer.
|
||||
The `composer.json` file that comes with silverstripe/installer may also explicitly state it requires the stable version of cms and framework - this is to ensure that when developers are getting started, running `composer update` won't upgrade their project to an unstable version
|
||||
Composer will by default download the latest stable version of silverstripe/installer. The `composer.json` file that
|
||||
comes with silverstripe/installer may also explicitly state it requires the stable version of cms and framework - this
|
||||
is to ensure that when developers are getting started, running `composer update` won't upgrade their project to an
|
||||
unstable version
|
||||
|
||||
However it is relatively easy to tell composer to use development versions. Not only
|
||||
is this required if you want to contribute back to the SilverStripe project, it also allows you to get fixes and API changes early.
|
||||
However it is relatively easy to tell composer to use development versions. Not only is this required if you want to
|
||||
contribute back to the Silverstripe project, it also allows you to get fixes and API changes early.
|
||||
|
||||
This is a two step process. First you get composer to start a project based on
|
||||
the latest unstable silverstripe/installer
|
||||
This is a two step process. First you get composer to start a project based on the latest unstable
|
||||
silverstripe/installer
|
||||
|
||||
```
|
||||
composer create-project silverstripe/installer ./my-project dev-master
|
||||
@ -192,24 +211,28 @@ composer create-project silverstripe/installer ./my-project 4.0.x-dev
|
||||
|
||||
## Working with project forks and unreleased modules
|
||||
|
||||
By default, Composer will install modules listed on the Packagist site. There are a few reasons that you might not
|
||||
want to do this. For example:
|
||||
By default, Composer will install modules listed on the Packagist site. There are a few reasons that you might not want
|
||||
to do this. For example:
|
||||
|
||||
* You may have your own fork of a module, either specific to a project, or because you are working on a pull request
|
||||
* You may have a module that hasn't been released to the public.
|
||||
* You may have your own fork of a module, either specific to a project, or because you are working on a pull request
|
||||
* You may have a module that hasn't been released to the public.
|
||||
|
||||
There are many ways that you can address this, but this is one that we recommend, because it minimises the changes you would need to make to switch to an official version in the future.
|
||||
There are many ways that you can address this, but this is one that we recommend, because it minimises the changes you
|
||||
would need to make to switch to an official version in the future.
|
||||
|
||||
This is how you do it:
|
||||
|
||||
* **Ensure that all of your fork repositories have correct composer.json files.** Set up the project forks as you would a distributed package. If you have cloned a repository that already has a composer.json file, then there's nothing you need to do, but if not, you will need to create one yourself.
|
||||
* **Ensure that all of your fork repositories have correct composer.json files.** Set up the project forks as you would
|
||||
a distributed package. If you have cloned a repository that already has a composer.json file, then there's nothing you
|
||||
need to do, but if not, you will need to create one yourself.
|
||||
|
||||
* **List all your fork repositories in your project's composer.json files.** You do this in a `repositories` section. Set the `type` to `vcs`, and `url` to the URL of the repository. The result will look something like this:
|
||||
* **List all your fork repositories in your project's composer.json files.** You do this in a `repositories` section.
|
||||
Set the `type` to `vcs`, and `url` to the URL of the repository. The result will look something like this:
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "silverstripe/installer",
|
||||
"description": "The SilverStripe Framework Installer",
|
||||
"description": "The Silverstripe Framework Installer",
|
||||
"repositories": [
|
||||
{
|
||||
"type": "vcs",
|
||||
@ -219,13 +242,16 @@ This is how you do it:
|
||||
}
|
||||
```
|
||||
|
||||
* **Install the module as you would normally.** Use the regular composer function - there are no special flags to use a fork. Your fork will be used in place of the package version.
|
||||
* **Install the module as you would normally.** Use the regular composer function - there are no special flags to use a
|
||||
fork. Your fork will be used in place of the package version.
|
||||
|
||||
```
|
||||
composer require silverstripe/cms
|
||||
```
|
||||
|
||||
Composer will scan all of the repositories you list, collect meta-data about the packages within them, and use them in favour of the packages listed on packagist. To switch back to using the mainline version of the package, just remove the `repositories` section from `composer.json` and run `composer update`.
|
||||
Composer will scan all of the repositories you list, collect meta-data about the packages within them, and use them in
|
||||
favour of the packages listed on packagist. To switch back to using the mainline version of the package, just remove
|
||||
the `repositories` section from `composer.json` and run `composer update`.
|
||||
|
||||
Now add an "upstream" remote to the original repository location so you can rebase or merge your fork as required.
|
||||
|
||||
@ -234,15 +260,21 @@ cd cms
|
||||
git remote add -f upstream git://github.com/silverstripe/silverstripe-cms.git
|
||||
```
|
||||
|
||||
For more information, read the ["Repositories" chapter of the Composer documentation](http://getcomposer.org/doc/05-repositories.md).
|
||||
For more information, read
|
||||
the ["Repositories" chapter of the Composer documentation](http://getcomposer.org/doc/05-repositories.md).
|
||||
|
||||
### Forks and branch names
|
||||
|
||||
Generally, you should keep using the same pattern of branch names as the main repositories does. If your version is a fork of 4.0, then call the branch `4.0`, not `4.0-myproj` or `myproj`. Otherwise, the dependency resolution gets confused.
|
||||
Generally, you should keep using the same pattern of branch names as the main repositories does. If your version is a
|
||||
fork of 4.0, then call the branch `4.0`, not `4.0-myproj` or `myproj`. Otherwise, the dependency resolution gets
|
||||
confused.
|
||||
|
||||
Sometimes, however, this isn't feasible. For example, you might have a number of project forks stored in a single repository, such as your personal GitHub fork of a project. Or you might be testing/developing a feature branch. Or it might just be confusing to other team members to call the branch of your modified version `4.0`.
|
||||
Sometimes, however, this isn't feasible. For example, you might have a number of project forks stored in a single
|
||||
repository, such as your personal GitHub fork of a project. Or you might be testing/developing a feature branch. Or it
|
||||
might just be confusing to other team members to call the branch of your modified version `4.0`.
|
||||
|
||||
In this case, you need to use Composer's aliasing feature to specify how you want the project branch to be treated, when it comes to dependency resolution.
|
||||
In this case, you need to use Composer's aliasing feature to specify how you want the project branch to be treated, when
|
||||
it comes to dependency resolution.
|
||||
|
||||
Open `composer.json`, and find the module's `require`. Then put `as (core version name)` on the end.
|
||||
|
||||
@ -257,72 +289,74 @@ Open `composer.json`, and find the module's `require`. Then put `as (core versio
|
||||
}
|
||||
```
|
||||
|
||||
What this means is that when the `myproj` branch is checked out into a project, this will satisfy any dependencies that `4.0.x-dev` would meet. So, if another module has `"silverstripe/framework": "^4.0.0"` in its dependency list, it won't get a conflict.
|
||||
What this means is that when the `myproj` branch is checked out into a project, this will satisfy any dependencies
|
||||
that `4.0.x-dev` would meet. So, if another module has `"silverstripe/framework": "^4.0.0"` in its dependency list, it
|
||||
won't get a conflict.
|
||||
|
||||
Both the version and the alias are specified as Composer versions, not branch names. For the relationship between branch/tag names and Composer versions, read [the relevant Composer documentation](http://getcomposer.org/doc/02-libraries.md#specifying-the-version).
|
||||
Both the version and the alias are specified as Composer versions, not branch names. For the relationship between
|
||||
branch/tag names and Composer versions,
|
||||
read [the relevant Composer documentation](http://getcomposer.org/doc/02-libraries.md#specifying-the-version).
|
||||
|
||||
This is not the only way to set things up in Composer. For more information on this topic, read the ["Aliases" chapter of the Composer documentation](http://getcomposer.org/doc/articles/aliases.md).
|
||||
This is not the only way to set things up in Composer. For more information on this topic, read
|
||||
the ["Aliases" chapter of the Composer documentation](http://getcomposer.org/doc/articles/aliases.md).
|
||||
|
||||
## FAQ
|
||||
|
||||
### Error "The requested package silverstripe/framework 1.0.0 could not be found"
|
||||
|
||||
Composer needs hints about the base package version, either by using `composer create-project`
|
||||
as described above, or by checking out the `silverstripe-installer` project directly from version control.
|
||||
In order to use Composer on archive downloads from silverstripe.org, or other unversioned sources,
|
||||
an advanced workaround is to set the `COMPOSER_ROOT_VERSION` before every command
|
||||
as described above, or by checking out the `silverstripe-installer` project directly from version control. In order to
|
||||
use Composer on archive downloads from silverstripe.org, or other unversioned sources, an advanced workaround is to set
|
||||
the `COMPOSER_ROOT_VERSION` before every command
|
||||
([details](http://getcomposer.org/doc/03-cli.md#composer-root-version))
|
||||
|
||||
### How do I convert an existing module to using Composer?
|
||||
|
||||
Simply decide on a [unique name and vendor prefix](https://packagist.org/about),
|
||||
create a `composer.json`, and either commit it or send a pull request to the module author.
|
||||
Look at existing modules like the ["blog" module](https://github.com/silverstripe/silverstripe-blog/blob/master/composer.json) for good examples on what this file should contain.
|
||||
It's important that the file contains a custom "type" to declare it as a
|
||||
`silverstripe-module` or `silverstripe-theme` (see [custom installers](http://getcomposer.org/doc/articles/custom-installers.md)).
|
||||
Then register the module on [packagist.org](http://packagist.org).
|
||||
Simply decide on a [unique name and vendor prefix](https://packagist.org/about), create a `composer.json`, and either
|
||||
commit it or send a pull request to the module author. Look at existing modules like
|
||||
the ["blog" module](https://github.com/silverstripe/silverstripe-blog/blob/master/composer.json) for good examples on
|
||||
what this file should contain. It's important that the file contains a custom "type" to declare it as a
|
||||
`silverstripe-module` or `silverstripe-theme` (
|
||||
see [custom installers](http://getcomposer.org/doc/articles/custom-installers.md)). Then register the module
|
||||
on [packagist.org](http://packagist.org).
|
||||
|
||||
### How should I name my module?
|
||||
|
||||
Follow the packagist.org advice on choosing a [unique name and vendor prefix](https://packagist.org/about). Please don't use the `silverstripe/<modulename>` vendor prefix, since that's reserved
|
||||
for modules produced by SilverStripe Ltd. In order to declare that your module is
|
||||
in fact a SilverStripe module, use the "silverstripe" tag in the composer.json file,
|
||||
and set the "type" to "silverstripe-module".
|
||||
Follow the packagist.org advice on choosing a [unique name and vendor prefix](https://packagist.org/about). Please don't
|
||||
use the `silverstripe/<modulename>` vendor prefix, since that's reserved for modules produced by Silverstripe Ltd. In
|
||||
order to declare that your module is in fact a Silverstripe module, use the "silverstripe" tag in the composer.json
|
||||
file, and set the "type" to "silverstripe-module".
|
||||
|
||||
### What about themes?
|
||||
|
||||
Themes are technically just "modules" which are placed in the `themes/` subdirectory.
|
||||
We denote a special type for them in the `composer.json` (`"type": "silverstripe-theme"`),
|
||||
which triggers their installation into the correct path.
|
||||
Themes are technically just "modules" which are placed in the `themes/` subdirectory. We denote a special type for them
|
||||
in the `composer.json` (`"type": "silverstripe-theme"`), which triggers their installation into the correct path.
|
||||
|
||||
### How do I convert an existing project to Composer?
|
||||
|
||||
Copy the `composer.json` file from a newer release, and adjust the
|
||||
version settings in the "require" section to your needs. Then refer to
|
||||
the [upgrading documentation](/upgrading).
|
||||
You'll also need to update your webserver configuration
|
||||
from there (`.htaccess` or `web.config` files), in order to prevent
|
||||
web access to the composer-generated files.
|
||||
Copy the `composer.json` file from a newer release, and adjust the version settings in the "require" section to your
|
||||
needs. Then refer to the [upgrading documentation](/upgrading). You'll also need to update your webserver configuration
|
||||
from there (`.htaccess` or `web.config` files), in order to prevent web access to the composer-generated files.
|
||||
|
||||
### Do I need composer on my live server?
|
||||
|
||||
It depends on your deployment process. If you copy or rsync files to your live server,
|
||||
the process stays the same. If the live server hosts a git repository checkout,
|
||||
which is updated to push a newer version, you'll also need to run `composer install` afterwards.
|
||||
We recommend looking into [Composer "lock" files](http://getcomposer.org/doc/01-basic-usage.md#composer-lock-the-lock-file) for this purpose.
|
||||
It depends on your deployment process. If you copy or rsync files to your live server, the process stays the same. If
|
||||
the live server hosts a git repository checkout, which is updated to push a newer version, you'll also need to
|
||||
run `composer install` afterwards. We recommend looking
|
||||
into [Composer "lock" files](http://getcomposer.org/doc/01-basic-usage.md#composer-lock-the-lock-file) for this purpose.
|
||||
|
||||
### Can I keep using Downloads, Subversion Externals or Git Submodules?
|
||||
|
||||
Composer is more than just a file downloader. It comes with additional features such as
|
||||
[autoloading](http://getcomposer.org/doc/01-basic-usage.md#autoloading)
|
||||
or [scripts](http://getcomposer.org/doc/articles/scripts.md)
|
||||
which some modules will start relying on.
|
||||
Please check the module README for specific installation instructions.
|
||||
which some modules will start relying on. Please check the module README for specific installation instructions.
|
||||
|
||||
### I don't want to get development versions of everything!
|
||||
|
||||
You don't have to, Composer is designed to work on the constraints you set.
|
||||
You can declare the ["minimum-stability"](http://getcomposer.org/doc/04-schema.md#minimum-stability)
|
||||
on your project as suitable, or even whitelist specific modules as tracking
|
||||
a development branch while keeping others to their stable release.
|
||||
Read up on [Composer "lock" files](http://getcomposer.org/doc/01-basic-usage.md#composer-lock-the-lock-file) on how this all fits together.
|
||||
You don't have to, Composer is designed to work on the constraints you set. You can declare
|
||||
the ["minimum-stability"](http://getcomposer.org/doc/04-schema.md#minimum-stability)
|
||||
on your project as suitable, or even whitelist specific modules as tracking a development branch while keeping others to
|
||||
their stable release. Read up
|
||||
on [Composer "lock" files](http://getcomposer.org/doc/01-basic-usage.md#composer-lock-the-lock-file) on how this all
|
||||
fits together.
|
||||
|
@ -12,8 +12,8 @@ server.
|
||||
For each of these environments we may require slightly different configurations for our servers. This could be our debug
|
||||
level, caching backends, or - of course - sensitive information such as database credentials.
|
||||
|
||||
To manage environment variables, as well as other server globals, the [api:SilverStripe\Core\Environment] class
|
||||
provides a set of APIs and helpers.
|
||||
To manage environment variables, as well as other server globals, the [api:SilverStripe\Core\Environment] class provides
|
||||
a set of APIs and helpers.
|
||||
|
||||
## Security considerations
|
||||
|
||||
@ -26,20 +26,23 @@ webserver.
|
||||
|
||||
## Managing environment variables with `.env` files
|
||||
|
||||
By default a file named `.env` must be placed in your project root (ie: the same folder as your `composer.json`) or the parent
|
||||
directory. If this file exists, it will be automatically loaded by the framework and the environment variables will be
|
||||
set. An example `.env` file is included in the default installer named `.env.example`.
|
||||
By default a file named `.env` must be placed in your project root (ie: the same folder as your `composer.json`) or the
|
||||
parent directory. If this file exists, it will be automatically loaded by the framework and the environment variables
|
||||
will be set. An example `.env` file is included in the default installer named `.env.example`.
|
||||
|
||||
**Note:** The file must be named exactly `.env` and not any variation (such as `mysite.env` or `.env.mysite`) or it will not be detected automatically. If you wish to load environment variables from a file with a different name, you will need to do so manually. See the [Including an extra `.env` file](#including-an-extra-env-file) section below for more information.
|
||||
**Note:** The file must be named exactly `.env` and not any variation (such as `mysite.env` or `.env.mysite`) or it will
|
||||
not be detected automatically. If you wish to load environment variables from a file with a different name, you will
|
||||
need to do so manually. See the [Including an extra `.env` file](#including-an-extra-env-file) section below for more
|
||||
information.
|
||||
|
||||
## Managing environment variables with Apache
|
||||
|
||||
You can set "real" environment variables using Apache. Please
|
||||
[see the Apache docs for more information](https://httpd.apache.org/docs/current/env.html)
|
||||
[see the Apache docs for more information](https://httpd.apache.org/docs/current/env.html).
|
||||
|
||||
## How to access the environment variables
|
||||
|
||||
Accessing the environment varaibles should be done via the `Environment::getEnv()` method
|
||||
Accessing the environment variables should be done via the `Environment::getEnv()` method.
|
||||
|
||||
```php
|
||||
use SilverStripe\Core\Environment;
|
||||
@ -59,23 +62,22 @@ To use environment variables in `.yaml` configs you can reference them using bac
|
||||
|
||||
```yaml
|
||||
SilverStripe\Core\Injector\Injector:
|
||||
MyServiceClass:
|
||||
properties:
|
||||
MyProperty: '`ENV_VAR_HERE`'
|
||||
MyServiceClass:
|
||||
properties:
|
||||
MyProperty: '`ENV_VAR_HERE`'
|
||||
```
|
||||
|
||||
[info]
|
||||
Environment variables cannot be used outside of Injector config as of version 4.2.
|
||||
[/info]
|
||||
|
||||
|
||||
## Including an extra `.env` file
|
||||
|
||||
Sometimes it may be useful to include an extra `.env` file - on a shared local development environment where all
|
||||
database credentials could be the same. To do this, you can add this snippet to your `app/_config.php` file:
|
||||
|
||||
Note that by default variables cannot be overloaded from this file; Existing values will be preferred
|
||||
over values in this file.
|
||||
Note that by default variables cannot be overloaded from this file; Existing values will be preferred over values in
|
||||
this file.
|
||||
|
||||
```php
|
||||
use SilverStripe\Core\EnvironmentLoader;
|
||||
@ -86,7 +88,7 @@ $loader->loadFile($env);
|
||||
|
||||
## Core environment variables
|
||||
|
||||
SilverStripe core environment variables are listed here, though you're free to define any you need for your application.
|
||||
Silverstripe core environment variables are listed here, though you're free to define any you need for your application.
|
||||
|
||||
| Name | Description |
|
||||
| ---- | ----------- |
|
||||
@ -99,12 +101,12 @@ SilverStripe core environment variables are listed here, though you're free to d
|
||||
| `SS_DATABASE_PREFIX`| A prefix to add to the database name.|
|
||||
| `SS_DATABASE_TIMEZONE`| Set the database timezone to something other than the system timezone.
|
||||
| `SS_DATABASE_NAME` | Set the database name. Assumes the `$database` global variable in your config is missing or empty. |
|
||||
| `SS_DATABASE_CHOOSE_NAME`| Boolean/Int. If defined, then the system will choose a default database name for you if one isn't give in the $database variable. The database name will be "SS_" followed by the name of the folder into which you have installed SilverStripe. If this is enabled, it means that the phpinstaller will work out of the box without the installer needing to alter any files. This helps prevent accidental changes to the environment. If `SS_DATABASE_CHOOSE_NAME` is an integer greater than one, then an ancestor folder will be used for the database name. This is handy for a site that's hosted from /sites/examplesite/www or /buildbot/allmodules-2.3/build. If it's 2, the parent folder will be chosen; if it's 3 the grandparent, and so on.|
|
||||
| `SS_DATABASE_CHOOSE_NAME`| Boolean/Int. If defined, then the system will choose a default database name for you if one isn't give in the $database variable. The database name will be "SS_" followed by the name of the folder into which you have installed Silverstripe. If this is enabled, it means that the phpinstaller will work out of the box without the installer needing to alter any files. This helps prevent accidental changes to the environment. If `SS_DATABASE_CHOOSE_NAME` is an integer greater than one, then an ancestor folder will be used for the database name. This is handy for a site that's hosted from /sites/examplesite/www or /buildbot/allmodules-2.3/build. If it's 2, the parent folder will be chosen; if it's 3 the grandparent, and so on.|
|
||||
| `SS_DEPRECATION_ENABLED` | Enable deprecation notices for this environment.|
|
||||
| `SS_ENVIRONMENT_TYPE`| The environment type: dev, test or live.|
|
||||
| `SS_DEFAULT_ADMIN_USERNAME`| The username of the default admin. This is a user with administrative privileges.|
|
||||
| `SS_DEFAULT_ADMIN_PASSWORD`| The password of the default admin. This will not be stored in the database.|
|
||||
| `SS_USE_BASIC_AUTH`| Baseline protection for requests handled by SilverStripe. Usually requires additional security measures for comprehensive protection. See [Environment Types](/developer_guides/debugging/environment_types) for caveats.|
|
||||
| `SS_USE_BASIC_AUTH`| Baseline protection for requests handled by Silverstripe. Usually requires additional security measures for comprehensive protection. See [Environment Types](/developer_guides/debugging/environment_types) for caveats.|
|
||||
| `SS_SEND_ALL_EMAILS_TO`| If you define this constant, all emails will be redirected to this address.|
|
||||
| `SS_SEND_ALL_EMAILS_FROM`| If you define this constant, all emails will be sent from this address.|
|
||||
| `SS_ERROR_LOG` | Relative path to the log file. |
|
||||
|
@ -8,7 +8,7 @@ icon: sitemap
|
||||
|
||||
## Introduction
|
||||
|
||||
The directory-structure in SilverStripe is built on "convention over configuration", so the placement of some files and
|
||||
The directory-structure in Silverstripe is built on "convention over configuration", so the placement of some files and
|
||||
directories is meaningful to its logic.
|
||||
|
||||
## Core Structure
|
||||
@ -16,35 +16,32 @@ directories is meaningful to its logic.
|
||||
Directory | Description
|
||||
--------- | -----------
|
||||
`public/` | Webserver public webroot
|
||||
`public/assets/` | Images and other files uploaded via the SilverStripe CMS. You can also place your own content inside it, and link to it from within the content area of the CMS.
|
||||
`public/assets/` | Images and other files uploaded via the Silverstripe CMS. You can also place your own content inside it, and link to it from within the content area of the CMS.
|
||||
`public/assets/.protected/` | Default location for [protected assets](/developer_guides/files/file_security)
|
||||
`public/_resources/` | Exposed public files added from modules. Folders within this parent will match that of the source root location (this can be altered by configuration).
|
||||
`vendor/` | SilverStripe modules and other supporting libraries (the framework is in `vendor/silverstripe/framework`)
|
||||
`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`)
|
||||
`themes/` | Standard theme installation location
|
||||
|
||||
## Custom Code Structure
|
||||
|
||||
We're using `app/` as the default folder.
|
||||
Note that until SilverStripe 4.2, this directory was named `mysite/`,
|
||||
and PHP code was stored in a `code/` rather than `src/` folder.
|
||||
We're using `app/` as the default folder. Note that until Silverstripe 4.2, this directory was named `mysite/`, and PHP
|
||||
code was stored in a `code/` rather than `src/` folder.
|
||||
|
||||
| Directory | Description |
|
||||
| Directory | Description |
|
||||
| --------- | ----------- |
|
||||
| `app/` | This directory contains all of your code that defines your website. |
|
||||
| `app/_config` | YAML configuration specific to your application |
|
||||
| `app/src` | PHP code for model and controller (subdirectories are optional) |
|
||||
| `app/tests` | PHP Unit tests |
|
||||
| `app/templates` | HTML [templates](/developer_guides/templates) with *.ss-extension for the `$default` theme |
|
||||
| `app/css ` | CSS files |
|
||||
| `app/images ` | Images used in the HTML templates |
|
||||
| `app/javascript` | Javascript and other script files |
|
||||
| `app/client` | More complex projects can alternatively contain frontend assets in a common `client` folder |
|
||||
| `app/themes/<yourtheme>` | Custom nested themes (note: theme structure is described below) |
|
||||
| `app/` | This directory contains all of your code that defines your website. |
|
||||
| `app/_config` | YAML configuration specific to your application |
|
||||
| `app/src` | PHP code for model and controller (subdirectories are optional) |
|
||||
| `app/tests` | PHP Unit tests |
|
||||
| `app/templates` | HTML [templates](/developer_guides/templates) with *.ss-extension for the `$default` theme |
|
||||
| `app/css ` | CSS files |
|
||||
| `app/images ` | Images used in the HTML templates |
|
||||
| `app/javascript` | Javascript and other script files |
|
||||
| `app/client` | More complex projects can alternatively contain frontend assets in a common `client` folder |
|
||||
| `app/themes/<yourtheme>` | Custom nested themes (note: theme structure is described below) |
|
||||
|
||||
|
||||
Arbitrary directory-names are allowed, as long as they don't collide with
|
||||
existing modules or the directories lists in "Core Structure".
|
||||
Here's how you would reconfigure your default folder to `myspecialapp`.
|
||||
Arbitrary directory-names are allowed, as long as they don't collide with existing modules or the directories lists in
|
||||
"Core Structure". Here's how you would reconfigure your default folder to `myspecialapp`.
|
||||
|
||||
*myspecialapp/_config/config.yml*
|
||||
|
||||
@ -53,76 +50,73 @@ Here's how you would reconfigure your default folder to `myspecialapp`.
|
||||
Name: myspecialapp
|
||||
---
|
||||
SilverStripe\Core\Manifest\ModuleManifest:
|
||||
project: 'myspecialapp'
|
||||
project: 'myspecialapp'
|
||||
```
|
||||
|
||||
Check our [JavaScript Coding Conventions](javascript_coding_conventions) for more details
|
||||
on folder and file naming in SilverStripe core modules.
|
||||
Check our [JavaScript Coding Conventions](javascript_coding_conventions) for more details on folder and file naming in
|
||||
Silverstripe core modules.
|
||||
|
||||
## Themes Structure
|
||||
|
||||
| Directory | Description |
|
||||
| Directory | Description |
|
||||
| ------------------ | --------------------------- |
|
||||
| `themes/simple/` | Standard "simple" theme |
|
||||
| `themes/<yourtheme>/` | Custom theme base directory |
|
||||
| `themes/<yourtheme>/templates` | Theme templates |
|
||||
| `themes/<yourtheme>/css` | Theme CSS files |
|
||||
| `themes/simple/` | Standard "simple" theme |
|
||||
| `themes/<yourtheme>/` | Custom theme base directory |
|
||||
| `themes/<yourtheme>/templates` | Theme templates |
|
||||
| `themes/<yourtheme>/css` | Theme CSS files |
|
||||
|
||||
|
||||
See [themes](/developer_guides/templates/themes)
|
||||
See [themes](/developer_guides/templates/themes).
|
||||
|
||||
## Module Structure {#module_structure}
|
||||
|
||||
Modules are commonly stored as composer packages in the `vendor/` folder.
|
||||
They need to have a `_config.php` file or a `_config/` directory present,
|
||||
and should follow the same conventions as posed in "Custom Site Structure".
|
||||
Modules are commonly stored as composer packages in the `vendor/` folder. They need to have a `_config.php` file or
|
||||
a `_config/` directory present, and should follow the same conventions as posed in "Custom Site Structure".
|
||||
|
||||
Example Forum:
|
||||
|
||||
| Directory | Description |
|
||||
| Directory | Description |
|
||||
| --------- | ----------- |
|
||||
| `vendor/silverstripe/blog/`| This directory contains all of your code that defines your website. |
|
||||
| `vendor/silverstripe/blog/code` | PHP code for model and controller (subdirectories are optional) |
|
||||
| ... | ... |
|
||||
| `vendor/silverstripe/blog/`| This directory contains all of your code that defines your website. |
|
||||
| `vendor/silverstripe/blog/code` | PHP code for model and controller (subdirectories are optional) |
|
||||
| ... | ... |
|
||||
|
||||
Note: Before SilverStripe 4.x, modules were living as top-level folders in the webroot itself.
|
||||
Some modules might not have been upgraded to support placement in `vendor/`
|
||||
Note: Before Silverstripe 4.x, modules were living as top-level folders in the webroot itself. Some modules might not
|
||||
have been upgraded to support placement in `vendor/`.
|
||||
|
||||
### Module documentation
|
||||
|
||||
Module developers can bundle developer documentation with their code by producing
|
||||
plain text files inside a 'docs' folder located in the module folder. These files
|
||||
can be written with the Markdown syntax (See [Contributing Documentation](/contributing/documentation))
|
||||
Module developers can bundle developer documentation with their code by producing plain text files inside a 'docs'
|
||||
folder located in the module folder. These files can be written with the Markdown syntax
|
||||
(see [Contributing Documentation](/contributing/documentation))
|
||||
and include media such as images or videos.
|
||||
|
||||
Inside the `docs/` folder, developers should organise the markdown files into each
|
||||
separate language they wish to write documentation for (usually just `en`). Inside
|
||||
each languages' subfolder, developers then have freedom to create whatever structure
|
||||
they wish for organising the documentation they wish.
|
||||
Inside the `docs/` folder, developers should organise the markdown files into each separate language they wish to write
|
||||
documentation for (usually just `en`). Inside each languages' subfolder, developers then have freedom to create whatever
|
||||
structure they wish for organising the documentation they wish.
|
||||
|
||||
Example Blog Documentation:
|
||||
|
||||
| Directory | Description |
|
||||
| Directory | Description |
|
||||
| --------- | ----------- |
|
||||
| `vendor/silverstripe/blog/docs` | |
|
||||
| `vendor/silverstripe/blog/docs/_manifest_exclude` | Empty file to signify that SilverStripe does not need to load classes from this folder |
|
||||
| `vendor/silverstripe/blog/docs/en/` | English documentation |
|
||||
| `vendor/silverstripe/blog/docs/en/index.md` | Documentation homepage. Should provide an introduction and links to remaining docs |
|
||||
| `vendor/silverstripe/blog/docs/en/Getting_Started.md` | Documentation page. Naming convention is Uppercase and underscores. |
|
||||
| `vendor/silverstripe/blog/docs/en/_images/` | Folder to store any images or media |
|
||||
| `vendor/silverstripe/blog/docs/en/Some_Topic/` | You can organise documentation into nested folders. Naming convention is Uppercase and underscores. |
|
||||
| `vendor/silverstripe/blog/docs/en/04_Some_Topic/00_Getting_Started.md`|Structure is created by use of numbered prefixes. This applies to nested folders and documentations pages, index.md should not have a prefix.|
|
||||
|
||||
| `vendor/silverstripe/blog/docs` | |
|
||||
| `vendor/silverstripe/blog/docs/_manifest_exclude` | Empty file to signify that Silverstripe does not need to load classes from this folder |
|
||||
| `vendor/silverstripe/blog/docs/en/` | English documentation |
|
||||
| `vendor/silverstripe/blog/docs/en/index.md` | Documentation homepage. Should provide an introduction and links to remaining docs |
|
||||
| `vendor/silverstripe/blog/docs/en/Getting_Started.md` | Documentation page. Naming convention is Uppercase and underscores. |
|
||||
| `vendor/silverstripe/blog/docs/en/_images/` | Folder to store any images or media |
|
||||
| `vendor/silverstripe/blog/docs/en/Some_Topic/` | You can organise documentation into nested folders. Naming convention is Uppercase and underscores. |
|
||||
| `vendor/silverstripe/blog/docs/en/04_Some_Topic/00_Getting_Started.md`|Structure is created by use of numbered prefixes. This applies to nested folders and documentations pages, index.md should not have a prefix.|
|
||||
|
||||
## Autoloading
|
||||
|
||||
SilverStripe recursively detects classes in PHP files by building up a manifest used for autoloading,
|
||||
as well as respecting Composer's built-in autoloading for libraries. This means
|
||||
in most cases, you don't need to worry about include paths or `require()` calls
|
||||
in your own code - after adding a new class, simply regenerate the manifest
|
||||
by using a `flush=1` query parameter. See the ["Manifests" documentation](/developer_guides/execution_pipeline/manifests) for details.
|
||||
Silverstripe recursively detects classes in PHP files by building up a manifest used for autoloading, as well as
|
||||
respecting Composer's built-in autoloading for libraries. This means in most cases, you don't need to worry about
|
||||
include paths or `require()` calls in your own code - after adding a new class, simply regenerate the manifest by using
|
||||
a `flush=1` query parameter. See the ["Manifests" documentation](/developer_guides/execution_pipeline/manifests) for
|
||||
details.
|
||||
|
||||
## Best Practices
|
||||
|
||||
### Making /assets readonly
|
||||
|
||||
See [Secure coding](/developer_guides/security/secure_coding#filesystem)
|
||||
|
@ -6,15 +6,24 @@ icon: clipboard
|
||||
|
||||
# Recipes
|
||||
|
||||
Silverstripe CMS is powered by a system of components in the form of Composer packages. It consists of two types of package:
|
||||
Silverstripe CMS is powered by a system of components in the form of Composer packages. It consists of two types of
|
||||
package:
|
||||
|
||||
- **Modules**, which provide pieces of functionality (such as `silverstripe/cms` and `silverstripe/framework`)
|
||||
- **Recipes**, which group related Modules together to make them easier to install and release.
|
||||
|
||||
When we announce a new version of Silverstripe CMS and publish a changelog for it, we refer to a new set of _Recipe_ versions, which include new versions of some or all of their associated Modules. The easiest way to keep up to date with new Silverstripe CMS releases is to depend on one of the core Recipes:
|
||||
When we announce a new version of Silverstripe CMS and publish a changelog for it, we refer to a new set of _Recipe_
|
||||
versions, which include new versions of some or all of their associated Modules. The easiest way to keep up to date with
|
||||
new Silverstripe CMS releases is to depend on one of the core Recipes:
|
||||
|
||||
- [`silverstripe/recipe-core`](https://packagist.org/packages/silverstripe/recipe-core): Contains only the base framework, without the admin UI or CMS features.
|
||||
- [`silverstripe/recipe-cms`](https://packagist.org/packages/silverstripe/recipe-cms): Includes `recipe-core`, and adds the admin UI and CMS features. We recommend specifying this recipe in your dependencies.
|
||||
- [`silverstripe/installer`](https://packagist.org/packages/silverstripe/installer): Includes `recipe-cms`, and adds a default theme for the front-end of your site. We recommend creating new projects based on this recipe (via `composer create-project silverstripe/installer myproject ^4`)
|
||||
- [`silverstripe/recipe-core`](https://packagist.org/packages/silverstripe/recipe-core): Contains only the base
|
||||
framework, without the admin UI or CMS features.
|
||||
- [`silverstripe/recipe-cms`](https://packagist.org/packages/silverstripe/recipe-cms): Includes `recipe-core`, and adds
|
||||
the admin UI and CMS features. We recommend specifying this recipe in your dependencies.
|
||||
- [`silverstripe/installer`](https://packagist.org/packages/silverstripe/installer): Includes `recipe-cms`, and adds a
|
||||
default theme for the front-end of your site. We recommend creating new projects based on this recipe (
|
||||
via `composer create-project silverstripe/installer myproject ^4`).
|
||||
|
||||
When determining whether you are running the latest version of Silverstripe CMS, it is easier to refer to the Recipe version than the individual Module versions, which may not align with Recipe versions. You can use Packagist to find detailed information on what versions of individual modules are contained in each Recipe release.
|
||||
When determining whether you are running the latest version of Silverstripe CMS, it is easier to refer to the Recipe
|
||||
version than the individual Module versions, which may not align with Recipe versions. You can use Packagist to find
|
||||
detailed information on what versions of individual modules are contained in each Recipe release.
|
||||
|
@ -1,27 +1,24 @@
|
||||
---
|
||||
title: Getting Started
|
||||
introduction: SilverStripe is a web application. This means that you will need to have a webserver and database. We will take you through the setup of the server environment as well the application itself.
|
||||
introduction: Silverstripe is a web application. This means that you will need to have a
|
||||
webserver and database. We will take you through the setup of the server environment as well the application itself.
|
||||
icon: rocket
|
||||
---
|
||||
|
||||
## Server Requirements
|
||||
|
||||
SilverStripe requires PHP 7.1 or newer.
|
||||
It runs on many webservers and databases,
|
||||
but is most commonly served using Apache and MySQL/MariaDB.
|
||||
Silverstripe requires PHP 7.1 or newer. It runs on many webservers and databases, but is most commonly served using
|
||||
Apache and MySQL/MariaDB.
|
||||
|
||||
If you are setting up your own environment,
|
||||
you'll need to consider a few configuration settings
|
||||
such as URL rewriting and protecting access to certain files.
|
||||
Refer to our [server requirements](server_requirements) for details.
|
||||
If you are setting up your own environment, you'll need to consider a few configuration settings such as URL rewriting
|
||||
and protecting access to certain files. Refer to our [server requirements](server_requirements) for details.
|
||||
|
||||
## Quickstart Installation
|
||||
|
||||
If you're running Apache with MySQL/MariaDB already,
|
||||
and know your way around webservers, follow these steps to get started.
|
||||
SilverStripe is installed via [Composer](https://getcomposer.org), a package management tool for PHP that
|
||||
lets you install and upgrade the framework and other modules.
|
||||
Assuming you've got this tool, run the following command to install SilverStripe:
|
||||
If you're running Apache with MySQL/MariaDB already, and know your way around webservers, follow these steps to get
|
||||
started. Silverstripe is installed via [Composer](https://getcomposer.org), a package management tool for PHP that lets
|
||||
you install and upgrade the framework and other modules. Assuming you've got this tool, run the following command to
|
||||
install Silverstripe:
|
||||
|
||||
```
|
||||
composer create-project silverstripe/installer my-project
|
||||
@ -29,9 +26,8 @@ composer create-project silverstripe/installer my-project
|
||||
|
||||
Within the newly created `my-project` folder, point your webserver at the `public/` folder.
|
||||
|
||||
Now create a `.env` file your project root (not the `public/` folder).
|
||||
It sets up the minimum required [environment variables](environment_management).
|
||||
Replace the placeholders as required:
|
||||
Now create a `.env` file your project root (not the `public/` folder). It sets up the minimum
|
||||
required [environment variables](environment_management). Replace the placeholders as required:
|
||||
|
||||
```
|
||||
SS_DATABASE_CLASS="MySQLDatabase"
|
||||
@ -50,11 +46,10 @@ Now you should be able to build your database by running this command:
|
||||
vendor/bin/sake dev/build
|
||||
```
|
||||
|
||||
Your website should be available on your domain now (e.g. `http://localhost`).
|
||||
The CMS login can be accessed at `/admin`.
|
||||
Your website should be available on your domain now (e.g. `http://localhost`). The CMS login can be accessed at `/admin`.
|
||||
|
||||
For more information on how to maintain your installation or install projects,
|
||||
check out [Using SilverStripe with Composer](composer).
|
||||
For more information on how to maintain your installation or install projects, check
|
||||
out [Using Silverstripe with Composer](composer).
|
||||
|
||||
## Guided Installation
|
||||
|
||||
@ -62,14 +57,12 @@ If you are unsure on how this all works, please jump on our [lessons](https://ww
|
||||
Webserver setup is covered in
|
||||
[Lesson 4: Setting up a local dev environment](https://www.silverstripe.org/learn/lessons/v4/up-and-running-setting-up-a-local-silverstripe-dev-environment-1).
|
||||
|
||||
|
||||
|
||||
## Keep learning
|
||||
|
||||
[CHILDREN]
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
If you run into trouble, see [the Tips & Tricks forum](https://forum.silverstripe.org/c/tips) or
|
||||
check our [community help options](https://www.silverstripe.org/community/).
|
||||
If you run into trouble, see [the Tips & Tricks forum](https://forum.silverstripe.org/c/tips) or get help on
|
||||
our [Slack channel](https://www.silverstripe.org/community/slack-signup/).
|
||||
|
||||
|
@ -1,50 +1,51 @@
|
||||
---
|
||||
title: SilverStripe Documentation
|
||||
summary: Welcome to the SilverStripe Developer Documentation. This website is aimed at website developers looking to learn how to build and manage web applications with the SilverStripe Framework.
|
||||
title: Silverstripe Documentation
|
||||
summary: Welcome to the Silverstripe Developer Documentation. This website is aimed at website developers looking to learn how to build and manage web applications with the Silverstripe Framework.
|
||||
---
|
||||
|
||||
## Getting Started with SilverStripe
|
||||
## Getting Started with Silverstripe
|
||||
|
||||
Before you start developing your first web application, you'll need to install the latest version of SilverStripe onto
|
||||
a web server. The [Getting Started](/getting_started) section will show you what
|
||||
Before you start developing your first web application, you'll need to install the latest version of Silverstripe onto a
|
||||
web server. The [Getting Started](/getting_started) section will show you what
|
||||
[server requirements](/getting_started/server_requirements) you will need to meet and how to
|
||||
[install SilverStripe with Composer](/getting_started/composer).
|
||||
[install Silverstripe with Composer](/getting_started/composer).
|
||||
|
||||
To check out the features that SilverStripe offers without installing it, read the [Feature Overview](http://www.silverstripe.org/software/)
|
||||
To check out the features that Silverstripe offers without installing it, read
|
||||
the [Feature Overview](http://www.silverstripe.org/software/)
|
||||
and play with our [interactive demos](http://silverstripe.org/try).
|
||||
|
||||
## Getting support
|
||||
## Getting support
|
||||
|
||||
SilverStripe has an wide range of options for getting support:
|
||||
Silverstripe has a wide range of options for getting support:
|
||||
|
||||
* Join our [forum](https://forum.silverstripe.org)
|
||||
* Ask technical questions on [Stack Overflow](https://stackoverflow.com/questions/tagged/silverstripe)
|
||||
* Get help on our [Slack channel](https://www.silverstripe.org/community/slack-signup/)
|
||||
* Join our [forum](https://forum.silverstripe.org)
|
||||
* Ask technical questions on [Stack Overflow](https://stackoverflow.com/questions/tagged/silverstripe)
|
||||
* Read the technical reference in our [API Documentation](http://api.silverstripe.org/)
|
||||
* Get a user-focused overview of the CMS features in our [User Help](http://userhelp.silverstripe.com)
|
||||
* Discuss new features, API changes and the development [roadmap](http://www.silverstripe.org/software/roadmap/)
|
||||
on the ["feature ideas" category](https://forum.silverstripe.org/c/feature-ideas) in our forums
|
||||
|
||||
## Building your first Silverstripe Web application
|
||||
|
||||
## Building your first SilverStripe Web application
|
||||
Once you have completed the [Getting Started](/getting_started) guide and have got Silverstripe installed and running,
|
||||
the following [Tutorials](http://silverstripe.org/learn/lessons) will lead through the basics and core concepts of
|
||||
Silverstripe.
|
||||
|
||||
Once you have completed the [Getting Started](/getting_started) guide and have got SilverStripe
|
||||
installed and running, the following [Tutorials](http://silverstripe.org/learn/lessons) will lead through the basics and core concepts of
|
||||
SilverStripe.
|
||||
Make sure you know the basic concepts of PHP7 before attempting to follow the tutorials. If you have not programmed with
|
||||
PHP5 be sure to read
|
||||
the [Introduction to PHP5 (zend.com)](http://devzone.zend.com/6/php-101--php-for-the-absolute-beginner).
|
||||
|
||||
Make sure you know the basic concepts of PHP5 before attempting to follow the tutorials. If you have not programmed with PHP5 be sure to read the [Introduction to PHP5 (zend.com)](http://devzone.zend.com/6/php-101--php-for-the-absolute-beginner).
|
||||
## Silverstripe Concepts
|
||||
|
||||
|
||||
## SilverStripe Concepts
|
||||
|
||||
The [Developer Guides](/developer_guides) contain more detailed documentation on certain SilverStripe topics, 'how to'
|
||||
The [Developer Guides](/developer_guides) contain more detailed documentation on certain Silverstripe topics, 'how to'
|
||||
examples and reference documentation.
|
||||
|
||||
[CHILDREN Folder=02_Developer_Guides]
|
||||
|
||||
## Contributing to SilverStripe
|
||||
## Contributing to Silverstripe
|
||||
|
||||
The SilverStripe Framework, Content Management System and related websites are open source and welcome community
|
||||
The Silverstripe Framework, Content Management System and related websites are open source and welcome community
|
||||
contributions.
|
||||
|
||||
[CHILDREN Folder=05_Contributing]
|
||||
|
Loading…
Reference in New Issue
Block a user