README

PHP 文档对象模型 (DOM) 的功能增强

概述

此包扩展了现有的 PHP DOM，添加了核心库中缺失的功能。最重要的和最有用的功能是使用 XPath 自动选择一个或多个节点、设置元素或属性值以及获取这些元素或属性值。ElementNode 也有所扩展，以自动化创建子节点，包括一些常见 HTML/XHTML 元素节点的快捷方式。

安装

composer require sterlingdesign/DOM

基本用法

以下是一些功能示例（请参阅 test/testdom.php）

<?php
require_once __DIR__ . "/../../../autoload.php";

$oDoc = new \Sterling\DOM\Document();

// selectSingleElement(string $strXPath, bool $bCreateIfNotPresent)
//
// $strXPath - The first parameter is the XPath to the element to get.
// $bCreateIfNotPresent - The second parameter, when set to 'true',
//   will create the element if it does not exist, if possible.
//   Note: yes, you could give an XPath that doesn't evaluate to
//   a specific element, but the function will return NULL.

$oRoot = $oDoc->selectSingleElement("/root", true);

// ElementNode::createChild(string $strFQN, string $strVal [,less common params]);
//
// creates an element node named "foo" under the $oRoot ElementNode,
// and sets it's value to "bar 1"
$oFoo1 = $oRoot->createChild("foo", "bar 1");
// creates another child element of $oRoot:
$oFoo2 = $oRoot->createChild("foo", "bar 2");

// setValue(string|bool|int|float $val, string $strXPath = ".")
//
// The first parameter is the POD type value to set.
// The second parameter is the XPath of the element to set the value.
$oRoot->setValue("bar X", "hello");
// If the first parameter is a bool, the bool is converted to
// the string "true" if true, or "false" if false.  This is for
// readability of the resulting XML.
$oRoot->setValue(true, "world");
// Numbers are saved by strval($num)
$oRoot->setValue(3.14, "PiAproximation");

// There are also specific functions for specific POD types for
// getting and setting values: setIntValue, setFloatValue, setBoolValue,
// and setStringValue
$oBool = $oRoot->createChild("MyBool");
$oBool->setBoolValue(false);

// When retrieving values from a DOM, a return value of NULL
// indicates that the element or attribute was not found:
$valMyOtherBool = $oRoot->getBoolValue("MyOtherBool");
if(is_null($valMyOtherBool))
  echo "my-other-bool Was Not Set!!" . PHP_EOL;

// Most of the time, you don't want to have to deal with the
// possiblity of a NULL return value, and you probably have
// a DEFAULT value for those cases.  The second parameter
// to any of the getXXXValue functions is a default
// value to be returned if the node does not exist.
// This way, the return value is guaranteed to be of the
// expected type
$valMyOtherBool = $oRoot->getBoolValue("MyOtherBool", false);
echo "MyOtherBool is " . ($valMyOtherBool ? "true" : "false") . PHP_EOL;

// You can create a deeper tree of elements:
$oRoot->setValue("Deep Value", "my/deep/path");
// and also set attribute values of elements
$oRoot->setValue("Deep Attribute Value", "my/deep/path/@myAttribute");

// If there are more than one sibling elements with the
// same name, the retrieved element is the first
// element in document order
$oFoo1 = $oRoot->selectSingleElement("foo");
if(is_object($oFoo1))
  echo $oFoo1->getStringValue() . PHP_EOL;
else
  echo "There are no foo elements" . PHP_EOL;


// You can get the value of XPath expressions
echo "There are " . $oRoot->getStringValue("count(foo)") . " foo elements under the document root". PHP_EOL;
// or use XPath to select a specific element
$oFoo2 = $oRoot->selectSingleElement("foo[2]");
if(is_object($oFoo2))
  echo "The value of the second foo element is: '{$oFoo2->getStringValue()}'" . PHP_EOL;
else
  echo "The second foo element does not exists" . PHP_EOL;

echo PHP_EOL . "*** DOCUMENT ***" . PHP_EOL;
$oDoc->formatOutput = true;
echo $oDoc->saveXML();

安全注意事项

很可能，这些基本用法功能没有包含在基础 libxml（或 PHP\DOM）库中，因为如果误用，这些类型的函数可能导致安全问题。

首先，了解 XPath 的工作原理非常重要。不要在您的代码中放置不合理的 xpath 语句。

其次，不要允许用户输入进入您的 XPath 语句：始终使用硬编码或由程序员生成的 XPath 语句，永远不要从用户输入中获取，除非有极端的偏见。

只需一点常识，我们相信这些增强的价值将变得明显，即使对于那些尚未自行实施类似功能的人来说也是如此。

路线图

到目前为止，此库只被有限数量的开发者使用，因此很可能存在我们尚未遇到的错误，因为我们使用模式的方式可能与您不同。最初发布的主要重点是解决任何明显的问题。

还有一些已知的改进有望在下一个主要版本发布中实现。

除此之外，维护与 libxml/libxsl 的兼容性将是主要目标。新功能/破坏性更改将有可能实现，但只有在它们听起来像好主意的情况下。

感谢您的关注，祝您成功

同时感谢数百名男性和女性为这些技术的实现而努力工作。希望将来能够添加一些致谢，但名单会很长。