How to update an existing D8 site to use media in core
Who is this guide for?
This guide is for developers wanting to convert media entity based sites to media in core.
Media in core
The media_entity module is now in core and there is an upgrade path. Of course, this is easier said than done. The following instructions will guide you through the process.
Due to the steps needing to be run on the database you cannot run through them, export them as config and then push them to the server and import them. This will not work. Instead you have to do the updates directly on a production (or stage) database.
- Clone the production database to your local and make sure you are working off the latest master branch.
- Make a hotfix branch and change to it.
- Ensure you have already updated to Drupal core 8.6.x or higher.
- Log in to your local site as user 1 or a user with database update permissions.
- Also log in to the production and stage sites as user 1.
web/modules/features/ac_image/ac_image.info.ymland remove the dependency on
Uninstall most of the feature modules:
lando drush pm-uninstall ac_editorial ac_media ac_page ac_search ac_video content_section_image content_section_long_text content_section_text_image content_section_video
Uninstalling modules does not remove the default config they come with so your site should not be affected. You can do a
lando drush cexbefore and after and check if any config has changed. You should only see
ac_image.info.ymlif you haven't committed that).
Manually download version 2.x of the media entity module from the module page: https://www.drupal.org/project/media_entity
Replace the media entity module in
web/modules/contrib/with the downloaded media entity module.
Check which other media related modules you have installed and replace those using the same manual download method (you may need to check this on production if your local throws errors). Most likely you will need at least
video_embed_mediawhich is part of
Note that you should not update entity browser module until after you have finished the upgrade to media in core.
/update.phpand check the requirements.
Create a commit.
Create a tag so you can return to this commit later on the server
git tag media-update
Correct any errors and then run the update using drush:
lando drush updb
You should now update your composer files with at least the following:
lando composer require drupal/video_embed_field:~2.0 drupal/media_entity_browser:~2.0 drupal/crop:~2.0; lando composer remove drupal/ac_editorial drupal/ac_media drupal/ac_page drupal/ac_search drupal/ac_video drupal/content_section_image drupal/content_section_long_text drupal/content_section_text_image drupal/content_section_video drupal/media_entity_image drupal/media_entity_document
Depending on your installed media module you may need to update other modules to
~2.0version before you can remove
media_entitydue to dependencies. For example media_entity_browser needs updating.
- You can now uninstall media entity and remove it:
lando drush pm-uninstall media_entity; lando composer remove drupal/media_entity
lando drush updbto make sure everything is up to date.
Export all config with
lando drush cex
web/themes/custom/site_theme/site_theme.themeand change the use statement for media (at the top of the file) to:
Do the same for any other custom code where you've used the media class. You can search your codebase for
Drupal\media_entityto see if its used elsewhere.
Make another commit at this point and then test your local site thoroughly.
Now you will need to run through this process (albeit simplified) on the production site. See the following section for the steps.
More information and the original update instructions on Drupal.org: https://www.drupal.org/docs/8/core/modules/media/faq-transition-from-media-entity-to-media-in-core
On production or staging
Once you're sure that everything works as it should on your local you will want to do this on staging and ask the client to check. If you're feeling confident you can do this on production too, although issuing a short content freeze on production, running it on staging and then overwriting the production database might be the best approach.
Issue a content freeze on production.
Clone production to staging.
Pull your branch on staging and change to it.
Checkout your tag from step 8 in the previous set of instructions:
git checkout media-update
Uninstall the feature modules:
drush pm-uninstall ac_editorial ac_media ac_page ac_search ac_video content_section_image content_section_long_text content_section_text_image content_section_video
You will probably see an error like
[error] Class Drupal\media\MediaInterface does not exist. You can ignore that.
Checkout the tip of your branch.
Check everything is working.
On your local, merge your branch to develop and master and push it up. Pull it onto stage and production.
Clone staging database to production.
Notify client of success and lift the content freeze.