Kit UrlParser
Version 2.2.0
UrlParser 는 RFC 3986 호환 URL 구문 분석기와 PSR-7 호환 URI 구성 요소를 제공하는 PHP 라이브러리입니다. 이 라이브러리의 목적은 몇 가지 미묘한 방식으로 사양과 다른 내장 함수인 parse_url() 과 달리 RFC 사양을 정확하게 구현하는 파서를 제공하는 것입니다.
이 라이브러리에는 두 가지 주요 목적이 있습니다. 구문 분석된 URL에서 정보를 최초로 제공합니다. 이를 달성하기 위해 라이브러리는 PSR-7의 표준 URI 처리 인터페이스를 구현하고 URL에서 일반적으로 사용되는 정보를 더 쉽게 검색할 수 있는 추가 메서드도 제공합니다. 두 번째 목적은 일부 작업을 보다 간단하게 만드는 몇 가지 추가 방법 외에 PSR-7 표준의 인터페이스를 사용하여 해당 URL의 수정을 허용하는 것입니다.
이 라이브러리는 주로 URL 구문 분석을 위한 것이지만 구문 분석은 단순히 일반 URI 구문을 기반으로 합니다. 따라서 이 라이브러리를 사용하여 일반 구문에 대해 다른 유형의 URI를 검증하고 구문 분석할 수 있습니다. 라이브러리는 URL에 대해 체계별 유효성 검사를 수행하지 않습니다.
기본 RFC 3986 호환 모드 외에도 라이브러리는 URL의 다양한 구성 요소에 UTF-8 문자가 포함된 URL을 구문 분석하는 동시에 적절한 백분율 인코딩 및 IDN ASCII 형식으로 변환할 수 있는 옵션도 제공합니다.
API 문서는 http://kit.riimu.net/api/urlparser/에서 확인할 수 있습니다.
^1.0 )intl (IDN 지원만 필요) 이 라이브러리를 설치하는 가장 쉬운 방법은 Composer를 사용하여 종속성을 처리하는 것입니다. Composer를 통해 이 라이브러리를 설치하려면 다음 두 단계를 따르십시오.
프로젝트 루트에서 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을 구문 분석하려면 구문 분석된 URL에서 생성된 Uri 인스턴스를 반환하는 UriParser 의 parse() 메서드에 URL을 문자열로 제공하면 됩니다.
예를 들어:
<?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을 문자열로 반환합니다.
Uri 구성 요소는 URL을 수정하고 새 URL을 구성하는 데 사용할 수 있는 다양한 방법을 제공합니다. 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에서 퍼센트로 인코딩됩니다. 그러나 기존 퍼센트 인코딩 문자는 이중 인코딩되지 않습니다.
기본적으로 이 라이브러리는 RFC 3986을 준수하는 파서를 제공합니다. RFC 사양은 도메인 이름이나 URL의 다른 부분에 UTF-8 문자 사용을 허용하지 않습니다. URL에서 이에 대한 올바른 표현은 도메인 이름에 대한 IDN 표준을 사용하고 다른 부분에서는 UTF-8 문자를 퍼센트 인코딩하는 것입니다.
그러나 UTF-8로 인코딩된 문자를 처리하는 데 도움이 되도록 Uri 구성 요소의 많은 메서드는 UTF-8 문자를 포함하여 URL에 자체적으로 삽입할 수 없는 모든 문자를 자동으로 퍼센트 인코딩합니다. 그러나 관련된 복잡성으로 인해 withHost() 메서드는 UTF-8로 인코딩된 문자를 허용하지 않습니다.
기본적으로 파서는 UTF-8로 인코딩된 문자가 포함된 URL도 구문 분석하지 않습니다. 이는 RFC 사양에 위배되기 때문입니다. 그러나 파서는 가능할 때마다 이러한 문자를 허용하는 두 가지 추가 구문 분석 모드를 제공합니다.
사용자 정보(예: 사용자 이름 또는 비밀번호), 경로, 쿼리 또는 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 활성화해야 합니다. 두 번째 생성자 매개 변수를 사용하여 Uri 구성 요소의 생성자에 적절한 구문 분석 모드를 제공할 수도 있습니다.
이러한 UTF-8 문자 구문 분석에 대한 지원이 제공되지만 이 라이브러리의 목적은 RFC 3986 호환 URI를 처리하는 것이기 때문에 이 라이브러리는 역방향 작업에 대한 메서드를 제공하지 않습니다.
RFC 3986 사양은 약간의 차이가 있음에도 불구하고 일부 URL을 동등한 것으로 정의하므로 이 라이브러리는 제공된 값에 대해 최소한의 정규화를 수행합니다. 예를 들어 사용자가 제공한 URL을 구문 분석할 때 이러한 인스턴스가 발생할 수 있습니다. 발생할 수 있는 가장 주목할만한 정규화는 다음과 같습니다.
scheme 와 host 구성 요소는 대소문자를 구분하지 않는 것으로 간주됩니다. 따라서 이러한 구성 요소는 항상 소문자로 정규화됩니다.getAuthority() 및 __toString() 이 반환하는 문자열에 포트 번호가 포함되지 않습니다.__toString() 이 반환한 문자열의 경로 시작 부분에 있는 슬래시 수는 URL에 authority 구성 요소가 있는지 여부에 따라 변경될 수 있습니다.UriParser 인코딩된 사용자 이름이나 비밀번호를 제공하는 방법을 제공하지 않는 PSR-7 사양과 함께 작동한다는 사실로 인해 userinfo 구성 요소에서 구문 분석되고 생성된 URI의 인코딩된 문자 비율이 다를 수 있습니다. 이 라이브러리의 저작권은 (c) 2013-2022 Riikka Kalliomäki입니다.
라이센스 및 복사 정보는 LICENSE를 참조하세요.
