Documentation

Url
in package
implements Stringable Uses BackwardCompatibility

Represents a URL string and allows performing various operations on the URL.

Most importantly, this class allows transparent handling of URLs that contain international characters (a.k.a. IRIs), so that they can easily be sanitized, normalized, validated, etc. This class also makes it easy to convert IRIs to raw ASCII URLs and back.

Table of Contents

Interfaces

Stringable

Properties

$fragment  : string
$host  : string
$pass  : string
$path  : string
$port  : int
$query  : string
$scheme  : string
$user  : string
$is_ascii  : bool
$url  : string|false
$backcompat  : array<string|int, mixed>

Methods

__construct()  : mixed
Constructor.
__toString()  : string
Return the string.
create()  : object
Convenience wrapper for constuctor.
exportStatic()  : void
Provides a way to export a class's public static properties and methods to global namespace.
getProxiedUrl()  : Url
Backward compatibility wrapper for the proxied method.
hasSSL()  : bool
Check if this URL has an SSL certificate.
httpsRedirectActive()  : bool
Backward compatibility wrapper for the redirectsToHttps method.
iriToUrl()  : object
Backward compatibility wrapper for the toAscii method.
isValid()  : bool
Checks whether this is a valid IRI. Makes no changes.
normalize()  : object
Performs Unicode normalization on the URL.
normalizeIri()  : object
Backward compatibility method.
parse()  : mixed
A wrapper for `parse_url()` that can handle URLs with international characters (a.k.a. IRIs)
parseIri()  : mixed
Backward compatibility wrapper for the parse method.
proxied()  : object
Gets the appropriate URL to use for images (or whatever) when using SSL.
redirectsToHttps()  : bool
Check if this URL has a redirect to https:// by querying headers.
sanitize()  : object
Removes illegal characters from the URL.
sanitizeIri()  : object
Backward compatibility method.
setTldRegex()  : void
Creates an optimized regex to match all known top level domains.
sslCertFound()  : bool
Backward compatibility wrapper for the hasSSL method.
toAscii()  : object
Converts an IRI (a URL with international characters) into an ASCII URL.
toUtf8()  : object
Decodes a URL containing encoded international characters to UTF-8.
urlToIri()  : object
Backward compatibility wrapper for the toUtf8 method.
validate()  : object
Checks whether this is a valid IRI, and sets $this->url to '' if not.
validateIri()  : object|false
Backward compatibility wrapper for the validate method.
checkIfAscii()  : void
Checks whether $this->url contains only ASCII characters.

Properties

$fragment

public string $fragment

The fragment component of the URL.

$host

public string $host

The host component of the URL.

$pass

public string $pass

The password component of the URL.

$path

public string $path

The path component of the URL.

$port

public int $port

The port component of the URL.

$query

public string $query

The query component of the URL.

$scheme

public string $scheme

The scheme component of the URL.

$user

public string $user

The user component of the URL.

$is_ascii

protected bool $is_ascii

Whether this contains only ASCII characters.

If not set, unknown.

$url

protected string|false $url

The URL string, or false if invalid.

$backcompat

private static array<string|int, mixed> $backcompat = ['func_names' => ['setTldRegex' => 'set_tld_regex', 'parseIri' => 'parse_iri', 'validateIri' => 'validate_iri', 'sanitizeIri' => 'sanitize_iri', 'normalizeIri' => 'normalize_iri', 'iriToUrl' => 'iri_to_url', 'urlToIri' => 'url_to_iri', 'getProxiedUrl' => 'get_proxied_url', 'sslCertFound' => 'ssl_cert_found']]

BackwardCompatibility settings for this class.

Methods

__construct()

Constructor.

public __construct(string $url[, bool $normalize = false ]) : mixed
Parameters
$url : string

The URL or IRI.

$normalize : bool = false

Whether to normalize the URL during construction. Default: false.

__toString()

Return the string.

public __toString() : string
Return values
string

create()

Convenience wrapper for constuctor.

public static create(string $url[, bool $normalize = false ]) : object

This is just syntactical sugar to ease method chaining.

Parameters
$url : string

The URL or IRI.

$normalize : bool = false

Whether to normalize the URL during construction. Default: false.

Return values
object —

The created object.

exportStatic()

Provides a way to export a class's public static properties and methods to global namespace.

public static exportStatic() : void

To do so:

  1. Use this trait in the class.
  2. At the END of the class's file, call its exportStatic() method.

Although it might not seem that way at first glance, this approach conforms to section 2.3 of PSR 1, since executing this method is simply a dynamic means of declaring functions when the file is included; it has no other side effects.

Regarding the $backcompat items:

A class's static properties are not exported to global variables unless explicitly included in $backcompat['prop_names']. Likewise, a class's static methods are not exported as global functions unless explicitly included in $backcompat['func_names'].

$backcompat['prop_names'] is a simple array where the keys are the names of one or more of a class's static properties, and the values are the names of global variables. In each case, the global variable will be set to a reference to the static property. Static properties that are not named in this array will not be exported.

$backcompat['func_names'] is a simple array where the keys are the names of one or more of a class's static methods, and the values are the names that should be used for global functions that will encapsulate those methods. Methods that are not named in this array will not be exported.

Adding non-static properties or methods to the $backcompat arrays will produce runtime errors. It is the responsibility of the developer to make sure not to do this.

getProxiedUrl()

Backward compatibility wrapper for the proxied method.

public static getProxiedUrl(string $url) : Url
Parameters
$url : string

The original URL of the requested resource.

Return values
Url —

A new instance of this class for the proxied URL.

