README

IDLeDOM

IDLeDOM 是一套 PHP 接口，用于自动从 WHATWG DOM 规范中的 WebIDL 源文件生成的，使用 WebIDL 的 PHP 绑定。

PHP 绑定在 WebIDL.md 中描述。它旨在与用于 PHP 内置 DOM 扩展的临时绑定大部分兼容。对于属性，使用显式的获取器和设置器函数，但使用 PHP 魔术方法以允许属性样式访问。然而，通过使用显式的获取器和设置器可以获得最佳性能。

IDLeDOM 不是一个 DOM 实现，它只是一套接口。实际的 DOM 实现如 mediawiki/dodo 将实现 IDLeDOM 定义的接口。客户端代码可以编写以与任何遵循 IDLeDOM PHP 绑定 WebIDL 的 DOM 实现一起工作。

IDLeDOM 包含了可以极大地帮助 DOM 实现的存根和辅助特质。将存根特质包含在您的 DOM 实现中将确保新添加到 IDLeDOM 中的方法将默认使用存根（抛出用户定义的异常），而不是由于未实现的新接口方法而破坏您的实现。在您的 DOM 实现中包含辅助特质将提供某些 PHP 魔术方法和 IDL "属性反射" 属性的实现。

有关该库的更多文档可以在 MediaWiki.org 上找到。

安装

此软件包可在 Packagist 上获取

$ composer require wikimedia/idle-dom

使用方法

当您希望与任何 PHP DOM 实现兼容时，请使用 Wikimedia\IDLeDOM\ 中的接口类型。例如，假设您的 DOM 实现提供了一个实现 Wikimedia\IDLeDOM\DOMImplementation 的对象，称为 $domImpl

$doc = $domImpl->createHTMLDocument( 'My HTML Document );
$doc->getBody()->setInnerHTML( '<p>Whee!!</p> );
// This is equivalent, but slightly slower:
$doc->body->innerHTML = '<p>Whee!!</p>';

// Use the interface type in type hints for max compatibility
$f = function( \Wikimedia\IDLeDOM\Document $doc ): string {
	return $doc->getTitle(); // or $doc->title
};

编写新的 DOM 实现

要编写新的 DOM 实现，您将实现 Wikimedia\IDLeDOM 中的接口类型。此库为大多数接口提供了两个特质，以简化任务

Wikimedia\IDLeDOM\Helper 中的辅助特质将为接口和字典实现魔术 __get 和 __set 方法，为字典实现 ArrayAccess 方法，为回调类实现魔术 __invoke 方法，并为回调和字典实现 cast 方法，将 callable 和关联数组分别转换为适当的回调或字典类型。辅助类将根据需要实现 Countable 和 IteratorAggregate。对于反映元素属性的 IDL 接口，辅助类还将使用 Element::getAttribute()、Element::hasAttribute() 和 Element::setAttribute() 调用来实现这些反射接口属性。
Wikimedia\IDLeDOM\Stub中的stub trait会通过实现接口并抛出由::_unimplemented()返回的异常（可以是您的自己的DOMException子类或其他您喜欢的类）来模拟接口的所有方法。这有助于启动DOM实现，并确保可以添加新的方法到DOM规范中，进而扩展到IDLeDOM接口，而不会破坏实现这些接口的代码。

将这些放在一起，一个典型的DOM实现的开始几行可能看起来像这样

// 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
	// (Note that the Document helper will also include reflected
	// attribute accessors for the mixin classes; you don't need
	// to include helper traits in your implementations of DOM mixins)
	use \Wikimedia\IDLeDOM\Helper\Document;

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

	// Your code here...
}

在IDLeDOM上进行修改

从spec/中的WebIDL源代码重新生成src/中的接口

composer build

运行测试

composer test

许可和致谢

此代码根据MIT许可证分发；有关更多信息，请参阅LICENSE。

wikimedia / idle-dom

维护者

详细信息