Documentation

Url
in package

Application

implements JsonSerializable

FinalYes

Generate a URL.

As input, this class takes a logical URI, which may include a range of configurable sub-parts (path, query, fragment, etc).

As output, it provides a concrete URL that can be used by a web-browser to make requests.

The typical way to construct a URL object is through Civi::url(), which features more documentation and examples.

This class-model has several properties. Most properties follow one of two patterns:

URL components (such as path, query, fragment, fragmentQuery). These have getter/setter/adder methods. They are stored as raw URL substrings.
Smart flags (such as preferFormat, ssl, cacheCode). These have getter/setter methods. They are stored as simple types (booleans or strings). They also have aliases via __construct(...$flags) and useFlags($flags)

URI components (path, query, etc) can be understood as raw-strings or data-arrays. Compare:

"Path": "civicrm/foo+bar/whiz+bang" vs ['civicrm', 'foo bar', 'whiz bang']
"Query: "a=100&b=Hello+world" vs ["a" => 100, "b" => "Hello world"]
"Fragment": "#/mailing/new" vs ["/mailing", "/new"]
"Fragment Query": "angularDebug=1" vs ["angularDebug" => 1]

The raw-string is supported from all angles (storage+getters+setters+adders). Additionally, the setters+adders accept arrays.

This cl

Interfaces

JsonSerializable

Properties

$cacheCode : bool|null: Whether to auto-append the cache-busting resource code.
$fragment : string|null
$fragmentQuery : string|null
$host : string: NOTE: In most schemes, this field will be ignored.
$htmlEscape : bool: Whether to HTML-encode the output.
$path : string
$port : string: NOTE: In most schemes, this field will be ignored.
$preferFormat : string|null: Preferred format.
$query : string
$scheme : string
$ssl : bool|null
$vars : array<string|int, string>|null: List of values to mix-in to the final/rendered URL.
$varsCallback : callable|null: Define a dynamic lookup for variables.

Methods

__construct() : mixed
__toString() : string: Render the final URL as a string.
addFragment() : $this: Add to fragment.
addFragmentQuery() : $this
addPath() : $this: Add new sections to the path.
addQuery() : $this
addVars() : $this: Add more variables. After composing all parts of the URL, variables will be replaced with their URL-encoded values.
getCacheCode() : bool|null
getFragment() : string|null: Get the primary fragment.
getFragmentQuery() : string|null
getHtmlEscape() : bool
getPath() : string|null
getPreferFormat() : string|null
getQuery() : string|null
getScheme() : string
getSsl() : bool|null
getVars() : array<string|int, string>|null
getVarsCallback() : callable|null
jsonSerialize() : mixed
merge() : $this: Take another URL. Add its components into the components of this URL.
setCacheCode() : mixed: Specify whether to append a cache-busting code.
setFragment() : $this: Replace the fragment.
setFragmentQuery() : $this
setHtmlEscape() : $this: Specify whether to enable HTML escaping of the final output.
setPath() : Url
setPreferFormat() : Url: Specify whether to prefer absolute or relative formatting.
setQuery() : $this
setScheme() : Url
setSsl() : Url: Specify whether the hyperlink should use SSL.
setVars() : $this: Specify a list of variables. After composing all parts of the URL, variables will be replaced with their URL-encoded values.
setVarsCallback() : $this: Configure dynamic lookup for variables.
useFlags() : $this: Apply a series of flags using short-hand notation.
useUri() : void: Parse a logical URI.
appendString() : void
composeFragment() : string
composeQuery() : string
detectFormat() : string
detectScheme() : string
encodePath() : string|null
replaceVars() : string|null
toRenderedPieces() : array{scheme: ?string, path: ?string, query: ?string}

$cacheCode

Whether to auto-append the cache-busting resource code.


    private
        bool|null
    $cacheCode

NULL definition TBD (either "off" or "automatic"?)

$fragment


    private
        string|null
    $fragment

