REST API: Add batch image editing

[ajlende]

Trac ticket: https://core.trac.wordpress.org/ticket/52192

See: WordPress/gutenberg#23369

This proposes a new API for image editing that should be more flexible and extensible than the existing API. The new API takes an array of modifiers that will be applied in the order they appear.

An example request body looks like this.

{
  "modifiers": [
    {
      "type": "crop",
      "args": {
        "left": 12.875,
        "top": 0.125,
        "width": 50,
        "height": 50
      }
    },
    {
      "type": "rotate",
      "args": {
        "angle": 90
      }
    }
  ]
}

Crop values are as a percentage of the original image and rotation angle is in degrees clockwise.

The crop values need to be percentages because the image loaded on the frontend may not be a scaled version of the original image, so naturalWidth and naturalHeight cannot be trusted as the actual width and height of the original image.

The rotation value is in degrees to avoid rounding errors for the types of rotations that are most common like 90 degrees. Clockwise versus anticlockwise may be up for debate. When using degrees it seems more natural to me to rotate clockwise, but mathematically, when you've converted to radians, a positive value indicates an anticlockwise rotation.

Different front-end implementations may apply edits in a different order, so passing an array will allow them to use their edits as-is without converting to a fixed order.

One example in the wild that actually uses both orders in different contexts is BeFunky. To see the difference, try one of their demo images with a horizon in it so you have a line that you can pay attention to. Then use the 'straighten' option followed by a 'horizontal flip' to see that the angle of the horizon hasn't changed even though you flipped the image. This means that the flip happens before the rotation. If you use the 'rotate' option instead of 'straighten, the rotation happens before the flip.

The old API continues to work, but when supplying the modifiers option, the old crop and rotation options are ignored.

Cropping and rotation are not constrained since the underlying WP_Image_Editor_Imagick and WP_Image_Editor_GD do not appear to be constrained.

---

This Pull Request is for code review only. Please keep all other discussion in the Trac ticket. Do not merge this Pull Request. See GitHub Pull Requests for Code Review in the Core Handbook for more details.

[github-actions]

Hi @ajlende! 👋

Thank you for your contribution to WordPress! 💖

It looks like this is your first pull request to wordpress-develop. Here are a few things to be aware of that may help you out!

No one monitors this repository for new pull requests. Pull requests must be attached to a Trac ticket to be considered for inclusion in WordPress Core. To attach a pull request to a Trac ticket, please include the ticket's full URL in your pull request description.

Pull requests are never merged on GitHub. The WordPress codebase continues to be managed through the SVN repository that this GitHub repository mirrors. Please feel free to open pull requests to work on any contribution you are making.

More information about how GitHub pull requests can be used to contribute to WordPress can be found in this blog post.

Please include automated tests. Including tests in your pull request is one way to help your patch be considered faster. To learn about WordPress' test suites, visit the Automated Testing page in the handbook.

If you have not had a chance, please review the Contribute with Code page in the WordPress Core Handbook.

The Developer Hub also documents the various coding standards that are followed:

• PHP Coding Standards
• CSS Coding Standards
• HTML Coding Standards
• JavaScript Coding Standards
• Accessibility Coding Standards
• Inline Documentation Standards

Thank you,
The WordPress Project

[TimothyBJacobs]

Let's also move the deprecated modifiers to the end of the args description.

[ajlende]

I know you had mentioned adding a new deprecated option, but I was weary of adding a non-standard key on the JSON Schema, so it seemed like just adding a notice to the description may be sufficient.

I can still go ahead and add that option if you still think it's needed—something like array( 'deprecated' => __( 'Use `modifiers` instead.' ) ) maybe rather than just a boolean.

And before we go ahead and merge this, I'd like @azaozz's opinion on updating it to use the args key which I had mentioned in the old PR, but hadn't changed until moving it here.

[TimothyBJacobs]

Let's leave a formal deprecated syntax for another ticket.

[antpb]

This PR has been merged in https://core.trac.wordpress.org/changeset/50124

Thank you for this awesome change @ajlende !