Kit UrlParserダウンロード - Kit UrlParserソースコードのダウンロード

Kit UrlParser

その他のカテゴリー

Version 2.2.0

ダウンロード

RFC 3986 URL パーサー

UrlParserは、RFC 3986 準拠の URL パーサーと PSR-7 互換の URI コンポーネントを提供する PHP ライブラリです。このライブラリの目的は、いくつかの微妙な点で仕様と異なる組み込み関数parse_url()とは異なり、RFC 仕様を正確に実装するパーサーを提供することです。

このライブラリには主に 2 つの目的があります。解析された URL からの情報を最初に提供します。これを実現するために、ライブラリは PSR-7 の標準 URI 処理インターフェイスを実装し、一般的に使用される情報を URL から簡単に取得できる追加メソッドも提供します。 2 番目の目的は、一部のタスクをより簡単にするいくつかの追加メソッドに加えて、PSR-7 標準のインターフェイスを使用して URL を変更できるようにすることです。

このライブラリは主に URL の解析を目的としていますが、解析は単に一般的な URI 構文に基づいています。したがって、このライブラリを使用して、他のタイプの URI を汎用構文に対して検証および解析することができます。ライブラリは、URL に対してスキーム固有の検証を実行しません。

このライブラリには、デフォルトの RFC 3986 準拠モードに加えて、URL のさまざまなコンポーネントに UTF-8 文字を含む URL を解析しながら、適切なパーセントエンコードおよび IDN ASCII 形式に変換できるオプションも用意されています。

API ドキュメントは http://kit.riimu.net/api/urlparser/ から入手できます。

要件

サポートされる最小 PHP バージョンは 5.6 です
このライブラリは、次の外部 PHP ライブラリに依存します。
- psr/http-message ( ^1.0 )
ライブラリは次の PHP 拡張機能に依存します。
- intl (必要な IDN サポートのみ)

インストール

Composer を使用したインストール

このライブラリをインストールする最も簡単な方法は、Composer を使用して依存関係を処理することです。 Composer 経由でこのライブラリをインストールするには、次の 2 つの手順に従ってください。

プロジェクトルートで Composer コマンドラインインストールを実行して、 composer.pharを取得します。
インストールスクリプトを実行すると、 composer.pharファイルがプロジェクトルートに存在し、次のコマンドを実行できるようになります。
```
 php composer.phar require "riimu/kit-urlparser:^2.1"
```

Composer 経由でこのライブラリをインストールした後、インストール中に Composer によって生成されたvendor/autoload.phpファイルを含めることでライブラリをロードできます。

ライブラリを依存関係として追加する

Composer の使用方法にすでに慣れている場合は、次のcomposer.jsonファイルをプロジェクトに追加し、 composer installコマンドを実行することで、ライブラリを依存関係として追加することもできます。

{
    "require" : {
        "riimu/kit-urlparser" : " ^2.1 "
    }
}

手動インストール

Composer を使用してライブラリをロードしたくない場合は、最新リリースをダウンロードし、 srcフォルダーをプロジェクトに抽出することで、ライブラリを手動でダウンロードすることもできます。次に、提供されたsrc/autoload.phpファイルをインクルードして、ライブラリクラスをロードできます。

Composer を使用すると、他の必要な PHP ライブラリも自動的にダウンロードされることに注意してください。このライブラリを手動でインストールする場合は、他の必要なライブラリも使用できるようにする必要があります。

使用法

このライブラリの使用は比較的簡単です。このライブラリは、URL 解析クラスUriParserと、URL を表す不変値オブジェクトクラスUriを提供します。 URL を解析するには、 UriParserのparse()メソッドに URL を文字列として指定するだけで、解析された URL から生成されたUriのインスタンスが返されます。

例えば：

 <?php

require ' vendor/autoload.php ' ;

$ parser = new  Riimu  Kit  UrlParser  UriParser ();
$ uri = $ parser -> parse ( ' http://www.example.com ' );

echo $ uri -> getHost (); // Outputs 'www.example.com'

