Sirv PHP SDK Documentation

Installation

composer require sirv/sirv-client

use Sirv\SirvClient;

Quick Start

use Sirv\SirvClient;

$sirv = new SirvClient(['domain' => 'demo.sirv.com', 'defaults' => ['q' => 80]]);

// Build a URL
$sirv->url('/image.jpg', ['w' => 300, 'h' => 200, 'format' => 'webp']);
// => https://demo.sirv.com/image.jpg?q=80&w=300&h=200&format=webp

// Generate an image tag
$sirv->image('/photo.jpg', ['alt' => 'A photo']);
// => <img class="Sirv" data-src="https://demo.sirv.com/photo.jpg" alt="A photo">

// Generate a script tag
$sirv->scriptTag(['modules' => ['spin', 'zoom']]);
// => <script src="https://scripts.sirv.com/sirvjs/v3/sirv.spin.zoom.js" async></script>

Constructor

new SirvClient(array $options)

Option	Type	Description
`domain`	string	Required. Sirv domain (e.g. `'demo.sirv.com'`)
`defaults`	array	Default query parameters merged into every URL

$sirv = new SirvClient([
  'domain' => 'demo.sirv.com',
  'defaults' => ['q' => 80]
]);

url(string $path, array $params = [])

Build a full Sirv URL. Nested arrays are flattened to dot-notation query parameters. Default parameters are merged with the provided params.

Param	Type	Description
`$path`	string	Asset path (e.g. `'/image.jpg'`)
`$params`	array	Transformation parameters (nested arrays are flattened)

// Simple params
$sirv->url('/image.jpg', ['w' => 300, 'h' => 200, 'format' => 'webp']);
// => https://demo.sirv.com/image.jpg?q=80&w=300&h=200&format=webp

// Nested params flatten to dot-notation
$sirv->url('/image.jpg', ['crop' => ['type' => 'face', 'pad' => ['width' => 10, 'height' => 10]]]);
// => ...?q=80&crop.type=face&crop.pad.width=10&crop.pad.height=10

// Params override defaults
$sirv->url('/image.jpg', ['q' => 90]);
// => https://demo.sirv.com/image.jpg?q=90

srcSet(string $path, array $params = [], array $options = [])

Generate a srcset string for responsive images. Supports three modes:

Explicit widths

$sirv->srcSet('/image.jpg', ['format' => 'webp'], ['widths' => [320, 640, 960, 1280, 1920]]);
// => https://demo.sirv.com/image.jpg?q=80&format=webp&w=320 320w,
//    https://demo.sirv.com/image.jpg?q=80&format=webp&w=640 640w, ...

Auto-generated widths (tolerance)

Generates widths between minWidth and maxWidth, stepping by current *= 1 + tolerance * 2.

$sirv->srcSet('/image.jpg', ['format' => 'webp'], [
  'minWidth' => 200, 'maxWidth' => 2000, 'tolerance' => 0.15
]);

Device pixel ratios (DPR)

Generates DPR variants with automatic variable quality: q = round(baseQ × 0.75^(dpr-1)). Width and height are multiplied by the DPR.

$sirv->srcSet('/hero.jpg', ['w' => 600, 'h' => 400], ['devicePixelRatios' => [1, 2, 3]]);
// 1x: q=80, w=600, h=400
// 2x: q=60, w=1200, h=800
// 3x: q=45, w=1800, h=1200

Option	Type	Description
`widths`	int[]	Explicit list of widths
`minWidth`	int	Minimum width for auto-generation
`maxWidth`	int	Maximum width for auto-generation
`tolerance`	float	Step tolerance (default 0.15)
`devicePixelRatios`	float[]	DPR values (e.g. `[1, 2, 3]`)

image(string $path, array $options = [])

Generate an <img> tag for a Sirv image with class="Sirv" and data-src.

Option	Type	Description
`transform`	array	Transformation parameters for the URL
`viewer`	array	Viewer options (serialized to `data-options`)
`alt`	string	Alt text
`className`	string	Additional CSS class(es)

$sirv->image('/tomatoes.jpg', ['alt' => 'Fresh tomatoes']);
// => <img class="Sirv" data-src="https://demo.sirv.com/tomatoes.jpg" alt="Fresh tomatoes">

$sirv->image('/photo.jpg', [
  'transform' => ['w' => 800, 'format' => 'webp'],
  'viewer' => ['autostart' => 'visible', 'threshold' => 200],
  'className' => 'hero-image'
]);
// => <img class="Sirv hero-image" data-src="...?q=80&w=800&format=webp"
//        data-options="autostart:visible;threshold:200">

zoom(string $path, array $options = [])

Generate a <div> tag for a Sirv zoom viewer with data-type="zoom".

