Preparing your Drupal 8.3 site with Media for Drupal 8.4

If you have the Media module for Drupal 8 installed (not a requirement to use media with Drupal 8, so this post may not apply to you), you need to remove it before you can upgrade to the latest core version (8.4). Unfortunately, there are a few gotchas involved with the process. This blog post is about getting rid of the old contrib Media module, so the site can be updated to Drupal 8.4 in a subsequent step. This is based on my personal experience. YMMV, as they say.

Originally I published this post on december 25th of 2017. Merry Christmas! Since this blog was added to Planet Drupal yesterday, I thought it would benefit others to re-date this to today, so it would appear in the Planet feed.

Having to maintain this site in my spare time, it has been far too long for me to upgrade it to Drupal 8.4 (it actually went live on Drupal 8.3 when 8.4 was already final, because the platform had been running for a while for another site and frankly, I just wanted it live—something about a plumber and leaky pipes). The site had been built with the contrib Media module, which turns out to be a bit of a mistake (just because of the problems I outline below, not because there was anything wrong with the module), but that's water under the bridge.

Where the Media module for Drupal 7 is the core for a (the?) leading Media solution, for Drupal 8 that responsibility moved to the new media_entity module, as well as a bunch of extension modules that add specific media types. In short, Media in Drupal 8 is much more modular. The Media module itself still existed, but it was basically a quick start suite of configuration and a few tweaks to how things worked out of the box.

The reason removing the contrib Media module is needed is that from 8.4 on, media_entity was integrated into core, except that is is now called... Media module. This means the contrib Media module would have a name collision with the new Media module in core. So, it needs to be disabled. Which is mostly OK (you can retain most of the configuration it adds), except for a new nasty gotchas.

Note that this is not about moving your site to the core media entity type. That is something that will have to happen eventually. You will have to wait for all extension modules (image, video, maybe gallery, Twitter or Instagram, etc.) to have versions that work with the core entity type, as well as for the upgrade path to be complete. This needs to happen, though, if you currently have Media module and you need to move to Drupal 8.4 (and you do need to; 8.3 stopped being supported when 8.4 came out).

Gotcha #1: Route "view.media.media_page_list" does not exist

When I first tried disabling the contrib Media module (which I will simply call Media module for the remainder of this blog post), I was greeted by this lovely error message. In full, it read:

Symfony\Component\Routing\Exception\RouteNotFoundException: Route "view.media.media_page_list" does not exist. in Drupal\Core\Routing\RouteProvider->getRouteByName() (line 190 of core/lib/Drupal/Core/Routing/RouteProvider.php).

It went along with the dreaded "An unexpected error occurred" as well as a giant stack trace, but that's just due to my development environment settings.

The View is what the Media module added in place of the View that's also added by media_entity module. I haven't quite figured out how this situation came to be, but there is still a View in the exported configuration, presumably the one added by media_entity. However, as far as I can tell, there were no actual changes to the exported configuration, so it is still a bit puzzling. Luckily, the solution turned out to be fairly straightforward; the View had its status key set to false in the exported configuration yml-file (views.view.media.yml):

langcode: nl
status: false
dependencies:
  config:
    - core.entity_view_mode.media.media_library
    - media_entity.bundle.gallery
  module:
    - entity_browser
    - media_entity
    - user

Changing it to true and re-importing configuration got rid of this problem (don't forget to remove media in core.extension.yml if you do this; chances are you didn't get a chance to actually export the configuration after disabling the Media module, so re-importing your exported configuration would happily re-enable it again—in fact, you could skip the step of disabling the module through the interface and simply remove its line from core.extension.yml).

Gotcha #2: Media module contains some tweaks

The Media module contains some useful tidbits (mostly tweaks to standard core or contrib functionality). If you are getting ready to update a site to the next minor core version, you are not in the state of mind to deal with functional regressions and/or changes (especially to find out how to turn regressions into changes). At least, I wasn't. That's why I created the Media Glue sandbox module, that basically just contains the css, javascript and hook implementations that Media did, except under a different name space so it does not collide with the new core Media module. It does contain one little change, which involves the styling for the entity browser. The Media module contained a small bug that caused the items to jump around in the browser when hovering over them (at least in my browser of choice, Safari). The css for the new module has been tweaked so the elements are the same size for both regular and hover states.

