Awesome

Easy Uploadcare Image Transformation URLs generation

Generate Uploadcare image processing URLs to transform and process your images. No need to write or generate the URL yourself. Just pass the UUID of the file, optionally pass the custom CDN and chain the methods you want to apply and the package generates the URL for you.

• Requirements
• Installation
• Usage
• Documentation
  • Using percentages or pixels as parameter
  • List of possible transformations
• Usage
  • Auto rotate
  • Basic color adjustments
  • Blur
  • Blur faces
  • Blur region
  • Convert to sRGB
  • Crop
  • Crop by objects
  • Crop by ratio
  • Enhance
  • Filter
  • Flip
  • Format
  • Grayscale
  • ICC profile size threshold
  • Invert
  • Miror
  • Overlay
  • Preview
  • Progressive
  • Quality
  • Rasterize
  • Resize
  • Rotate
  • Scale crop
  • Set fill
  • Sharpen
  • Smart crop
  • Smart resize
  • Zoom objects
• Testing
• Changelog
• Contributing
• Security Vulnerabilities
• Credits
• License

Requirements

Installation

You can install the package via composer:

composer require vormkracht10/php-uploadcare-transformations

Usage

use Vormkracht10\UploadcareTransformations\UploadcareTransformation;

$uuid = '12a3456b-c789-1234-1de2-3cfa83096e25';
$cdnUrl = 'https://example.com/cdn/';

$transformation = (new UploadcareTransformation($uuid, $cdnUrl));

$url = $transformation->crop(width: 320, height: '50p', offsetX: 'center')->setFill(color: 'ffffff');

echo $url;
// https://example.com/cdn/12a3456b-c789-1234-1de2-3cfa83096e25/-/crop/320x50p/center/-/set_fill/ffffff

If you prefer to use a shorter version you can also use the helper method:

$uuid = '12a3456b-c789-1234-1de2-3cfa83096e25';
$cdnUrl = 'https://example.com/cdn/';

$url = uc($uuid, $cdnUrl)
        ->crop(width: 320, height: '50p', offsetX: 'center')
        ->setFill(color: 'ffffff')
        ->getUrl();

echo $url;
// https://example.com/cdn/12a3456b-c789-1234-1de2-3cfa83096e25/-/crop/320x50p/center/-/set_fill/ffffff

Using the Laravel framework

When you are using the Laravel framework it might be better to define the CDN in your .env file and get the value from the .env file in a config file. You can create a dedicated config/uploadcare config or add it to the config/services file.

Your .env file:

UPLOADCARE_CDN_URL=https://ucarecdn.com
UPLOADCARE_PROXY_URL=https://endpoint.ucr.io

Add to config/services.php file:

'uploadcare' => [
    'cdn_url' => env('UPLOADCARE_CDN_URL', 'https://ucarecdn.com'),
    'proxy_url' => env('UPLOADCARE_PROXY_URL', 'https://endpoint.ucr.io'),
],

In your code:

$url = uc($uuid, config('services.uploadcare.cdn_url'))->crop(width: 320, height: '50p', offsetX: 'center')->setFill(color: 'ffffff');

Documentation

Using percentages or pixels as parameter

In some of the methods you can pass parameters in various ways. For example in the scaleCrop() method you can pass the offset in the form of a percentage or pixels. To make it easier to recognize when a pixel or percentage is used you can pass the parameters as following.

// Using percentages
$url = $transformation->scaleCrop(width: 320, height: 320, offsetX: '50p', offsetY: '60p');
// https://example.com/cdn/12a3456b-c789-1234-1de2-3cfa83096e25/scale_crop/320x320/50px60p/


// Using pixels
$url = $transformation->scaleCrop(width: 320, height: 320, offsetX: 50, offsetY: 60);
// https://example.com/cdn/12a3456b-c789-1234-1de2-3cfa83096e25/scale_crop/320x320/50x60/

As stated in the Uploadcare Documentation, in URLs, % is an escape character and should be encoded with %25 escape sequence, e.g. /scale_crop/440x440/80%25,80%25/. For convenience, we can use the p shortcut for percent which doesn't require encoding.

List of possible transformations

Each transformation follows the documentation on Uploadcare which you may find <a href="https://uploadcare.com/docs/">here</a>. The current list of possible transformations and where to find the documentation:

Usage

Adding filename

Original filenames can be accessed via Uploadcare's REST API. This can be done by making a request to receive a JSON response with file parameters including original_filename.

You can set an optional filename that users will see instead of the original name:

