PHP-dataURI documentation
PHP-dataURI documentation¶
Introduction¶
PHP-DataURI is a library which handles URI scheme and provide a way to include data in-line in web pages as if they were external ressources.
This feature is mainly used with HTML5 file API.
This is supposed 100% RFC 2397
Installation¶
We rely on composer to use this library. If you do
no still use composer for your project, you can start with this composer.json
at the root of your project:
{
"require": {
"data-uri/data-uri": "dev-master"
}
}
Install composer :
# Install composer
curl -s http://getcomposer.org/installer | php
# Upgrade your install
php composer.phar install
You now just have to autoload the library to use it :
<?php
require 'vendor/autoload.php';
This is a very short intro to composer. If you ever experience an issue or want to know more about composer, you will find help on their website http://getcomposer.org/.
PHP dataURI¶
The PHP-dataURI library is very simple and consists of three main classes :
- One represents a data URI scheme as a PHP object
- One parses the data URI string
- One dumps the data URI PHP object
Parser¶
<?php
use DataURI;
$dataString = "data:text/plain;charset=utf-8,%23%24%25";
// Parse one data URI scheme and return a Data object
$dataObject = DataURI\Parser::parse($dataString);
echo $dataObject->getMimeType();
// Output text/plain
echo $dataObject->getData();
// Output #$%
var_dump($dataObject->getParameters());
// Output an array of parameters array('charset' => 'utf-8')
Dumper¶
<?php
use DataURI;
// Instance a Data object
$dataObject = new DataURI\Data("#$%");
// Add some parameters
$dataObject->addParameters('charset' => 'utf-8');
echo DataURI\Dumper::dump($dataObject);
// Output data:text/plain;charset=utf-8,%23%24%25
Dump URI from file¶
<?php
use DataURI;
$dataObject = DataURI\Data::buildFromFile("/path/to/my/image.png");
echo DataURI\Dumper::dump($dataObject);
// Output data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...+S/EAAAAASUVORK5CYII=
Dump URI from url¶
<?php
use DataURI;
$dataObject = DataURI\Data::buildFromUrl("http://www.example.org/path/to/my/image.png");
echo DataURI\Dumper::dump($dataObject);
// Output data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...+S/EAAAAASUVORK5CYII=
Handling Exceptions¶
PHP-dataURI throws 4 different types of exception :
\DataURI\Exception\FileNotFoundException
is thrown when an invalid pathfile is supplied or when we don’t get a valid response from URL\DataURI\Exception\InvalidDataException
is thrown when raw data could not be decoded\DataURI\Exception\TooLongDataException
is thrown when provided data is too long according to the RFC 2397\DataURI\Exception\InvalidArgumentException
is thrown when provided data URI scheme could not be parsed extends SPL InvalidArgumentException
All these Exception implements DataURI\Exception\Exception
so you can catch
any of these exceptions by catching this exception interface.
Report a bug¶
If you experience an issue, please report it in our issue tracker. Before reporting an issue, please be sure that it is not already reported by browsing open issues.
Contribute¶
You find a bug and resolved it ? You added a feature and want to share ? You found a typo in this doc and fixed it ? Feel free to send a Pull Request on GitHub, we will be glad to merge your code.
Run tests¶
PHP-dataURI relies on PHPUnit for unit tests. To run tests on your system, ensure you have PHPUnit installed, and, at the root of PHP-dataURI, execute it :
phpunit
About¶
PHP-dataURI has been written by Nicolas Le Goff @ Alchemy for Phraseanet, our DAM software. Try it, it’s awesome !
License¶
PHP-dataURI is licensed under the MIT License