Imgix PHP

https://github.com/imgix/imgix-php
Admin
Imgix PHP is a client library for generating imgix image URLs, supporting features like signed URLs...
Tokens:28,006
Snippets:213
Trust Score:8.5
License:BSD-2-Clause
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install imgix-php with Composer

Source: https://github.com/imgix/imgix-php/blob/main/README.md

Install the imgix-php client library via Composer. This is the recommended installation method and will add the package to your project's dependencies.

```bash
composer require imgix/imgix-php
```

--------------------------------

### createURL basic example

Source: https://github.com/imgix/imgix-php/blob/main/_autodocs/api-reference/UrlBuilder.md

Basic example of createURL with width and height parameters, producing an https URL.

```php
$builder = new UrlBuilder("demos.imgix.net", true, "", false);
echo $builder->createURL("bridge.png", ["w" => 100, "h" => 100]);
// 'https://demos.imgix.net/bridge.png?h=100&w=100'
```

--------------------------------

### Install dependencies with Composer

Source: https://github.com/imgix/imgix-php/blob/main/CONTRIBUTING.md

Installs project dependencies using Composer. Requires PHP and Composer to be installed locally.

```bash
php composer.phar i
```

--------------------------------

### Basic validateWidths example

Source: https://github.com/imgix/imgix-php/blob/main/_autodocs/api-reference/Validator.md

Basic usage example showing a valid widths array passed to validateWidths.

```php
$opts = ["widths" => [144, 240, 320, 446, 640]];
Validator::validateWidths($opts["widths"]); // ok
```

--------------------------------

### getURL basic signed example

Source: https://github.com/imgix/imgix-php/blob/main/_autodocs/api-reference/UrlHelper.md

Creates a UrlHelper with a sign key and initial parameters, then outputs the signed URL.

```php
$uh = new UrlHelper("imgix-library-secure-test-source.imgix.net", "dog.jpg", "http", "EHFQXiZhxP4wA2c4", ["w" => 500]);
echo $uh->getURL();
// 'http://imgix-library-secure-test-source.imgix.net/dog.jpg?w=500&s=e4eb402d12bbdf267bf0fc5588170d56'
```

--------------------------------

### createURL nested-array and signing example

Source: https://github.com/imgix/imgix-php/blob/main/_autodocs/api-reference/UrlBuilder.md

Example of createURL with a nested array parameter and a signing key, producing a signed URL.

```php
$builder = new UrlBuilder("demos.imgix.net", true, "test1234", false);
echo $builder->createURL("bridge.png", ["auto" => ["compress", "format"], "w" => 100]);
// 'https://demos.imgix.net/bridge.png?auto=compress%2Cformat&w=100&s=...'
```

--------------------------------

### setParameter basic example

Source: https://github.com/imgix/imgix-php/blob/main/_autodocs/api-reference/UrlHelper.md

Creates a UrlHelper instance and sets the 'w' parameter to 500, then outputs the signed URL.

```php
$uh = new UrlHelper("imgix-library-secure-test-source.imgix.net", "dog.jpg", "https", "EHFQXiZhxP4wA2c4");
$uh->setParameter("w", 500);
echo $uh->getURL();
// 'https://imgix-library-secure-test-source.imgix.net/dog.jpg?w=500&s=e4eb402d12bbdf267bf0fc5588170d56'
```

--------------------------------

### setUseHttps example

Source: https://github.com/imgix/imgix-php/blob/main/_autodocs/api-reference/UrlBuilder.md

Example usage of setUseHttps with a UrlBuilder instance, generating a URL with the http scheme.

```php
$builder = new UrlBuilder("demos.imgix.net");
$builder->setUseHttps(false);
echo $builder->createURL("bridge.png", ["w" => 100]);
// 'http://demos.imgix.net/bridge.png?w=100...'
```

--------------------------------

### validateWidths error handling example

Source: https://github.com/imgix/imgix-php/blob/main/_autodocs/api-reference/Validator.md

Error handling example demonstrating exceptions for negative values and null input.

```php
try {
    Validator::validateWidths([0, -1, 100]);
} catch (InvalidArgumentException $e) {
    // 'width values in `widths` cannot be negative'
}
try {
    Validator::validateWidths(null);
} catch (InvalidArgumentException $e) {
    // "`widths` array cannot be `null`"
}
```

--------------------------------

### Basic formatPath example

Source: https://github.com/imgix/imgix-php/blob/main/_autodocs/api-reference/UrlHelper.md

Shows basic usage of formatPath with a plain path containing a non-ASCII character. The output demonstrates percent-encoding of 'ü' to '%C3%BC'.

```php
use Imgix\UrlHelper;

$uh = new UrlHelper("test.imgix.net", "images/püg.jpg");
echo $uh->formatPath("images/püg.jpg");
// '/images/p%C3%BCg.jpg'
```

--------------------------------

### validateTolerance usage example

Source: https://github.com/imgix/imgix-php/blob/main/_autodocs/api-reference/Validator.md

Example showing a valid tolerance (0.08) and an invalid one (0.001) that throws an exception.

```php
Validator::validateTolerance(0.08);            // ok (library default)
try { Validator::validateTolerance(0.001); } catch (InvalidArgumentException $e) { /* ... */ }
```

--------------------------------

### validateMinMaxTol usage example

Source: https://github.com/imgix/imgix-php/blob/main/_autodocs/api-reference/Validator.md

Example of a full-range validation: a valid call and an invalid tolerance that throws an exception.

