|
6 | 6 | [](./LICENSE) |
7 | 7 |
|
8 | 8 | ## Introduction |
| 9 | +This project template provides a starter kit for managing your site |
| 10 | +dependencies with [Composer](https://getcomposer.org/). |
9 | 11 |
|
10 | 12 | Fork of [drupal-composer/drupal-project](https://github.com/drupal-composer/drupal-project) used to pin down Drupal core versions |
11 | 13 | for [islandora-playbook](https://github.com/Islandora-Devops/islandora-playbook). |
@@ -46,3 +48,133 @@ We recommend using the [islandora-playbook](https://github.com/Islandora-Devops/ |
46 | 48 | ## License |
47 | 49 |
|
48 | 50 | [GPLv2](http://www.gnu.org/licenses/gpl-2.0.txt) |
| 51 | +> Note: The instructions below refer to the [global composer installation](https://getcomposer.org/doc/00-intro.md#globally). |
| 52 | +You might need to replace `composer` with `php composer.phar` (or similar) |
| 53 | +for your setup. |
| 54 | + |
| 55 | +After that you can create the project: |
| 56 | + |
| 57 | +``` |
| 58 | +composer create-project drupal-composer/drupal-project:8.x-dev some-dir --no-interaction |
| 59 | +``` |
| 60 | + |
| 61 | +With `composer require ...` you can download new dependencies to your |
| 62 | +installation. |
| 63 | + |
| 64 | +``` |
| 65 | +cd some-dir |
| 66 | +composer require drupal/devel:~1.0 |
| 67 | +``` |
| 68 | + |
| 69 | +The `composer create-project` command passes ownership of all files to the |
| 70 | +project that is created. You should create a new git repository, and commit |
| 71 | +all files not excluded by the .gitignore file. |
| 72 | + |
| 73 | +## What does the template do? |
| 74 | + |
| 75 | +When installing the given `composer.json` some tasks are taken care of: |
| 76 | + |
| 77 | +* Drupal will be installed in the `web`-directory. |
| 78 | +* Autoloader is implemented to use the generated composer autoloader in `vendor/autoload.php`, |
| 79 | + instead of the one provided by Drupal (`web/vendor/autoload.php`). |
| 80 | +* Modules (packages of type `drupal-module`) will be placed in `web/modules/contrib/` |
| 81 | +* Theme (packages of type `drupal-theme`) will be placed in `web/themes/contrib/` |
| 82 | +* Profiles (packages of type `drupal-profile`) will be placed in `web/profiles/contrib/` |
| 83 | +* Creates default writable versions of `settings.php` and `services.yml`. |
| 84 | +* Creates `web/sites/default/files`-directory. |
| 85 | +* Latest version of drush is installed locally for use at `vendor/bin/drush`. |
| 86 | +* Latest version of DrupalConsole is installed locally for use at `vendor/bin/drupal`. |
| 87 | +* Creates environment variables based on your .env file. See [.env.example](.env.example). |
| 88 | + |
| 89 | +## Updating Drupal Core |
| 90 | + |
| 91 | +This project will attempt to keep all of your Drupal Core files up-to-date; the |
| 92 | +project [drupal/core-composer-scaffold](https://github.com/drupal/core-composer-scaffold) |
| 93 | +is used to ensure that your scaffold files are updated every time drupal/core is |
| 94 | +updated. If you customize any of the "scaffolding" files (commonly .htaccess), |
| 95 | +you may need to merge conflicts if any of your modified files are updated in a |
| 96 | +new release of Drupal core. |
| 97 | + |
| 98 | +Follow the steps below to update your core files. |
| 99 | + |
| 100 | +1. Run `composer update drupal/core drupal/core-dev --with-dependencies` to update Drupal Core and its dependencies. |
| 101 | +2. Run `git diff` to determine if any of the scaffolding files have changed. |
| 102 | + Review the files for any changes and restore any customizations to |
| 103 | + `.htaccess` or `robots.txt`. |
| 104 | +1. Commit everything all together in a single commit, so `web` will remain in |
| 105 | + sync with the `core` when checking out branches or running `git bisect`. |
| 106 | +1. In the event that there are non-trivial conflicts in step 2, you may wish |
| 107 | + to perform these steps on a branch, and use `git merge` to combine the |
| 108 | + updated core files with your customized files. This facilitates the use |
| 109 | + of a [three-way merge tool such as kdiff3](http://www.gitshah.com/2010/12/how-to-setup-kdiff-as-diff-tool-for-git.html). This setup is not necessary if your changes are simple; |
| 110 | + keeping all of your modifications at the beginning or end of the file is a |
| 111 | + good strategy to keep merges easy. |
| 112 | + |
| 113 | +## Generate composer.json from existing project |
| 114 | + |
| 115 | +With using [the "Composer Generate" drush extension](https://www.drupal.org/project/composer_generate) |
| 116 | +you can now generate a basic `composer.json` file from an existing project. Note |
| 117 | +that the generated `composer.json` might differ from this project's file. |
| 118 | + |
| 119 | + |
| 120 | +## FAQ |
| 121 | + |
| 122 | +### Should I commit the contrib modules I download? |
| 123 | + |
| 124 | +Composer recommends **no**. They provide [argumentation against but also |
| 125 | +workrounds if a project decides to do it anyway](https://getcomposer.org/doc/faqs/should-i-commit-the-dependencies-in-my-vendor-directory.md). |
| 126 | + |
| 127 | +### Should I commit the scaffolding files? |
| 128 | + |
| 129 | +The [Drupal Composer Scaffold](https://github.com/drupal/core-composer-scaffold) plugin can download the scaffold files (like |
| 130 | +index.php, update.php, …) to the web/ directory of your project. If you have not customized those files you could choose |
| 131 | +to not check them into your version control system (e.g. git). If that is the case for your project it might be |
| 132 | +convenient to automatically run the drupal-scaffold plugin after every install or update of your project. You can |
| 133 | +achieve that by registering `@composer drupal:scaffold` as post-install and post-update command in your composer.json: |
| 134 | + |
| 135 | +```json |
| 136 | +"scripts": { |
| 137 | + "post-install-cmd": [ |
| 138 | + "@composer drupal:scaffold", |
| 139 | + "..." |
| 140 | + ], |
| 141 | + "post-update-cmd": [ |
| 142 | + "@composer drupal:scaffold", |
| 143 | + "..." |
| 144 | + ] |
| 145 | +}, |
| 146 | +``` |
| 147 | +### How can I apply patches to downloaded modules? |
| 148 | + |
| 149 | +If you need to apply patches (depending on the project being modified, a pull |
| 150 | +request is often a better solution), you can do so with the |
| 151 | +[composer-patches](https://github.com/cweagans/composer-patches) plugin. |
| 152 | + |
| 153 | +To add a patch to drupal module foobar insert the patches section in the extra |
| 154 | +section of composer.json: |
| 155 | +```json |
| 156 | +"extra": { |
| 157 | + "patches": { |
| 158 | + "drupal/foobar": { |
| 159 | + "Patch description": "URL or local path to patch" |
| 160 | + } |
| 161 | + } |
| 162 | +} |
| 163 | +``` |
| 164 | +### How do I switch from packagist.drupal-composer.org to packages.drupal.org? |
| 165 | + |
| 166 | +Follow the instructions in the [documentation on drupal.org](https://www.drupal.org/docs/develop/using-composer/using-packagesdrupalorg). |
| 167 | + |
| 168 | +### How do I specify a PHP version ? |
| 169 | + |
| 170 | +This project supports PHP 7.0 as minimum version (see [Drupal 8 PHP requirements](https://www.drupal.org/docs/8/system-requirements/drupal-8-php-requirements)), however it's possible that a `composer update` will upgrade some package that will then require PHP 7+. |
| 171 | + |
| 172 | +To prevent this you can add this code to specify the PHP version you want to use in the `config` section of `composer.json`: |
| 173 | +```json |
| 174 | +"config": { |
| 175 | + "sort-packages": true, |
| 176 | + "platform": { |
| 177 | + "php": "7.0.33" |
| 178 | + } |
| 179 | +}, |
| 180 | +``` |
0 commit comments