twicpics / url
a library to build TwicPics URLs
Requires
- php: >=5.3.0
Requires (Dev)
- php: >=7.1.0
- php-coveralls/php-coveralls: 2.1.0
- phpunit/phpunit: 7.3.0
- squizlabs/php_codesniffer: 3.3.1
This package is not auto-updated.
Last update: 2025-07-06 09:41:45 UTC
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)
.
License
Copyright (c) 2018 TwicPics Licensed under the MIT license.