```php
Validator::validateMinMaxTol(100, 2000, 0.08); // ok
try { Validator::validateMinMaxTol(100, 2000, 0.005); } catch (InvalidArgumentException $e) { /* tol error */ }
```

--------------------------------

### targetWidths validation error example

Source: https://github.com/imgix/imgix-php/blob/main/_autodocs/api-reference/UrlBuilder.md

Example of a validation error when start is greater than stop. It catches the InvalidArgumentException and shows the error message.

```php
$builder = new UrlBuilder("demos.imgix.net");
try {
    $builder->targetWidths(400, 100); // start > stop
} catch (InvalidArgumentException $e) {
    // '`start` width value must be less than `stop` width value'
}
```

--------------------------------

### Basic targetWidths example

Source: https://github.com/imgix/imgix-php/blob/main/_autodocs/api-reference/UrlBuilder.md

Basic usage of targetWidths. It returns an ascending list of target pixel widths from 100 to 384 with a tolerance of 0.20, producing the commented output.

```php
$builder = new UrlBuilder("demos.imgix.net");
$builder->targetWidths(100, 384, 0.20);
// [100, 140, 196, 274, 384]
```

--------------------------------

### Basic UrlBuilder usage

Source: https://github.com/imgix/imgix-php/blob/main/_autodocs/api-reference/UrlBuilder.md

Basic usage example: creates a UrlBuilder with a valid domain, disables the ixlib parameter, and generates a URL with width and height parameters. Output is shown in the comment.

```php
use Imgix\UrlBuilder;

$builder = new UrlBuilder("demos.imgix.net"); // https, unsigned, ixlib on
$builder->setIncludeLibraryParam(false);
echo $builder->createURL("bridge.png", ["w" => 100, "h" => 100]);
// 'https://demos.imgix.net/bridge.png?h=100&w=100'
```

--------------------------------

### validateMinWidth usage example

Source: https://github.com/imgix/imgix-php/blob/main/_autodocs/api-reference/Validator.md

Example calls to validateMinWidth: a valid positive value and an invalid negative value caught with try/catch.

```php
Validator::validateMinWidth(100);   // ok
try { Validator::validateMinWidth(-1); } catch (InvalidArgumentException $e) { /* ... */ }
```

--------------------------------

### deleteParameter example

Source: https://github.com/imgix/imgix-php/blob/main/_autodocs/api-reference/UrlHelper.md

Sets a parameter, deletes it, and outputs the URL without the 'w' parameter.

```php
$uh->setParameter("w", 500);
$uh->deleteParameter("w");
echo $uh->getURL();
// 'https://imgix-library-secure-test-source.imgix.net/dog.jpg?s=...'
```

--------------------------------

### validateMaxWidth usage example

Source: https://github.com/imgix/imgix-php/blob/main/_autodocs/api-reference/Validator.md

Example calls to validateMaxWidth: a valid positive value and an invalid negative value caught with try/catch.

```php
Validator::validateMaxWidth(8192);  // ok
try { Validator::validateMaxWidth(-5); } catch (InvalidArgumentException $e) { /* ... */ }
```

--------------------------------

### Create srcset with width range using start and stop options

Source: https://github.com/imgix/imgix-php/blob/main/README.md

Limit the minimum and maximum widths of a non-fixed srcset by specifying 'start' and 'stop' in the options array. The output shows the generated srcset attribute with widths ranging from 500 to 2000 pixels.

```php
$builder = new UrlBuilder("demo.imgix.net", true, "", false);
$opts = array('start' => 500, 'stop' => 2000);
$srcset = $builder->createSrcSet($path="image.jpg", $params=array(), $options=$opts);
```

```html
https://demo.imgix.net/image.jpg?w=500 500w,
https://demo.imgix.net/image.jpg?w=580 580w,
https://demo.imgix.net/image.jpg?w=673 673w,
https://demo.imgix.net/image.jpg?w=780 780w,
https://demo.imgix.net/image.jpg?w=905 905w,
https://demo.imgix.net/image.jpg?w=1050 1050w,
https://demo.imgix.net/image.jpg?w=1218 1218w,
https://demo.imgix.net/image.jpg?w=1413 1413w,
https://demo.imgix.net/image.jpg?w=1639 1639w,
https://demo.imgix.net/image.jpg?w=1901 1901w,
https://demo.imgix.net/image.jpg?w=2000 2000w
```

--------------------------------

### Fluid-width srcset with custom range and tolerance

Source: https://github.com/imgix/imgix-php/blob/main/_autodocs/api-reference/UrlBuilder.md

Creates a fluid-width srcset with explicit start, stop, and tolerance values. The output shows the generated width descriptors.

```php
$builder = new UrlBuilder("demo.imgix.net", true, "", false);
echo $builder->createSrcSet("image.jpg", [], ["start" => 100, "stop" => 384, "tol" => 0.20]);
// https://demo.imgix.net/image.jpg?w=100 100w,
// https://demo.imgix.net/image.jpg?w=140 140w,
// https://demo.imgix.net/image.jpg?w=196 196w,
// https://demo.imgix.net/image.jpg?w=274 274w,
// https://demo.imgix.net/image.jpg?w=384 384w
```

--------------------------------

### validateRange failure example

Source: https://github.com/imgix/imgix-php/blob/main/_autodocs/api-reference/Validator.md

Example of a validation failure where $begin is greater than $end, causing an InvalidArgumentException to be thrown.

```php
$begin = 400;
$end = 100;
try {
    Validator::validateRange($begin, $end);
} catch (InvalidArgumentException $e) {
    // '`start` width value must be less than `stop` width value'
}
```

--------------------------------

### targetWidths method signature

Source: https://github.com/imgix/imgix-php/blob/main/_autodocs/api-reference/UrlBuilder.md

Signature of the targetWidths method. It accepts optional start, stop, and tolerance parameters with defaults MIN_WIDTH (100), MAX_WIDTH (8192), and SRCSET_WIDTH_TOLERANCE (0.08).

```php
public function targetWidths(
    $start=self::MIN_WIDTH,
    $stop=self::MAX_WIDTH,
    $tol=self::SRCSET_WIDTH_TOLERANCE
)
```

--------------------------------

### Create srcset with custom width tolerance using tol option

Source: https://github.com/imgix/imgix-php/blob/main/README.md

Set a custom width tolerance by providing a positive scalar value as 'tol' in the options array. The example sets tolerance to 20 percent, which is reflected in the difference between subsequent widths in the srcset pair. The default tolerance is 8 percent.

```php
$builder = new UrlBuilder("demo.imgix.net", true, "", false);
$opts = array('start' => 100, 'stop' => 384, 'tol' => 0.20);
$srcset = $builder->createSrcSet($path="image.jpg", $params=array(), $options=$opts);
```

```html
https://demo.imgix.net/image.jpg?w=100 100w,
https://demo.imgix.net/image.jpg?w=140 140w,
https://demo.imgix.net/image.jpg?w=196 196w,
https://demo.imgix.net/image.jpg?w=274 274w,
https://demo.imgix.net/image.jpg?w=384 384w
```

--------------------------------

### validateRange exception message

Source: https://github.com/imgix/imgix-php/blob/main/_autodocs/api-reference/Validator.md

Exception message thrown when the start width is greater than the stop width.

```text
\InvalidArgumentException: '`start` width value must be less than `stop` width value'
```

--------------------------------

### UrlBuilder error handling

Source: https://github.com/imgix/imgix-php/blob/main/_autodocs/api-reference/UrlBuilder.md

Error handling example: passing a domain with a protocol triggers an InvalidArgumentException. The catch block shows the exact error message.

```php
use Imgix\UrlBuilder;

try {
    $builder = new UrlBuilder("https://demos.imgix.net"); // protocol is not allowed
} catch (InvalidArgumentException $e) {
    // 'Domain must be passed in as fully-qualified domain name and should not
    //  include a protocol or any path element, i.e. "example.imgix.net".'
}
```

--------------------------------

### validateMinWidth error message

Source: https://github.com/imgix/imgix-php/blob/main/_autodocs/api-reference/Validator.md

The exact error message thrown when the start width is less than zero.

```text
\InvalidArgumentException: '`start` width value must be greater than zero'
```

--------------------------------

### validateRange signature

Source: https://github.com/imgix/imgix-php/blob/main/_autodocs/api-reference/Validator.md

Signature of the static method that validates a width range. It runs validateMinWidth($start) then validateMaxWidth($stop) and throws an InvalidArgumentException if $start > $stop.

```php
public static function validateRange($start, $stop)
```

--------------------------------

### createURL method signature

Source: https://github.com/imgix/imgix-php/blob/main/_autodocs/api-reference/UrlBuilder.md

Creates a full imgix URL for the given path and rendering parameters. Internally adds ixlib unless disabled, and uses UrlHelper to build the URL.

```php
public function createURL($path, $params = [])
```

--------------------------------

### UrlHelper Constructor and Methods

Source: https://github.com/imgix/imgix-php/blob/main/_autodocs/configuration.md

Documentation for the UrlHelper class constructor and its per-call configuration methods.

```APIDOC
## Constructor: `new UrlHelper($domain, $path, $scheme = 'http', $signKey = '', $params = [])`

### Description
Instantiates a `UrlHelper` object for low-level URL assembly. It is used internally by `UrlBuilder::createURL` but can be used directly.

### Method
Constructor

### Parameters
- **$domain** (string) - Required - imgix source domain (not validated by UrlHelper).
- **$path** (string) - Required - Raw path or full URL; normalized by `formatPath` during construction.
- **$scheme** (string) - Optional, default `'http'` - `'http'` or `'https'`.
- **$signKey** (string) - Optional, default `''` - Signature key; empty disables signing.
- **$params** (array) - Optional, default `[]` - Initial query parameters (associative array).

### Request Example
```php
$urlHelper = new UrlHelper('mysource.imgix.net', '/images/example.png', 'https', 'mySignKey', ['w' => 100]);
```

### Response
Returns a `UrlHelper` instance.

## Method: `setParameter($key, $value)`

### Description
Sets, overwrites, or removes a query parameter. Falsy values except `0` remove the parameter.

### Method
setParameter

### Parameters
- **$key** (string) - Required - The parameter name.
- **$value** (mixed) - Required - The parameter value. Falsy values except `0` remove the parameter.

### Request Example
```php
$urlHelper->setParameter('w', 200);
```

### Response
No return value specified.

## Method: `deleteParameter($key)`

### Description
Removes a query parameter unconditionally.

### Method
deleteParameter

### Parameters
- **$key** (string) - Required - The parameter name to remove.

### Request Example
```php
$urlHelper->deleteParameter('w');
```

### Response
No return value specified.
```

--------------------------------

### Create a basic imgix URL with UrlBuilder

Source: https://github.com/imgix/imgix-php/blob/main/README.md

Creates an imgix URL with query parameters. HTTPS is enabled by default.

