|
1 | | -# Composer template for Drupal projects |
| 1 | +# Disclaimer |
2 | 2 |
|
3 | | -[](https://travis-ci.org/drupal-composer/drupal-project) |
| 3 | +First off I'd like to say this not an ideal solution and should never be considered as an alternative to using composer via CLI. |
4 | 4 |
|
5 | | -This project template should provide a kickstart for managing your site |
6 | | -dependencies with [Composer](https://getcomposer.org/). |
| 5 | +We're in an awkward situtation where composer is becoming a hard requirement for Drupal. If all this project achieves is more awareness of the proplem and convinces composer naysayers that it's actually better to use composer CLI, I'd be happy. |
7 | 6 |
|
8 | | -If you want to know how to use it as replacement for |
9 | | -[Drush Make](https://github.com/drush-ops/drush/blob/8.x/docs/make.md) visit |
10 | | -the [Documentation on drupal.org](https://www.drupal.org/node/2471553). |
| 7 | +However, I understand that there are some cases where composer via CLI might be technically impossible leaving some users behind and the only option would be to use another CMS. |
11 | 8 |
|
12 | | -## Usage |
| 9 | +To be clear, it would still be better to address the educational / technical limitations. |
13 | 10 |
|
14 | | -First you need to [install composer](https://getcomposer.org/doc/00-intro.md#installation-linux-unix-osx). |
| 11 | +Currently, this is just a proof of concept and is very insecure and should not be used on any externally accessible webserver. |
15 | 12 |
|
16 | | -> Note: The instructions below refer to the [global composer installation](https://getcomposer.org/doc/00-intro.md#globally). |
17 | | -You might need to replace `composer` with `php composer.phar` (or similar) |
18 | | -for your setup. |
| 13 | +It would be nice if this could be integrated into Drupal's existing authentication and only allow access to user 1 similar to `update.php`. |
19 | 14 |
|
20 | | -After that you can create the project: |
21 | | - |
22 | | -``` |
23 | | -composer create-project drupal-composer/drupal-project:8.x-dev some-dir --stability dev --no-interaction |
24 | | -``` |
25 | | - |
26 | | -With `composer require ...` you can download new dependencies to your |
27 | | -installation. |
28 | | - |
29 | | -``` |
30 | | -cd some-dir |
31 | | -composer require drupal/devel:~1.0 |
32 | | -``` |
33 | | - |
34 | | -The `composer create-project` command passes ownership of all files to the |
35 | | -project that is created. You should create a new git repository, and commit |
36 | | -all files not excluded by the .gitignore file. |
37 | | - |
38 | | -## What does the template do? |
39 | | - |
40 | | -When installing the given `composer.json` some tasks are taken care of: |
41 | | - |
42 | | -* Drupal will be installed in the `web`-directory. |
43 | | -* Autoloader is implemented to use the generated composer autoloader in `vendor/autoload.php`, |
44 | | - instead of the one provided by Drupal (`web/vendor/autoload.php`). |
45 | | -* Modules (packages of type `drupal-module`) will be placed in `web/modules/contrib/` |
46 | | -* Theme (packages of type `drupal-theme`) will be placed in `web/themes/contrib/` |
47 | | -* Profiles (packages of type `drupal-profile`) will be placed in `web/profiles/contrib/` |
48 | | -* Creates default writable versions of `settings.php` and `services.yml`. |
49 | | -* Creates `web/sites/default/files`-directory. |
50 | | -* Latest version of drush is installed locally for use at `vendor/bin/drush`. |
51 | | -* Latest version of DrupalConsole is installed locally for use at `vendor/bin/drupal`. |
52 | | - |
53 | | -## Updating Drupal Core |
54 | | - |
55 | | -This project will attempt to keep all of your Drupal Core files up-to-date; the |
56 | | -project [drupal-composer/drupal-scaffold](https://github.com/drupal-composer/drupal-scaffold) |
57 | | -is used to ensure that your scaffold files are updated every time drupal/core is |
58 | | -updated. If you customize any of the "scaffolding" files (commonly .htaccess), |
59 | | -you may need to merge conflicts if any of your modified files are updated in a |
60 | | -new release of Drupal core. |
61 | | - |
62 | | -Follow the steps below to update your core files. |
63 | | - |
64 | | -1. Run `composer update drupal/core --with-dependencies` to update Drupal Core and its dependencies. |
65 | | -1. Run `git diff` to determine if any of the scaffolding files have changed. |
66 | | - Review the files for any changes and restore any customizations to |
67 | | - `.htaccess` or `robots.txt`. |
68 | | -1. Commit everything all together in a single commit, so `web` will remain in |
69 | | - sync with the `core` when checking out branches or running `git bisect`. |
70 | | -1. In the event that there are non-trivial conflicts in step 2, you may wish |
71 | | - to perform these steps on a branch, and use `git merge` to combine the |
72 | | - updated core files with your customized files. This facilitates the use |
73 | | - 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; |
74 | | - keeping all of your modifications at the beginning or end of the file is a |
75 | | - good strategy to keep merges easy. |
76 | | - |
77 | | -## Generate composer.json from existing project |
78 | | - |
79 | | -With using [the "Composer Generate" drush extension](https://www.drupal.org/project/composer_generate) |
80 | | -you can now generate a basic `composer.json` file from an existing project. Note |
81 | | -that the generated `composer.json` might differ from this project's file. |
82 | | - |
83 | | - |
84 | | -## FAQ |
85 | | - |
86 | | -### Should I commit the contrib modules I download? |
87 | | - |
88 | | -Composer recommends **no**. They provide [argumentation against but also |
89 | | -workrounds if a project decides to do it anyway](https://getcomposer.org/doc/faqs/should-i-commit-the-dependencies-in-my-vendor-directory.md). |
90 | | - |
91 | | -### Should I commit the scaffolding files? |
92 | | - |
93 | | -The [drupal-scaffold](https://github.com/drupal-composer/drupal-scaffold) plugin can download the scaffold files (like |
94 | | -index.php, update.php, …) to the web/ directory of your project. If you have not customized those files you could choose |
95 | | -to not check them into your version control system (e.g. git). If that is the case for your project it might be |
96 | | -convenient to automatically run the drupal-scaffold plugin after every install or update of your project. You can |
97 | | -achieve that by registering `@drupal-scaffold` as post-install and post-update command in your composer.json: |
98 | | - |
99 | | -```json |
100 | | -"scripts": { |
101 | | - "drupal-scaffold": "DrupalComposer\\DrupalScaffold\\Plugin::scaffold", |
102 | | - "post-install-cmd": [ |
103 | | - "@drupal-scaffold", |
104 | | - "..." |
105 | | - ], |
106 | | - "post-update-cmd": [ |
107 | | - "@drupal-scaffold", |
108 | | - "..." |
109 | | - ] |
110 | | -}, |
111 | | -``` |
112 | | -### How can I apply patches to downloaded modules? |
113 | | - |
114 | | -If you need to apply patches (depending on the project being modified, a pull |
115 | | -request is often a better solution), you can do so with the |
116 | | -[composer-patches](https://github.com/cweagans/composer-patches) plugin. |
117 | | - |
118 | | -To add a patch to drupal module foobar insert the patches section in the extra |
119 | | -section of composer.json: |
120 | | -```json |
121 | | -"extra": { |
122 | | - "patches": { |
123 | | - "drupal/foobar": { |
124 | | - "Patch description": "URL to patch" |
125 | | - } |
126 | | - } |
127 | | -} |
128 | | -``` |
129 | | -### How do I switch from packagist.drupal-composer.org to packages.drupal.org? |
130 | | - |
131 | | -Follow the instructions in the [documentation on drupal.org](https://www.drupal.org/docs/develop/using-composer/using-packagesdrupalorg). |
| 15 | +# What? |
| 16 | + |
| 17 | +This project provides a way to run common composer commands via a browser. |
| 18 | + |
| 19 | +# How? |
| 20 | + |
| 21 | +It creates a simple endpoint that will run a command on the project codebase. |
| 22 | + |
| 23 | +eg. `/composer/update/drupal/core/--/with-dependencies` would run `composer update drupal/core --with-dependencies`. |
| 24 | + |
| 25 | +# limitations. |
| 26 | + |
| 27 | +Due to memory limitations it is unlikely you'd be able to run `install` to install all dependencies, also an unfiltered `update` would be impossible. |
| 28 | +However, if you include most packages in the tarball you don't have to install all packages and `require` or `update` on single packages are possible. |
| 29 | + |
| 30 | +# Request structure. |
| 31 | + |
| 32 | +/composer/[command]/[argument]/--/[options] |
| 33 | + |
| 34 | +# Examples. |
| 35 | + |
| 36 | +`/composer/validate` (default) |
| 37 | + |
| 38 | +`/composer/show` |
| 39 | + |
| 40 | +`/composer/require/drupal/devel/--/prefer-dist` |
| 41 | + |
| 42 | +`/composer/install` |
| 43 | + |
| 44 | +`/composer/install/--/no-dev` |
| 45 | + |
| 46 | +`/composer/update/drupal/core/--/with-dependencies` |
| 47 | + |
0 commit comments