$url = $transformation->autoRotate(false)->filename('my-filename.jpg');
// https://example.com/cdn/.../-/autorotate/no/my-filename.jpg

Please note that the filename should comply with <a href="https://tools.ietf.org/html/rfc3986#section-3.3">file name conventions</a>. For more more information about how to use filenames please check the <a href="https://uploadcare.com/docs/delivery/cdn/#cdn-filename">Uploadcare API documentation</a>.

Auto rotate

The default behavior goes with parsing EXIF tags of original images and rotating them according to the “Orientation” tag. Using false as parameter allows turning off the default behavior.

$url = $transformation->autoRotate(false);
// https://example.com/cdn/.../-/autorotate/no/

$url = $transformation->autoRotate(true);
// https://example.com/cdn/.../-/autorotate/yes/

Basic color adjustments

The value parameter controls the strength of any applied adjustment. Ranges of the value parameter differ between operations. There also is a zero point for each operation — the value producing outputs equal to original images.

Adjustment (color) must be one of the following values: brightness, exposure, contrast, saturation, gamma, vibrance, warmth.

For a complete overview of allowed values based upon the chosen adjustment, take a look at the Uploadcare Documentation.

$url = $transformation->basicColorAdjustments(color: 'brightness', value: 50);
// https://example.com/cdn/.../-/adjust/brightness/50/

Blur

Blurs images by the strength factor. The filtering mode is Gaussian Blur, where strength parameter sets the blur radius — effect intensity.

$url = $transformation->blur(strength: 50, amount: null);
// https://example.com/cdn/.../-/blur/50/

Blur faces

When faces is specified the regions are selected automatically by utilizing face detection.

$url = $transformation->blurFaces(strength: 50);
// https://example.com/cdn/.../-/blur_faces/50/

Blur region

Blurs the specified region of the image by the strength factor. The filtering mode is Gaussian Blur, where strength parameter sets the blur radius — effect intensity.

Dimensions and coordinates must be pixels or percentages.

// Using pixels.
$url = $transformation->blurRegion(dimensionX: 250, dimensionY: 250, coordinateX: 50, coordinateY: 50, strength: 200);
// https://example.com/cdn/.../-/blur_region/250/250/50/50/200/

// Using percentages.
$url = $transformation->blurRegion(dimensionX: '50p', dimensionY: '50p', coordinateX: '80p', coordinateY: '20p', strength: 200);
// https://example.com/cdn/.../-/blur_region/50p/50p/80p,20p/200/

Convert to sRGB

The operation sets how Uploadcare behaves depending on different color profiles of uploaded images. See the Uploadcare Documentation to learn more about the possible outcomes.

The profile parameter must be one of the following values: fast, icc, keep_profile.

$url = $transformation->convertToSRGB(profile: 'icc');
// https://example.com/cdn/.../-/srgb/icc/

Crop

Crops an image by using specified dimensions and alignment.

Dimensions parameters can be in pixels or percentages. To see how pixels or percentages can be used, see the Using percentages or pixels as parameter paragraph.

Alignment can also be in pixels and percentages but also a shortcut can be used. The possible values are: top, center, bottom, left, right.

// Using percentages and a shortcut.
$url = $transformation->crop(width: 100, height: '50p', offsetX: 'center');
// https://example.com/cdn/.../-/crop/100x50p/center/

// Using pixels only.
$url = $transformation->crop(width: 100, height: 100, offsetX: 50, offsetY: 50);
// https://example.com/cdn/.../-/crop/100x100/50,50/

// Using both pixels and percentages.
$url = $transformation->crop(width: 100, height: '50p', offsetX: '25p', offsetY: '25p');
// https://example.com/cdn/.../-/crop/100x50p/25p,25p/

Crop by objects

Crops the image to the object specified by the tag parameter.

Tag can be one of face or image.

Ratio are two numbers greater than zero separated by :. Ratio is the quotient from the division of these numbers.

Dimensions and alignment must be set in percentages. In case of the alignment you can also use the shortcut. The possible values are: top, center, bottom, left, right. If alignment is not specified, center value is used.

Dimensions should be relative when used with a tag. So you are required to set both width and height with pixels.

// Using no ratio, percentages and pixels combined.
$url = $transformation->cropByObjects(tag: 'face', ratio: null, width: '50p', height: '50p');
// https://example.com/cdn/../-/crop/face/50px50p/

// Using ratio, percentages and a shortcut.
$url = $transformation->cropByObjects(tag: 'face', ratio: '4:3', width: '50p', height: '50p', offsetX: 'bottom');
// https://example.com/cdn/../-/crop/face/4:3/50px50p/bottom/

