Using Composer on Pantheon

I worked through and chased a few rabbits, and ultimately landed on what I think a pretty simple workflow.
The main thing I was interested in was how to use composer to effectively manage a drupal project on pantheon.

Composer is practically required for building the codebase of Drupal 8 because there are so many external dependencies now. Composer handles downloading the right versions of all packages.

The main steps

  • Create a new site at pantheon, selecting "Drops 8 Composer"
  • Install site using the UI.
  • Switch to git mode.
  • Clone pantheon repo locally.
  • Use composer locally to add additional modules and packages.
  • Commit updates to composer.json, composer.lock, AND the build/downloaded packages.
    • Delete any .git directories that composer added because of checkouts, before committing downloaded packages. If you don't, git will see them as subprojects, which are unsupported on Pantheon.
  • Commit custom code in modules/custom and themes/custom.

This ignores pantheon "upstreams" of any sort.
When a new drupal core release comes out, running composer update drupal/core will get it.
Same type of thing with drupal modules.

More options

  • Use a separate repo for custom code and set up composer.json to use it.
  • Keep a separate, slim repo with only the composer files, not the installed codebase.
    • Cleaner separation of source files and built out codebase.
    • More complexity in code management, because an additional repo or branches would be needed for tracking the built out codebase.
  • Create a custom upstream to deploy updates.
    • Adds a step to deploys.
    • Does not change how you assemble the codebase.
    • Probably not worth the extra effort for a single site.

More notes

  • Running composer directly on a Pantheon site looks interesting.
    • The composer binary is available on pantheon; you just need a plugin of some sort to use it.
    • Can use terminus plugin rvtraveller/terminus-composer.
    • Another example that works: web/private/scripts/deploy_product/composer-install.php


Thanks for posting this

Thanks for posting this information. I have tried this out with my web site, hosted on Pantheon. Based on that experience, I have a question:

When you say "Delete any .git directories that composer added because of checkouts, before committing downloaded packages", can you give an example?

In my experience, composer generates a nearly unmanageable number of changes in tmy git repository (up to 7000), when I do a . I suspect most of these should not be tracked but I don't know how to systematically identify the extraneous ones. Can you provide more directions for that? (I have added /vendor to the .gitignore file.)

Also, based on my experience, you can not use composer using terminus. Pantheon member limits for composer are to low to allow any practical updates that way. Forget trying to do an update of core that way.

I am using Drupal 8 with Commerce2, so composer is absolutely required to manage the library dependencies.

Hi Basscleff. I like your

Hi Basscleff. I like your username!

An example of deleting .git directories is actually in the prepare-for-pantheon action in pantheon's composer.json. Here's a direct link:

That function is in scripts/composer/ScriptHandler.php: The first section of the function deletes all .git directories in directories one child deep or deeper, just skipping the top level .git directory.

The method I have been using is in fact the method that generates lots of file changes, as you have experienced. If possible, try to update only one thing at a time. This will help prevent massive changes that are very difficult fathom or revert. So if you want to update drupal commerce, run composer update drupal/commerce --with-dependencies. And if you want to update drupal core, run composer update drupal/core --with-dependencies.

After running one of those update commands, commit all of the changed code and push it to Pantheon. You should not have have the vendor directory in your .gitignore file. The changes that composer makes in the vendor directory are important, and are the main effect of using composer.

I agree this this method is a little bit messy, because you have the control files (composer.json, composer.lock) AND the resulting controlled files (/vender, /web/modules/contrib, etc.) all in the same repository. The cleanest setup would be one where the control files are tracked in one distinct repository; that is built into an artifact; that artifact is committed into a separate repository, and pushed to pantheon.

Some additional resources: