The Source Collection

This page is about the Kiwa Source Collection extension, which makes it easy to create HTML audio, picture and video elements with multiple sources.

Table of contents

Introduction

Modern browsers support next-gen formats like WebP, AVIF, or the compressed variants of video and audio files. To use them, a developer usually has to write multiple <source> elements by hand. The Source Collection finds all files with the same name automatically and creates the picture, video or audio element with all <source> elements, ordered by format.

Installation

This library is made for the use with Composer. Add it to your project by running

$ composer require kiwa/source-collection

Creating a picture collection

To use the automatic mode, you need to enable it and tell the root folder in which the files are stored:

<?php

use Kiwa\SourceCollection\Picture;

Picture::enableAutoSearchGenerally(
    'path/to/dir'
);

After that, you can create a new Picture object with the file name you want to have printed later. This path may be relative:

<?php

$picture = new Picture('/build/images/my-image.jpg');
echo $picture; // or $picture->getPicture()

The library searches for files with the same name and uses them as additional sources. Depending on the files that are available, the output could look like that:

<picture>
    <source srcset="/build/images/my-image.webp" type="image/webp"/>
    <source srcset="/build/images/my-image.jpg" type="image/jpeg"/>
    <img src="/build/images/my-image.jpg"/>
</picture>

Next-gen formats like webp or avif are always printed first, so a browser which supports them will take them.

Creating a video collection

Creating a video element works in the same way:

<?php

use Kiwa\SourceCollection\Video;

Video::enableAutoSearchGenerally(
    'path/to/dir'
);

echo new Video('/some/path/test-file.mp4');

This will result in something like:

<video>
    <source src="/some/path/test-file.mp4" type="video/mp4"/>
    <source src="/some/path/test-file.mov" type="video/quicktime"/>
</video>

Creating an audio collection

Creating an audio element works in the same way:

<?php

use Kiwa\SourceCollection\Audio;

Audio::enableAutoSearchGenerally(
    'path/to/dir'
);

echo new Audio('/some/path/test-file.mp3');

This will result in something like:

<audio>
    <source src="/some/path/test-file.mp3" type="audio/mpeg"/>
    <source src="/some/path/test-file.ogg" type="audio/ogg"/>
</audio>

Options

Manual mode

You don't need to use the auto mode. Instead, you can add source files by your own with addSourceFile(string $fileSrc, array $fileOptions = []):

<?php

use Kiwa\SourceCollection\Picture;

$picture = new Picture('/build/images/my-image.jpg');
$picture->addSourceFile('/build/images/my-image.webp');

echo $picture;

The fileOptions array adds all given attributes to the <source> element, for example media or sizes. The type and src/srcset attributes are added automatically.

Attributes

The root element can receive attributes. For a Picture those attributes go to the <img> element, for Audio and Video they go to the root element itself:

<?php

use Kiwa\SourceCollection\Picture;

echo new Picture(
    '/build/images/my-image.jpg',
    [
        'alt' => 'This is an alt text',
        'title' => 'This is a title text',
    ]
);

This will result in:

<picture>
    <source srcset="/build/images/my-image.jpg" type="image/jpeg"/>
    <img src="/build/images/my-image.jpg" alt="This is an alt text" title="This is a title text"/>
</picture>

Attributes can also be added later with addAttributes(array $attributes); attributes that are false or empty will be removed. The options of the root element can be set with setRootFileOptions(array $rootFileOptions).

Auto search

Beside the global setting enableAutoSearchGenerally(string ...$rootFolder) which affects all elements of that type, the auto search can also be enabled per instance:

<?php

use Kiwa\SourceCollection\Picture;

$picture = new Picture('/build/images/my-image.jpg');
$picture->enableAutoSearch('path/to/dir');

echo $picture;

Attribute cache

The Source Collection can read attributes from cache files. The cache files are created by the Kiwa Console command asset:attribute-cache:create, but you can also create them by yourself: every cache file is a PHP file that returns a named array:

<?php

return [
    'width' => 1024,
    'height' => 512,
    'alt' => 'Some image',
];

Enable the attribute cache with enableAttributeCache(string $attributeCacheFolder):

<?php

use Kiwa\SourceCollection\Picture;

Picture::enableAttributeCache('attributes-cache');

echo new Picture('/build/images/my-image.jpg');

You can find the source of the extension under bitbucket.org/wirbelwild/kiwa-source-collection.