Crop by ratio

Crops the image to the specified aspect ratio, cutting off the rest of the image.

Ratio are two numbers greater than zero separated by :. Ratio is the quotient from the division of these numbers.

Alignment can be set in pixels and percentages but also a shortcut can be used. The possible values are: top, center, bottom, left, right. If alignment is not specified, center value is used.

// Using percentages and a shortcut.
$url = $transformation->cropByRatio(ratio: '4:3', offsetX: 'bottom');
// https://example.com/cdn/.../-/crop/4:3/bottom/

// Using percentage in combination with pixels.
$url = $transformation->cropByRatio(ratio: '4:3', offsetX: '50p', offsetY: 240);
// https://example.com/cdn/.../-/crop/4:3/50p,240/

Enhance

Auto-enhances an image by performing the following operations: auto levels, auto contrast, and saturation sharpening.

Strength must be a number between 0 and 100. Default value is 50.

$url = $transformation->enhance(strength: 50);
// https://example.com/cdn/.../-/enhance/50/

Filter

Applies one of predefined photo filters by its name. The way your images look affects their engagement rates. You apply filters thus providing beautiful images consistent across content pieces you publish.

The name parameter should be one of the following: adaris, briaril, calarel, carris, cynarel, cyren, elmet, elonni, enzana, erydark, fenralan, ferand, galen, gavin, gethriel, iorill, iothari, iselva, jadis, lavra, misiara, namala, nerion, nethari, pamaya, sarnar, sedis, sewen, sorahel, sorlen, tarian, thellassan, varriel, varven, vevera, virkas, yedis, yllara, zatvel, zevcen.

The amount parameter must be a number between -100 and 200.

$url = $transformation->filter(name: 'adaris', value: 50);
// https://example.com/cdn/.../-/filter/adaris/50/

Flip

Flips images.

$url = $transformation->flip();
// https://example.com/cdn/.../-/flip/

Format

Converts an image to one of the following formats: jpg, png, webp, auto.

$url = $transformation->format(format: 'jpeg');
// https://example.com/cdn/.../-/format/jpg/

Grayscale

Desaturates images. The operation has no additional parameters and simply produces a grayscale image output when applied.

$url = $transformation->grayscale();
// https://example.com/cdn/.../-/grayscale/

ICC profile size threshold

The operation defines which RGB color profile sizes will be considered “small” and “large” when using srgb in fast or icc modes. The number stands for the ICC profile size in kilobytes.

The default value is 10 (10240 bytes). Most of the common RGB profile sizes (sRGB, Display P3, ProPhoto, Adobe RGB, Apple RGB) are below the threshold.

Please note, that because this transformation should always be used in combination with convertToSRGB() its method should be called <strong>after</strong> convertToSRGB(). Otherwise the ICC profile size threshold gets overwritten by the convertToSRGB() transformation.

$url = $transformation->convertToSRGB(profile: 'fast')->iccProfileSizeThreshold(number: 10);
// https://example.com/cdn/.../-/max_icc_size/10/srgb/fast/

Invert

Inverts images rendering a 'negative' of the input.

$url = $transformation->invert();
// https://example.com/cdn/.../-/invert/

Miror

Mirrors images.

$url = $transformation->mirror();
// https://example.com/cdn/.../-/mirror/

Overlay

The overlay operation allows to layer images one over another. One of the most common use cases here are watermarks: semi-transparent images layered over opaque ones to complicate their unauthorized usage, etc.

Every overlay parameter is optional and can be omitted. However, the order of parameter URL directives should be preserved. For example, if you want to use coordinateX parameter, you should also specify width and height parameters. Also note that the opacity parameter should be specified with percentages.

$uuidOverlay = 'e6b0c1c0-1b1a-4b1a-9b1a-1b1a1b1a1b1a';

$url = $transformation->overlay(
  uuid: $uuidOverlay,
  width: 150,
  height: 150,
  coordinateX: 200,
  coordinateY: 300,
  opacity: '25p'
)->getUrl();
// https://example.com/cdn/.../-/overlay/e6b0c1c0-1b1a-4b1a-9b1a-1b1a1b1a1b1a/150x150/200,300/25p/

Preview

Downscales an image proportionally to fit the given width and height in pixels.

$url = $transformation->preview(width: 100, height: 100);
// https://example.com/cdn/.../-/preview/100x100/

Progressive

Returns a progressive image. In progressive images, data are compressed in multiple passes of progressively higher detail. The operation does not affect non-JPEG images; does not force image formats to JPEG.