$fragmentQuery


    private
        string|null
    $fragmentQuery

$host

NOTE: In most schemes, this field will be ignored.


    private
        string
    $host

It is only handled for HTTP/HTTPS. I haven't looked through the edge-cases of mixing "host"ed vs non-"host"ed URLs. If you think through those edges and want to expose more helpers, cool.

$htmlEscape

Whether to HTML-encode the output.


    private
        bool
    $htmlEscape
     = FALSE

Note: Why does this exist? It's insane, IMHO. There's nothing intrinsically HTML-y about URLs. However, practically speaking, this class aims to replace CRM_Utils_System::url() which performed HTML encoding by default. Retaining some easy variant of this flag should make the off-ramp a bit smoother.

$path


    private
        string
    $path

Ex: 'civicrm/dashboard'

$port

NOTE: In most schemes, this field will be ignored.


    private
        string
    $port

It is only handled for HTTP/HTTPS. I haven't looked through the edge-cases of mixing "host"ed vs non-"host"ed URLs. If you think through those edges and want to expose more helpers, cool.

$preferFormat

Preferred format.


    private
        string|null
    $preferFormat

Note that this is not strictly guaranteed. It may sometimes return absolute URLs even if you prefer relative URLs (e.g. if there's no easy/correct way to form a relative URL).

'relative' or 'absolute' NULL means "decide automatically"

$query


    private
        string
    $query

Ex: abc=123&xyz=456

$scheme


    private
        string
    $scheme

Ex: 'frontend', 'backend'

$ssl


    private
        bool|null
    $ssl
     = NULL

NULL means "decide automatically"

$vars

List of values to mix-in to the final/rendered URL.


    private
        array<string|int, string>|null
    $vars

$varsCallback

Define a dynamic lookup for variables.


    private
        callable|null
    $varsCallback

__construct()


    public
                    __construct([string|null $logicalUri = NULL ][, string|null $flags = NULL ]) : mixed

Parameters

$logicalUri : string|null = NULL
$flags : string|null = NULL

__toString()

Render the final URL as a string.


    public
                    __toString() : string

Return values

string

addFragment()

Add to fragment.


    public
                    addFragment(string|array<string|int, string> $fragment) : $this

Parameters

$fragment : string|array<string|int, string>: Ex: 'mailing/new' Ex: 'foo+bar/newish%3F' Ex: ['foo bar', 'newish?']

Return values

$this

addFragmentQuery()


    public
                    addFragmentQuery(string|array<string|int, mixed> $fragmentQuery) : $this

Parameters

$fragmentQuery : string|array<string|int, mixed>: Ex: 'name=John+Doughnut&id=9' Ex: ['name' => 'John Doughnut', 'id' => 9]

Return values

$this

addPath()

Add new sections to the path.


    public
                    addPath(string|array<string|int, string> $path) : $this

When adding new parts to the path, there is an implicit delimiter ('/') between parts.

Parameters

$path : string|array<string|int, string>: Ex: 'civicrm/event/info' Ex: 'civicrm/hello+world%3F' Ex: ['civicrm', 'hello world?']

Return values

$this

addQuery()


    public
                    addQuery(string|array<string|int, string> $query) : $this

Parameters

$query : string|array<string|int, string>: Ex: 'name=John+Doughnut&id=9' Ex: ['name' => 'John Doughnut', 'id' => 9]

Return values

$this

addVars()

Add more variables. After composing all parts of the URL, variables will be replaced with their URL-encoded values.


    public
                    addVars(array<string|int, string> $vars) : $this

Example: Civi::url('frontend://civicrm/greeter?cid=[contact]&msg=[message]') ->addVars(['contact' => 123, 'message' => 'Hello to you & you & you!');

Parameters

$vars : array<string|int, string>

Return values

$this

getCacheCode()


    public
                    getCacheCode() : bool|null

Return values

bool|null

getFragment()

Get the primary fragment.


    public
                    getFragment() : string|null

NOTE: This is the primary fragment identifier (as in #id or #/client/side/route). and does not include fregment queries. (as in '#?angularDebug=1').

Return values

string|null —

Ex: '/mailing/new' Ex: '/foo+bar%3F/newish%3F'

getFragmentQuery()


    public
                    getFragmentQuery() : string|null

Return values

string|null —

Ex: 'name=John+Doughnut&id=9'

getHtmlEscape()


    public
                    getHtmlEscape() : bool

Return values

bool

getPath()


    public
                    getPath() : string|null

Return values

string|null —

Ex: 'civicrm/event/info' Ex: 'civicrm/hello+world%3F'

getPreferFormat()


    public
                    getPreferFormat() : string|null

Return values

string|null —

'relative' or 'absolute'

getQuery()


    public
                    getQuery() : string|null

Return values

string|null —

Ex: 'name=John+Doughnut&id=9'

getScheme()


    public
                    getScheme() : string

Return values

string —

Ex: 'frontend' or 'backend'

getSsl()


    public
                    getSsl() : bool|null

Return values

bool|null

getVars()


    public
                    getVars() : array<string|int, string>|null

Return values

array<string|int, string>|null

getVarsCallback()


    public
                    getVarsCallback() : callable|null

Return values

callable|null

jsonSerialize()


    public
                    jsonSerialize() : mixed

#[ReturnTypeWillChange]

merge()

Take another URL. Add its components into the components of this URL.


    public
                    merge(Url $other, array<string|int, string> $parts) : $this

Parameters

$other : Url
$parts : array<string|int, string>: Ex: ['path', 'query', 'fragment', 'fragmentQuery', 'flags']

Return values

$this

setCacheCode()

Specify whether to append a cache-busting code.


    public
                    setCacheCode(bool|null $cacheCode) : mixed

Parameters

$cacheCode : bool|null: TRUE: Do append FALSE: Do not append

setFragment()

Replace the fragment.


    public
                    setFragment(string|array<string|int, string>|null $fragment) : $this

NOTE: This is the primary fragment identifier (as in #id or #/client/side/route). and does not include fregment queries. (as in '#?angularDebug=1').

Parameters

$fragment : string|array<string|int, string>|null: Ex: '/mailing/new' Ex: '/foo+bar/newish%3F' Ex: ['', 'foo bar', 'newish?']

Return values

$this

setFragmentQuery()


    public
                    setFragmentQuery(string|array<string|int, string>|null $fragmentQuery) : $this

Parameters

$fragmentQuery : string|array<string|int, string>|null: Ex: 'name=John+Doughnut&id=9' Ex: ['name' => 'John Doughnut', 'id' => 9]

Return values

$this

setHtmlEscape()

Specify whether to enable HTML escaping of the final output.


    public
                    setHtmlEscape(bool $htmlEscape) : $this

Parameters

$htmlEscape : bool

Return values

$this

setPath()


    public
                    setPath(string|array<string|int, string>|null $path) : Url

Parameters

$path : string|array<string|int, string>|null: Ex: 'civicrm/event/info' Ex: 'civicrm/hello+world%3F' Ex: ['civicrm', 'hello world?']

Return values

Url

setPreferFormat()

Specify whether to prefer absolute or relative formatting.


    public
                    setPreferFormat(string|null $preferFormat) : Url

Parameters

$preferFormat : string|null

One of:

'relative': Prefer relative format, if available
'absolute': Prefer absolute format
NULL: Decide format based on current environment/request. (Ordinary web UI requests prefer 'relative'.)

Return values

Url

setQuery()


    public
                    setQuery(string|array<string|int, string>|null $query) : $this

Parameters

$query : string|array<string|int, string>|null: Ex: 'name=John+Doughnut&id=9' Ex: ['name' => 'John Doughnut', 'id' => 9]

Return values

$this

setScheme()


    public
                    setScheme(string|null $scheme) : Url

Parameters

$scheme : string|null: Ex: 'frontend' or 'backend'

Return values

Url

setSsl()

Specify whether the hyperlink should use SSL.


    public
                    setSsl(bool|null $ssl) : Url

Parameters

$ssl : bool|null: TRUE: Force SSL on. (Convert "http:" to "https:") FALSE: Force SSL off. (Convert "https:" to "http:") NULL: Inherit current SSL-ness

Return values

Url

setVars()

Specify a list of variables. After composing all parts of the URL, variables will be replaced with their URL-encoded values.


    public
                    setVars(array<string|int, string>|null $vars) : $this

Example: Civi::url('frontend://civicrm/greeter?cid=[contact]&msg=[message]') ->setVars(['contact' => 123, 'message' => 'Hello to you & you & you!');

Parameters

$vars : array<string|int, string>|null

Return values

$this

setVarsCallback()

Configure dynamic lookup for variables.


    public
                    setVarsCallback(callable|null $varsCallback) : $this

Parameters

$varsCallback : callable|null: Function(string $varName): ?string Determine the string-value of the variable. (May be ''.) If the variable is unavailable, return NULL.

Return values

$this

useFlags()

Apply a series of flags using short-hand notation.


    public
                    useFlags(string $flags) : $this

Parameters

$flags : string: List of flag-letters, such as (a)bsolute or (r)elative For a full list, see Civi::url().

Return values

$this

useUri()

Parse a logical URI.


    protected
                    useUri(string $logicalUri) : void

Parameters

$logicalUri : string

appendString()


    private
            static        appendString(string|null &$var, string $separator, string|null $value) : void

Parameters

$var : string|null
$separator : string
$value : string|null

composeFragment()


    private
                    composeFragment(string|null $baseFragment, string|null $fragmentQuery) : string

Parameters

$baseFragment : string|null
$fragmentQuery : string|null

Return values

string —

'' or '#foobar'

composeQuery()


    private
                    composeQuery(string|null $query) : string

Parameters

$query : string|null

Return values

string —

'' or '?foo=bar'

detectFormat()


    private
            static        detectFormat() : string

Return values

string

detectScheme()


    private
            static        detectScheme() : string

Return values

string

encodePath()


    private
            static        encodePath(string|array<string|int, string>|null $path) : string|null

Parameters

$path : string|array<string|int, string>|null: Ex: 'greet/hello+world/en' Ex: ['greet', 'hello world', 'en']

Return values

string|null —

Ex: 'greet/hello+world/en'

replaceVars()


    private
                    replaceVars(string $context, string|null $expr) : string|null

Parameters

$context : string
$expr : string|null

Return values

string|null

toRenderedPieces()


    private
                    toRenderedPieces() : array{scheme: ?string, path: ?string, query: ?string}

Return values

array{scheme: ?string, path: ?string, query: ?string}

Url in package Application implements JsonSerializable

Tags

Table of Contents

Interfaces

Properties

Methods

Properties

$cacheCode

$fragment

$fragmentQuery

$host

$htmlEscape

$path

$port

$preferFormat

$query

$scheme

$ssl

$vars

$varsCallback

Methods

__construct()

Parameters

Tags

__toString()

Return values

addFragment()

Parameters

Return values

addFragmentQuery()

Parameters

Return values

addPath()

Parameters

Return values

addQuery()

Parameters

Return values

addVars()

Parameters

Return values

getCacheCode()

Return values

getFragment()

Tags

Return values

getFragmentQuery()

Return values

getHtmlEscape()

Return values

getPath()

Return values

getPreferFormat()

Return values

getQuery()

Return values

getScheme()

Return values

getSsl()

Return values

getVars()

Return values

getVarsCallback()

Return values

jsonSerialize()

Attributes

merge()

Parameters

Return values

setCacheCode()

Parameters

Tags

setFragment()

Parameters

Tags

Return values

setFragmentQuery()

Parameters

Return values

setHtmlEscape()

Url
in package

Application

implements JsonSerializable