README

符合 WHATWG URL 规范的 URL 解析器，用于处理 URL 和它们的查询字符串。

此 API 提供了两个对象，您可以使用它们来帮助您处理 URL；《URL》和《URLSearchParams》。

演示

查看交互式演示 此处。

要求

• PHP >= 8.1
• ext-mbstring
• brick/math
• rowbot/idna

安装

composer require rowbot/url

URL

URL 对象是处理 URL 的主要对象。

URL 构造函数

URL(string|\Stringable $url[, null|string|\Stringable $base = null, array $options = []])

参数 $options 接受一个数组，其中有一个键 logger，其值为实现 \Psr\Log\LoggerInterface 的对象。有关更多信息，请参阅 日志记录。

URL 构造函数抛出

• \Rowbot\URL\Exception\TypeError
  • 当 URL 解析器确定提供的输入不是有效的 URL 时。

use Rowbot\URL\URL;

// Construct a new URL object.
$url = new URL('https://example.com/');

// Construct a new URL object using a relative URL, by also providing the constructor with the base URL.
$url = new URL('path/to/file.php?query=string', 'http://example.com');
echo $url->href; // Outputs: "http://example.com/path/to/file.php?query=string"

// You can also pass an existing URL object to either the $url or $base arguments.
$url = new URL('https://example.org:123');
$url1 = new URL('foo/bar/', $url);
echo $url1->href; // Outputs: "https://example.org:123/foo/bar/"

// Catch the error when URL parsing fails.
try {
    $url = new URL('http://2001::1]');
} catch (\Rowbot\URL\Exception\TypeError $e) {
    echo 'Invalid URL';
}

URL 成员

注意：为了方便起见，如果尝试获取或设置无效的属性，则 __get() 和 __set() 方法将抛出 \InvalidArgumentException。

string URL::href

getter href 返回 URL 的序列化。setter href 将解析整个字符串，使用新值更新 URL 的所有组件。提供无效的 URL 将导致 setter 抛出 \Rowbot\URL\TypeError。

readonly string URL::origin

成员 origin 是只读的。其输出形式为 scheme://host:port。如果 URL 没有端口，则将从输出中排除。

string URL::protocol

getter protocol，也称为方案，返回 URL 的协议，例如 http、ftp 或 ssh。setter protocol 用于更改 URL 的协议。

string URL::username

getter username 返回 URL 的用户名部分，如果 URL 不包含用户名，则为空字符串。setter username 更改 URL 的用户名。

string URL::password

getter password 返回 URL 的密码部分，如果 URL 不包含密码，则为空字符串。setter password 更改 URL 的密码。

string URL::host

getter host 返回 hostname 和 port 的组合。输出将类似于 hostname:port。如果 URL 没有端口，则端口将不出现在输出中。setter host 允许您同时更改 hostname 和 port。

string URL::hostname

getter hostname 返回 URL 的主机名。例如，https://example.com:31 的主机名将是 example.com。setter hostname 将更改 URL 的主机名部分。

string URL::port

getter port 返回表示 URL 端口的整数字符串。如果 URL 没有端口，则返回空字符串。setter port 更新 URL 的端口。

string URL::pathname

getter pathname 返回 URL 的路径。setter pathname 更新 URL 的路径。

string URL::search

search属性获取器返回URL的查询字符串。search属性设置器更新URL的URLSearchParams列表。

只读的URLSearchParams URL::searchParams

返回与此URL关联的URLSearchParams对象，允许您在不覆盖整个查询字符串的情况下修改查询参数。这将始终返回相同的对象。

string URL::hash

hash属性获取器，也称为URL的片段，返回跟在"#"字符后面的URL部分。hash属性设置器更新跟在"#"后面的URL部分。

bool URL::canParse(string|\Stringable $url[, null|string|\Stringable $base = null])

一个静态方法，允许用户快速检查一个URL是否可解析，而无需构造一个新的URL对象并在其中添加try/catch语句。

string URL::toJSON()