```php
use Imgix\UrlBuilder;

$builder = new UrlBuilder("demos.imgix.net");
$params = array("w" => 100, "h" => 100);
echo $builder->createURL("bridge.png", $params);
// 'https://demos.imgix.net/bridge.png?h=100&w=100'
```

--------------------------------

### formatPath full URL and edge cases

Source: https://github.com/imgix/imgix-php/blob/main/_autodocs/api-reference/UrlHelper.md

Demonstrates formatPath with an empty path and full URLs. Empty input returns '/', and full URLs are percent-encoded entirely, including the protocol and host.

```php
$uh = new UrlHelper("test.imgix.net", "");
echo $uh->formatPath("");                                // '/'
echo $uh->formatPath("http://mywebsite.com/images/dog.jpg");
// '/http%3A%2F%2Fmywebsite.com%2Fimages%2Fdog.jpg'
echo $uh->formatPath("/http://mywebsite.com/images/dog.jpg");
// '/http%3A%2F%2Fmywebsite.com%2Fimages%2Fdog.jpg'
```

--------------------------------

### Generate a signed URL with setSignKey()

Source: https://github.com/imgix/imgix-php/blob/main/README.md

Produces a signed URL by providing the signature key via setSignKey(). Requires secure URLs enabled on the source.

```php
use Imgix\UrlBuilder;

$builder = new UrlBuilder("demos.imgix.net");
$builder->setSignKey("test1234");
$params = array("w" => 100, "h" => 100);
echo $builder->createURL("bridge.png", $params);
// 'http://demos.imgix.net/bridge.png?h=100&w=100&s=bb8f3a2ab832e35997456823272103a4'
```

--------------------------------

### __construct

Source: https://github.com/imgix/imgix-php/blob/main/_autodocs/api-reference/UrlBuilder.md

Creates a new UrlBuilder instance for generating imgix image URLs.

```APIDOC
## `__construct`

```php
public function __construct($domain, $useHttps = true, $signKey = '', $includeLibraryParam = true)
```

Source: `src/UrlBuilder.php:34-46`.

### Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `$domain` | string | yes | — | Fully-qualified imgix source domain, e.g. `"demos.imgix.net"`. Must not include protocol or path elements. |
| `$useHttps` | bool | no | `true` | Whether generated URLs use the `https` scheme |
| `$signKey` | string | no | `''` | Secure-URL signature key (empty = unsigned URLs) |
| `$includeLibraryParam` | bool | no | `true` | Whether to append the `ixlib` diagnostic parameter |

### Throws

| Error | Condition |
|-------|-----------|
| `\InvalidArgumentException` | `$domain` is not a string → message `'UrlBuilder must be passed a string domain'` (`src/UrlBuilder.php:37`) |
| `\InvalidArgumentException` | `$domain` fails the FQDN pattern → message `'Domain must be passed in as fully-qualified domain name and should not include a protocol or any path element, i.e. "example.imgix.net".'` (`src/UrlBuilder.php:53`) |

### Example — basic

```php
use Imgix\UrlBuilder;

$builder = new UrlBuilder("demos.imgix.net"); // https, unsigned, ixlib on
$builder->setIncludeLibraryParam(false);
echo $builder->createURL("bridge.png", ["w" => 100, "h" => 100]);
// 'https://demos.imgix.net/bridge.png?h=100&w=100'
```

### Example — error handling

```php
use Imgix\UrlBuilder;

try {
    $builder = new UrlBuilder("https://demos.imgix.net"); // protocol is not allowed
} catch (InvalidArgumentException $e) {
    // 'Domain must be passed in as fully-qualified domain name and should not
    //  include a protocol or any path element, i.e. "example.imgix.net".'
}
```
```

--------------------------------

### Run unit tests with PHPUnit

Source: https://github.com/imgix/imgix-php/blob/main/CONTRIBUTING.md

Runs the unit test suite using PHPUnit.

```bash
./vendor/bin/phpunit
```

--------------------------------

### Git workflow for contributing to imgix-php

Source: https://github.com/imgix/imgix-php/blob/main/CONTRIBUTING.md

Step-by-step Git workflow for contributing to the imgix-php project: clone the fork, sync with upstream, create a topic branch, merge/rebase upstream changes, and push the branch to your fork.

```bash
# Clone your fork of the repo into the current directory
git clone git@github.com:<YOUR_USERNAME>/imgix-php.git
# Navigate to the newly cloned directory
cd imgix-php
# Assign the original repo to a remote called "upstream"
git remote add upstream https://github.com/imgix/imgix-php
```

```bash
git checkout <dev-branch>
git pull upstream <dev-branch>
```

```bash
git checkout -b <topic-branch-name>
```

```bash
git pull [--rebase] upstream <dev-branch>
```

```bash
git push origin <topic-branch-name>
```

--------------------------------

### Fluid-width srcset with defaults

Source: https://github.com/imgix/imgix-php/blob/main/_autodocs/api-reference/UrlBuilder.md

Creates a fluid-width srcset with default options. The output is a comma-and-newline separated list of URLs with width descriptors.

```php
$builder = new UrlBuilder("demos.imgix.net", true, "my-key", false);
echo $builder->createSrcSet("image.png");
// https://demos.imgix.net/image.png?w=100&s=... 100w,
// https://demos.imgix.net/image.png?w=116&s=... 116w,
// ... up to ...w=8192 8192w
```

--------------------------------

### Import Imgix classes

Source: https://github.com/imgix/imgix-php/blob/main/_autodocs/index.md

Import the three public classes from the Imgix namespace. Required before using the library's URL generation and validation features.

