README

概览

Web Utilities 包旨在提供一些工具，以便快速轻松地执行常见的网络相关操作。

该包目前包含以下帮助程序：

• XML 生成和解析
• HTTP 请求生成和响应解析

此包已配置与 Composer 和 Laravel 集成，但您也可以轻松下载并独立使用这些重负载类。

安装

1. 执行 composer require vector88/webutils 将 webutils 包包含到您的 composer 项目中。

配置

如果您想使用此包与 Laravel 集成，您需要将一些条目添加到您的 config/app.php 文件中，以便使用提供者和外观。

<?php

'providers' => [
    ...
    Vector88\WebUtils\Providers\WebUtilsServiceProvider::class,
    ...
],

'aliases' => [
    ...
    'XmlHelper'          => Vector88\WebUtils\Facades\XmlHelper::class,
	'HttpRequestHelper'  => Vector88\WebUtils\Facades\HttpRequestHelper::class,
    ...
],

如果您不使用 Laravel，只需包含您想使用的 PHP 文件即可！您可以使用自动加载脚本或直接包含来执行此操作。

<?php

require __DIR__ . "/vendor/autoload.php";

use Vector88\WebUtils\XmlHelper;
use Vector88\WebUtils\HttpRequestHelper;

使用方法

HTTP 请求助手

HTTP 请求助手旨在使 HTTP 请求变得简单，适用于介于 file_get_contents 和 curl_setopt 之间的请求，许多 API 似乎都处于这种复杂性水平。

以下示例展示了大多数功能：

<?php

// Build a request (using Laravel with IOC)
$request = HttpRequestHelper::uri( $uri )
  ->authUsername( 'user' )
  ->authPassword( 'password' )
  ->method( 'POST' )
  ->header( 'Content-type', 'text/plain' )
  ->header( 'Cache-control', 'no-cache' )
  ->body( "Hello World! Here's some data..." );

// Execute the request
$response = $request->execute();

// If the request was successful:
if( $response->success ) {

  // Display the response code
  echo "{$response->code}<br />";

  // Display the response headers
  foreach( $response->headers as $header ) {
    echo "$header<br />";
  }

  // Display the response body
  echo "<br />";
  echo $response->body;

// Otherwise, if the request failed then display the error message and code
} else {
  echo "Request failed: {$response->errstr} ({$response->errno}).";

}

如果您不使用 Laravel，构建请求的步骤略有不同

<?php

// Build a request (not using Laravel)
$request = new HttpRequestHelper();
$request->uri( $uri )
  ...

XML 助手

XML 助手旨在使 XML 对象的处理变得简单。在文档级别，它能够

• 加载现有的 DOMDocument 实例
• 创建新的 XML 树
• 解析 XML 字符串
• 输出 XML 字符串

在节点级别，有一系列方法可用于轻松读取和写入节点。在读取方面，还有处理节点集合的方法。

请注意：如果无法获取值，大多数操作将简单地返回 NULL。

使用 XML 助手

如果您使用 Laravel 使用 XML 助手，可以利用 IOC 机制。

<?php
$xml = XmlHelper::loadStream( $xmlString );
...

如果您在 Laravel 之外使用 XML 助手，可以创建一个新的实例并从那里使用方法。

<?php
$xml = new XmlHelper();
$xml->loadStream( $xmlString );
...

加载 XML 字符串

<?php

// Load an XML String (using Laravel with IOC)
$xml = XmlHelper::loadStream( $xmlString );

使用现有的 DOMDocument

<?php

// Load a DOMDocument
$xml = XmlHelper::setElement( $document );

如果您有一个附加到 DOMDocument 的 DOMNode，您还可以这样做，将 DOMNode 作为许多 XmlHelper 可以执行的操作的“根元素”来处理

<?php

// Load a DOMNode
$xml = XmlHelper::setElement( $node );

创建一个新的 XML 对象

<?php

// Create an empty XML object (with a document element)
$xml = XmlHelper::create();

查找元素

假设我们有一个名为 $xml 的 XmlHelper 实例加载了以下 XML

<?xml version="1.0" encoding="utf-8"?>
<catalogue>
  <books>
    <book isbn="9780582186552">
      <title>Hobbit, The</title>
      <author>Tolkien, J. R. R.</author>
      <year>1937</year>
    </book>
    <book isbn="9780718179465">
      <title>Rachel Khoo's Kitchen Notebook</title>
      <author>Khoo, R.</author>
      <year>2015</year>
    </book>
  </books>
</catalogue>

检索单个元素

以下代码可以用来检索 <catalogue> 节点（作为 DOMNode 实例）

<?php
$catalogue = $xml->findFirst( 'catalogue' );

由于 XmlHelper 主要依赖于 DOMXPath，因此提供 XPath 字符串是完全可能的。要检索第一个书元素...

<?php
$book = $xml->findFirst( '//book' );

由于 XPath 就是 XPath，您可以用千万种方式检索相同的元素

