Composerizing a non-composerized Drupal site to a Composerized Drupal site

Why do we need to use Composer?

1. “Composer is a dependency manager tool for PHP.”
    This means that we can easily manage php libraries and their dependencies using Composer.
2. In terms of Drupal, we can download and manage Drupal core, contributed profiles, modules, themes and libraries using Composer. In fact, the entire project can also be managed using Composer.
3. Using Composer is the modern way to work in PHP as modern frameworks utilize Composer to manage their dependencies, and it is nice that we can do the same in Drupal.
4. Composer also gives us the ability to autoload PHP classes thus making code easier to read and write.

How do we shift from Non-Composer managed website to Composer managed website?

1. Take a backup of the entire site

   1. It is very important to take a backup of entire Drupal site codebase.
   2. This is so that if any error occurs during site Composerization, we can easily recover stuff from the backup.
   3. Or better still, rename your project directory to something else.

2. Note down contributed modules and themes used in the project

   1. Make a list of contributed modules and themes being used in the project.
   2. Note down their names and version number. Noting version number is important as we would like to download the same version of the code that we are using in the non-Composerized site.
   3. For custom themes and modules, these will not be managed using Composer. So let these remain.

3. Download a new project using Composer template for Drupal

   1. First, make sure you have Composer installed in your machine!
      Run composer in your terminal/command prompt and you should see a screen like this:
      
       
      
      If you don’t and see some other message, that means you do not have Composer installed in your machine. You can do so by visiting Composer’s official website and following the steps there.
   2. Run the following command in your terminal:
      composer create-project drupal-composer/drupal-project:8.x-dev new-drupal-project --stability dev --no-interaction
   3. Replace 'new-drupal-project' in the above command with the name of your previous project directory.
   4. This will start downloading the entire Drupal project template.
   5. Have patience! It will take some time!!!
   6. If you face some error during the process, please check the error messages. Normally it would be related to PHP version. If so then update your PHP version to the one specified in the errors or higher.
   7. Now when the project template is downloaded, you have the core, vendor, sites directories, the main directories among others.
   8. You may have noticed a change in the directory structure. The sites, themes, core, modules etc. directories are missing and instead, you see some weird directories like ‘drush’, ‘scripts’, ‘vendor’ and ‘web’.
      Also you see some other files!
      But where did the modules, code, themes etc. modules, that resided in your old Drupal docroot go to?
   9. Do not worry! Navigate to the web directory and you shall find what you are looking for. There you’ll see all the old directories and files that you are used to seeing.
   10. IMP! As docroot is now inside ‘web’, you may need to change your ‘Virtual Host’ configuration in Apache/nginx to use ‘web’ as the new docroot. Then restart your server.

4. Download contributed profiles, modules and themes

   1. Now that you are done with getting the new Drupal Composer template, it's time to get the contributed profiles, modules and themes.
   2. Go back to the place where you had noted the names of the contributed profiles, modules and themes and their versions.
   3. Go to the Drupal.org page for the profile/module/theme.
   4. In the Downloads section of the page where the latest release of the profile/module/theme is mentioned, click on the version number.
   5. You’ll be taken to the release notes page with Download link button for the zip/tar version of the module.
   6. There you will find the Install with Composer section where the command is given which when run will download the profile/module/theme to your project.
   7. The command is of the format
      composer require drupal/abcd:^2.3
   8. You can use this command to download the latest version of the profile/module/theme.
   9. Else if you would like to restrict the version to the version you are currently using, use the following command:
      composer require drupal/abcd:2.3
      Here the ‘carat`(^) sign is not there, and so the version we specify is downloaded.
   10. To run the command, go to the terminal, to the root directory of your directory, before your ‘web’ directory and paste command then and press enter.
   11. If you do from some other directory, then Composer will itself ask you whether to use the composer.json file, the Composer configuration file in your root directory. Press ‘Y’ and hit ‘Enter’.
   12. Using this method, one by one, download the contributed profiles, modules and themes into your project.
   13. IMP! Note that in case you have specified a particular version of the profile/module/theme for Composer to download, then you shall need to edit your composer.json file if you want to update.
       Go through the Composer official documentation on how to update a composer library.

5. Custom profiles, modules and themes

   1. Now, for custom profile/module/theme, you should create the following directories:
      1. Custom module: web/modules/custom
      2. Custom theme: web/themes/custom
      3. Custom profile: web/profiles/custom
   2. Copy the custom profile, module, theme directories from the old project directory and place it in the respective directory in the new project directory.
   3. That is it!!!

6. The sites, patches, directory, .htaccess, robots.txt

   1. sites directory:
      1. Copy the sites directory from your old project and place it in the same path in the new project.
      2. You may delete the already created sites directory created in the new project and replace it with your own or you can merge them.
   2. .htaccess, robots.txt files:
      1. For the .htaccess and robots.txt file, compare the changes of your previous files with the current files provided by the templates and merge the differences.
   3. Patches directory: 
      1. Copy the patches directory from your old project to the ‘web’ directory of the new project.
      2. Make changes in the composer.json file following the explanation given here.
      3. Any pending patches will automatically be run when you run 'composer install'.
      4. Don’t forget to run `composer install` after shifting the patches folder to the new project directory as now all fresh copies of contrib directories have been downloaded using composer and do not have the patches applied unless it is the latest version which might contain the patch already.

7. Maintain the changes in version control

   1. If you use git or other version control system, commit your changes.
   2. Before committing, please note that the .gitignore file provided in this project template is different from the usual one provided with Drupal.
   3. If something was there in your old .gitignore file but not there in the new .gitignore file, add them here. But do not remove anything from the new .gitignore file.
   4. In .gitignore we now have:
      /vendor/
      /web/core/
      /web/modules/contrib/
      /web/themes/contrib/
      /web/profiles/contrib/
   5. composer.json and composer.lock files in the project root contain all the required information for the contributed modules, themes, profiles, core and vendor folder.
   6. So we do not commit these directories to git any more.
   7. Instead, whoever pulls the git branch containing this project structure change, has to run ‘composer install’ in the project root.
   8. Automatically all the required core, profiles, themes, modules and vendor folder will be downloaded in their instance.
   9. If previously, you used to commit these directories to git, now you can remove them from git version control using the command:
      git rm -r --cached folder_name
   10. This will show the directory as being deleted from version control but will be there in your local.
   11. One by one, run the above command for all contributed directories, core and vendor directory.
   12. So now the repository becomes cleaner, lighter as it is free of the above directories.
   13. To mention once again, once these changes are pulled to another machine, a person has to run ‘composer install’ to download the directories.
   14. In future, any contrib profile/theme/module that is to be downloaded/updated has to be downloaded/updated using Composer.
   15. Only the changes in composer.json and composer.lock files will now show as the contrib directories have now been ignored in git.
   16. Once the changes have been committed and someone else pulls it in their machine, they have to run ‘composer install’ command so that they get the changes in their machine.

Conclusion

        Follow the above steps to migrate your site from a non-Composer based installation to Composer based installation. After doing everything, make sure your site is running properly. If any error occurs, you need to check if you have missed any step. Also, check if you have by chance updated any of the contrib projects that is causing the error. Check the issue queue. You can always remove the project and reinstall the specific version using the method mentioned above. To remove a project, say ‘abcd’, type: composer remove drupal/abcd.

Do full testing of the site before doing so to ensure that everything is working as expected.

If still errors creep up, you can always restore your old project from the backup of the codebase that you had taken initially!