README

Kiwa Source Collection

The Kiwa Source Collection makes it easy to create HTML audio, picture and video elements with multiple sources.

Installation

This library is made for the use with Composer. Add it to your project by running $ composer require kiwa/source-collection.

Usage

Creating a picture collection

To run the library in auto-mode, enable the auto search and tell the root folder, where all the images or video files are stored in:

<?php

use Kiwa\SourceCollection\Picture;

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

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

<?php

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

The library will search for files with the same name then and use them as additional sources. Print the object then:

echo $picture; // or $picture->getPicture()

Depending on the images there 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>

Creating a video collection

Creating a video element goes 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:

<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 goes 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:

<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:

<?php

use Kiwa\SourceCollection\Picture;

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

Attributes

The constructor and the addSourceFile method have a second parameter, which can be used to add HTML parameters:

<?php

use Kiwa\SourceCollection\Picture;

echo new Picture(
    '/build/images/my-image.jpg',
    [
        'alt' => 'This is a 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 a alt text" title="This is a title text"/>
</picture>

Handling attributes globally

All attributes like the width and height can be stored and handled globally. It can be enabled like this:

<?php

use Kiwa\SourceCollection\AbstractSourceCollection;

AbstractSourceCollection::enableAttributeCache(
    Path::getRootFolder() . DIRECTORY_SEPARATOR . 'attributes-cache'
);

Whenever a file is getting requested, the script will look for a file having the same name. For example

<?php

use Kiwa\SourceCollection\Picture;

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

will cause the script to search for a file called build-images-my-image-jpg-attributes.php. The file itself should contain and return an array with attributes then, for example:

<?php

return [
    'width' => 1024,
    'height' => 938,
];

This is especially useful in combination with the Kiwa Console's AssetAttributeCacheCreateCommand, where all assets are getting scanned and their information exctracted automatically. It can even use image recognition to create the alt and title descriptions.

Help

If you have any questions, feel free to contact us under hello@bitandblack.com.

Further information about Bit&Black can be found under www.bitandblack.com.