I will probably want to figure out how I want to get rid of this module at some point, as I usually prefer to stay closer to base functionality as opposed to install all sorts of little modules that may add small niceties; extra modules can break and also add a slight performance penalty. There also apparently are various modules that do something similar, which would appear to be better starting points. But that's stuff for another blog post.

Gotcha #3: When you decide you don't need Media entity slideshow

As said, Media module came with a bunch of configuration. It added all that configuration as install configuration (not optional), so it had dependencies on extension modules that were required for all that configuration. As I previously mentioned, I'm no great fan of stuff I don't really need; all it can do is break. So I figured I could remove some of the extras that came with Media. Mostly, this is no problem. You can disable the Document, Instagram and Twitter modules if you don't need them. Any configuration dependent on them, like media entity bundles and display settings, will be removed. (The same likely goes for the video embed module, but I haven't tried).

However, when you elect to remove the Media Entity Slideshow module, Drupal will make an odd report about configuration that will be removed; in addition to the usual suspects (the media bundle and all its derived configuration like fields and displays) it will want to remove the Media Embed and Media Library entity browsers as well as the Media library View. The last one is the key here. The other two depend on it, because they use it as their browser view. The View itself contains two displays that are used for the Entity Browser that is meant for creating galleries (which, oddly, does not get removed, in my experience). These displays contain a filter option to exclude galleries (in order to avoid gallery inception). Thus, the View depends on its existence and if we wish to remove the bundle, we need to remove the View. 

At this point, the safest option is to abort the uninstalling of the module and go and edit the troublesome View. You need to remove the two displays:

1. Gallery media select modal
2. Gallery User Media select modal

Save the View and export the configuration.

Unfortunately, this did not remove the actual dependency from the View, only the displays that are the reason for having the dependency. Open the views.view.media_libary.yml file in your editor and look for all values containing gallery. This will turn up everything that had to do with the media bundle. Remove the lines you find. Save the file and re-import configuration. 

Go and uninstall the module again. If the View and entity browsers are still being listed, try and clear the cache. Finally, remove the gallery_media_library entity browser (admin/config/content/entity_browser).

After the module is uninstalled, do another config export.

Next steps

That's basically it. At this point, you will have to release your changes through your DTAP street (if that doesn't mean anything to you, don't worry; it simply means you have to get these changes into production) to prepare your site for the actual move to Drupal 8.4. You can not remove the Media module before getting it disabled (if you have a clever release process, you might be able to do removals at the very end, which would allow you to do things in one go).

If you use a composer-based build process, you will need to remove drupal/media from your composer.json. At the same time, you will need to add back any modules that were previously dependencies of Media that you wish to keep. The full list of dependencies for (from its .info.yml file) Media looks like this:

dependencies:
  - media_entity:media_entity
  - media_entity_image:media_entity_image
  - video_embed_field:video_embed_field
  - video_embed_field:video_embed_media
  - media_entity_slideshow:media_entity_slideshow
  - media_entity_instagram:media_entity_instagram
  - media_entity_twitter:media_entity_twitter
  - media_entity_document:media_entity_document
  - slick_media:slick_media
  - entity_browser:entity_browser
  - entity_browser:entity_browser_entity_form
  - entity_embed:entity_embed
  - dropzonejs:dropzonejs_eb_widget
  - image_widget_crop:image_widget_crop
  - drupal:link
  - drupal:editor
  - inline_entity_form:inline_entity_form
test_dependencies:
  - media_entity:media_entity
  - media_entity_image:media_entity_image
  - video_embed_field:video_embed_field
  - video_embed_field:video_embed_media
  - media_entity_slideshow:media_entity_slideshow
  - media_entity_instagram:media_entity_instagram
  - media_entity_twitter:media_entity_twitter
  - media_entity_document:media_entity_document
  - slick_media:slick_media
  - entity_browser:entity_browser
  - entity_browser:entity_browser_entity_form
  - entity_embed:entity_embed
  - dropzonejs:dropzonejs_eb_widget
  - image_widget_crop:image_widget_crop
  - drupal:link
  - drupal:editor
  - inline_entity_form:inline_entity_form

Find out the versions you have installed currently and require them explicitly in your composer.json. If you added everything you need to keep, you can go ahead and remove media itself. Rebuild the site and make sure everything still works. You are now ready to actually take the step and update to Drupal 8.4.