```php
use Imgix\UrlBuilder;
use Imgix\UrlHelper;
use Imgix\Validator;
```

--------------------------------

### UrlBuilder::createSrcSet Options

Source: https://github.com/imgix/imgix-php/blob/main/_autodocs/configuration.md

Documentation for the `UrlBuilder::createSrcSet` method options and parameters.

```APIDOC
## `UrlBuilder::createSrcSet` Options

### Description
Creates a srcset string for responsive images. The `$options` array controls target-width generation.

### Method
`createSrcSet($path, $params = [], $options = [])`

### Parameters
#### Path Parameters
- **$path** (string) - Required - The image path.

#### Query Parameters
- **$params** (array) - Optional - Image parameters passed to the imgix CDN.

#### Request Body
- **$options** (array) - Optional - Options controlling target-width generation.

### Options
| Key | Type | Required | Default | Description |
|-----|------|----------|---------|-------------|
| `widths` | int[] | no | — | Explicit list of target widths. Takes precedence over `start`/`stop`/`tol`. Validated by `Validator::validateWidths`. When present, `w=<width> ...w` pairs are generated for exactly these widths. **Note:** per README, custom `widths` are ignored in fixed-width (DPR) mode. |
| `start` | int | no | `self::MIN_WIDTH` = `100` | Starting (minimum) target width for fluid-width srcsets |
| `stop` | int | no | `self::MAX_WIDTH` = `8192` | Stopping (maximum) target width, inclusive |
| `tol` | number | no | `self::SRCSET_WIDTH_TOLERANCE` = `0.08` | Width tolerance — each successive width grows by `1 + tol * 2`. Minimum allowed value `0.01` (`Validator::ONE_PERCENT`). |
| `disableVariableQuality` | bool | no | `false` | In DPR (fixed-width) mode, suppress automatic `q` quality params. A `q` value passed in `$params` always wins, regardless of this flag. |

### `$params` (used by both `createURL` and `createSrcSet`)
| Key | Type | Description |
|-----|------|-------------|
| `w` | number/string | Image width. Truthy `w` or `h` switches `createSrcSet` into DPR mode (`isDpr`, `src/UrlBuilder.php:162`). |
| `h` | number/string | Image height. Same DPR-mode trigger as `w`. |
| `q` | number | Quality override — when present, `createDPRSrcSet` never injects variable-quality values (`src/UrlBuilder.php:188`). |
| `ar`, `fit`, `auto`, `txt64`, any other | mixed | Passed through to the imgix CDN as query params. Keys ending in `64` get URL-safe base64 values; array values are comma-flattened. |
| `ixlib` | string | Injected as `php-<version>` by `createURL` when `includeLibraryParam` is true (overwrites any user-supplied `ixlib`). |

### Value-encoding rules (apply to every query param)
| Value shape | Encoding |
|-------------|----------|
| scalar | `rawurlencode(val)` |
| array | `rawurlencode(implode(',', val))` — comma-joined |
| key ending in `"64"` | URL-safe base64, no padding (`+`/`/` → `-`/`_`, `=` stripped) |
| key | always `rawurlencode`d |
```

--------------------------------

### createURL

Source: https://github.com/imgix/imgix-php/blob/main/_autodocs/api-reference/UrlBuilder.md

Generates a full imgix URL for the given image path and rendering parameters.

```APIDOC
## `createURL`

### Description
Generates a full imgix URL for the given image path and rendering parameters.

### Method
`createURL`

### Parameters
- `$path` (string) - Required - Image path or fully-qualified remote URL (e.g. `"bridge.png"` or `"http://media.giphy.com/.../giphy.gif"`). Encoding handled by `UrlHelper::formatPath`.
- `$params` (array assoc) - Optional - Default `[]` - imgix rendering params keyed by param name, e.g. `["w" => 100, "h" => 100, "auto" => ["compress", "format"]]`. Array values are flattened with commas.

### Returns
`string` — a full imgix URL, e.g. `https://demos.imgix.net/bridge.png?h=100&w=100`. If a sign key is configured the URL ends with `&s=<md5>` / `?s=<md5>`.

### Behavior
- Internally adds `ixlib=php-<currentVersion>` to `$params` unless `includeLibraryParam` is `false`.
- Instantiates `new UrlHelper($this->domain, $path, $scheme, $this->signKey, $params)` where `$scheme` is `'https'` or `'http'` per `useHttps`, and returns `$uh->getURL()`.

### Example — basic
```php
$builder = new UrlBuilder("demos.imgix.net", true, "", false);
echo $builder->createURL("bridge.png", ["w" => 100, "h" => 100]);
// 'https://demos.imgix.net/bridge.png?h=100&w=100'
```

### Example — nested-array param and signing
```php
$builder = new UrlBuilder("demos.imgix.net", true, "test1234", false);
echo $builder->createURL("bridge.png", ["auto" => ["compress", "format"], "w" => 100]);
// 'https://demos.imgix.net/bridge.png?auto=compress%2Cformat&w=100&s=...'
```
```

--------------------------------

### getURL

Source: https://github.com/imgix/imgix-php/blob/main/_autodocs/api-reference/UrlHelper.md

Builds and returns the final imgix URL, including query parameters and optional signing.

```APIDOC
## `getURL`

### Description
Builds and returns the final imgix URL, including query parameters and optional signing.

### Method
`getURL`

### Signature
`public function getURL()`

### Returns
`string` — the final imgix URL. Example: `http://.../dog.jpg?w=500&s=e4eb402d12bbdf267bf0fc5588170d56`.

