Allow developers to tweak which image formats should be used

[felixarntz]

#142 changes the default implementation of the webp-uploads module to generate WebP versions in addition to JPEG versions for all sub-sizes of an image. This was decided in #96, replacing the original implementation from #4 where only WebP versions would be generated.

It has already been established that we would still like to provide developers with the flexibility to make their own decision though: For example, if they want to only generate WebP versions, or even only JPEG versions, they should be free to do so.

This issue is about defining the developer API and integration to control that behavior.

[felixarntz]

@adamsilverstein @mitogh I'd like to suggest the following here:

• We already have a filter webp_uploads_supported_image_mime_transforms. That filter exists only to control in what additional MIME types image sub-sizes will be generated, based on the MIME type originally uploaded.
• That filter allows us to generate JPEG and WebP sub-sizes for JPEG uploads, as well as to generate WebP and JPEG sub-sizes for WebP uploads. What it does not allow us yet is to only generate WebP sub-sizes even if a JPEG is uploaded, or only generate JPEG sub-sizes even if a WebP is uploaded (the latter is probably an edge-case, but worth considering).

Suggested filter

In order to keep the management of these formats simple while allowing for the additional flexibility of creating only one format at all time, I suggest we replace the above filter by something like this:

• A new filter like webp_uploads_image_mime_transforms (in core that would become wp_image_mime_transforms).
• The type of the value filtered would be similar to the above exiting filter, it would be a map of an image MIME type and the one or more image MIME types that other image versions can be created for.
• However, to allow the flexibility we need it should also allow include the original MIME type itself in the list of MIME types to transform into. That sounds a bit complicated to explain, so I added some examples below to clarify what I mean.

Examples for possible filter values

The following would mean for every JPEG upload, sub-sizes are generated in JPEG and WebP, and for every WebP upload, sub-sizes are generated in WebP and JPEG. This is what #142 does, so it's essentially the default.

$image_mime_transforms = array(
	'image/jpeg' => array( 'image/jpeg', 'image/webp' ),
	'image/webp' => array( 'image/webp', 'image/jpeg' ),
);

The following would mean regardless of whether JPEG or WebP is uploaded, only WebP sub-sizes are generated. This is what the original webp-uploads implementation from #4 did. Sites which don't need JPEG at all would likely go that approach.

$image_mime_transforms = array(
	'image/jpeg' => array( 'image/webp' ),
	'image/webp' => array( 'image/webp' ),
);

The following would mean for every JPEG and WebP uploaded, sub-sizes are generated in the same MIME type. This is basically how WP core currently works.

$image_mime_transforms = array(
	'image/jpeg' => array( 'image/jpeg' ),
	'image/webp' => array( 'image/webp' ),
);

The following would mean regardless of whether JPEG or WebP is uploaded, only JPEG sub-sizes are generated. This is a bit of an obscure use-case IMO, but I guess if a site really needs JPEG and doesn't care about WebP, it's possible.

$image_mime_transforms = array(
	'image/jpeg' => array( 'image/jpeg' ),
	'image/webp' => array( 'image/jpeg' ),
);

Implementation

We could easily implement this filter in its own function. It would tie in nicely with the existing implementation from #142, we would just need to make sure that in that filter we would ignore the formats that already exist for the image (e.g. if only JPEG sub-sizes should be generated for JPEG uploads, we don't need to do anything extra).

We would then also need to re-introduce a filter for image_editor_output_format, similar to the one from the original implementation in #4, which based on the above new filter either changes the format to JPEG/WebP or keeps it as is.

Whatever we decide on, we can start development once #147 has been merged. Curious to hear feedback on this proposal!

[adamsilverstein]

@felixarntz 👍🏼 your proposed filter sounds right, I like the flexibility of the mime->mime array mapping. This will also work well when we want to add support for an additional mime type like avif.

The following would mean regardless of whether JPEG or WebP is uploaded, only JPEG sub-sizes are generated. This is a bit of an obscure use-case IMO, but I guess if a site really needs JPEG and doesn't care about WebP, it's possible.

This could be applicable for sites that for some reason need to support clients that don't support WebP (eg. IE or older MacOS, or windows Outlook)

The following would mean regardless of whether JPEG or WebP is uploaded, only WebP sub-sizes are generated.