$url = $transformation->progressive(true);
// https://example.com/cdn/.../-/progressive/yes/

$url = $transformation->progressive(false);
// https://example.com/cdn/.../-/progressive/no/

Quality

Sets output JPEG and WebP quality. Since actual settings vary from codec to codec, and more importantly, from format to format, we provide five simple tiers and two automatic values which suits most cases of image distribution and are consistent.

Quality must be one of the following values: smart, smart_retina, normal, better, best, lighter, lightest.

$url = $transformation->quality(quality: 'smart');
// https://example.com/cdn/.../-/quality/smart/

Rasterize

Rasterize SVG images.

$url = $transformation->rasterize();
// https://example.com/cdn/.../-/rasterize/

Resize

Resizes an image to one or two dimensions. When you set both width and height explicitly, it may result in a distorted image. If you specify either side, this operation will preserve the original aspect ratio and resize the image accordingly. Mode should be one of the following values: on, off, fill.

// Using width, height, stretch and 'fill' mode.
$url = $transformation->resize(width: 100, height: null, stretch: true, mode: 'fill');
// https://example.com/cdn/.../-/resize/100x/stretch/fill/

// Using only height, no stretch and no mode.
$url = $transformations->resize(width: null, height: 250, stretch: false);
// https://example.com/cdn/.../-/resize/250x/

Rotate

Right-angle image rotation, counterclockwise. The value of angle must be a multiple of 90.

$url = $transformation->rotate(angle: 180);
// https://example.com/cdn/.../-/rotate/180/

Scale crop

Scales an image until it fully covers the specified dimensions; the rest gets cropped. Mostly used to place images with various dimensions into placeholders (e.g., square shaped).

Dimensions must be set in pixels.

Alignment must be set in percentages or shortcut. The possible values are: top, center, bottom, left, right. If alignment is not specified, 0,0 value is used.

// Using percentages.
$url = $transformation->scaleCrop(width: 100, height: 100, offsetX: '30p', offsetY: '50p');
// https://example.com/cdn/.../-/scale_crop/100x100/30p,50p/

// Using shortcut.
$url = $transformation->scaleCrop(width: 100, height: 100, offsetX: 'bottom');
// https://example.com/cdn/../-/scale_crop/100x100/bottom/

Set fill

Sets the fill color used with crop, stretch or when converting an alpha channel enabled image to JPEG.

Color must be a hex color code <b>without using the hashtag</b>.

$url = $transformation->setFill(color: 'ff0000');
// https://example.com/cdn/.../-/setfill/ff0000/

Sharpen

Sharpens an image, might be especially useful with images that were subjected to downscaling. strength can be in the range from 0 to 20 and defaults to the value of 5.

$url = $transformation->sharpen(strength: 20);
// https://example.com/cdn/.../-/sharp/20/

Smart crop

Switching the crop type to one of the smart modes enables the content-aware mechanics. Uploadcare applies AI-based algorithms to detect faces and other visually sensible objects to crop the background and not the main object.

Dimensions must be set in pixels.

Type must be one of the following values: smart, smart_faces_objects, smart_faces, smart_objects, smart_faces_points, smart_points, smart_objects_faces_points, smart_objects_points or smart_objects_faces.

Aligment must be set in percentages or shortcut. The possible values are: top, center, bottom, left, right. If alignment is not specified, 0,0 value is used.

// Using percentages.
$url = $transformation->smartCrop(width: 100, height: 100, type: 'smart_faces_objects', offsetX: '30p', offsetY: '50p');
// https://example.com/cdn/.../-/scale_crop/100x100/smart_faces_objects/30p,50p/

// Using shortcut.
$url = $transformation->smartCrop(width: 100, height: 100, type: 'smart_faces_objects', offsetX: 'right');
// https://example.com/cdn/.../-/scale_crop/100x100/smart_faces_objects/right/

Smart resize

Content-aware resize helps retaining original proportions of faces and other visually sensible objects while resizing the rest of the image using intelligent algorithms.

$url = $transformation->smartResize(width: 500, height: 500);
// https://example.com/cdn/.../-/smart_resize/500x500/

Zoom objects

Zoom objects operation is best suited for images with solid or uniform backgrounds.

Zoom must be a number between 1 and 100.

$url = $transformation->zoomObjects(zoom: 50);
// https://example.com/cdn/.../-/zoom_objects/50/

Testing

./-/vendor/bin/pest

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• Bas van Dinther
• Mark van Eijk
• All Contributors

License

The MIT License (MIT). Please see License File for more information.