### Behavior
1. **Query assembly** — if `$params` is non-empty, keys are sorted (`ksort`), then for each `key => val`:
   - key string ending in `'64'` (e.g. `txt64`) → value is URL-safe base64-encoded without padding (`base64url_encode`).
   - array value → `rawurlencode(implode(',', val))` (flattened with commas, e.g. `["compress","format"]` → `compress%2Cformat`).
   - other values → `rawurlencode(val)`.
   - keys are always `rawurlencode`d.
   - Pairs joined with `&`, prefixed with `?` if non-empty.
2. **Signing** — if `$signKey` is truthy: `$toSign = $signKey . $path . $query`, `$sig = md5($toSign)`; appended as `&s=<sig>` (or `?s=<sig>` when there is no query).
3. **Join** — returns `scheme://host/path?query` (`joinURL`).

### Example — basic (signed, setter-added params)
```php
$uh = new UrlHelper("imgix-library-secure-test-source.imgix.net", "dog.jpg", "http", "EHFQXiZhxP4wA2c4", ["w" => 500]);
echo $uh->getURL();
// 'http://imgix-library-secure-test-source.imgix.net/dog.jpg?w=500&s=e4eb402d12bbdf267bf0fc5588170d56'
```

### Example — base64 param key variant and unsigned URL
```php
$uh = new UrlHelper("demo.imgix.net", "~text", "https", "", ["txt64" => "I cannøt belîév∑ it wors! 😱"]);
echo $uh->getURL();
// 'https://demo.imgix.net/~text?txt64=SSBjYW5uw7h0IGJlbMOuw6l24oiRIGl0IHdvcu-jv3MhIPCfmLE'
```
```

--------------------------------

### targetWidths

Source: https://github.com/imgix/imgix-php/blob/main/_autodocs/api-reference/UrlBuilder.md

Documentation for the targetWidths method of the UrlBuilder class, which generates a list of target pixel widths for responsive images.

```APIDOC
## `targetWidths`

### Description
Generates an ascending list of target pixel widths for use in responsive image srcset attributes. The widths are calculated iteratively from a start value to a stop value using a tolerance multiplier.

### Method
`targetWidths`

### Signature
```php
public function targetWidths(
    $start=self::MIN_WIDTH,
    $stop=self::MAX_WIDTH,
    $tol=self::SRCSET_WIDTH_TOLERANCE
)
```

### Parameters
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `$start` | int | no | `self::MIN_WIDTH` (100) | Minimum target width, inclusive |
| `$stop` | int | no | `self::MAX_WIDTH` (8192) | Maximum target width, inclusive |
| `$tol` | number | no | `self::SRCSET_WIDTH_TOLERANCE` (0.08) | Tolerance multiplier; each generated width grows by `1 + tol * 2` |

### Behavior
- If `$start === $stop`, returns `[(int) $start]` immediately without validation.
- Otherwise validates via `Validator::validateMinMaxTol($start, $stop, $tol)`.
- Iteratively appends `round($start)` then sets `$start *= 1 + $tol * 2`, stopping once `$start >= $stop` or `$start >= self::MAX_WIDTH`.
- If the last value is still below `$stop`, appends `(int) $stop` to make the stop value inclusive.

### Returns
`int[]` — ascending list of target pixel widths beginning with `$start` and ending with `$stop`.

### Example — basic
```php
$builder = new UrlBuilder("demos.imgix.net");
$builder->targetWidths(100, 384, 0.20);
// [100, 140, 196, 274, 384]
```

### Example — validation error
```php
$builder = new UrlBuilder("demos.imgix.net");
try {
    $builder->targetWidths(400, 100); // start > stop
} catch (InvalidArgumentException $e) {
    // '`start` width value must be less than `stop` width value'
}
```

### Throws
| Error | Condition |
|-------|-----------|
| `\InvalidArgumentException` | `$start < 0` → `` '`start` width value must be greater than zero' `` |
| `\InvalidArgumentException` | `$stop < 0` → `` '`stop` width value must be greater than zero' `` |
| `\InvalidArgumentException` | `$start > $stop` → `` '`start` width value must be less than `stop` width value' `` |
| `\InvalidArgumentException` | `$tol < 0.01` → `` '`tol`erance value must be greater than, or equal to one percent, ie. >= 0.01' `` |
```

--------------------------------

### setIncludeLibraryParam method signature

Source: https://github.com/imgix/imgix-php/blob/main/_autodocs/api-reference/UrlBuilder.md

Controls the ixlib=php-<version> diagnostic query parameter appended by createURL. Setting false omits ixlib from generated URLs.

```php
public function setIncludeLibraryParam($includeLibraryParam)
```

--------------------------------

### formatPath

Source: https://github.com/imgix/imgix-php/blob/main/_autodocs/api-reference/UrlHelper.md

Documentation for the formatPath method of the UrlHelper class.

```APIDOC
## `formatPath`

```php
public function formatPath($path)
```

### Description
Formats a raw image path or fully-qualified URL into a normalized, percent-encoded path with a leading slash. It handles three cases: full URLs, already-encoded URLs, and plain paths, applying appropriate encoding rules for each.

### Method
`formatPath`

### Parameters
- **$path** (string) - Required - Raw image path or fully-qualified URL

