2.x Add ImageHelper filters to customize paths

[mcaskill]

Related:

• 2.x Fix theme images generation (using Twig filters and such) #2458
• Timber 2.x - ImageHelper::theme_url_to_dir() returns an invalid path when theme template is theme-name/theme #2453

Issue

As reported in aforementioned issue and pull request, the ImageHelper::theme_url_to_dir() method is unable to resolve a URL/path in a non-standard theme directory structure.

This is the case if your "stylesheet" directory is located in a subdirectory of your theme my-theme/theme as was initially proposed in Timber's v2 starter-theme and employed by various theme boilerplates.

Solution

The solution, as proposed by @gchtr, is to add filters in ImageHelper to allow one to customize the logic of converting a URL to a path.

For example, we could add a timber/theme_url_to_dir filter that allows you to filter the result of Timber\ImageHelper::theme_url_to_dir().

I've added four filters:

• ImageHelper::analyze_url()
  • timber/image_helper/pre_analyze_url to short-circuit the method's default URL analysis logic.
  • timber/image_helper/analyze_url to mutate the default analyzed URL components.
• ImageHelper::theme_url_to_dir()
  • timber/image_helper/pre_theme_url_to_dir to short-circuit the method's default path resolution logic.
  • timber/image_helper/theme_url_to_dir to mutate the default resolved path.

I've added filters to analyze_url() since it's the one that calls theme_url_to_dir() and also contains opinionated logic for analyzing the URL.

Maybe the short-circuit filters could still call their non-pre filters, this would involve wrapping the default logic in a "did pre-filter return null".

Here's how its being used in a client project:

public function register_filters() : void {
	add_filter( 'timber/image_helper/pre_theme_url_to_dir', [ $this, 'filter_timber_image_helper_pre_theme_url_to_dir' ], 10, 2 );
}

public function filter_timber_image_helper_pre_theme_url_to_dir( ?string $path, string $src ): ?string {
	if ( is_null( $path ) && str_starts_with( $src, $this->theme_uri ) ) {
		$path = str_replace( $this->theme_uri, '', strtok( $src, '?' ) );
		$path = $this->theme_path . '/' . ltrim( $path, '/' );
	}

	return $path;
}

Impact

Adding an extra hooks could affect performance but it should be minor.

Usage Changes

The current logic of those methods does not change, filters are added to allow one to handle them early or mutate the default resulting values.

Considerations

See discussions from #2458

Testing

• Modified install-wp-tests.sh to ensure TMPDIR is canonical.
• Fixed tests of TestTimberImageHelperInternals::testAnalyzeURLTheme().
• Added tests for filters in ImageHelper::analyze_url().
• Added tests for filters in ImageHelper::theme_url_to_dir().

[coveralls]

coverage: 88.744% (+0.2%) from 88.522% when pulling e09279e on mcaskill:2.x-add-image-helper-filters into f56f062 on timber:2.x.

[gchtr]

Adding filters is definitely the way to go. Because this isn’t a breaking change and we want to focus on getting 2.0 ready, I switched this to 2.x Future.

[Moustachos]

@gchtr any update on this one now that 2.x is stable? :)

Thanks!

[Levdbas]

Hi @Moustachos , we have this in mind for a first minor release for Timber 2. Release date is TBD.

[Moustachos]

Thanks @Levdbas 👍

[gchtr]

Thanks for taking this on, @mcaskill. And sorry for the longer wait.

I really appreciate that you took the time to carefully craft the DocBlocks for the filters with proper descriptions 🙌.

I just have on issue with the underscore prefixes in the private function names. Otherwise, this looks good to me and I think we can merge this for the next minor release.

[gchtr]

This looks good from my side 👍.

@nlemoine Can you have a quick look and merge this, if it looks alright to you, too?

[nlemoine]

Still feels a bit odd to handle such things but doesn't hurt 👍