IDLeDOM

IDLeDOM is a set of PHP interfaces automatically generated from the HTML DOM API, based on a rigorous PHP binding of the WHATWG WebIDL specification. It is not a DOM implementation (look at Dodo for that), merely the interfaces that a compatible DOM library will implement. It does contain a set of helpers and stubs for common functionality.

It uses wikimedia/webidl to parse the upstream DOM spec, but this is not required at runtime.

Installation edit

In MediaWiki edit

IDLeDOM will become available in MediaWiki as a composer dependency of wikimedia/parsoid (via wikimedia/dodo) when the Dodo library is mature.

Everywhere else edit

Install the wikimedia/idle-dom package from Packagist:

composer require wikimedia/idle-dom

Semantic versioning is used.

The major version number will be incremented for every change that breaks backwards compatibility.

Architecture overview edit

For full reference documentation, please see the documentation generated from the source (or the source itself)

Generated API documentation

WebIDL binding edit

The full PHP binding is documented in WebIDL.md in the source tree. It is intended to be largely compatible with the ad hoc binding used for the PHP built-in DOM extension. Explicit getter and setter functions are used for attributes, but PHP magic methods are used to allow property-style access. The best performance will be obtained by using the explicit getters and setters, however.

Writing a new DOM implementation edit

To write a new DOM implementation you will be implementing the interface types in Wikimedia\IDLeDOM. This library provides two traits for most interfaces in order to ease the task:

The helper trait in Wikimedia\IDLeDOM\Helper will implement the magic __get and __set methods for interfaces and dictionaries, ArrayAccess methods for dictionaries, the magic __invoke method for callback classes, and cast methods for callbacks and dictionaries to turn a callable and associative-array, respectively, into the proper callback or dictionary type. The helper will also implement Countable and IteratorAggregate where appropriate.
The stub trait in Wikimedia\IDLeDOM\Stub will stub out all methods of the interface by implementing them to throw the exception returned by ::_unimplemented() (which can be your own subclass of DOMException or whatever you like). This helps bootstrap a DOM implementation and ensures that new methods can be added to the DOM spec, and by extension to the IDLeDOM interfaces, without breaking code which implements these interfaces.

Putting these together, the first few lines of a typical DOM implementation will look something like this:

// Your implementations of DOM mixins are traits, like this:
trait NonElementParentNode /* implements \Wikimedia\IDLeDOM\NonElementParentNode */ {
	use \Wikimedia\IDLeDOM\Stub\NonElementParentNode;

	// Your code here...
}

// DOM interfaces are classes:
class Document extends Node implements \Wikimedia\IDLeDOM\Document {
	// DOM mixins: these are your code, but they include
	// the appropriate IDLeDOM stubs
	use DocumentOrShadowRoot;
	use NonElementParentNode;
	use ParentNode;
	use XPathEvaluatorBase;

	// Stub out methods not yet implemented.
	use \Wikimedia\IDLeDOM\Stub\Document;

	// Helper functions from IDLeDOM
	use \Wikimedia\IDLeDOM\Helper\Document;

	protected function _unimplemented() : \Exception {
		return new UnimplementedException(); // your own exception type
	}

	// Your code here...
}

Hacking on IDLeDOM edit

To regenerate the interfaces in src/ from the WebIDL sources in spec/:

composer build

To run tests:

composer test