README

twicpics/url provides a simple yet expressive fluent API to generate TwicPics 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

Use composer:

php composer.phar require twicpics/url

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

auth

auth( AUTHENTICATION_TOKEN )

Adds an authentication token.

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

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( <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( <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( <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( <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( <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( <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( <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( <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( [ <quality> ] )

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

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( <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()

Shortcut for format("png").

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( <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( <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( <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( <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()

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()

Alias of __toString.

webp

webp( [ <quality> ] )

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

twicpics / url

Maintainers

Details