diff --git a/docs/en/00_Getting_Started/02_Composer.md b/docs/en/00_Getting_Started/02_Composer.md index 3e2878ccb..6dd8dde71 100644 --- a/docs/en/00_Getting_Started/02_Composer.md +++ b/docs/en/00_Getting_Started/02_Composer.md @@ -3,50 +3,29 @@ title: Composer summary: What is composer and how to use it with Silverstripe CMS --- -# Installing and Upgrading with Composer +# Using SilverStripe with Composer -Composer is a package management tool for PHP that lets you install and upgrade SilverStripe and its modules. Although installing Composer is one extra step, it will give you much more flexibility than just downloading the file from silverstripe.org. This is our recommended way of downloading SilverStripe and managing your code. +## Requirements -For more information about Composer, visit [its website](http://getcomposer.org/). +[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). -# Basic usage - -## Installing composer - 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 composer is installed globally. - -You can then run Composer commands by calling `composer`. For example: +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 ``` -[hint] -It is also possible to keep `composer.phar` out of your path, for example, to put it in your project root. Every command would then start with `php composer.phar` instead of `composer`. This is handy if need to keep your installation isolated from the rest of your computer's set-up, but we recommend putting composer into the path for most people. -[/hint] - -#### Updating composer - -If you already have composer installed you can update it by running: - -``` -sudo composer self-update -``` - -Composer updates regularly, so you should run this command fairly often. These instructions assume you are running the latest version. - -## Installing Composer on Windows WAMP -For those that use WAMP as a development environment, [detailed information is available on installing using Composer.](/getting_started/installation/windows) - ## Create a new site -Composer can create a new site for you, using the installer as a template (by default composer will download the latest stable version): +Composer 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/website/folder ^4 +composer create-project silverstripe/installer my-project ``` If you want to get all additional fixtures for testing, such as behat and phpunit configuration, @@ -56,15 +35,15 @@ 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. -`./my/website/folder` should be the root directory where your site will live. +`./my-project` should be the root directory where your site will live. For example, on OS X, you might use a 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 `3.5.0` release: +You can also specify a version to download that version explicitly, i.e. this will download the older `4.3.3` release: ``` -composer create-project silverstripe/installer ./my/website/folder 3.5.0 +composer create-project silverstripe/installer ./my-project 4.3.3 ``` When `create-project` is used with a release version like above, @@ -74,36 +53,20 @@ 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. 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/forum +composer require silverstripe/blog ``` -This will install the forum module in the latest compatible version. If you know the specific version you want to install already (such as `^0.8`), you can add it after the package name. For more information, read the [Composer documentation](http://getcomposer.org/doc/01-basic-usage.md#the-require-key): +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/forum ^0.8 +composer require silverstripe/blog ^2 ``` -By default, Composer updates other existing modules (like `framework` and `cms`), -and installs "dev" dependencies like PHPUnit. In case you don't need those dependencies, -use the following command instead: - -``` -composer require --no-update silverstripe/forum -composer update --no-dev -``` - -The `require` command has two parts. First is `silverstripe/forum`. This is the name of the package. -You can find other packages with the following command: - -``` -composer search silverstripe -``` - -This will return a list of package names of the forum `vendor/package`. If you prefer, you can search for packages on [packagist.org](https://packagist.org/search/?q=silverstripe). - [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`. [/warning] @@ -115,7 +78,7 @@ Except for the control code of the Voyager space probe, every piece of code in t To get the latest updates of the modules in your project, run this command: ``` -composer update --no-dev +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. @@ -135,77 +98,11 @@ So your deployment process, as it relates to Composer, should be as follows: ## Composer managed modules, Git and .gitignore -Modules and themes managed by composer should not be committed with your projects source code. 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). -Since SilverStripe modules are installed into their own folder, you have to manage your [.gitignore](http://git-scm.com/docs/gitignore) to ensure they are ignored from your repository. - -Here is the default SilverStripe [.gitignore](http://git-scm.com/docs/gitignore) with the forum module ignored - -``` -assets/* -.env -tools/phing-metadata -silverstripe-cache -.buildpath -.project -.settings -.idea -.DS_Store -vendor/ -# Don't include the forum module, as this will be installed with composer -forum -``` - -In large projects it can get difficult to manage your [.gitignore](http://git-scm.com/docs/gitignore) and ensure it contains all composer managed modules and themes. - -You can automate this with the [SSAutoGitIgnore](https://github.com/guru-digital/SSAutoGitIgnore/) package. -This package will maintain your [.gitignore](http://git-scm.com/docs/gitignore) and ensure it is kept up to date with your composer managed modules without affecting custom ignores. Once installed and setup, it will automatically run every time you install, remove or update modules using composer. - -### Installing and enabling the SSAutoGitIgnore package - -Include the package in your project by running this command - -``` -composer require gdmedia/ss-auto-git-ignore --dev -``` - -Edit your `composer.json` and insert: - -```json -"scripts": { - "post-update-cmd": "GDM\\SSAutoGitIgnore\\UpdateScript::Go" -} -``` - -This will instruct composer to run SSAutoGitIgnore after every update. SSAutoGitIgnore will then ensure composer managed models and themes are correctly added to your [.gitignore](http://git-scm.com/docs/gitignore). -For more information about SSAutoGitIgnore, see the [SSAutoGitIgnore home page](https://github.com/guru-digital/SSAutoGitIgnore/). -For more information about post-updated-cmd and scripts, read the ["Scripts" chapter of the Composer documentation](https://getcomposer.org/doc/articles/scripts.md). - -Full example of composer.json with the SSAutoGitIgnore installed and enabled - -```json -{ - "name": "silverstripe/installer", - "description": "The SilverStripe Framework Installer", - "require": { - "php": ">=5.5.0", - "silverstripe/cms": "^4.0", - "silverstripe/framework": "^4.0", - "silverstripe-themes/simple": "~3.2.0" - }, - "require-dev": { - "silverstripe/docsviewer": "^3.0", - "gdmedia/ss-auto-git-ignore": "^1.0" - }, - "scripts": { - "post-update-cmd": "GDM\\SSAutoGitIgnore\\UpdateScript::Go" - }, - "minimum-stability": "dev", - "prefer-stable": true -} -``` - -# Dev Environments for Contributing Code {#contributing} +## 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: @@ -217,11 +114,11 @@ You have to tell composer three things in order to be able to do this: The first two steps are done as part of the initial create project using additional arguments. ``` -composer create-project --keep-vcs --dev silverstripe/installer ./my/website/folder 4.0.x-dev --prefer-source +composer create-project --keep-vcs --dev silverstripe/installer ./my-project 4.x-dev --prefer-source ``` -The process will take a bit longer, since all modules are checked out as full git repositories which you can work on. The command checks out from the 4.0 release line. To check out from master instead, -replace `4.0.x-dev` with `dev-master` (more info on [composer version naming](http://getcomposer.org/doc/02-libraries.md#specifying-the-version)). +The 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 @@ -251,13 +148,13 @@ To remove dependencies, or if you prefer seeing all your dependencies in a text "name": "silverstripe/installer", "description": "The SilverStripe Framework Installer", "require": { - "php": ">=5.5.0", - "silverstripe/cms": "^4.0", - "silverstripe/framework": "^4.0", - "silverstripe-themes/simple": "~3.2.0" + "php": ">=7.3", + "silverstripe/cms": "^4", + "silverstripe/framework": "^4", + "silverstripe-themes/simple": "^3" }, "require-dev": { - "silverstripe/docsviewer": "^3.0" + "silverstripe/docsviewer": "^3" }, "minimum-stability": "dev", "prefer-stable": true @@ -284,13 +181,13 @@ This is a two step process. First you get composer to start a project based on the latest unstable silverstripe/installer ``` -composer create-project silverstripe/installer ./my/website/folder dev-master +composer create-project silverstripe/installer ./my-project dev-master ``` Or for the latest development version in the 4.0.x series ``` -composer create-project silverstripe/installer ./my/website/folder 4.0.x-dev +composer create-project silverstripe/installer ./my-project 4.0.x-dev ``` ## Working with project forks and unreleased modules @@ -416,7 +313,7 @@ We recommend looking into [Composer "lock" files](http://getcomposer.org/doc/01- ### Can I keep using Downloads, Subversion Externals or Git Submodules? -Yes and no. Composer comes with additional features such as +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. diff --git a/docs/en/00_Getting_Started/index.md b/docs/en/00_Getting_Started/index.md index c53626b68..d4dad373e 100644 --- a/docs/en/00_Getting_Started/index.md +++ b/docs/en/00_Getting_Started/index.md @@ -19,7 +19,7 @@ Refer to our [server requirements](server_requirements) for details. 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](composer), a package management tool for PHP that +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: @@ -28,9 +28,20 @@ composer create-project silverstripe/installer my-project ``` Within the newly created `my-project` folder, point your webserver at the `public/` folder. -Rename `.env.example` to `.env` in your project, and configure your database connection there. -See [environment variables](environment_management) for available configuration options, -e.g. to configure a default CMS login via `SS_DEFAULT_ADMIN_USERNAME`. + +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" +SS_DATABASE_NAME="" +SS_DATABASE_SERVER="localhost" +SS_DATABASE_USERNAME="" +SS_DATABASE_PASSWORD="" +SS_DEFAULT_ADMIN_USERNAME="admin" +SS_DEFAULT_ADMIN_PASSWORD="password" +``` Now you should be able to build your database by running this command: @@ -41,11 +52,14 @@ 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`. +For more information on how to maintain your installation or install projects, +check out [Using SilverStripe with Composer](composer). + ## Guided Installation If you are unsure on how this all works, please jump on our [lessons](https://www.silverstripe.org/learn/lessons/v4/). Webserver setup is covered in -[Lesson 4: Setting up a local dev environment](https://www.silverstripe.org/learn/lessons/v4/up-and-running-setting-up-a-local-silverstripe-dev-environment-1) +[Lesson 4: Setting up a local dev environment](https://www.silverstripe.org/learn/lessons/v4/up-and-running-setting-up-a-local-silverstripe-dev-environment-1). diff --git a/docs/en/02_Developer_Guides/01_Templates/06_Themes.md b/docs/en/02_Developer_Guides/01_Templates/06_Themes.md index 62ead9a04..445b97d81 100644 --- a/docs/en/02_Developer_Guides/01_Templates/06_Themes.md +++ b/docs/en/02_Developer_Guides/01_Templates/06_Themes.md @@ -12,17 +12,15 @@ application can provide multiple unique themes (i.e a mobile theme). ## Downloading Head to the [ themes section of the addons site ](http://addons.silverstripe.org/add-ons?search=&type=theme) to check out the range of themes the -community has built. Each theme has a page with links you can use to preview and download it. Themes are normally published and downloaded using Composer, -but may be available as archive files as well. +community has built. Each theme has a page with links you can use to preview and download it. Themes are published and downloaded using Composer, +just like any other [SilverStripe module](/developer_guides/extending/modules). ## Installation -### Via Composer - -If a theme has Composer support you can require it directly through `composer`. +Themes can be installed through `composer`. ```bash -composer require author/theme_name [version] +composer require my_vendor/my_theme [version] ``` *Note:* `[version]` should be replaced with a version constraint if you know it, otherwise leave it blank to pull the latest version compatible with your project. @@ -71,11 +69,6 @@ main styles of syntax: - `mymodule:` - Also points to the base folder of the given module, but without a vendor. The `:` is necessary to distinguish this from a non-module theme. -### Manually - -Unpack the contents of the zip file you download into the `themes` directory in your SilverStripe installation. The -theme should be accessible at `themes/theme_name`. - ## Developing your own theme A `theme` within SilverStripe is simply a collection of templates and other front end assets such as javascript and CSS located within the `themes` directory. diff --git a/docs/en/02_Developer_Guides/05_Extending/00_Modules.md b/docs/en/02_Developer_Guides/05_Extending/00_Modules.md index 037b18282..aff8e3636 100644 --- a/docs/en/02_Developer_Guides/05_Extending/00_Modules.md +++ b/docs/en/02_Developer_Guides/05_Extending/00_Modules.md @@ -11,7 +11,8 @@ framework. A module is a collection of classes, templates, and other resources that is loaded into a directory. Usually this directory is a [Composer package](https://getcomposer.org/), which is placed in the `vendor/` folder. -SilverStripe modules are just Composer packages with a toplevel `_config` directory or `_config.php` file. +SilverStripe modules are just Composer packages with a toplevel `_config` directory or `_config.php` file, +as well as a special type in their `composer.json` file. ``` app/ @@ -29,7 +30,7 @@ vendor/my_vendor/my_module/ SilverStripe will automatically include any PHP classes and templates from within your module when you next flush your cache. -Creating a module is a good way to re-use abstract code and templates across multiple projects. SilverStripe already +Creating a module is a good way to re-use code and templates across multiple projects. SilverStripe already has certain modules included, for example the `cms` module and core functionality such as commenting and spam protection are also abstracted into modules allowing developers the freedom to choose what they want. diff --git a/docs/en/02_Developer_Guides/06_Testing/index.md b/docs/en/02_Developer_Guides/06_Testing/index.md index fe825053a..345bed2c9 100644 --- a/docs/en/02_Developer_Guides/06_Testing/index.md +++ b/docs/en/02_Developer_Guides/06_Testing/index.md @@ -26,7 +26,6 @@ fundamental concepts that we build on in this documentation. In order to run tests, you need to install SilverStripe using [/getting-started/composer](Composer), which will pull in the required development dependencies to run tests. -These are not included in the standard archive downloads provided from silverstripe.org. Tests are run from the commandline, in your webroot folder: diff --git a/docs/en/04_Changelogs/4.5.0.md b/docs/en/04_Changelogs/4.5.0.md index fb9555645..92b038032 100644 --- a/docs/en/04_Changelogs/4.5.0.md +++ b/docs/en/04_Changelogs/4.5.0.md @@ -25,6 +25,19 @@ The installer UI will continue to live on under the name "installer-wizard" in a can be added incrementally to core recipe installation, using `composer require silverstripe/installer-wizard`. It is no longer a commercially supported module. +## Archive downloads have been removed + +SilverStripe has gradually switched from using file archives +to installation via [Composer](https://getcomposer.org). +This enabled a much more diverse module ecosystem, +with clear dependency management and greater ability to +check and enforce constraints and semantic versioning. + +Starting with this release, we are no longer publishing `silverstripe/installer` +as a file archive download on silverstripe.org. +If your workflow relied on these downloads, please switch to using Composer. +See [#9232](https://github.com/silverstripe/silverstripe-framework/issues/9232) for details. + ## Generic login form styling {#login-forms} Login forms in SilverStripe are traditionally embedded in your page template. diff --git a/docs/en/05_Contributing/05_Making_A_SilverStripe_Core_Release.md b/docs/en/05_Contributing/05_Making_A_SilverStripe_Core_Release.md index a7c229913..032d6ca3c 100644 --- a/docs/en/05_Contributing/05_Making_A_SilverStripe_Core_Release.md +++ b/docs/en/05_Contributing/05_Making_A_SilverStripe_Core_Release.md @@ -349,47 +349,23 @@ Once this has been done, then the release is ready to be published live. ### Stage 2: Release publication Once a release has been generated, has its translations updated, changelog generated, -and tested, the next step is to publish the release. This involves tagging, -building an archive, and uploading to -[www.silverstripe.org](http://www.silverstripe.org/software/download/) download page. - -Invoked by running `cow release:publish` in the format as below: +and tested, the next step is to publish the release by tagging all modules +in the release plan. `cow release:publish [] -vvv` -E.g. +Example on how to publish the installer: `cow release:publish 4.0.1 silverstripe/installer` -This command has these options: +Options: * `-vvv` to ensure all underlying commands are echoed * `--directory ` to specify the folder to look for the project created in the prior step. As with above, it will be guessed if omitted. You can run this command in the `./release-` directory and omit this option. -* `--aws-profile ` to specify the AWS profile name for uploading releases to s3. Check with - damian@silverstripe.com if you don't have an AWS key setup. -* `--skip-archive-upload` to disable both "archive" and "upload". This is useful if doing a private release and - you don't want to upload this file to AWS. -* `--skip-upload` to disable the "upload" command (but not archive) -As with the `cow release` command, this step is broken down into the following -subtasks which are invoked in sequence: - -* `release:tag` Each module will have the appropriate tag applied (except the theme). All tags are pushed up to origin - on github. -* `release:archive` This will generate a new tar.gz and zip archive, each for - cms and framework-only installations. These will be copied to the root folder - of the release directory, although the actual build will be created in temporary - directories (so any temp files generated during testing will not end up in the release). - If the tags generated in the prior step are not yet available on packagist (which can - take a few minutes at times) then this task will cycle through a retry-cycle, - which will re-attempt the archive creation periodically until these tags are available. -* `release:upload` This will invoke the AWS CLI command to upload these archives to the - s3 bucket `silverstripe-ssorg-releases`. If you have setup your AWS profile - for silverstripe releases under a non-default name, you can specify this profile - on the command line with the `--aws-profile=` command. - See "Stage 3: Let the world know" to check if this worked correctly. +Note: We are no longer creating or publishing archive downloads on silverstripe.org/download. Once all of these commands have completed there are a couple of final tasks left that aren't strictly able to be automated: @@ -467,9 +443,7 @@ will need to be regularly updated. silverstripe.org has the release available. If it's a stable, it will appear at the top of the page. If it's a pre-release, it will be available under the [development builds](http://www.silverstripe.org/download#download-releases) - section. If it's not available, you might need to check that the release was - properly uploaded to aws s3, or that you aren't viewing a cached version of - the download page. You can cache-bust this by adding `?release=` to + section. You can cache-bust this by adding `?release=` to the url. If things aren't working properly (and you have admin permissions) you can run the [CoreReleaseUpdateTask](http://www.silverstripe.org/dev/tasks/CoreReleaseUpdateTask) to synchronise with packagist.