Do you have a Drupal 8 website that you have migrated from Drupal 4 to 5 to 6 to 7 and then to 8 (or anywhere along this timeline)?
Do you have a Drupal 8 website that is not managed with Composer? (Maybe you installed the site manually?)
If your answer is Yes to any of the above, then this quick guide tutorial is for you. This tutorial will explain in 10 easy and proven steps how to take a Drupal 8 website and get it to be managed under Composer.
Read how Drupal 8 uses Composer.
For this tutorial to be effective for you, you must take care of all the Assumptions I mentioned below BEFORE you start.
Assumptions
- You have a Drupal 8 website and it is under GIT version control (using master branch).
- You have not hacked core (but if you did note where you did it).
- You have contrib modules and/or themes in your code base.
- Any custom module or custom theme is in their usual Drupal folder (for e.g. drupal_root/modules/custom_module OR drupal_root/themes/custom_theme)
- You have updated all Drupal core, contributed modules and themes to their latest stable version. (This is important for Step 6 to go smoothly)
- For this tutorial code base means your Drupal root directory
Step 1
Backup the following folders:
-
your public files folder
-
database
Do not worry about the rest of your code base because it is under version control.
Step 2
Git clone your code base locally and create a new branch off your master branch (or whatever branch your live repos sits on).
Commands
git clone <your git repo >
Now change directory into your newly cloned git repos.
git checkout -b composerize-drupal master
composerize-drupal is just the name of the branch we will be working in for this tutorial so we don't mess with our master branch. Once we are successful, we will merge this branch back into master.
Step 3
Note down the names of the contributed modules/themes that you currently use. It is ok to skip this step because your git version control (master branch) will have these folders still so you can refer to it from there through the git web interface.
But here are the Drush commands if you wish to do it this way:
To list all the contributed module: drush pm-list --type=Module --no-core --status=enabled
To list all the contributed themes: drush pm-list --type=Theme --no-core --status=enabled
If you hacked core or made custom patches, note down where these hacks/patches are in your codebase (again it should be viewable in your git interface in the master branch so you do not need to actually write this down)
Step 4
In your local branch , delete everything including all the files that begin with “.” (dot) from your Drupal root EXCEPT the .git folder. So now your code base should only have the .git folder.
Now you can stage and commit this change to the current branch composer-drupal:
git add -A
git commit -m "Remove all files and folders except .git"
Step 5
Install a new version of Drupal using Composer:
composer create-project drupal-composer/drupal-project:8.x-dev composerized-drupal --no-interaction
The name of the folder that composer will install Drupal too is composerized-drupal.
Now you need to move ALL of the files and folders from the folder composerized-drupal into the root of your original code base hence consequently leaving the composerized-drupal folder empty. Don't forget to move all the files that begin with a dot.
So from your code base root:
mv composerized-drupal/* ./
mv composerized-drupal/.* ./
rm -rf composerized-drupal
Now your code base should have the default Drupal composer files like Figure 2.
Now it’s a good time to commit these changes.
git add -A
git commit -m "Added default Drupal composer files"
Step 6
For each contributed module, theme or profile from your old site you need to add it to the current code base by using composer such as:
composer require drupal/adsense drupal/backup_migrate drupal/codefilter drupal/ctools drupal/insert drupal/pathauto drupal/rules drupal/sharethis drupal/tagadelic drupal/token drupal/typed_data
Composer will then fetch the latest stable release and put it in the correct directory automatically.
Now it’s a good time to stage and commit your changes.
git add -A
git commit -m "Add contrib projects to the codebase."
Step 7
For any of your custom code:
-
Place modules in drupal_root/web/modules/custom/
-
Place themes in drupal_root/web/themes/custom/
-
Place profiles in drupal_root/web/profiles/custom/
Visit this link if you use 3rd party libraries.
If you made customizations to .htaccess or robots.txt, here is how to apply those changes in a composer managed Drupal site. (Don't forget to commit your changes to composer.json)
If you patched core, contributed modules or themes see this link to patch with composer.
NB - Do not just randomly add your customizations in without letting composer know about it. If you do this, your changes will be lost next time you run composer install or composer update.
Step 8
TEST, TEST, TEST!
Restore a copy of the LIVE database to your local machine and visit the URL of the local site in your browser.
Drupal will automatically go to the install step. Follow through with the process and fix any errors along the way.
Clear the cache: drush cr
You may have to find other ways to clear Drupal cache if Drush does not work at this point.
Check the status reports and click around the site. Any errors you find, fix it and commit it.
The status page may have Drupal updates to the database available. Update the Drupal database if you need too.
Usually I visit admin/config/media/file-system to double check the public and private folder paths are set correctly.
NB - your custom files folder will be missing from your code base at this point. You can copy the files folder locally to drupal_root/web/sites/default/files if you need it for testing purposes but this will be taken care of in Step 10 on the LIVE site.
At the end of this step, drush status and drush cr should return clean results with no errors.
Step 9
This is the big step where you push the changes up to the master branch.
So push your changes up: git push -u origin composerize-drupal
Now we want to merge our composer branch into master:
git checkout master
git merge --no-ff composerize-drupal
Delete the composer branch as we no longer need it:
git branch -d composerize-drupal
Push the changes up:
git push -u origin master
Step 10
Now we need to pull in the changes on your LIVE server. Your LIVE site will be down for a few minutes in this step so you should do this at an off-peak time. In the event that something drastically goes wrong, you would need to revert the commit with the merge and restore your database and files folder.
On LIVE:
Change your Webserver document root to point to code_base/web since composer would have placed all the Drupal files into a sub directory named “web.” This is a very important step.
Then
git pull
composer install --no-dev
After running the above command, if you had previously made customizations to core, contrib modules or contrib themes, and you didn't tell composer about it, they will be lost like I said in Step 7.
At this point you may notice your original sites folder is still at code_base/sites. You can delete the folder completely because the web/sites folder will be in use now.
Copy your custom files folder to code_base/web/sites/default/files
Now visit your site and repeat Step 8 (except restoring a copy of the LIVE database to your local as you would be on LIVE now).
I hope this tutorial is helpful to you. You can leave a comment if you had any edge cases and the solutions that you found.