As any developer working with Drupal 8 knows, working with Composer has become an integral part of working with Drupal. This can be daunting for those without previous experience working with command line, and can still be a confusing experience for those who do.
This is the third post in an explorative series of blog posts on Drupal and Composer, hopefully clearing up some of the confusion. The four blog posts on this topic will be as follows:
- Part 1: Understanding Composer
- Part 2: Managing a Drupal 8 site with Composer
- Part 3: Converting Management of an Existing Drupal 8 Site to Composer
- Part 4: Composer for Drupal Developers
If you have not yet read part 1 and part 2, then before reading through this post, it is probably best to ensure you understand the concepts outlined in the summaries of those articles.
Switching Management of your Drupal site to Composer
So you’ve worked your way through parts one and two of this series, and you now understand what Composer is, how it can be used to work with Drupal 8, and how to start a new Drupal 8 project using Composer. But, you started your current project without using Composer, and want to switch to managing your project using Composer. Where do you start? This article will discusses a few strategies behind converting your existing system to Drupal. Fortunately some automated tools exist for converting existing sites to Composer, and in the situation that neither of these tools work, an overview is provided on how to manually convert an existing site
But, before moving on to any of these methods...
Take a backup! As this process will be destructive to your system, make sure you take a backup of your file system, and take a backup of your database. Then go and check to ensure that you have a full backup of the file system, and a full back up of the database.
If you skip this step, or do not do it properly, you may end up with an entirely broken system, so don’t skip this step.
Method 1: Composerize (Composer plugin)
Composerize Drupal is a Composer plugin that has been built to convert existing Drupal installations to use Composer. Instructions are on the download page. If this method doesn't work, you can try the Drupal Composerize module:
Method 2: Composerize (Drupal module)
The Composerize module is a Drupal module that is built to convert existing Drupal installations to use Composer. At the time of writing, this module has the following disclaimer on the page:
This module is still in development. It supports very basic Drupal 8 setups, but there are many necessary features it still lacks (e.g., support for patches, JavaScript libraries, distributions, etc). We're working on all that stuff, but this module is definitely not ready for prime time.
If this method doesn't work, you'll likely have to manually convert your site.
Method 3: Manual method
If the above steps fail, your last option is to convert your installation to using the Drupal Composer Template manually. Note that pretty much every system will be different, so these instructions are an overview of the end goal, rather than a complete set of steps that will convert your system. There is a good chance you’ll run into issues along the way that are not covered here, so make sure you took that backup!
Converting a system to the template requires achieving the following goals:
- Setting up the file structure of the system to match the Drupal Composer Template
- Delete old Composer files
- Add the Template file system to your Drupal system
- Set up the configuration directory and the private files directory
- Set up your profiles, modules and themes to be managed by Composer
Step 1: Convert your file structure to match the Drupal Composer Template file structure
The Drupal Composer Template is set up to manage the directory above the webroot, as well as the webroot. The webroot is located in the [PROJECT ROOT]/web folder. Therefore you will need this structure:
/- Project root. Contains various scaffolding files such as composer.json and composer.lock, as well as the configuration export folder, and the webroot folder/web- The webroot. Contains all Drupal core, profile, module and theme files.
You'll need to set up your Drupal installation to match this structure, and make sure that the server is set up so that the web root is at [PROJECT ROOT]/web.
Note: Some servers require the webroot to be in a directory with a specific name, such as public_html, or www. In this case, you can try setting up symlinks from the required directory name to the /web directory, so that, for example, [PROJECT ROOT]/public_html is a symlink pointing at [PROJECT ROOT]/web. Your Drupal files will then reside in the /web directory (satisfying the Drupal template), and also be accessible at /public_html (satisfying the server requirements). If this does not work, another option would be to edit the composer.json file (which is added in step 3) and change any paths that point at the /web directory, to point at the directory name you are actually using.
Step 2: Delete old Composer files
I'll say it again, because it needs to be said, make sure you took that backup in step 0!
If any of the following files or folders exist in your installation, delete them. Note however that you may want to save the composer.json file for reference if you've manually added any libraries into your existing installation using Composer.
[PROJECT ROOT]/vendordirectory[PROJECT ROOT]/composer.jsonfile[PROJECT ROOT]/composer.lockfile[PROJECT ROOT]/web/vendordirectory[PROJECT ROOT]/web/composer.jsonfile[PROJECT ROOT]/web/composer.lockfile.
Step 3: Add the Template file system to your Drupal system
Go here, click 'clone or download' and download the .zip file (note - or clone the Git repository if you prefer)
- Save/move the zip file into the project root folder (the directory above the 'web' folder you created above). You can then unpack it using the following command. Before this step, the file
/composer.jsonshould not exist. After this step, if you've done it correctly, this file will exist.
tar -zxvf [FILE] --strip-components=1 - Run the following command from the project root folder. This command will Install the Composer dependencies as well as create the
/vendordirectory.
composer install - Run the following to ensure your database is up to date, and caches are cleared.
drush updb; drush cr;
Step 4: Set up the configuration directory and the private files directory (Optional)
This next step is optional, however it will make for a more secure system. First, the following directories need to be created if they don't already exist:
[PROJECT ROOT]/config/sync[PROJECT_ROOT]/private
The first folder is where exports of the Drupal 8 configuration system will be exported to. The second folder is the private files folder. Creating both of these directories as siblings to the webroot adds security, as the files are not in a web-accessible location. The next thing to do is tell the system of the location of these files. This is done by declaring the folder paths in settings.php. You can do this by adding the following two lines to the bottom of settings.php:
$config_directories['sync'] = '../config/sync';
$settings['file_private_path'] = '../private';
After this, clear the registry (drush cr;). You can confirm that the configuration directory was properly set by running drush cex sync, and then checking that there are .yml files in the [PROJECT ROOT]/config/sync directory. You can confirm that the private files folder was properly set by going to Admin -> Configuration -> Media -> File System, and confirming that the private files directory is listed as ../private.
Step 5: Set up your profiles, modules and themes to be managed by Composer
The final step is to set up Composer to manage Drupal profiles, modules and themes to be managed by Composer. The Drupal Composer Template tracks Core by default, but needs to be informed of the rest of your code. Note that if you do not want to use the most recent version of these profiles/modules/themes, you will need to alter the commands below to set the version you want to install.
Drupal profiles, modules and themes can be installed with the following command:
composer require drupal/[PACKAGE NAME]
For example, if you were using the Administration Toolbar module (admin_toolbar), you would run:
composer require drupal/admin_toolbar
After you have done this, ensure you are up to date with a DB update and cache clear:
drush updb; drush cr;
At this point, your system should be converted to the Drupal Composer Template, with contributed code being managed by Composer.
Summary
This article looks at converting exiting Drupal 8 sites to being managed by the Drupal Composer Template. Doing this can potentially be automated using the Composerize Composer plugin or the Composerize Drupal module. In situations where this does not work, the manual directions in this article can be used as an alternative.
In the next and final part of this series, we'll look at how Drupal developers can integrate 3rd party libraries into their custom Drupal profiles, modules and themes.
