Error handling strategy for image toolkit operations

Created on 11 June 2014, almost 11 years ago

Updated 14 April 2025, 8 days ago

Follow-up to #2073759: Convert toolkit operations to plugins → and for now postponed on that issue until it gets committed. Part of #2105863: [meta] Images, toolkits and operations → .

Problem/Motivation

Image toolkit operations historically lack good error handling. On a relatively high level an error gets logged and false is returned while other methods may throw an exception.
- This prevents good trouble shooting as it is not always clear exactly what statement failed (see for an example issue #2215369: Various bugs with PHP 5.5 imagerotate(), including when incorrect color indices are passed in → ).
- This cannot be considered a good consistent API

Proposed resolution

As I consider the image system to be a base component, I think that all errors should result in an exception that does not get logged by the sub system itself as it lacks context to decide how severe the error is. For example, the image style controller may decide that a missing operation will be silently ignored (just a record logged) while the image field may decide that a missing scale/resize operation is considered fatal.

Based on the above observation, I propose the following clear and consistent error handling strategy.

Toolkit and its operations:
- should not log anything
- should throw an exception if they cannot successfully complete a request. This is preferred over returning false, as it gives the opportunity to return a message.
- should not alter the internal image (resource for GD) in case of errors.
- the apply/execute method thus should always return true
Image: same, plus it should not normally catch an exception.
Image effect: same as Image.
ImageStyle: catch all exceptions (and false return values for now), log them and continue to deliver.
Image field: catch resize errors and return the form with an upload failure set.

(Typical) Exceptions to throw:

Missing operations PluginNotFoundException
Parameter validation failure: InvalidArgument
Missing GD function: RuntimeException
Method call on not correctly initialized object (e.g. save on not valid image): BadMethodCall

Remaining tasks

Refactor the GD operations and its usages (in core) to comply with the new error handling strategy
Refactor the GD operations to better check the results of calls to the GD library.
Refactor Image, ImageEffect and ImageStyle
Refactor other usages as necessary, including Image fields

API changes

The operations provided by a toolkit are not seen as a real API, nor are their parameter definitions. So no API changes, though core and contrib effects and contrib toolkits may have to be adapted to catch an exceptin instead of checking a re turn value.

User interface changes

None.

📌 Task

Status

Postponed: needs info

Version

11.0 🔥

Component

image system

Created by

🇫🇷France fietserwin Le Mont-Dore

Live updates comments and jobs are added and updated live.

stale-issue-cleanup
To track issues in the developing policy for closing stale issues, [Policy, no patch] closing older issues

Incomplete comments

Comments & Activities

Not all content is available!

It's likely this issue predates Contrib.social: some issue and comment data are missing.

Comment 8 days ago →
🇺🇸United States smustgrave
Thank you for creating this issue to improve Drupal.

We are working to decide if this task is still relevant to a currently supported version of Drupal. There hasn't been any discussion here for over 8 years which suggests that this has either been implemented or is no longer relevant. Your thoughts on this will allow a decision to be made.

Since we need more information to move forward with this issue, the status is now Postponed (maintainer needs more info). If we don't receive additional information to help with the issue, it may be closed after three months.

Thanks!

contrib.social Blog FAQ Discussions

Production build 0.71.5 2024