<?php
$book = $xml->findFirst( '/catalogue/books/book' );
$book = $xml->findFirst( '//books/book[starts-with(@isbn, "97805")]' );
$book = $xml->findFirst( '/catalogue//book[contains(author, "kien")]' );
...

检索元素集合

我相信当您看到 findFirst 时，您已经知道也可能存在 findAll 方法。

<?php
$books = $xml->findAll( '//books' );

同样，此方法检索与检索到的元素对应的 DOMNode 条目。

检索元素的 XmlHelper

如果您希望检索用于搜索元素的 XmlHelper 实例，可以直接使用 helper() 方法获取一个

<?php
$catalogueHelper = $xml->helper( 'catalogue' );

请注意，helper() 方法并不完全等同于 findX() 方法：实际上，它会在处理之前将 ./ 预先添加到 XPath 中。这很方便，因为所有内容都相对于当前元素，但如果你试图做其他事情，那就不好了，因为所有内容都相对于当前元素。

./ 被添加的原因是它允许辅助函数在子节点级别上重用 - 也就是说，所有元素查询都将始终相对于当前的 DOMNode，而不是 DOMDocument 的根。

例如

<?php
// GOOD. Do this.
$bookHelper = $xml->helper( 'catalogue/books/book' );

// OK. Because './' gets prepended, this is actually acceptable.
$bookHelper = $xml->helper( '/book' );

// BAD. Don't do this.
$bookHelper = $xml->helper( ''//book' );

为元素检索多个 XmlHelper 实例

也可以检索一个包含对应 DOMNode 集合的 XmlHelper 实例数组...

<?php
$bookHelpers = $xml->helpers( 'catalogue/books/book' );

检索元素值

这是本库中非常有用的功能。如果你有一个围绕上述列出的 <book /> 元素之一的 XmlHelper 实例，你可以使用一些辅助方法来检索节点值。

<?php
// Retrieve a helper for the first book element that can be found
$book = $xml->helper( '/book' );

// Retrieve and display the book title and year
echo "Book Title: " . $book->string( "title" ) . "<br />";
echo "Year: " . $book->integer( "year" ) . "<br />";

如果你想一举完成，可以利用 XPath 的奇妙之处，间接定位元素。

<?php
$title = $xml->string( '/book/title' );
$year = $xml->integer( '/book/year' );

除了 string() 和 integer()，还有 float() 可以检索浮点值，以及 dateTime() 可以检索（你猜对了）日期时间元素。调用 dateTime() 需要第二个参数，即日期格式字符串。这个格式字符串与在 DateTime::createFromFormat() 中使用的是相同的，所以如果你不确定要放什么，可以查看它。

检索多个元素值

上述函数也有数组版本，允许你从所有匹配给定 XPath 的节点中获取给定类型的值数组。

<?php
$allBookTitles = $xml->strings( '/book/title' );
$allBookYears = $xml->integers( '/book/year' );

对于 floats() 和 dateTimes() 也是如此。

检索属性值

可能正如你所预期的

<?php
$book = $xml->helper( '/book' );
$isbn = $book->stringAttribute( 'isbn' );

另外还有 integerAttribute() 和 floatAttribute()。

DOM 操作

这里只有几个简单的方法，因为这不是本包原始目的的一部分（但你可以自由扩展它！）

<?php
$booksHelper = $xml->helper( '/catalogue/books' );

// Add (and get) a new book element to the books element
$newBookHelper = $booksHelper->add( 'book' );

// Use the XML helper to set some attributes and add additional children
$newBookHelper->setAttribute( 'isbn', '9780764555893' );
$newBookHelper->add( 'title', 'PHP and MySQL for Dummies' );
$newBookHelper->add( 'author', 'Valade, J' );
$newBookHelper->add( 'year', '2002' );

XML 字符串生成

使用 toString() 方法从底层文档生成一个 XML 字符串。请注意，XML 将从你使用的辅助函数的“根节点”生成。

<?php
$xmlString = $xml->toString();

待办事项：添加一种方法让你检索底层元素、根元素或这些事物的辅助函数，这样你就可以以某种方式回到根元素。

命名空间集成

XML 辅助函数能够处理命名空间中的元素。只需声明一个命名空间，然后使用你的命名空间前缀来处理该命名空间中的元素。

<?php
$xml = XmlHelper::loadStream( $xmlString );
$xml->withNamespace( "http://example.com/animals", "ns" );
$animals = $xml->findAll( "ns:animals/ns:animal" );

当使用 XML 辅助函数生成子或子元素时，命名空间将在生成时克隆并传递，因此你不需要在后续调用中重新声明命名空间。

<?php
$animalHelpers = $xml->helpers( "ns:animals/ns:animal" );
foreach( $animalHelpers as $animalHelper ) {
  echo $animalHelper->string( "ns:species" ) . "<br />";
  echo $animalHelper->string( "ns:subspecies" ) . "<br />";
}

很好，但我会用 DOMDocument 和 DOMXPath 做所有这些...

公平地说，这个辅助函数只是 DOMDocument 和 DOMXPath 的一个前端，但我做这个是因为我很懒（我知道这很讽刺）。