Converting from manual management of Drupal to Composer-based

As from version 8, Drupal recommends using Composer to manage dependencies. This has thrown off users who are not comfortable working in the command line. But using Composer to manage packages in Drupal is not explicitly required, it is only a recommendation. You can still manage Drupal version 8 and upwards just the way you managed version 7 being downloading and installing from tarball or installing with Softaculous - these methods are still valid with Drupal. So users who are not comfortable working in the command line should not feel left out, you can still manage your Drupal 8/9 website manually the way you did for Drupal 7.

But Composer is a very useful tool and managing your site with Composer is a superior workflow. Composer is a dependency manager for PHP.

Even though you can still manage your sites manually like Drupal 7, there are some modules that may force the use of Composer like Commerce 2, Geofield, the Social Initiative suite of modules and a few others which expressly demand being installed and managed with Composer. If you run into one of these, then you will need to use Composer and you will have to change the management of your site from manual to Composer-based.

Even at that if you insist you can use Ludwig module and still use Commerce 2 (and some others) and still continue to manage your site manually.  

If you decide to switch from manual to Composer-based, it is now easier since version 8.8.x because with ^8.8.0 a new Composer template drupal/recommended-project was introduced in Drupal core which has control of the site out of the box. This means you can easily switch from manual management to Composer-based management without 'Composerizing' like you needed to do prior to 8.8. Prior to 8.8, if you wanted to switch from manual to Composer-based you needed to use tools like the Composerize Drupal module, the Composerize Drupal plugin or the GoComposer plugin. My favorite back then was Composerize Drupal, it worked seamlessly. Now you do not need any of these anymore.

Here are the steps to make the switch:

There is documentation for this on Drupal.org but this is the way I do it.

1) Make a local copy of your site, do not do this on your live site.

2) Ensure you are using up to 8.8 version of Drupal, if not manually update your site to version, say, 8.8.6. If you updated from versions prior to 8.8.x you will have to update the sync directory in settings.php because 8.8.x changed the sync directory from being defined in $config_directories to now defined in $settings. Open settings.php file and locate the definition for sync directory, it would look something like this $config_directories['sync'] = 'sites/default/files/config_YLZJmmpOqc_KBWbMc2I58ky3-8c7qtg4G-OpSqFClHs5E0NL9YMFgyF4RRTv8IFdl_kAMs_Bdw/sync';, change $config_directories['sync'] to $settings['config_sync_directory'] so that in the end it now looks something like this $settings['config_sync_directory'] = 'sites/default/files/config_YLZJmmpOqc_KBWbMc2I58ky3-8c7qtg4G-OpSqFClHs5E0NL9YMFgyF4RRTv8IFdl_kAMs_Bdw/sync';

To switch to Composer-based management you will just use the Composer commands straightaway and they will work, but once you start managing the site with Composer you cannot go back to manual management else the site will break.

3) Check if the recommended Composer template is available, run composer show drupal/core-recommended. If this shows information about the package then you are good to go.

4) Update Drupal core by running the command composer update drupal/core "drupal/core-*" --with-all-dependencies.

Composer will update core straightaway. But for your modules and base themes you cannot start updating them yet because even though Drupal core is registered in your composer.json, your modules and base themes are not because you installed them manually.

5) For you to manage the modules and base themes likewise with Composer you will first have to 'composer require' them with command composer require drupal/module-name and composer require drupal/basetheme-name. Before you run this command be sure to check that your contrib modules and themes are packed in sub-folder 'contrib' inside modules and themes folders, such that your folder structure will be 'modules/contrib' for all contributed modules and 'themes/contrib' for the contributed/base themes. Also 'modules/custom' for custom modules and 'themes/custom' for custom themes. If you do not put them in these folders and you have your contributed modules in the root of modules folder like 'modules/', Composer will duplicate them because Composer will place all contributed projects inside sub-folder 'contrib'. Once you have done this you can then 'composer require' all your modules and base themes and straightaway Composer will download them afresh and then register them in it's configuration. E.g. for the Admin Toolbar module you will run composer require drupal/admin_toolbar. To be sure you do not get errors from module compatibility you may want to require exact versions of the modules like composer require 'drupal/admin_toolbar:^2.3'.

Tip: You can 'require' all the projects in one command, like composer require drupal/module1-name drupal/module2-name drupal/theme1-name drupal/theme2-name and Composer will require and download all of them at once.

Once you have 'composer required' all of them, your site is now fully Composerized.

6) If you want to keep to the recommended best practices you can then move the vendor folder, composer.json and composer.lock one folder up, away from your web-root (public_html in case of Cpanel). When you do this the site will stop loading because Drupal cannot find the vendor folder anymore. To tell Drupal the new location of vendor, edit autoload.php located in the Drupal root, change the line return require __DIR__ . '/vendor/autoload.php'; to return require __DIR__ . '/../vendor/autoload.php'; to tell Drupal vendor has been moved one folder up. Clear caches and site should be up again. Do not forget to update the installer paths in composer.json to reflect your docroot.

Another surefire way to do this is to move composer.json and composer.lock up one folder into the project-root, delete vendor folder and core folder, update the installer paths in composer.json and run composer install --no-dev. Composer will re-download vendor and core and update autoload.php by itself. This is a magic way to resolve knotty issues sometimes. For an illustration of how to update installer paths, see this cPanel example.

This is the folder structure you will get if you installed Drupal with Composer from beginning, vendor folder and the Composer files are placed, one folder up, away from web-root. This adds even extra security for the site by keeping the libraries inside vendor totally away from the web-root.

7) After this has worked successfully in local, you can move the settings to live.

In concluding:

This means you are free to manage your site manually and if at any time you are forced by a module or you feel comfortable working with Composer, you can easily switch over without much ado.

Meanwhile, if you own a Drupal 8/9 site that you started manually and you want to switch to Composer, you can let us know and we shall take care of it; we are top-notch web designers in Nigeria specializing in Drupal.

Last updated: March 04, 2022