How to update an existing D8 site to use media in core

This page is out of date and needs reviewing.

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.

Preparation

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.

Steps

Edit web/modules/features/ac_image/ac_image.info.yml and remove the dependency on ac_media
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 cex before and after and check if any config has changed. You should only see core.extension changed (and ac_image.info.yml if 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_media which is part of video_embed_field module.

Note that you should not update entity browser module until after you have finished the upgrade to media in core.
Visit /update.php and 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.0 version before you can remove media_entity due 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

Run a lando drush updb to make sure everything is up to date.
Export all config with lando drush cex
Edit web/themes/custom/site_theme/site_theme.theme and change the use statement for media (at the top of the file) to:

use Drupal\media\Entity\Media;

Do the same for any other custom code where you've used the media class. You can search your codebase for Drupal\media_entity to 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.

Run drush updb
Checkout the tip of your branch.
Run drush cim
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.

Last updated: 3:09pm, 16th August 2023