README

DeDEX is a DDEX XML file parser. DDEX is a standard used in the music industry to deliver rich media content. See more info at ddex.net. This covers only the ERN (Electronic Release Notification) standard, for the following versions.

Supported versions:

• 3.8.2
• 4.1
• 4.1.1
• 4.2
• 4.3

Simple Entities speak your language and will make you smoothly parse your first ERNs.

Rule (and Rules Set) contain the minimal consistent information YOU need in your system. XML may be valid, but inaccurate for your needs.

I created this DDEX ERN parser that is as convenient as I always hoped for.

✍️ Contribute here if you feel like it. Make DeDEX the first repo you contribute for! 🙌

⭐️ If you find this work useful, please star the repository.

🐘 DeDEX on packagist.

Installation

composer require miqwit/dedex

⚠️ Runtime: PHP 7.4+. As per composer configuration, development and test tools need 8.1+ to work. It is not maintained for 7.4+ versions.

Usage

Convert a DDEX file to a SimpleAlbum

use DedexBundle\Controller\ErnParserController;
use DedexBundle\Simplifiers\SimpleAlbum;

$xml_path = "tests/samples/with_assets/004_complete/1199119911991.xml";
$parser = new ErnParserController();
$ern = $parser->parse($xml_path);
$album = new SimpleAlbum($ern);

// Then you can access high level property of this album
$release_date = $album->getOriginalReleaseDate();
$artists_at_album_level = $album->getArtists();
$tracks_for_cd_1 = $album->getTracksPerCd()[1];

// You can also access exact XML mapping by getting 
// ddex objects at album or track level
$ddex_release = $album->getDdexRelease();
$ddex_release->getReleaseId()[0]->getICPN()->value(); // direct access
$ddex_track = $tracks_for_cd_1[1]->getDdexSoundRecording()->getDuration(); // direct access

Parse a file without XSD validation

use DedexBundle\Controller\ErnParserController;

$xml_path = "tests/samples/001_audioalbum_complete.xml";
$parser = new ErnParserController();
$ern = $parser->parse($xml_path);

// Then you can access properties of the ERN
$created_at = $ern->getMessageHeader()->getMessageCreatedDateTime();

Parse a file with XSD validation

XSD validation will load all XML and XSD in memory, making this library less efficient. Use with care. Is not adapted to gigantic files.

use DedexBundle\Controller\ErnParserController;

$xml_path = "tests/samples/001_audioalbum_complete.xml";
$parser = new ErnParserController();
$parser->setXsdValidation(true);
$ern = $parser->parse($xml_path);

Parse a file with Rules

use DedexBundle\Controller\ErnParserController;
use DedexBundle\Rule\AtLeastOneImage;
use DedexBundle\Exception\RuleValidationException;

$xml_path = "tests/samples/001_audioalbum_complete.xml";
$parser = new ErnParserController();
$parser->addRule(new AtLeastOneImage(Rule::LEVEL_ERROR));
// ... can add multiple rules one by one
// ... or multiple rules with $parser->addRuleSet([])
$ern = $parser->parse($xml_path);  // will raise an RuleValidationException if rule is broken

Parser config

Here are handy function from the parser.

$parser=new ErnParserController();

$parser->setDisplayLog(true);

Displays parsing logs. For debugging purpose mainly. (default: false)

$parser->setXsdValidation(true);

Validates XML against XSD. (default: false because will load XSD and XML in memory)

$parser->getRuleMessages();

Returns a formatted string (with new lines) of all the errors generated by the rule checking. To be called when parsing ended. If one of the ERROR rules fail, the parser will throw an exception with these messages. In the case of only WARNING raised during the parsing, this function is the only way to read them.

$parser->addRuleSet();

Will store a set of Rule (array). For example, each provider could be check with a specific rule set.

Standard updates

Official email in September 2024

From March 1, 2025, all the versions 3 as well as version 4.0 of the Electronic Release Notification standard, their respective profiles, and choreographies will no longer be supported. This means that from that date, no further updates, bug fixes, or AVS additions will be made to these versions of the ERN standard. Also, the XML schemas and all articles or implementation advice about ERN- 3 and ERN 4.0 will be removed from all DDEX websites. All schemas, standard texts, and supporting information about ERN -4.1, 4.2, and, of course, 4.3.1 will remain.