Functions
	encode_url ($url)
	This function encodes URL to form a URL which is properly percent encoded to replace disallowed characters. More...

	extract_css_urls ( $text)
	Extract URLs from UTF-8 CSS text. More...

	extract_html_urls ( $text)
	Extract URLs from a web page. More...

	join_url ( $parts, $encode=FALSE)
	This function joins together URL components to form a complete URL. More...

	split_url ( $url, $decode=FALSE)
	This function parses an absolute or relative URL and splits it into individual components. More...

	url_remove_dot_segments ( $path)
	Filter out "." and ".." segments from a URL's path and return the result. More...

	url_to_absolute ( $baseUrl, $relativeUrl)
	Combine a base URL and a relative URL to produce a new absolute URL. More...

Detailed Description

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
Neither the names of David R. Nadeau or NadeauSoftware.com, nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Function Documentation

◆ encode_url()

encode_url ( $url )

This function encodes URL to form a URL which is properly percent encoded to replace disallowed characters.

RFC3986 specifies the allowed characters in the URL as well as reserved characters in the URL. This function replaces all the disallowed characters in the URL with their repective percent encodings. Already encoded characters are not encoded again, such as '%20' is not encoded to '%2520'.

Parameters: url the url to encode.

Return values: Returns the encoded URL string.

◆ extract_css_urls()

extract_css_urls ( $text )

Extract URLs from UTF-8 CSS text.

URLs within @import statements and url() property functions are extracted and returned in an associative array of arrays. Array keys indicate the use context for the URL, including:

"import"
"property"

Each value in the associative array is an array of URLs.

Parameters: text the UTF-8 text to scan

Return values: an associative array of arrays of URLs.

See: http://nadeausoftware.com/articles/2008/01/php_tip_how_extract_urls_css_file

◆ extract_html_urls()

extract_html_urls ( $text )

Extract URLs from a web page.

URLs are extracted from a long list of tags and attributes as defined by the HTML 2.0, HTML 3.2, HTML 4.01, and draft HTML 5.0 specifications. URLs are also extracted from tags and attributes that are common extensions of HTML, from the draft Forms 2.0 specification, from XHTML, and from WML 1.3 and 2.0.

The function returns an associative array of associative arrays of arrays of URLs. The outermost array's keys are the tag (element) name, such as "a" for or "img" for . The values for these entries are associative arrays where the keys are attribute names for those tags, such as "href" for . Finally, the values for those arrays are URLs found in those tags and attributes throughout the text. Parameters: text the UTF-8 text to scan Return values: an associative array where keys are tags and values are an associative array where keys are attributes and values are an array of URLs. See: http://nadeausoftware.com/articles/2008/01/php_tip_how_extract_urls_web_page

◆ join_url()

join_url	(	$parts,
		$encode = `FALSE`
	)

This function joins together URL components to form a complete URL.

RFC3986 specifies the components of a Uniform Resource Identifier (URI). This function implements the specification's "component recomposition" algorithm for combining URI components into a full URI string.

The $parts argument is an associative array containing zero or more of the following:

"scheme" The scheme, such as "http". "host" The host name, IPv4, or IPv6 address. "port" The port number. "user" The user name. "pass" The user password. "path" The path, such as a file path for "http". "query" The query. "fragment" The fragment.

The "port", "user", and "pass" values are only used when a "host" is present.

The optional $encode argument indicates if appropriate URL components should be percent-encoded as they are assembled into the URL. Encoding is only applied to the "user", "pass", "host" (if a host name, not an IP address), "path", "query", and "fragment" components. The "scheme" and "port" are never encoded. When a "scheme" and "host" are both present, the "path" is presumed to be hierarchical and encoding processes each segment of the hierarchy separately (i.e., the slashes are left alone).

The assembled URL string is returned.

Parameters: parts an associative array of strings containing the individual parts of a URL.

encode an optional boolean flag selecting whether to do percent encoding or not. Default = true.

Return values: Returns the assembled URL string. The string is an absolute URL if a scheme is supplied, and a relative URL if not. An empty string is returned if the $parts array does not contain any of the needed values.

◆ split_url()

split_url	(	$url,
		$decode = `FALSE`
	)

This function parses an absolute or relative URL and splits it into individual components.

RFC3986 specifies the components of a Uniform Resource Identifier (URI). A portion of the ABNFs are repeated here:

URI-reference = URI / relative-ref

URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ]

relative-ref = relative-part [ "?" query ] [ "#" fragment ]

hier-part = "//" authority path-abempty / path-absolute / path-rootless / path-empty

relative-part = "//" authority path-abempty / path-absolute / path-noscheme / path-empty

authority = [ userinfo "@" ] host [ ":" port ]

So, a URL has the following major components:

scheme The name of a method used to interpret the rest of the URL. Examples: "http", "https", "mailto", "file'.

authority The name of the authority governing the URL's name space. Examples: "example.com", "user@example.com", "example.com:80", "user:password@example.com:80".

The authority may include a host name, port number, user name, and password.

The host may be a name, an IPv4 numeric address, or an IPv6 numeric address.

path The hierarchical path to the URL's resource. Examples: "/index.htm", "/scripts/page.php".

query The data for a query. Examples: "?search=google.com".

fragment The name of a secondary resource relative to that named by the path. Examples: "#section1", "#header".

An "absolute" URL must include a scheme and path. The authority, query, and fragment components are optional.

A "relative" URL does not include a scheme and must include a path. The authority, query, and fragment components are optional.

This function splits the $url argument into the following components and returns them in an associative array. Keys to that array include:

"scheme" The scheme, such as "http". "host" The host name, IPv4, or IPv6 address. "port" The port number. "user" The user name. "pass" The user password. "path" The path, such as a file path for "http". "query" The query. "fragment" The fragment.

One or more of these may not be present, depending upon the URL.

Optionally, the "user", "pass", "host" (if a name, not an IP address), "path", "query", and "fragment" may have percent-encoded characters decoded. The "scheme" and "port" cannot include percent-encoded characters and are never decoded. Decoding occurs after the URL has been parsed.

Parameters: url the URL to parse.

decode an optional boolean flag selecting whether to decode percent encoding or not. Default = TRUE.

Return values: the associative array of URL parts, or FALSE if the URL is too malformed to recognize any parts.

◆ url_remove_dot_segments()

url_remove_dot_segments ( $path )

Filter out "." and ".." segments from a URL's path and return the result.

This function implements the "remove_dot_segments" algorithm from the RFC3986 specification for URLs.

This function supports multi-byte characters with the UTF-8 encoding, per the URL specification.

Parameters: path the path to filter

Return values: The filtered path with "." and ".." removed.

◆ url_to_absolute()

url_to_absolute	(	$baseUrl,
		$relativeUrl
	)

Combine a base URL and a relative URL to produce a new absolute URL.

The base URL is often the URL of a page, and the relative URL is a URL embedded on that page.

This function implements the "absolutize" algorithm from the RFC3986 specification for URLs.