あるいは、 UriParserの使用を完全にスキップし、単純に URL をコンストラクターパラメーターとしてUriに指定することもできます。

 <?php

require ' vendor/autoload.php ' ;
$ uri = new  Riimu  Kit  UrlParser  Uri ( ' http://www.example.com ' );
echo $ uri -> getHost (); // Outputs 'www.example.com'

parse()メソッドとコンストラクターの使用の主な違いは、指定された URL が有効な URL でない場合、 parse()メソッドはnullを返すのに対し、コンストラクターはInvalidArgumentExceptionをスローすることです。

URL からさまざまなタイプの情報を取得するために、 Uriクラスにはさまざまなメソッドが用意されています。使用可能なさまざまな方法の概要として、簡単な例を次に示します。

 <?php

require ' vendor/autoload.php ' ;

$ parser = new  Riimu  Kit  UrlParser  UriParser ();
$ uri = $ parser -> parse ( ' http://jane:[email protected]:8080/site/index.php?action=login&prev=index#form ' );

echo $ uri -> getScheme () . PHP_EOL ;         // outputs: http
echo $ uri -> getUsername () . PHP_EOL ;       // outputs: jane
echo $ uri -> getPassword () . PHP_EOL ;       // outputs: pass123
echo $ uri -> getHost () . PHP_EOL ;           // outputs: www.example.com
echo $ uri -> getTopLevelDomain () . PHP_EOL ; // outputs: com
echo $ uri -> getPort () . PHP_EOL ;           // outputs: 8080
echo $ uri -> getStandardPort () . PHP_EOL ;   // outputs: 80
echo $ uri -> getPath () . PHP_EOL ;           // outputs: /site/index.php
echo $ uri -> getPathExtension () . PHP_EOL ;  // outputs: php
echo $ uri -> getQuery () . PHP_EOL ;          // outputs: action=login&prev=index
echo $ uri -> getFragment () . PHP_EOL ;       // outputs: form

print_r ( $ uri -> getPathSegments ());    // [0 => 'site', 1 => 'index.php']
print_r ( $ uri -> getQueryParameters ()); // ['action' => 'login', 'prev' => 'index']

Uriコンポーネントには、URL を変更するためのさまざまなメソッドも用意されており、これにより、別のコンポーネントから新しい URL を構築したり、既存の URL を変更したりできます。 Uriコンポーネントは不変の値オブジェクトであることに注意してください。これは、各変更メソッドが既存の Uri インスタンスを変更するのではなく、新しいUriインスタンスを返すことを意味します。以下は、コンポーネントから URL を構築する簡単な例です。

 <?php

require ' vendor/autoload.php ' ;

$ uri = ( new  Riimu  Kit  UrlParser  Uri ())
    -> withScheme ( ' http ' )
    -> withUserInfo ( ' jane ' , ' pass123 ' )
    -> withHost ( ' www.example.com ' )
    -> withPort ( 8080 )
    -> withPath ( ' /site/index.php ' )
    -> withQueryParameters ([ ' action ' => ' login ' , ' prev ' => ' index ' ])
    -> withFragment ( ' form ' );

// Outputs: http://jane:[email protected]:8080/site/index.php?action=login&prev=index#form
echo $ uri ;

前の例からわかるように、 Uriコンポーネントは URL を文字列として提供する__toString()メソッドも提供します。

情報の取得

URL から情報を取得するためにUriコンポーネントが提供するメソッドのリストを次に示します。