One caveat here is that if the server lacks WebP support we should output jpeg sub-sizes for jpeg uploads (for WebP uploads we won't be able to do resizing at all if WebP support is missing)

We would then also need to re-introduce a filter for image_editor_output_format

Right, this will let us control the default output format from the plugin. for the core merge, we may be able to introduce the output change more directly by calling the function directly in get_output_format.

[felixarntz]

@adamsilverstein

One caveat here is that if the server lacks WebP support we should output jpeg sub-sizes for jpeg uploads (for WebP uploads we won't be able to do resizing at all if WebP support is missing)

Absolutely. I think that will need to be handled by the logic consuming the filter value. If the formats provided in the filter are not supported by the server, the implementation should always fall back to generating sub-sizes in the originally uploaded format, so that in any case there will be sub-sizes generated.

[mitogh]

This approach looks good to me, just a couple of notes for some scenarios that would be great to define.

The following would mean for every JPEG and WebP uploaded, sub-sizes are generated in the same MIME type. This is basically how WP core currently works.

$image_mime_transforms = array(
	'image/jpeg' => array( 'image/jpeg' ),
	'image/webp' => array( 'image/webp' ),
);

This is great, however another way to make this work would be by just returning an empty array

$image_mime_transforms = array();

So by doing this we let WP core to handle the logic for the images which should be the default behavior, allowing using an empty array, simplifies the removal of this behavior by just adding the callback __return_empty_array to the filter.

Another thing about this one is the fact that this approach does not handle valid transformations, meaning that a using this approach we could specify something like:

$image_mime_transforms = array(
	'image/jpeg' => array( 'image/gif', 'image/png' ),
);

While technically that would work in some cases, I don't think it would make sense, (mostly an edge case but something to take in mind) to open the possibility to define a safe list of transformations between formats likeget_allowed_mime_types so a function like get_allowed_mime_transformations that would verify or ensure that the provided list of transformations is valid can be an enchantment.

cc @felixarntz @adamsilverstein 0

[felixarntz]

@mitogh

This is great, however another way to make this work would be by just returning an empty array

That could make sense, however it makes for an inconsistent API if we don't include the original format itself in the transforms values as well:

• Based on my proposal 'image/jpeg' => array( 'image/jpeg', 'image/webp' ) clearly says "I want JPEG and WebP for all JPEG". And 'image/jpeg' => array( 'image/webp' ) clearly says "I want only WebP for all JPEG".
• If we omit the original format like you're suggesting, then both of the above scenarios would be 'image/jpeg' => array( 'image/webp' ), so it would be unknown whether the user wants JPEG and WebP or only WebP.

So I think my original proposal is more clear here.

Another thing about this one is the fact that this approach does not handle valid transformations, meaning that a using this approach we could specify something like:

Agreed, but I don't think that's a problem with the API. We need to make sure that whatever developers provide in the filter is validated. We have to decide what we would allow there, and for example we could initially limit the filter to only support any permutations of JPEG and WebP. Still, the API makes sense to be flexible, we should build it in a future-proof way.

[mitogh]

If we omit the original format like you're suggesting, then both of the above scenarios would be 'image/jpeg' => array( 'image/webp' ), so it would be unknown whether the user wants JPEG and WebP or only WebP.

Correct, the main idea is defining that scenario, I think the behavior if a mime type is not defined basically that the source property won't be created for that mime type, which would be the case for a PNG or a GIF image for example. So when an empty array is returned from this filter no transformation should take place, or that would be the definition of unknown in this case.

Agreed, but I don't think that's a problem with the API. We need to make sure that whatever developers provide in the filter is validated. We have to decide what we would allow there, and for example we could initially limit the filter to only support any permutations of JPEG and WebP. Still, the API makes sense to be flexible, we should build it in a future-proof way.

💯

[mitogh]

Hey @felixarntz @adamsilverstein ,

I was looking at this filter again, and just to confirm and not to create a new issue, the main idea with this filter is to control the uploads right? Not so the rendering or the image delivery to the client (browser). Meaning that currently there's no way for a user to determine which format would be delivered to the users when opening a page, besides image/webp by default.

Take a look at: #186 (comment) as well for another approach.

Regardless of the suggested approach above, I feel there should be a filter that short-circuit all the logic to deliver a mime type regardless. Let me know if you are envisioning this filter to handle that use case or if you are in favor of a new filter instead so I can open a new ticket.

My personal preference would be to have a single filter to specify a mime type that would be rendered if no mime-type is specified the logic from #186 would be used instead. If a mime is specified that mime type would be used regardless of the logic from #186