README

解析、修改和构建 URL。

内容

• 特性
• 需求
• 用法
  • 创建新的 URL
  • 解析 URL
  • 获取 URL 组件
  • 获取查询参数
  • 操作查询参数
    • 设置单个参数
    • 删除单个参数
    • 设置多个参数
    • 替换所有参数
    • 删除所有参数
  • 构建 URL
    • 使用 build() 或 __toString()
    • 使用 buildAbsolute()
    • 使用 buildRelative()

特性

• 解析 URL
• 构建相对和绝对 URL，包括协议相对 URL
• 获取、检查和设置单个 URL 组件
  • 方案
  • 主机
  • 端口
  • 路径
  • 查询参数
  • 片段

需求

• PHP 7.1+

用法

创建新的 URL

创建一个新的 Url 实例，并使用构造函数参数或设置器来定义组件

<?php

use Kuria\Url\Url;

$url = new Url();

$url->setScheme('http');
$url->setHost('example.com');
$url->setPath('/test');
// many more setters are available..

echo $url;

输出

http://example.com/test

解析 URL

<?php

use Kuria\Url\Url;

$url = Url::parse('http://example.com:8080/test?foo=bar&lorem=ipsum#fragment');

技巧

如果您想确定当前请求的 URL，可以使用与 kuria/url 集成的 kuria/request-info 组件。

注意

支持解析包含用户名和密码的 URL，但这些组件会被忽略。

根据 RFC 3986，此类 URL 已被弃用。

获取 URL 组件

var_dump(
    $url->getScheme(),
    $url->getHost(),
    $url->getFullHost(),
    $url->getPort(),
    $url->getPath(),
    $url->getQuery(),
    $url->getFragment()
);

// checking whether a certain component is defined
var_dump(
    $url->hasScheme(),
    $url->hasHost(),
    $url->hasPort(),
    $url->hasPath(),
    $url->hasQuery(),
    $url->hasFragment()
);

输出

string(4) "http"
string(11) "example.com"
string(16) "example.com:8080"
int(8080)
string(5) "/test"
array(2) {
  ["foo"]=>
  string(3) "bar"
  ["lorem"]=>
  string(5) "ipsum"
}
string(8) "fragment"
bool(true)
bool(true)
bool(true)
bool(true)
bool(true)
bool(true)

获取查询参数

<?php

use Kuria\Url\Url;

$url = Url::parse('/test?foo=bar&lorem%5B0%5D=ipsum&lorem%5B1%5D=dolor');

var_dump(
    $url->has('foo'),
    $url->has('nonexistent'),
    $url->get('foo'),
    $url->get('lorem'),
    $url->get('nonexistent')
);

输出

bool(true)
bool(false)
string(3) "bar"
array(2) {
  [0]=>
  string(5) "ipsum"
  [1]=>
  string(5) "dolor"
}
NULL

操作查询参数

设置单个参数

<?php

$url->set('parameter', 'value');

删除单个参数

<?php

$url->remove('foo');

设置多个参数

<?php

$url->add(['foo' => 'bar', 'lorem' => 'ipsum']);

替换所有参数

<?php

$url->setQuery(['foo' => 'bar']);

删除所有参数

<?php

$url->removeAll();

构建 URL

使用 build() 或 __toString()

这些方法将返回绝对或相对 URL。

• 如果没有指定主机，将返回相对 URL
• 如果指定了主机，将返回绝对 URL（除非将 首选格式选项 设置为相对）

<?php

use Kuria\Url\Url;

$url = new Url();

$url->setPath('/test');

var_dump($url->build());

$url->setScheme('http');
$url->setHost('example.com');

var_dump($url->build());

输出

string(5) "/test"
string(23) "http://example.com/test"

指定首选格式

默认情况下，如果指定了主机，则 build() 和 __toString() 返回绝对 URL。

可以通过将 $preferredFormat 参数传递给构造函数、Url::parse() 或 setPreferredFormat() 方法来更改此行为。

• Url::RELATIVE - 即使指定了主机也优先生成相对 URL
• Url::ABSOLUTE - 如果指定了主机，则优先生成绝对 URL

<?php

use Kuria\Url\Url;

$url = Url::parse('http://example.com/foo');

// print URL using the default preferred format (absolute)
echo $url, "\n";

// set the preferred format to relative
$url->setPreferredFormat(Url::RELATIVE);

echo $url, "\n";

输出

http://example.com/foo
/foo

使用 buildAbsolute()

此方法始终返回绝对 URL。

如果没有定义主机，将抛出 Kuria\Url\Exception\IncompleteUrlException。

<?php

use Kuria\Url\Url;

$url = new Url();

$url->setScheme('http');
$url->setHost('example.com');
$url->setPath('/test');

var_dump($url->buildAbsolute());

输出

string(23) "http://example.com/test"

注意

使用未定义方案的绝对 URL 将产生协议相对 URL。

示例： //localhost/test

使用 buildRelative()

此方法始终返回相对 URL，无论是否定义了主机。

<?php

use Kuria\Url\Url;

$url = new Url();

$url->setScheme('http');
$url->setHost('example.com');
$url->setPath('/test');

var_dump($url->buildRelative());

输出

string(5) "/test"