getScheme() URL からスキームを返すか、URL にスキームがない場合は空の文字列を返します。
getAuthority()ユーザー名、パスワード、ホスト名、ポートで構成されるコンポーネントを URL からuser-info@hostname:portの形式で返します。
getUserInfo()コロンで区切られたユーザー名とパスワードを含むコンポーネントを URL から返します。
getUsername() URL からデコードされたユーザー名を返すか、URL にユーザー名が存在しない場合は空の文字列を返します。
getPassword() 、URL からデコードされたパスワードを返すか、URL にパスワードが存在しない場合は空の文字列を返します。
getHost() URL からホスト名を返すか、URL にホストがない場合は空の文字列を返します。
getIpAddress()ホストが IP アドレスの場合、ホストから IP アドレスを返します。それ以外の場合、このメソッドはnullを返します。 IPv6 アドレスが指定された場合、アドレスは括弧なしで返されます。
getTopLevelDomain()ホストからトップレベルのドメインを返します。ホストが存在しない場合、またはホストが IP アドレスである場合は、代わりに空の文字列が返されます。
getPort() URL からポートを返します。URL にポートが存在しない場合はnullを返します。このメソッドは、ポートが現在のスキームの標準ポート (たとえば、http の場合は 80) である場合にもnullを返します。
getStandardPort()現在のスキームの標準ポートを返します。スキームがない場合、またはスキームの標準ポートが不明な場合は、代わりにnullが返されます。
getPath() 、URL からのパスを返すか、URL にパスがない場合は空の文字列を返します。
getPathSegments()デコードされたパスセグメント (つまり、各スラッシュで分割されたパス) の配列を返します。空のパスセグメントは破棄され、返される配列には含まれません。
getPathExtension()パスからファイル拡張子を返すか、URL にパスがない場合は空の文字列を返します。
getQuery() 、URL からクエリ文字列を返すか、URL にクエリ文字列がない場合は空の文字列を返します。
getQueryParameters() parse_str()関数を使用して URL からクエリ文字列を解析し、解析された値の配列を返します。
getFragment() URL からフラグメントを返すか、URL にフラグメントがない場合は空の文字列を返します。
__toString() URL を文字列として返します。

URLの変更

Uriコンポーネントは、URL を変更したり、新しい URL を構築したりするために使用できるさまざまなメソッドを提供します。 Uriクラスは不変の値オブジェクトであるため、各メソッドは既存の Uri インスタンスを変更するのではなく、新しいUriインスタンスを返すことに注意してください。

withScheme($scheme)指定されたスキームを持つ新しいインスタンスを返します。空のスキームを使用すると、URL からスキームを削除できます。提供されたスキームはすべて小文字に正規化されることに注意してください。
withUserInfo($user, $password = null)指定されたユーザー名とパスワードを持つ新しいインスタンスを返します。ユーザー名が指定されない限り、パスワードは無視されることに注意してください。空のユーザー名を使用すると、URL からユーザー名とパスワードを削除できます。単独で URL に挿入できない文字はパーセントでエンコードされます。
withHost($host)指定されたホストの新しいインスタンスを返します。空のホストを使用すると、URL からホストを削除できます。この方法では国際ドメイン名は受け入れられないことに注意してください。この方法ではホストも小文字に正規化されることに注意してください。
withPort($port)指定されたポートを持つ新しいインスタンスを返します。 null使用すると、URL からポートを削除できます。
withPath($path)指定されたパスを持つ新しいインスタンスを返します。空のパスを使用すると、URL からパスを削除できます。有効なパス文字ではない文字は URL 内でパーセントエンコードされることに注意してください。ただし、既存のパーセントエンコード文字は二重エンコードされません。
withPathSegments(array $segments)パスセグメントの配列から構築されたパスを持つ新しいインスタンスを返します。スラッシュや既存のパーセントエンコード文字を含め、セグメント内の無効なパス文字はすべてパーセントエンコードされます。
withQuery($query)指定されたクエリ文字列を持つ新しいインスタンスを返します。空のクエリ文字列を使用すると、URL からパスを削除できます。有効なクエリ文字列文字ではない文字は URL 内でパーセントエンコードされることに注意してください。ただし、既存のパーセントエンコード文字は二重エンコードされません。
withQueryParameters(array $parameters) http_build_query()関数を使用して、指定されたパラメーターから構築されたクエリ文字列を持つ新しいインスタンスを返します。アンパサンド、等号、既存のパーセントエンコード文字を含め、パラメータ内の無効なクエリ文字列文字はすべてパーセントエンコードされます。
withFragment($fragment)指定されたフラグメントを持つ新しいインスタンスを返します。空の文字列を使用すると、URL からフラグメントを削除できます。有効なフラグメント文字ではない文字は URL 内でパーセントエンコードされることに注意してください。ただし、既存のパーセントエンコード文字は二重エンコードされません。