hasSSL()

Check if this URL has an SSL certificate.

public hasSSL() : bool
Return values
bool —

Whether the URL has an SSL certificate.

httpsRedirectActive()

Backward compatibility wrapper for the redirectsToHttps method.

public httpsRedirectActive(string $url) : bool
Parameters
$url : string

The URL to check.

Return values
bool —

Whether a redirect to HTTPS was found.

iriToUrl()

Backward compatibility wrapper for the toAscii method.

public static iriToUrl(string $iri) : object
Parameters
$iri : string

The IRI to convert to an ASCII URL.

Return values
object —

A reference to an object for the URL.

isValid()

Checks whether this is a valid IRI. Makes no changes.

public isValid([int $flags = 0 ]) : bool

Similar to filter_var($url, FILTER_SANITIZE_URL, $flags), except that it correctly handles URLs with international characters (a.k.a. IRIs), it recognizes schemeless URLs like '//www.example.com', and it only returns a boolean rather than a mixed value.

Parameters
$flags : int = 0

Optional flags for filter_var's third parameter.

Return values
bool —

Whether this is a valid IRI.

normalize()

Performs Unicode normalization on the URL.

public normalize() : object

Internally calls $this->sanitize(), then performs Unicode normalization on the URL as a whole, using NFKC normalization for the domain name (see RFC 3491) and NFC normalization for the rest.

Return values
object

normalizeIri()

Backward compatibility method.

public static normalizeIri(string $iri) : object
Parameters
$iri : string

The IRI to normalize.

Return values
object —

A reference to an object for the IRI.

parse()

A wrapper for `parse_url()` that can handle URLs with international characters (a.k.a. IRIs)

public parse([int $component = -1 ]) : mixed
Parameters
$component : int = -1

Optional flag for parse_url's second parameter.

Return values
mixed —

Same as parse_url(), but with unmangled Unicode.

parseIri()

Backward compatibility wrapper for the parse method.

public static parseIri(string $iri[, int $component = -1 ]) : mixed
Parameters
$iri : string

The IRI to parse.

$component : int = -1

Optional flag for parse_url's second parameter.

Return values
mixed —

Same as parse_url(), but with unmangled Unicode.

proxied()

Gets the appropriate URL to use for images (or whatever) when using SSL.

public proxied() : object

The returned URL may or may not be a proxied URL, depending on the situation.

Mods can implement alternative proxies using the 'integrate_proxy' hook.

Return values
object —

A new instance of this class for the proxied URL.

redirectsToHttps()

Check if this URL has a redirect to https:// by querying headers.

public redirectsToHttps() : bool
Return values
bool —

Whether a redirect to HTTPS was found.

sanitize()

Removes illegal characters from the URL.

public sanitize() : object

Unlike filter_var($url, FILTER_SANITIZE_URL), this correctly handles URLs with international characters (a.k.a. IRIs).

Return values
object —

A reference to this object for method chaining.

sanitizeIri()

Backward compatibility method.

public static sanitizeIri(string $iri) : object
Parameters
$iri : string

The IRI to sanitize.

Return values
object —

A reference to an object for the IRI.

setTldRegex()

Creates an optimized regex to match all known top level domains.

public static setTldRegex([bool $update = false ]) : void

The optimized regex is stored in Config::$modSettings['tld_regex'].

To update the stored version of the regex to use the latest list of valid TLDs from iana.org, set the $update parameter to true. Updating can take some time, based on network connectivity, so it should normally only be done by calling this function from a background or scheduled task.

If $update is not true, but the regex is missing or invalid, the regex will be regenerated from a hard-coded list of TLDs. This regenerated regex will be overwritten on the next scheduled update.

Parameters
$update : bool = false

If true, fetch and process the latest official list of TLDs from iana.org.

sslCertFound()

Backward compatibility wrapper for the hasSSL method.

public static sslCertFound(string $url) : bool
Parameters
$url : string

The URL to check.

Return values
bool —

Whether the URL has an SSL certificate.

toAscii()

Converts an IRI (a URL with international characters) into an ASCII URL.

public toAscii() : object

Uses Punycode to encode any non-ASCII characters in the domain name, and uses standard URL encoding on the rest.

Return values
object —

A reference to this object for method chaining.

toUtf8()

Decodes a URL containing encoded international characters to UTF-8.

public toUtf8() : object

Decodes any Punycode encoded characters in the domain name, then uses standard URL decoding on the rest.

Return values
object —

A reference to this object for method chaining.

urlToIri()

Backward compatibility wrapper for the toUtf8 method.

public static urlToIri(string $url) : object
Parameters
$url : string

The URL to convert to an IRI.

Return values
object —

A reference to an object for the IRI.

validate()

Checks whether this is a valid IRI, and sets $this->url to '' if not.

public validate([int $flags = 0 ]) : object
Parameters
$flags : int = 0

Optional flags for filter_var's third parameter.

Return values
object —

A reference to this object for method chaining.

validateIri()

Backward compatibility wrapper for the validate method.

public static validateIri(string $iri[, int $flags = 0 ]) : object|false
Parameters
$iri : string

The IRI to parse.

$flags : int = 0

Optional flags for filter_var's third parameter.

Return values
object|false —

A reference to an object for the IRI if it is valid, or false if the IRI is invalid.

checkIfAscii()

Checks whether $this->url contains only ASCII characters.

protected checkIfAscii() : void

Sets the value of $this->is_ascii to the result.


        

        
    




    

    

                                

                

                                
    

        On this page

        
    


                

                            

            

    

        

            
Search results