Changes for README.md: 7 added lines, 61 removed lines.
Original line number
Diff line number
Diff line
Automatic Updates
---------------
### Requirements
- The Drupal project's codebase must be writable in order to use Automatic Updates. This includes Drupal, modules, themes and the Composer dependencies in the vendor directory. This makes Automatic Updates incompatible with some hosting platforms.
- The Composer executable must be in the PATH of the web server. If the Composer executable cannot be found the location can be set by adding
`$config['package_manager.settings']['executables']['composer'] = '/path/to/composer';` in `settings.php`
### Limitations
- Drupal multi-site installations are not supported.
- Automatic Updates does not support version control such as Git. It is the responsibility of site administrators to commit any updates to version control if needed.
- Automatic Updates does not support symlinks. See [What if Automatic Updates says I have symlinks in my codebase?](#what-if-automatic-updates-says-i-have-symlinks-in-my-codebase) for help if you have any.
### Updating contributed modules and themes
Automatic Updates includes a sub-module, Automatic Updates Extensions, which supports updating contributed modules and themes.
⚠️ ☢️️ **Automatic Updates Extensions is still experimental and under heavy development.** We encourage you to test it in your local development environment, or another low-stakes testing situation, but it is emphatically NOT ready for use in a production environment. ☢️ ⚠️
Package Manager is a framework for updating Drupal core and installing contributed modules and themes via Composer. It has no user interface, but it provides an API for creating a temporary copy of the current site, making changes to the copy, and then syncing those changes back into the live site.
#### What if Automatic Updates says I have symlinks in my codebase?
A fresh Drupal installation should not have any symlinks, but third party libraries and custom code can add them. If Automatic Updates says you have some, run the following command in your terminal to find them:
```shell
cd /var/www # Wherever your active directory is located.
find .-type l
```
You might see output like the below, indicating symlinks in Drush's `docs` directory, as an example:
Follow and read more on the [Automatic Updates Initiative overview and roadmap](https://www.drupal.org/project/ideas/issues/2940731).
Symlinks in Composer libraries can be addressed with [Drupal's Vendor Hardening Composer Plugin](https://www.drupal.org/docs/develop/using-composer/using-drupals-vendor-hardening-composer-plugin), which "removes extraneous directories from the project's vendor directory". Use it as follows.
First, add `drupal/core-vendor-hardening` to your Composer project:
```shell
composer require drupal/core-vendor-hardening
```
Then, add the following to the `composer.json` in your site root to handle the most common, known culprits. Add your own as necessary.
```json
"extra":{
"drupal-core-vendor-hardening":{
"drush/drush":["docs"],
"grasmash/yaml-expander":["scenarios"]
}
}
```
The new configuration will take effect on the next Composer install or update event. Do this to apply it immediately:
Automatic Updates includes a sub-module, Automatic Updates Extensions, which supports updating contributed modules and themes.
```shell
composer install
```
⚠️ ☢️️ **Automatic Updates Extensions is still experimental and under heavy development.** We encourage you to test it in your local development environment, or another low-stakes testing situation, but it is emphatically NOT ready for use in a production environment. ☢️ ⚠️
##### Custom code
### More info
Symlinks are seldom truly necessary and should be avoided in your own code. No solution currently exists to get around them--they must be removed in order to use Automatic Updates.
Get more details about the Package Manager module, once installed, at it help page (`admin/help/package_manager`).
$output.='<p>'.t('Package Manager is a framework for updating Drupal core and installing contributed modules and themes via Composer. It has no user interface, but it provides an API for creating a temporary copy of the current site, making changes to the copy, and then syncing those changes back into the live site.').'</p>';
$output.='<p>'.t('Package Manager dispatches events before and after various operations, and external code can integrate with it by subscribing to those events. For more information, see <code>package_manager.api.php</code>.').'</p>';
$output.='<p>'.t('Package Manager requires Composer @version or later available as an executable, and PHP must have permission to run it. The path to the executable may be stored in config, or it will be automatically detected. To set the path to Composer, you can add the following line to settings.php:',['@version'=>ComposerExecutableValidator::MINIMUM_COMPOSER_VERSION]).'</p>';
$output.='<p>'.t("Because Package Manager modifies the current site's code base, it is intentionally limited in certain ways to prevent unexpected changes from being made to the live site:").'</p>';
$output.='<ul>';
$output.='<li>'.t('Package Manager can only maintain one copy of the site at any given time. If a copy of the site already exists, another one cannot be created until the existing copy is destroyed.').'</li>';
$output.='<li>'.t('The temporary copy of the site is associated with the user or session that originally created it, and only that user or session can make changes to it.').'</li>';
$output.='<li>'.t('Modules cannot be uninstalled while Package Manager is syncing changes into live site.').'</li>';
$output.=' <li>'.t("The Drupal application's codebase must be writable in order to use Automatic Updates. This includes Drupal core, modules, themes and the Composer dependencies in the <code>vendor</code> directory. This makes Automatic Updates incompatible with some hosting platforms.").'</li>';
$output.=' <li>'.t('Package Manager requires Composer @version or later available as an executable, and PHP must have permission to run it. It should be detected automatically. If not, see <a href="#package-manager-faq-composer-not-found">What if it says the "composer" executable cannot be found?</a>.',['@version'=>ComposerExecutableValidator::MINIMUM_COMPOSER_VERSION]).'</li>';
$output.='<p>'.t("Because Package Manager modifies the current site's code base, it is intentionally limited in certain ways to prevent unexpected changes to the live site:").'</p>';
$output.='<ul>';
$output.=' <li>'.t('It does not support Drupal multi-site installations.').'</li>';
$output.=' <li>'.t('It does not support symlinks. If you have any, see <a href="#package-manager-faq-composer-not-found">What if it says I have symlinks in my codebase?</a>.').'</li>';
$output.=' <li>'.t('It does not automatically perform version control operations, e.g., with Git. Site administrators are responsible for committing updates.').'</li>';
$output.=' <li>'.t('It can only maintain one copy of the site at any given time. If a copy of the site already exists, another one cannot be created until the existing copy is destroyed.').'</li>';
$output.=' <li>'.t('It associates the temporary copy of the site with the user or session that originally created it, and only that user or session can make changes to it.').'</li>';
$output.=' <li>'.t('It does not allow modules to be uninstalled while syncing changes into live site.').'</li>';
$output.='</ul>';
$output.='<p>'.t('For more information, see the <a href=":package-manager-documentation">online documentation for the Package Manager module</a>.',[':package-manager-documentation'=>'https://www.drupal.org/docs/8/core/modules/package-manager']).'</p>';
$output.='<h4 id="package-manager-faq-composer-not-found">'.t('What if it says the "composer" executable cannot be found?').'</h4>';
$output.='<p>'.t('If the <code>composer</code> executable path cannot be automatically determined, it can be explicitly set in by adding the following line to <code>settings.php</code>:').'</p>';
$output.='<h4 id="package-manager-faq-symlinks-found">'.t('What if it says I have symlinks in my codebase?').'</h4>';
$output.='<p>'.t('A fresh Drupal installation should not have any symlinks, but third party libraries and custom code can add them. If Automatic Updates says you have some, run the following command in your terminal to find them:').'</p>';
$output.='<pre><code>';
$output.='cd /var/www # Wherever your active directory is located.'.PHP_EOL;
$output.='find . -type l';
$output.='</code></pre>';
$output.='<p>'.t("You might see output like the below, indicating symlinks in Drush's <code>docs</code> directory, as an example:").'</p>';
$output.='<p>'.t('Symlinks in Composer libraries can be addressed with <a href=":vendor-hardening-composer-plugin-documentation">Drupal\'s Vendor Hardening Composer Plugin</a>, which "removes extraneous directories from the project\'s vendor directory". Use it as follows.',[':vendor-hardening-composer-plugin-documentation'=>'https://www.drupal.org/docs/develop/using-composer/using-drupals-vendor-hardening-composer-plugin']).'</p>';
$output.='<p>'.t('First, add `drupal/core-vendor-hardening` to your Composer project:').'</p>';
$output.='<p>'.t('Then, add the following to the `composer.json` in your site root to handle the most common, known culprits. Add your own as necessary.').'</p>';
$output.='<p>'.t('Symlinks are seldom truly necessary and should be avoided in your own code. No solution currently exists to get around them--they must be removed in order to use Automatic Updates.').'</p>';