UTF-8 および国際ドメイン名

デフォルトでは、このライブラリは RFC 3986 に準拠したパーサーを提供します。 RFC 仕様では、ドメイン名または URL のその他の部分で UTF-8 文字を使用することは許可されていません。 URL でのこれらの正しい表現は、ドメイン名には IDN 標準を使用し、他の部分では UTF-8 文字をパーセントエンコードすることです。

ただし、UTF-8 でエンコードされた文字を処理しやすくするために、 Uriコンポーネントのメソッドの多くは、UTF-8 文字を含め、単独では URL に挿入できない文字を自動的にパーセントエンコードします。ただし、複雑な関係があるため、 withHost()メソッドでは UTF-8 でエンコードされた文字を使用できません。

デフォルトでは、パーサーは RFC 仕様に違反するため、UTF-8 でエンコードされた文字を含む URL も解析しません。ただし、パーサーは、可能な限りこれらの文字を許可する 2 つの追加の解析モードを提供します。

ユーザー情報 (ユーザー名またはパスワード)、パス、クエリ、または URL のフラグメントコンポーネントに UTF-8 文字が含まれる可能性がある URL を解析する場合は、単純に UTF-8 解析モードを使用できます。例えば：

 <?php

require ' vendor/autoload.php ' ;

$ parser = new  Riimu  Kit  UrlParser  UriParser ();
$ parser -> setMode ( Riimu  Kit  UrlParser UriParser:: MODE_UTF8 );

$ uri = $ parser -> parse ( ' http://www.example.com/föö/bär.html ' );
echo $ uri -> getPath (); // Outputs: /f%C3%B6%C3%B6/b%C3%A4r.html

ただし、ドメイン名に UTF-8 文字が含まれる場合は、もう少し複雑な問題になります。ただし、パーサーは、IDNA モードを使用してこれらのドメイン名を解析するための基本的なサポートを提供します。例えば：

 <?php

require ' vendor/autoload.php ' ;

$ parser = new  Riimu  Kit  UrlParser  UriParser ();
$ parser -> setMode ( Riimu  Kit  UrlParser UriParser:: MODE_IDNA );

$ uri = $ parser -> parse ( ' http://www.fööbär.com ' );
echo $ uri -> getHost (); // Outputs: www.xn--fbr-rla2ga.com

この解析モードを使用するには、PHP 拡張機能intl有効にする必要があることに注意してください。 2 番目のコンストラクターパラメーターを使用して、適切な解析モードをUriコンポーネントのコンストラクターに提供することもできます。

これらの UTF-8 文字の解析のサポートは利用可能ですが、このライブラリの目的は RFC 3986 準拠の URI を処理することであるため、このライブラリは逆の操作のメソッドを提供しません。

URLの正規化

RFC 3986 仕様では、いくつかのわずかな違いはあるものの、一部の URL が同等であると定義されているため、このライブラリは、提供された値に対して最小限の正規化を行います。たとえば、ユーザーが提供した URL を解析するときに、このようなインスタンスが発生する可能性があります。発生する可能性のある最も注目すべき正規化は次のとおりです。

schemeとhostコンポーネントは大文字と小文字を区別しないとみなされます。したがって、これらのコンポーネントは常に小文字に正規化されます。
ポートが現在のスキームの標準ポートである場合、 getAuthority()および__toString()によって返される文字列にはポート番号は含まれません。
パーセントエンコーディングは大文字と小文字を区別せずに処理されます。したがって、このライブラリは 16 進文字を大文字に正規化します。
__toString()によって返される文字列内のパスの先頭にあるスラッシュの数は、URL にauthorityコンポーネントがあるかどうかに応じて変化する可能性があります。
userinfoコンポーネントで解析および生成された URI 内のエンコードされた文字の割合は、 UriParserエンコードされたユーザー名またはパスワードを提供する方法を提供しない PSR-7 仕様で動作するという事実により異なる場合があります。