Option	Type	Description
`transform`	array	Transformation parameters
`viewer`	array	Viewer options
`className`	string	Additional CSS class(es)

$sirv->zoom('/product.jpg');
// => <div class="Sirv" data-src="https://demo.sirv.com/product.jpg" data-type="zoom"></div>

$sirv->zoom('/product.jpg', ['viewer' => ['mode' => 'deep', 'wheel' => false]]);
// => <div ... data-type="zoom" data-options="mode:deep;wheel:false"></div>

spin(string $path, array $options = [])

Generate a <div> tag for a Sirv 360 spin viewer. No data-type attribute is added (Sirv JS auto-detects .spin files).

Option	Type	Description
`viewer`	array	Viewer options
`className`	string	Additional CSS class(es)

$sirv->spin('/product.spin');
// => <div class="Sirv" data-src="https://demo.sirv.com/product.spin"></div>

$sirv->spin('/product.spin', ['viewer' => ['autostart' => 'visible', 'autospin' => 'lazy']]);

video(string $path, array $options = [])

Generate a <div> tag for a Sirv video.

$sirv->video('/clip.mp4');
// => <div class="Sirv" data-src="https://demo.sirv.com/clip.mp4"></div>

model(string $path, array $options = [])

Generate a <div> tag for a Sirv 3D model viewer.

$sirv->model('/shoe.glb');
// => <div class="Sirv" data-src="https://demo.sirv.com/shoe.glb"></div>

gallery(array $items, array $options = [])

Generate a gallery container with multiple asset divs. Each item can have its own type, transform params, and viewer options. Gallery-level viewer options apply to the container.

Item properties

Property	Type	Description
`src`	string	Required. Asset path
`type`	string	Asset type override (e.g. `'zoom'`)
`transform`	array	Per-item transformation params
`viewer`	array	Per-item viewer options

Gallery options

Option	Type	Description
`viewer`	array	Gallery-level viewer options
`className`	string	Additional CSS class(es)

$sirv->gallery([
  ['src' => '/product.spin'],
  ['src' => '/front.jpg', 'type' => 'zoom'],
  ['src' => '/side.jpg', 'type' => 'zoom'],
  ['src' => '/video.mp4']
], [
  'viewer' => ['arrows' => true, 'thumbnails' => 'bottom']
]);
// => <div class="Sirv" data-options="arrows:true;thumbnails:bottom">
//      <div data-src="https://demo.sirv.com/product.spin"></div>
//      <div data-src="https://demo.sirv.com/front.jpg" data-type="zoom"></div>
//      <div data-src="https://demo.sirv.com/side.jpg" data-type="zoom"></div>
//      <div data-src="https://demo.sirv.com/video.mp4"></div>
//    </div>

scriptTag(array $options = [])

Generate a <script> tag to load Sirv JS. Optionally specify modules to load only what you need.

Option	Type	Description
`modules`	string[]	Modules to load (e.g. `['spin', 'zoom']`)
`async`	bool	Add async attribute (default `true`)

$sirv->scriptTag();
// => <script src="https://scripts.sirv.com/sirvjs/v3/sirv.js" async></script>

$sirv->scriptTag(['modules' => ['spin', 'zoom']]);
// => <script src="https://scripts.sirv.com/sirvjs/v3/sirv.spin.zoom.js" async></script>

Full Examples

Responsive Product Page

use Sirv\SirvClient;
$sirv = new SirvClient(['domain' => 'mystore.sirv.com', 'defaults' => ['q' => 80]]);

// Responsive image with srcset
$srcset = $sirv->srcSet('/hero.jpg', ['format' => 'webp'], [
  'widths' => [320, 640, 960, 1280, 1920]
]);
echo '<img srcset="' . $srcset . '" sizes="100vw">';

// Product gallery with zoom, spin, and video
$gallery = $sirv->gallery([
  ['src' => '/products/shoe.spin'],
  ['src' => '/products/shoe-front.jpg', 'type' => 'zoom'],
  ['src' => '/products/shoe-side.jpg', 'type' => 'zoom'],
  ['src' => '/products/shoe-video.mp4']
], ['viewer' => ['thumbnails' => 'bottom']]);

// Load Sirv JS for spin + zoom
$script = $sirv->scriptTag(['modules' => ['spin', 'zoom']]);

Thumbnail Grid with Face Crop

$images = ['/team/alice.jpg', '/team/bob.jpg', '/team/carol.jpg'];
$html = array_map(function ($path) use ($sirv) {
  return $sirv->image($path, [
    'transform' => ['w' => 200, 'h' => 200, 'crop' => ['type' => 'face']],
    'alt' => basename($path)
  ]);
}, $images);
echo implode("\n", $html);