### Behavior
1. If `$path` is not a string or its length is less than 1 → returns `'/'`.
2. Strips one leading `/`.
3. **Full-URL branch** — if the path matches `^https?://`, the entire string is passed through `rawurlencode` (the protocol, host and query get percent-encoded).
4. **Encoded-URL branch** — else, if the rawurl-decoded path matches `^https?://[^\s\/$.?#]*\.[^\s]*$` (Stephenhay's URL regex, cf. mathiasbynens.be/demo/url-regex), only characters outside `[\w\-\/\:@%]` are percent-encoded.
5. **Plain-path branch** — otherwise, only characters outside `[\w\-\/\:@]` are percent-encoded (e.g. spaces ` ` → `%20`, `ü` → `%C3%BC`; `/`, `:`, `@`, `-`, `_`, `.` and letters/digits remain raw).
6. Prepends `/` and returns.

### Returns
`string` — a normalized, percent-encoded path with a leading `/`.

### Example — basic
```php
use Imgix\UrlHelper;

$uh = new UrlHelper("test.imgix.net", "images/püg.jpg");
echo $uh->formatPath("images/püg.jpg");
// '/images/p%C3%BCg.jpg'
```

### Example — full URL and edge cases
```php
$uh = new UrlHelper("test.imgix.net", "");
echo $uh->formatPath("");                                // '/'
echo $uh->formatPath("http://mywebsite.com/images/dog.jpg");
// '/http%3A%2F%2Fmywebsite.com%2Fimages%2Fdog.jpg'
echo $uh->formatPath("/http://mywebsite.com/images/dog.jpg");
// '/http%3A%2F%2Fmywebsite.com%2Fimages%2Fdog.jpg'
```

Note: percent signs in already-encoded input are re-encoded (`p%C3%BCg.jpg` → `p%25C3%25BCg.jpg`) in the full-URL branch; the encoded-URL branch preserves valid `%XX` sequences for plain paths.
```

--------------------------------

### UrlBuilder constructor signature

Source: https://github.com/imgix/imgix-php/blob/main/_autodocs/api-reference/UrlBuilder.md

Constructor signature for UrlBuilder. Accepts a fully-qualified imgix source domain, optional HTTPS flag, signature key, and library parameter flag. Throws InvalidArgumentException for invalid domain.

```php
public function __construct($domain, $useHttps = true, $signKey = '', $includeLibraryParam = true)
```

--------------------------------

### getURL base64 param key variant and unsigned URL

Source: https://github.com/imgix/imgix-php/blob/main/_autodocs/api-reference/UrlHelper.md

Uses a 'txt64' parameter to demonstrate base64 encoding of the value, and an empty sign key to produce an unsigned URL.

```php
$uh = new UrlHelper("demo.imgix.net", "~text", "https", "", ["txt64" => "I cannøt belîév∑ it wors! 😱"]);
echo $uh->getURL();
// 'https://demo.imgix.net/~text?txt64=SSBjYW5uw7h0IGJlbMOuw6l24oiRIGl0IHdvcu-jv3MhIPCfmLE'
```

--------------------------------

### setIncludeLibraryParam

Source: https://github.com/imgix/imgix-php/blob/main/_autodocs/api-reference/UrlBuilder.md

Controls the `ixlib=php-<version>` diagnostic query parameter appended by `createURL`.

```APIDOC
## `setIncludeLibraryParam`

### Description
Controls the `ixlib=php-<version>` diagnostic query parameter appended by `createURL`.

### Method
`setIncludeLibraryParam`

### Parameters
- `$includeLibraryParam` (bool) - Required - `false` omits `ixlib` from generated URLs

### Returns
`void`
```

--------------------------------

### Update dependencies with Composer

Source: https://github.com/imgix/imgix-php/blob/main/CONTRIBUTING.md

Updates project dependencies using Composer.

```bash
php composer.phar u
```

--------------------------------

### setParameter removal and zero handling

Source: https://github.com/imgix/imgix-php/blob/main/_autodocs/api-reference/UrlHelper.md

Shows that setting a parameter to 0 keeps it, while setting it to null removes it.

```php
$uh->setParameter("w", 0);       // 0 === 0 → parameter kept
$uh->setParameter("w", null);    // falsy, not 0 → parameter removed
```

--------------------------------

### getURL method signature

Source: https://github.com/imgix/imgix-php/blob/main/_autodocs/api-reference/UrlHelper.md

Declares the getURL method. It assembles the query string, signs it if a sign key is set, and returns the final URL.

```php
public function getURL()
```

--------------------------------

### Generate fixed-width srcset with height parameter

Source: https://github.com/imgix/imgix-php/blob/main/README.md

Creates a fixed-width srcset by providing a height parameter. The output includes DPR values from 1x to 5x with signed URLs when a key is provided.

```php
$builder = new UrlBuilder("demos.imgix.net", true, "my-key", false);
echo $builder->createSrcSet("image.png", array("h"=>800, "ar"=>"3:2", "fit"=>"crop"));
```

```html
https://demos.imgix.net/image.png?ar=3%3A2&dpr=1&fit=crop&h=800&s=6cf5c443d1eb98bc3d96ea569fcef088 1x,
https://demos.imgix.net/image.png?ar=3%3A2&dpr=2&fit=crop&h=800&s=d60a61a5f34545922bd8dff4e53a0555 2x,
https://demos.imgix.net/image.png?ar=3%3A2&dpr=3&fit=crop&h=800&s=590f96aa426f8589eb7e449ebbeb66e7 3x,
https://demos.imgix.net/image.png?ar=3%3A2&dpr=4&fit=crop&h=800&s=c89c2fd3148957647e86cfc32ba20517 4x,
https://demos.imgix.net/image.png?ar=3%3A2&dpr=5&fit=crop&h=800&s=3d73af69d78d49eef0f81b4b5d718a2c 5x
```

--------------------------------

### setSignKey method signature

Source: https://github.com/imgix/imgix-php/blob/main/_autodocs/api-reference/UrlBuilder.md

Replaces the signature key; all subsequently generated URLs become signed with the new key. An empty key disables signing.

```php
public function setSignKey($key)
```

--------------------------------

### setSignKey

Source: https://github.com/imgix/imgix-php/blob/main/_autodocs/api-reference/UrlBuilder.md

Replaces the signature key; all subsequently generated URLs become signed with the new key. An empty key disables signing.

```APIDOC
## `setSignKey`

### Description
Replaces the signature key; all subsequently generated URLs become signed with the new key. An empty key disables signing.

### Method
`setSignKey`

### Parameters
- `$key` (string) - Required - MD5 signature key (from the imgix secure-source settings)

### Returns
`void`
```

--------------------------------

### Class constant ONE_PERCENT

Source: https://github.com/imgix/imgix-php/blob/main/_autodocs/api-reference/Validator.md

Defines the minimum acceptable tolerance value (0.01). Any tolerance strictly below this is rejected by validateTolerance and validateMinMaxTol.

```php
public const ONE_PERCENT = 0.01;
```

--------------------------------

### Exception message for empty widths

Source: https://github.com/imgix/imgix-php/blob/main/_autodocs/api-reference/Validator.md

Exception message thrown when $widths is an empty array.

```text
\InvalidArgumentException: "`widths` array cannot be empty"
```

--------------------------------

### Generate a srcset with createSrcSet()

Source: https://github.com/imgix/imgix-php/blob/main/README.md

Generates a srcset attribute for responsive image width mappings. The output is a comma-separated list of URLs with width descriptors.

```php
$builder = new UrlBuilder("demos.imgix.net", true, "my-key", false);
echo $builder->createSrcSet("image.png");
```

```html
https://demos.imgix.net/image.png?w=100&s=e415797545a77a9d2842dedcfe539c9a 100w,
https://demos.imgix.net/image.png?w=116&s=b2da46f5c23ef13d5da30f0a4545f33f 116w,
https://demos.imgix.net/image.png?w=135&s=b61422dead929f893c04b8ff839bb088 135w,
                                        ...
https://demos.imgix.net/image.png?w=7401&s=ad671301ed4663c3ce6e84cb646acb96 7401w,
https://demos.imgix.net/image.png?w=8192&s=a0fed46e2bbcc70ded13dc629aee5398 8192w
```

--------------------------------

### Generate HTTP URLs with setUseHttps(false)

Source: https://github.com/imgix/imgix-php/blob/main/README.md

Disables HTTPS on the URL builder to generate HTTP URLs. Call setUseHttps(false) on the builder.

```php
use Imgix\UrlBuilder;

$builder = new UrlBuilder("demos.imgix.net");
$builder->setUseHttps(false);
$params = array("w" => 100, "h" => 100);
echo $builder->createURL("bridge.png", $params);
// 'http://demos.imgix.net/bridge.png?h=100&w=100'
```

--------------------------------

### setParameter

Source: https://github.com/imgix/imgix-php/blob/main/_autodocs/api-reference/UrlHelper.md

Sets a single imgix URL parameter on the URL helper instance. Falsy values other than `0` cause the parameter to be removed.

```APIDOC
## `setParameter`

### Description
Sets a single imgix URL parameter on the URL helper instance. Falsy values other than `0` cause the parameter to be removed.

### Method
`setParameter`

### Signature
`public function setParameter($key, $value)`

### Parameters
- `$key` (string) - Required - Parameter name
- `$value` (mixed) - Required - Parameter value. Falsy values other than `0` cause the parameter to be removed.

### Behavior
- If `$key` is truthy **and** (`$value` is truthy **or** `$value === 0`) → sets `$this->params[$key] = $value`.
- Otherwise (null, empty string, false, missing key) → removes param `$key` if it exists.

### Example
```php
$uh = new UrlHelper("imgix-library-secure-test-source.imgix.net", "dog.jpg", "https", "EHFQXiZhxP4wA2c4");
$uh->setParameter("w", 500);
echo $uh->getURL();
// 'https://imgix-library-secure-test-source.imgix.net/dog.jpg?w=500&s=e4eb402d12bbdf267bf0fc5588170d56'
```

### Example — removal and zero handling
```php
$uh->setParameter("w", 0);       // 0 === 0 → parameter kept
$uh->setParameter("w", null);    // falsy, not 0 → parameter removed
```
```

--------------------------------

### UrlBuilder class constants

Source: https://github.com/imgix/imgix-php/blob/main/_autodocs/api-reference/UrlBuilder.md

Defines the default target widths, DPR ratios, DPR qualities, minimum and maximum widths, and srcset width tolerance used by UrlBuilder for generating srcsets.

```php
public const TARGET_WIDTHS = [
    100, 116, 134, 156, 182, 210, 244, 282,
    328, 380, 442, 512, 594, 688, 798, 926,
    1074, 1246, 1446, 1678, 1946, 2258, 2618,
    3038, 3524, 4088, 4742, 5500, 6380, 7400, 8192];

public const TARGET_RATIOS = [1, 2, 3, 4, 5];

public const DPR_QUALITIES = [1 => 75, 2 => 50, 3 => 35, 4 => 23, 5 => 20];

public const MIN_WIDTH = 100;

public const MAX_WIDTH = 8192;

public const SRCSET_WIDTH_TOLERANCE = 0.08;
```
Tokens:
Raw