返回URL的JSON编码字符串。注意，此方法转义了正斜杠，这不是PHP的json_encode()的默认行为，但与JavaScript的JSON.stringify()的默认行为相匹配。如果您想控制序列化，请将URL对象传递给json_encode()函数。

string URL::jsonSerialize()

URL对象实现了JsonSerializable接口，允许您将整个对象传递给json_encode()函数。

string URL::toString()

返回URL的序列化表示。

string URL::__toString()

参见 URL::toString()

URLSearchParams

URLSearchParams对象允许您在不需要完整的URL时处理查询字符串。URLSearchParams对象实现了Iterator接口，以便您可以遍历搜索参数列表。迭代器将返回一个包含正好2个项目的数组。第一个项目是参数名称，第二个项目是参数值。

The URLSearchParams constructor

URLSearchParams([iterable<int|string, array<int|string, scalar|\Stringable>|(\Traversable<int|string, scalar|\Stringable>&\Countable)>|object|string|\Stringable $init])

URLSearchParams构造函数抛出

• \Rowbot\URL\Exception\TypeError
  • 当传递一个可迭代对象并且它的某个值不是可迭代的。
  • 当传递一个可迭代对象并且它的某个值不是可计数的，例如，实现了\Iterator但没有实现\Countable的对象。
  • 当传递一个可迭代对象并且它的某个序列不包含正好2个项目，例如，只包含1个字符串的数组。

use Rowbot\URL\URLSearchParams;

// Construct an empty list of search params.
$params = new URLSearchParams();

// Construct a new list from a query string. Remember that a leading "?" will be stripped.
$params = new URLSearchParams('?foo=bar');

// Construct a new list using an array of arrays containing strings. Alternatively, you could pass an
// object that implements the Traversable interface and whose iterator returns an array of arrays,
// with each array containing exactly 2 items.
$params = new URLSearchParams([
    ['foo', 'bar'],
    ['foo', 'bar'] // Duplicates are allowed!
    ['one', 'two']
]);

// Iterate over a URLSearchParams object.
foreach ($params as $index => $param) {
    if ($index > 0) {
        echo '&';
    }

    echo $param[0] . '=' . $param[1];
}

// Above loop prints "foo=bar&foo=bar&one=two".

// Construct a new list using an object
$obj = new \stdClass();
$obj->foo = 'bar';
$params = new URLSearchParams($obj);

// Copy an existing URLSearchParams object into a new one.
$params1 = new URLSearchParams($params);

URLSearchParams成员

void URLSearchParams::append(string $name, string $value)

向列表中追加一个新名称-值对。

void URLSearchParams::delete(string $name[, string $value])

从列表中删除所有名称为$name的名称-值对。如果提供了可选的$value，则仅删除具有相同名称和值的对。

string|null URLSearchParams::get(string $name)

返回列表中第一个名称为$name的名称-值对的值，如果列表中没有名称为$name的名称-值对，则返回null。

string[] URLSearchParams::getAll(string $name)

返回所有名称为$name的名称-值对的值列表，按列表顺序排列，如果列表中没有名称为$name的名称-值对，则返回空列表。

bool URLSearchParams::has(string $name[, string $value])

如果列表中存在名称-值对，则返回true，否则返回false。

void URLSearchParams::set(string $name, string $value)

如果列表中包含名称为$name的名称-值对，则列表中第一个名称为$name的名称-值对的值将更改为$value，并且列表中后续的名称-值对将被删除。如果列表中没有名称为$name的名称-值对，则新名称-值对将被追加到列表中。

void URLSearchParams::sort()

通过比较代码单元对搜索参数列表进行排序。具有相同名称的名称-值对的相对顺序被保留。

string URLSearchParams::toString()

返回名称-值对列表的序列化。

int URLSearchParams::$size

返回列表中查询参数的数量。

string URLSearchParams::__toString()

参见 URLSearchParams::toString()

日志记录

给定的记录器记录验证错误。级别为 warning 的条目是导致解析器失败的致命错误。级别为 notice 的条目不是致命的。所有验证错误都有一个 input 键和 column 或 column_range 偏移量键。列偏移量从 1 开始。

日志记录上下文