Technical Information

The information on this page are meant for developers who quickly want to learn how Image Source Control works, technically. It also contains tweaks that this user group might find useful.

Compatibility

ISC works with the PHP WordPress is officially supporting. While we are not actively testing for compatibility with higher PHP versions, we are happy to make appropriate updates to the code if users find issues with official or upcoming PHP releases.

Browser support according to WordPress Core Browser Support.
E.g., IE up to 11 is not supported

How ISC searches for image sources

ISC stores image sources as post meta for the attachment.

When creating the source list in the frontend, ISC looks for attachment IDs in the frontend code following a few patterns created by WordPress standards.

In addition to that, the plugin also looks for image URLs. If they are missing an attachment ID then the plugin tries to identify them based on the URL in the database. It looks for a match in the _wp_attached_file post meta field.

When looking for the original image URL in the database, ISC automatically removes strings only available for images in the frontend, like -scaled, rotated, or other additional added by WordPress.

If the image URL is changed in other ways then ISC might not be able to find it.

Indexing

ISC creates two indexes, which are stored as post meta values:

Workflow

  1. A post with images in the content is visited for the first time
  2. ISC looks through the content and creates an index that associates the post and all images with each other
  3. ISC creates source captions if that option is enabled
  4. ISC creates the list of sources below the content, if that option is enabled, this is taken from the stored index created in #2

When the post is visited for a second time, the index is not created again, but taken from the stored value.

The index is also created again with the next visit of the post when the content of the post was changed in the backend manually or automatically. Updating a post removes the index of isc_post_images.

Indexing can best be examined when using the full source list:

  • [isc_list_all] only shows images that are associated with a post already (read: indexed). You can see it growing with any new images indexed
  • [isc_list_all included="all"] shows all images from the media library. The column for associated posts is empty when the index is not filled (yet)

Since the full source list is built from isc_image_posts, it will contain the information for posts that have been updated but not yet re-indexed by visiting it in the frontend. That data is updated as soon as the post is visited again.

isc_post_images

Stored with posts.

It contains an array of images that are either in the content of a given post or their featured image.

The list of image sources below a post is built from this array.

isc_image_posts

Stored with images

It contains an array of IDs of posts in which images are either in the content or featured images.

Other notes on indexing

Only images that are technically added to the content with a priority for the_content lower than 20 are taken into account.

Indexing only works on single pages, not on archives. This decision was made to prevent cases in which some content on archive pages might be different from the original single page.

Image source list

Included image sources

The “Image Source List” option comes with three levels of which images are included in the list. Find a few test cases below.

Each method also covers the images found of the previous one.

A: Images in the content

  • any img tag in the content
  • images in the WP gallery block
  • images in the Cover block
  • featured images

B: Images on the whole page

  • any img tag in <body>
  • including images in sidebar

C: Any Image URL

  • background image (as set in WP) which is in <head>
  • URL in a data attribute like <div class="e-gallery-image elementor-gallery-item__image" data-thumbnail="https://example.com/wp-content/uploads/2020/07/image.png" data-width="300" data-height="169" alt="…"></div>

Replacing the source list

The following is relevant if you show sources for images outside the main content.

  • If multiple image source lists are on the page, only the last one is filled with sources. This could lead to unexpected behavior when using multiple image source lists, e.g., on archive pages. Additional source lists might only contain the sources for images in the main content.

Constants

Use define('ISC_DISABLE_PRO', true ) in wp-config.php to disable the execution of Pro in the base plugin.

Debugging

Enable the “Debug log” option in the plugin settings to log all image source activity in isc.log in the ISC plugin directory.

Attach ?isc-log to any URL in the frontend to log the actions ISC is performing in the isc.log file.

Disabling the option will remove the log file.

Replicating issues

To debug an issue on a site that is not yours, you could copy the whole HTML output to your local environment.

  • Use a “Custom HTML” block to debug issues that relate to the content of posts (which then would run through the_content)
  • or create a new post template in the theme and copy the output there instead of the dynamic content to open that “page” locally.

When testing code for image recognition locally, you need to change or the IDs of the images in the code to some that are locally hosted in your database.

E.g.

<img class="aligncenter wp-image-123 size-medium" src="300x250.png" alt="" width="300" height="200">
Code language: JavaScript (javascript)

Would look for the attachment with the ID 123, which would not work, if you don’t have an attachment with the same ID in your database. Removing wp-image-123 allows a local installation to find the image if it is in the DB with another ID.