www.aleph1.co.uk Git - yaffs-website/blob - vendor/drupal-composer/drupal-scaffold/README.md

   1 # drupal-scaffold
   2
   3 [![Build Status](https://travis-ci.org/drupal-composer/drupal-scaffold.svg?branch=master)](https://travis-ci.org/drupal-composer/drupal-scaffold)
   4
   5 Composer plugin for automatically downloading Drupal scaffold files (like
   6 `index.php`, `update.php`, …) when using `drupal/core` via Composer.
   7
   8 It is recommended that the vendor directory be placed in its standard location
   9 at the project root, outside of the Drupal root; however, the location of the
  10 vendor directory and the name of the Drupal root may be placed in whatever
  11 location suits the project.  Drupal-scaffold will generate the autoload.php
  12 file at the Drupal root to require the Composer-generated autoload file in the
  13 vendor directory.
  14
  15 ## Usage
  16
  17 Run `composer require drupal-composer/drupal-scaffold:dev-master` in your composer
  18 project before installing or updating `drupal/core`.
  19
  20 Once drupal-scaffold is required by your project, it will automatically update
  21 your scaffold files whenever `composer update` changes the version of
  22 `drupal/core` installed.
  23
  24 ## Configuration
  25
  26 You can configure the plugin with providing some settings in the `extra` section
  27 of your root `composer.json`.
  28
  29 ```json
  30 {
  31   "extra": {
  32     "drupal-scaffold": {
  33       "source": "http://cgit.drupalcode.org/drupal/plain/{path}?h={version}",
  34       "excludes": [
  35         "google123.html",
  36         "robots.txt"
  37       ],
  38       "includes": [
  39         "sites/default/example.settings.my.php"
  40       ],
  41       "initial": {
  42         "sites/default/default.services.yml": "sites/default/services.yml",
  43         "sites/default/default.settings.php": "sites/default/settings.php"
  44       },
  45       "omit-defaults": false
  46     }
  47   }
  48 }
  49 ```
  50 The `source` option may be used to specify the URL to download the
  51 scaffold files from; the default source is drupal.org. The literal string
  52 `{version}` in the `source` option is replaced with the current version of
  53 Drupal core being updated prior to download.
  54
  55 With the `drupal-scaffold` option `excludes`, you can provide additional paths
  56 that should not be copied or overwritten. The plugin provides no excludes by
  57 default.
  58
  59 Default includes are provided by the plugin:
  60 ```
  61 .csslintrc
  62 .editorconfig
  63 .eslintignore
  64 .eslintrc (Drupal <= 8.2.x)
  65 .eslintrc.json (Drupal >= 8.3.x)
  66 .gitattributes
  67 .htaccess
  68 index.php
  69 robots.txt
  70 sites/default/default.settings.php
  71 sites/default/default.services.yml
  72 sites/development.services.yml
  73 sites/example.settings.local.php
  74 sites/example.sites.php
  75 update.php
  76 web.config
  77 ```
  78
  79 When setting `omit-defaults` to `true`, neither the default excludes nor the
  80 default includes will be provided; in this instance, only those files explicitly
  81 listed in the `excludes` and `includes` options will be considered. If
  82 `omit-defaults` is `false` (the default), then any items listed in `excludes`
  83 or `includes` will be in addition to the usual defaults.
  84
  85 The `initial` hash lists files that should be copied over only if they do not
  86 exist in the destination. The key specifies the path to the source file, and
  87 the value indicates the path to the destination file.
  88
  89 ## Limitation
  90
  91 When using Composer to install or update the Drupal development branch, the
  92 scaffold files are always taken from the HEAD of the branch (or, more
  93 specifically, from the most recent development .tar.gz archive). This might
  94 not be what you want when using an old development version (e.g. when the
  95 version is fixed via composer.lock). To avoid problems, always commit your
  96 scaffold files to the repository any time that composer.lock is committed.
  97 Note that the correct scaffold files are retrieved when using a tagged release
  98 of `drupal/core` (recommended).
  99
 100 ## Custom command
 101
 102 The plugin by default is only downloading the scaffold files when installing or
 103 updating `drupal/core`. If you want to call it manually, you have to add the
 104 command callback to the `scripts`-section of your root `composer.json`, like this:
 105
 106 ```json
 107 {
 108   "scripts": {
 109     "drupal-scaffold": "DrupalComposer\\DrupalScaffold\\Plugin::scaffold"
 110   }
 111 }
 112 ```
 113
 114 After that you can manually download the scaffold files according to your
 115 configuration by using `composer drupal-scaffold`.
 116
 117 It is assumed that the scaffold files will be committed to the repository, to
 118 ensure that the correct files are used on the CI server (see **Limitation**,
 119 above). After running `composer install` for the first time commit the scaffold
 120 files to your repository.