URL の操作

Url、UrlImmutable、UrlScriptのクラスは、URL の生成、解析、加工を簡単にします。

→ インストールと要件

Url

Nette\Http\Urlクラスは、URL とその個々の部分を簡単に扱えるようにします。図のとおりです。

scheme  user  password  host   port    path        query  fragment
  |      |      |        |      |       |            |       |
/--\   /--\ /------\ /-------\ /--\/----------\ /--------\ /----\
http://john:xyz%2A12@nette.org:8080/en/download?name=param#footer
\______\__________________________/
    |               |
 hostUrl        authority

URL の生成は直感的です。

use Nette\Http\Url;

$url = new Url;
$url->setScheme('https')
	->setHost('localhost')
	->setPath('/edit')
	->setQueryParameter('foo', 'bar');

echo $url; // 'https://localhost/edit?foo=bar'

URL を解析してから加工することもできます。

$url = new Url(
	'http://john:xyz%2A12@nette.org:8080/en/download?name=param#footer',
);

Url クラスは JsonSerializable インターフェースを実装し、__toString() メソッドを持つので、このオブジェクトはそのまま出力できますし、json_encode() に渡すデータの中でも使えます。

echo $url;
echo json_encode([$url]);

URL の部分

URL の個々の部分を取り出したり変えたりするのに、次のメソッドが使えます。

getUser()、getPassword()、setUser()、setPassword() のメソッドは非推奨です。資格情報を URL に直接埋め込むことは勧められないからです。

注意: HTTP のリクエストから得た URL を扱うときは、ブラウザがフラグメントをサーバーへ送らないので、そこにフラグメントは入っていないことを忘れないでください。

個々のクエリのパラメータも次のもので扱えます。

getDomain (int $level = 2): string

ホストの右側または左側の部分を返します。ホストが www.nette.org のときの働きは次のとおりです。

isEqual (string|Url $url): bool

2 つの URL が同一かを調べます。

$url->isEqual('https://nette.org');

canonicalize()

URL を正式な形に変えます。ホスト名を小文字にし、パスを整えます（パーセントの符号化と余計な文字の除去）。クエリの文字列はそのままです。

Url::isAbsolute (string $url): bool

URL が絶対かを調べます。URL はスキーム（たとえば http、https、ftp）とそれに続くコロンで始まるとき、絶対と見なされます。

Url::isAbsolute('https://nette.org');    // true
Url::isAbsolute('//nette.org');          // false

Url::removeDotSegments (string $path): string

特別な部分 . と .. を取り除いて URL のパスを整えます。このメソッドは、ウェブブラウザと同じやり方で余計なパスの要素を取り除きます。

Url::removeDotSegments('/path/../subtree/./file.txt');  // '/subtree/file.txt'
Url::removeDotSegments('/../foo/./bar');                // '/foo/bar'
Url::removeDotSegments('./today/../file.txt');          // 'file.txt'

UrlImmutable

Nette\Http\UrlImmutableクラスは Urlクラスの、変更できない側の選択肢です（PHP で DateTimeImmutable が DateTime の変更できない側の選択肢であるのと同じです）。セッターの代わりに wither があり、それはオブジェクトを変えずに、値を変えた新しいインスタンスを返します。

use Nette\Http\UrlImmutable;

$url = new UrlImmutable(
	'https://nette.org:8080/en/download?name=param#footer',
);

$newUrl = $url
	->withHost('example.com')
	->withPath('/en/')
	->withQueryParameter('name', 'value');

echo $newUrl; // 'https://example.com:8080/en/?name=value#footer'

UrlImmutable クラスは JsonSerializable インターフェースを実装し、__toString() メソッドを持つので、このオブジェクトはそのまま出力できますし、json_encode() に渡すデータの中でも使えます。

echo $url;
echo json_encode([$url]);

URL の部分

URL の個々の部分を取り出したり変えたりするのに、次のメソッドが使えます。

getUser()、getPassword()、withUser()、withPassword()、withoutUserInfo() のメソッドは非推奨です。資格情報を URL に直接埋め込むことは勧められないからです。

個々のクエリのパラメータも次のもので扱えます。

getDomain (int $level = 2): string

ホストの右側または左側の部分を返します。ホストが www.nette.org のときの働きは次のとおりです。

resolve (string $reference): UrlImmutable

ブラウザが HTML のページのリンクを処理するのと同じやり方で、絶対 URL を解決します。

• リンクが絶対 URL（スキームを含む）なら、そのまま使われます
• リンクが // で始まるなら、今の URL のスキームだけが受け継がれます
• リンクが / で始まるなら、ドメインの根からの絶対パスが作られます
• そのほかの場合、URL は今のパスからの相対で組み立てられます

$url = new UrlImmutable('https://example.com/path/page');
echo $url->resolve('../foo');           // 'https://example.com/foo'
echo $url->resolve('/bar');             // 'https://example.com/bar'
echo $url->resolve('sub/page.html');    // 'https://example.com/path/sub/page.html'

isEqual (string|Url $url): bool

2 つの URL が同一かを調べます。

$url->isEqual('https://nette.org');

UrlScript

Nette\Http\UrlScriptクラスは UrlImmutableの子孫で、プロジェクトの根のディレクトリなど、仮想的な URL の部分をさらに足します。親のクラスと同じく、変更できないオブジェクトです。

次の図は UrlScript が見分ける部分を示します。

     baseUrl    basePath  relativePath  relativeUrl
        |          |        |               |
/---------------/-----\/--------\---------------------------\
http://nette.org/admin/script.php/pathinfo/?name=param#footer
                \_______________/\________/
                       |              |
                  scriptPath       pathInfo

• baseUrl はアプリケーションの基本の URL で、ドメインとアプリケーションの根のディレクトリまでのパスの部分を含みます
• basePath はアプリケーションの根のディレクトリまでのパスの部分です
• scriptPath は今のスクリプトへのパスです
• relativePath は basePath からの相対でのスクリプトの名前（とそれに続くパスの部分）です
• relativeUrl は baseUrl のあとの URL の部分すべてで、クエリの文字列とフラグメントも含みます
• pathInfo は今ではめったに使われない、スクリプトの名前のあとの URL の部分です

これらの URL の部分を取り出すのに、次のメソッドが使えます。

ふつう UrlScript オブジェクトを自分で作ることはありません。代わりに Nette\Http\Request::getUrl()メソッドが、今の HTTP のリクエストに合わせて各部分が正しく設定されたものを返します。