Image styles broken after upgrade from Drupal 7

[jromine]

On this page https://docs.backdropcms.org/documentation/step-3-upgrade-the-drupal-site at step 5, it says

    Recommended: Move the files from where Drupal put them, to where you would prefer to have them
        Copy the files directory from Drupal 7 (usually drupal/sites/default/files) into the Backdrop site (usually backdrop/files)
        Create a default directory within backdrop/sites.
        [Create a symlink](https://stackoverflow.com/questions/1951742/how-to-symlink-a-file-in-linux) in your filesystem from sites/default/files to files .
        After the upgrade, update the "Public file system path setting at admin/config/media/file-system to files.

My experience is changing the Public file system path setting to "files" causes image style generation to break for existing images. For example, if you have a embedded image in the Body field such as \<img src="/sites/default/files/styles/large/public/image.jpg"> then the image will not be generated and you'll get a broken link (or page not found error if you try to load the image separately).

In image_menu() Backdrop requires the image style path to be under the Public file system path to generate the image style, so the img src path and configuration setting need to match.

I think the Drupal upgrade documentation should mention this concern, and/or not recommend changing the Public file system path setting.

[olafgrabienski]

if you have a embedded image in the Body field such as <img src="/sites/default/files/styles/large/public/image.jpg">

@jromine I also find it difficult to handle existing images in Body fields after an upgrade. To understand this issue here better, I'm curious: How did you embed your images with an image style in the Body field?

[jromine]

@olafgrabienski I use Insert module.

[olafgrabienski]

changing the Public file system path setting to "files" causes image style generation to break for existing images

I use Insert module.

Okay, I see! As far as I know, the Insert module selects the path to the image (style) only once, when you insert the image. It doesn't generate or update the style later. If my assumption is correct, the issue after changing the Public file system path isn't style generation. Can you verify this by inserting a new image to the Body field? That should work, and the module should use the new Public file system path.

I guess, the issue is rather that the old paths aren't valid anymore. How to work around the issue, depends on individual configuration and upgrade procedure, e.g. have you created a symlink during the upgrade?

[jromine]

@olafgrabienski yes, existing image paths from an upgraded site won't be valid anymore if you change Public file system path. Yet the instructions say to change Public file system path.

My solution for the broken images is to add a symlink at sites/default/files -> ../../files as recommended in the instructions; however, leave Public file system path (sites/default/files) unchanged after upgrade. Other solutions, such as changing all the image paths manually (possibly by using a module like Search & Replace scanner) could also work.

The issue here is that the upgrade documentation recommends a step that could break image generation on an upgraded site without warning the user of this possibility or what actions to take to resolve it. So I think the documentation should note this possibility.

[olafgrabienski]

I agree, the recommendation can be misleading, and I find it generally difficult to wrap my head around this part of an upgrade. Do you have a suggestion how to change the text?

[jromine]

I have been thinking of how to describe this. So far I have been unable to find the Backdrop documentation page that describes what image style presets are, or how/why you would use them. For comparison, the Drupal page is at https://www.drupal.org/docs/core-modules-and-themes/core-modules/image-module/working-with-images

Here is a draft wording and placement:

After the upgrade, consider updating the "Public file system path" setting at admin/config/media/file-system to files. If your site has existing styled inline images, changing this setting could break image style generation, so leave it unchanged.

If we have a documentation page like the Drupal one on image styles, the paragraph could also link to it.

[olafgrabienski]

Thanks for the draft, and sorry for responding late. I'm still not convinced this is a question of image style "generation", but have no time for the next two weeks, so let's ask others for more feedback.