Upgrading Drupal Media module to 7.x-2.x

I recently spent some time fighting against the Drupal Media and File Entity modules in order to upgrade them from version 7.x-1.x to 7.x-2.x. (To be specific, Media was upgraded from 7.x-1.4 to 7.x-2.0-beta1, and File Entity to 7.x-2.0-beta2). Through this post, I will share with you my trials and tribulations, with the hope that one day no one else will endure the pain and suffering that I have endured. This is one of those situations where ultimately there was not that much that needed to be done, but a lot of time was spent on trial and error.

Incompatibility with Media Crop module

Based on all the comments/documentation I've seen around this upgrade, it seems like everyone's experience differs slightly. I assume that is because everyone is updating from and to slightly different versions of the Media module. Complications can also arise from modules that are dependent on the Media module. The site I was working on uses the Media Crop module which, as it turns out, is not yet compatible with Media 2.x (at least at the time of writing this). Luckily our client was not actually using the functionality of Media Crop and didn't mind losing it. Unfortunately though, simply uninstalling Media Crop seemed to leave some traces of the module on any images that were added via a WYSIWYG editor (Image styles referencing Media Crop, CSS classes and strange markup). This seemed like a rabbit hole I did not want to go down so I was happy to find that applying this patch resolved the rendering issues I was having. For whatever reason, the actual crop functionality is no longer accessible from the WYSIWYG but at least the upgrade does not destroy the rendering of current images. If you're using the Media Crop module I would recommend applying the patch before updating Media.

To Media Colorbox or not to Media Colorbox?

This site was also using the Media Colorbox module. I heard rumors that the functionality provided by Media Colorbox comes with Media 2.x, making the Media Colorbox module obsolete. Personally I couldn't find a way to keep that functionality without using Media Colorbox so this is still a mystery to me. I kept Media Colorbox installed.

Bash script to update Media and File Entity modules

So, with encouragement/prodding from Keith Dechant, I decided to write a Bash script to carry out the tasks of the actual upgrade:

echo "------ Disabling Media sub modules and Features that depend on Media"
drush dis media_crop, media_internet, media_youtube, media_colorbox, media_wysiwyg -y
drush dis custom_feature, another_custom_feature -y
 
echo "------ Disabling Media and File Entity"
drush dis media -y
drush dis file_entity -y
 
echo "------ Downloading latest versions of Media and File Entity modules"
drush dl file_entity, media -y
 
echo "------ Enabling File Entity and running cron"
drush en file_entity -y
drush cron
 
echo "------ Enabling Media"
drush en media -y
 
echo "------ Running DB updates"
drush updb -y
 
echo "------ Re-enabling Media sub modules and Features that depend on Media"
drush en media_crop, media_internet, media_youtube, media_colorbox, media_wysiwyg -y
drush en custom_feature, another_custom_feature -y
 
echo "------ Setting new permissions added by latest version of Media and File Entity modules"
# Media permissions
drush role-add-perm Programmer 'administer media browser'
drush role-add-perm Administrator 'administer media browser'
 
drush role-add-perm Programmer 'access media browser'
drush role-add-perm 'Content Editor' 'access media browser'
drush role-add-perm Administrator 'access media browser'
 
drush role-add-perm Programmer 'use media wysiwyg'
drush role-add-perm 'Content Editor' 'use media wysiwyg'
drush role-add-perm Administrator 'use media wysiwyg'
 
drush role-add-perm Programmer 'administer media wysiwyg view mode'
drush role-add-perm Administrator 'administer media wysiwyg view mode'
 
# File Entity permissions
drush role-add-perm Programmer 'administer file types'
drush role-add-perm Administrator 'administer file types'
 
drush role-add-perm Programmer 'create files'
drush role-add-perm 'Content Editor' 'create files'
drush role-add-perm Administrator 'create files'
 
drush role-add-perm Programmer 'view own files'
drush role-add-perm 'Content Editor' 'view own files'
drush role-add-perm Administrator 'view own files'
 
drush role-add-perm Programmer 'view own private files'
drush role-add-perm 'Content Editor' 'view own private files'
drush role-add-perm Administrator 'view own private files'
 
drush role-add-perm Programmer 'view private files'
drush role-add-perm 'Content Editor' 'view private files'
drush role-add-perm Administrator 'view private files'

The script is probably mostly self explanatory, but I went a little comment happy anyways. I ran this script on my local environment (many many many many times). You do not want to run it on a Production site because you will probably need to do some modifications to get it working for your situation. Once it is ready, you should export the Production database down to your local environment, get the site up and running, and then run the script. Next, export your local database and import it to Production. The first thing that the script does is disable modules that are dependent upon Media or File Entity. You might need to do a test disabling of Media and File Entity to note which other modules get disabled. Make sure that you add these modules to the reenable part of the script. Since we use Features, there were also some Features that listed Media or File Entity as a dependency and so I disabled them as well.

Media 2.x and File Entity 2.x also create a few new permissions that need to be set. If you use this script, be sure to replace our roles with roles that are relevant to your site. Also, some permissions provided by previous versions of the modules have been removed. If you save permission configuration in Features you might need to update your Features after upgrading.

WYSIWYG Woes

After running the script I still found that images added via WYSIWYG were not rendering correctly. There was now extra markup around images that was causing styling issues, and links were being removed from around images. I struggled with this for a while until I happened upon an obscure comment somewhere deep within the bowels of Drupal bug tickets. For reasons unknown to me, Media 2.x has changed the markup around images. However, there is a simple resolution to this in the Media module config: Go to /admin/config/media/browser and check the box "Legacy rendering (using field attach)" and your markup will be as it was before upgrading.

While we're talking about obscure configuration, make sure that your text formats have the "Convert Media tags to markup" filter enabled.

Conclusion

Hopefully I didn’t forget to mention anything major and I hope that this is useful to someone out there. If you find yourself here because you are trying to perform this upgrade: good luck you brave poor soul.

References

I found comments 9, 10 and 11 very helpful here:
https://www.drupal.org/node/2082037#comment-9489011

This was also a useful reference:
http://justmagicdesign.com/blog/201507/updating-drupal-7x-websites-media-1x-media-2x