PHPackages                             twicpics/url - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. twicpics/url

ActiveLibrary[Utility & Helpers](/categories/utility)

twicpics/url
============

a library to build TwicPics URLs

0.0.1(7y ago)11891MITPHPPHP >=5.3.0

Since Aug 6Pushed 7y ago3 watchersCompare

[ Source](https://github.com/TwicPics/php_url)[ Packagist](https://packagist.org/packages/twicpics/url)[ Docs](https://github.com/TwicPics/php_url)[ RSS](/packages/twicpics-url/feed)WikiDiscussions master Synced 1w ago

READMEChangelogDependencies (3)Versions (3)Used By (0)

twicpics/url
============

[](#twicpicsurl)

[![Packagist](https://camo.githubusercontent.com/53a5f9708e3098ed61631b92f7ce3988ca0560e5e2f731516ca333fb92dfb4f0/68747470733a2f2f706f7365722e707567782e6f72672f74776963706963732f75726c2f76657273696f6e3f666f726d61743d666c61742d737175617265)](https://packagist.org/packages/twicpics/url)[![License](https://camo.githubusercontent.com/56c45c9bf8487ae50be7f46adc73c2aab2fb6dc52c5e39fe09ed26b48b1d9361/68747470733a2f2f706f7365722e707567782e6f72672f74776963706963732f75726c2f6c6963656e73653f666f726d61743d666c61742d737175617265)](https://raw.githubusercontent.com/TwicPics/php_url/master/LICENSE)

[![Build Status](https://camo.githubusercontent.com/491789bbc3f9a5f92dd2177957e4dca3f87a8a49ddfe72020716de8d15818014/68747470733a2f2f696d672e736869656c64732e696f2f7472617669732f54776963506963732f7068705f75726c2e7376673f7374796c653d666c61742d737175617265)](https://travis-ci.org/TwicPics/php_url)[![Coverage Status](https://camo.githubusercontent.com/518fb244723782b426b837c63315f25e4ac652c5c41010477f257b7a52856493/68747470733a2f2f696d672e736869656c64732e696f2f636f766572616c6c732f54776963506963732f7068705f75726c2e7376673f7374796c653d666c61742d737175617265)](https://coveralls.io/github/TwicPics/php_url)[![Code Style](https://camo.githubusercontent.com/cec085f21e1adb612bc9ec6f7680007bb1c22c5ac075ed42c9cc38bb84642b53/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f636f64652532307374796c652d50485043532d627269676874677265656e2e7376673f7374796c653d666c61742d737175617265)](https://github.com/squizlabs/PHP_CodeSniffer)

`twicpics/url` provides a simple yet expressive fluent API to generate [TwicPics](https://www.twicpics.com) URLs.

Here are some examples of what it can do:

```
$builder = new TwicPics\URL();

// Create a url in one pass
$onePassUrl = $builder->cover("1:1")->resize(700)->src(SRC_URL)->url();

// Pre-crop an image then apply different transformations to it
$precrop = $builder->src(SRC_URL)->focus("25p", "71p")->crop(560, 280);
$squareUrl = $precrop->cover("1:1")->url();
$landscapeUrl = $precrop->cover("16:9")->url();

// Prepare manipulations to be applied to different sources
$square = $builder->cover("1:1")->resize(300);
$landscape = $builder->cover("1:1")->resize(300);

$squaredUrl = $square->src(SRC_URL)->url();
$squaredPrecrop = $square->src($precrop)->url();

$landscapedUrl = $landscape->src(SRC_URL)->url();
$landscapedPrecrop = $landscape->src($precrop)->url();
```

Installation
------------

[](#installation)

Use composer:

```
php composer.phar require twicpics/url

```

Usage
-----

[](#usage)

`twicpics/url` exports a single class (`TwicPics\URL`) that will be autoloaded. Just create an instance of this class and you're good to go:

```
// Get the builder
$builder = new TwicPics\URL();

// Use the builder
$myFirstUrl = $builder->src(MY_IMAGE_URL)->resize( 300 )->url();
```

The builder's API is fluent and each method call returns a new immutable object. As such you can re-use an existing object and create a totally new and independent URL:

```
$authorizedAndSquared = $builder->auth(MY_TOKEN)->cover("1:1");

$url1 = $authorizedAndSquared->src(MY_IMAGE_URL_1)->url();
$url2 = $authorizedAndSquared->src(MY_IMAGE_URL_2)->url();
```

Last, but not least, any builder object can be used as a source image by another builder object. So you can create generic manipulations to be applied on different, eventually pre-transformed, images:

```
$square500 = $builder->cover(500, 500);

// Use authentication for an image I don't own
$external = $builder->auth(MY_TOKEN)->src(URL_TO_IMAGE_I_DONT_OWN);

// Precrop an image I own
$precrop = $builder->src(URL_TO_IMAGE_I_OWN)->crop(
    [
        "x" => 150,
        "y" => 256,
        "width" => 700,
        "height" => 889
    ]
);

// square the image I don't own
$square500->src(external)->url();

// square the image I own
$square500->src(precop)->url();
```

API
---

[](#api)

### auth

[](#auth)

*auth( AUTHENTICATION\_TOKEN )*

Adds an authentication token.

```
$builder->auth("aaaaaaaa-aaaa-4aaa-aaaa-aaaaaaaaaaaa");
```

### contain

[](#contain)

*contain( <expr> )*

*contain( <width> \[, <height> \] )*

*contain( { width, height } )*

Adds a `contain` transformation.

```
// These four lines are strictly equivalent
$builder->contain("500x400");
$builder->contain(500, 400);
$builder->contain(
    [
        "width" => 500,
        "height" => 400
    ]
);
$builder->contain(
    json_decode(
        '{
            "width": 500,
            "height": 400
        }'
    )
);
```

### containMax

[](#containmax)

*containMax( <expr> )*

*containMax( <width> \[, <height> \] )*

*containMax( { width, height } )*

Adds a `contain-max` transformation.

```
// These four lines are strictly equivalent
$builder->containMax("500x400");
$builder->containMax(500, 400);
$builder->containMax(
    [
        "width" => 500,
        "height" => 400
    ]
);
$builder->containMax(
    json_decode(
        '{
            "width": 500,
            "height": 400
        }'
    )
);
```

### containMin

[](#containmin)

*containMin( <expr> )*

*containMin( <width> \[, <height> \] )*

*containMin( { width, height } )*

Adds a `contain-min` transformation.

```
// These four lines are strictly equivalent
$builder->containMin("500x400");
$builder->containMin(500, 400);
$builder->containMin(
    [
        "width" => 500,
        "height" => 400
    ]
);
$builder->containMin(
    json_decode(
        '{
            "width": 500,
            "height": 400
        }'
    )
);
```

### cover

[](#cover)

*cover( <expr> )*

*cover( <width> \[, <height> \] )*

*cover( { width, height } )*

Adds a `cover` transformation.

```
// These four lines are strictly equivalent
$builder->cover("500x400");
$builder->cover(500, 400);
$builder->cover(
    [
        "width" => 500,
        "height" => 400
    ]
);
$builder->cover(
    json_decode(
        '{
            "width": 500,
            "height": 400
        }'
    )
);
```

### coverMax

[](#covermax)

*coverMax( <expr> )*

*coverMax( <width> \[, <height> \] )*

*coverMax( { width, height } )*

Adds a `cover-max` transformation.

```
// These four lines are strictly equivalent
$builder->coverMax("500x400");
$builder->coverMax(500, 400);
$builder->coverMax(
    [
        "width" => 500,
        "height" => 400
    ]
);
$builder->coverMax(
    json_decode(
        '{
            "width": 500,
            "height": 400
        }'
    )
);
```

### coverMin

[](#covermin)

*coverMin( <expr> )*

*coverMin( <width> \[, <height> \] )*

*coverMin( { width, height } )*

Adds a `cover-min` transformation.

```
// These four lines are strictly equivalent
$builder->coverMin("500x400");
$builder->coverMin(500, 400);
$builder->coverMin(
    [
        "width" => 500,
        "height" => 400
    ]
);
$builder->coverMin(
    json_decode(
        '{
            "width": 500,
            "height": 400
        }'
    )
);
```

### crop

[](#crop)

*crop( <expr> )*

*crop( <width>\[, <height> \[, <x> \[, <y> \] \] \] )*

*crop( { x, y, width, height } )*

Adds a crop transformation.

```
// The following four lines create the same crop without origin
$builder->crop("500x400");
$builder->crop(500, 400);
$builder->crop(
    [
        "width" => 500,
        "height" => 400
    ]
);
$builder->crop(
    json_decode(
        '{
            "width": 500,
            "height": 400
        }'
    )
);

// The following four lines create the same crop with origin
$builder->crop("500x400@15x20");
$builder->crop(500, 400, 15, 20);
$builder->crop(
    [
        "x" => 15,
        "y" => 20,
        "width" => 500,
        "height" => 400
    ]
);
$builder->crop(
    json_decode(
        '{
            "x": 15,
            "y": 20,
            "width": 500,
            "height": 400
        }'
    )
);
```

### focus

[](#focus)

*focus( <expr> )*

*focus( <x> \[, <y> \] )*

*focus( { x, y } )*

Sets the focus point.

```
// These four lines set the exact same focus point
$builder->focus("67x987");
$builder->focus(67, 987);
$builder->focus(
    [
        "x" => 67,
        "y" => 987
    ]
);
$builder->focus(
    json_decode(
        '{
            "x": 67,
            "y": 987
        }'
    )
);
```

### format

[](#format)

*format( <type> \[, <quality> \] )*

*format( { type, quality } )*

Sets the image format.

Accepted types are `"jpeg"`, `"png"` and `"webp"`. Only `jpeg` and `webp` accept a quality value.

```
$builder->format( "jpeg", 45 );
$builder->format(
    [
        "type" => "jpeg",
        "quality" => 62
    ]
);
$builder->format( "png" );
$builder->format(
    json_decode(
        '{
            "type": "webp",
            "quality": 80,
        }'
    )
);
```

### jpeg

[](#jpeg)

*jpeg( \[ <quality> \] )*

Shortcut for `format("jpeg", $quality)`.

### max

[](#max)

*max( <expr> )*

*max( <width> \[, <height> \] )*

*max( { width, height } )*

Adds a `max` transformation.

```
// These four lines are strictly equivalent
$builder->max("500x400");
$builder->max(500, 400);
$builder->max(
    [
        "width" => 500,
        "height" => 400
    ]
);
$builder->max(
    json_decode(
        '{
            "width": 500,
            "height": 400
        }'
    )
);
```

### min

[](#min)

*min( <expr> )*

*min( <width> \[, <height> \] )*

*min( { width, height } )*

Adds a `min` transformation.

```
// These four lines are strictly equivalent
$builder->min("500x400");
$builder->min(500, 400);
$builder->min(
    [
        "width" => 500,
        "height" => 400
    ]
);
$builder->min(
    json_decode(
        '{
            "width": 500,
            "height": 400
        }'
    )
);
```

### png

[](#png)

*png()*

Shortcut for `format("png")`.

### resize

[](#resize)

*resize( <expr> )*

*resize( <width> \[, <height> \] )*

*resize( { width, height } )*

Adds a `resize` transformation.

```
// These four lines are strictly equivalent
$builder->resize("500x400");
$builder->resize(500, 400);
$builder->resize(
    [
        "width" => 500,
        "height" => 400
    ]
);
$builder->resize(
    json_decode(
        '{
            "width": 500,
            "height": 400
        }'
    )
);
```

### resizeMax

[](#resizemax)

*resizeMax( <expr> )*

*resizeMax( <width> \[, <height> \] )*

*resizeMax( { width, height } )*

Adds a `resize-max` transformation.

```
// These four lines are strictly equivalent
$builder->resizeMax("500x400");
$builder->resizeMax(500, 400);
$builder->resizeMax(
    [
        "width" => 500,
        "height" => 400
    ]
);
$builder->resizeMax(
    json_decode(
        '{
            "width": 500,
            "height": 400
        }'
    )
);
```

### resizeMin

[](#resizemin)

*resizeMin( <expr> )*

*resizeMin( <width> \[, <height> \] )*

*resizeMin( { width, height } )*

Adds a `resize-min` transformation.

```
// These four lines are strictly equivalent
$builder->resizeMin("500x400");
$builder->resizeMin(500, 400);
$builder->resizeMin(
    [
        "width" => 500,
        "height" => 400
    ]
);
$builder->resizeMin(
    json_decode(
        '{
            "width": 500,
            "height": 400
        }'
    )
);
```

### src

[](#src)

*src( <url> )*

*src( <builder object> )*

Sets the source image on which the current manipulation has to be performed.

If a URL is provided than it will be used as the master image to transform.

```
$builder->resize(300)->src(MY_IMAGE); // generated a 300 pixels-wide version of MY_IMAGE
```

If a builder object is provided than its source will be used as the new manipulation's source while its transformations will be prepended to the current ones.

```
$precrop = $builder->src(MY_IMAGE)->crop(
    [
        "x": 150,
        "y": 256,
        "width": 700,
        "height": 889
    ]
);

// This will first crop MY_IMAGE then apply a cover=500x500
$builder->cover(500, 500)->src($precop);
```

### step

[](#step)

*step( <expr> )*

*step( <width> \[, <height> \] )*

*step( { width, height } )*

Adds a `step` transformation.

```
// These four lines are strictly equivalent
$builder->step("10x10");
$builder->step(10, 10);
$builder->step(
    [
        "width" => 10,
        "height" => 10
    ]
);
$builder->step(
    json_decode(
        '{
            "width": 10,
            "height": 10
        }'
    )
);
```

### \_\_toString

[](#__tostring)

*\_\_toString()*

Generates the URL as a string. Note that you must have provided an image URL using `.src()` prior to this call or an exception will be thrown.

```
$builder->__toString(); // throws an exception
$builder->src(MY_IMAGE_URL)->__toString(); // works
```

### url

[](#url)

*url()*

Alias of `__toString`.

### webp

[](#webp)

*webp( \[ <quality> \] )*

Shortcut for `format("webp", $quality)`.

License
-------

[](#license)

Copyright (c) 2018 [TwicPics](mailto:hello@twic.pics)Licensed under the [MIT license](https://raw.githubusercontent.com/TwicPics/php_url/master/LICENSE).

###  Health Score

26

—

LowBetter than 43% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity16

Limited adoption so far

Community11

Small or concentrated contributor base

Maturity48

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 88.9% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~0 days

Total

2

Last Release

2842d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/138848526cdd7c1b8140846ef531a0ed31cfabc90f28d1b0507a9b8be038fbd2?d=identicon)[jaubourg](/maintainers/jaubourg)

---

Top Contributors

[![jaubourg](https://avatars.githubusercontent.com/u/160354?v=4)](https://github.com/jaubourg "jaubourg (8 commits)")[![Krinkle](https://avatars.githubusercontent.com/u/156867?v=4)](https://github.com/Krinkle "Krinkle (1 commits)")

###  Code Quality

TestsPHPUnit

Code StylePHP\_CodeSniffer

### Embed Badge

![Health badge](/badges/twicpics-url/health.svg)

```
[![Health](https://phpackages.com/badges/twicpics-url/health.svg)](https://phpackages.com/packages/twicpics-url)
```

###  Alternatives

[markrassamni/inline-boolean

A Laravel Nova boolean field that can be directly edited from the index or detail page of a resource.

16161.6k](/packages/markrassamni-inline-boolean)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)