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();Use composer:
php composer.phar require twicpics/url
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();auth( AUTHENTICATION_TOKEN )
Adds an authentication token.
$builder->auth("aaaaaaaa-aaaa-4aaa-aaaa-aaaaaaaaaaaa");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( <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( <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( <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( <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( <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( <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( <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( <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( [ <quality> ] )
Shortcut for format("jpeg", $quality).
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( <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()
Shortcut for format("png").
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( <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( <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( <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_IMAGEIf 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( <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()
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(); // worksurl()
Alias of __toString.
webp( [ <quality> ] )
Shortcut for format("webp", $quality).
Copyright (c) 2018 TwicPics Licensed under the MIT license.