Collaboration diagram for ILIAS\UI\URLBuilder:

Public Member Functions
	__construct (URI $uri)

	withURI (URI $uri)
	Changes the base URI of the Builder. More...

	withFragment (?string $fragment)
	Change the fragment/hash part of the URL. More...

	acquireParameter (array $namespace, string $name, ?string $initial_value=null)
	Add a new parameter with a namespace and get its token for subsequent changes. More...

	acquireParameters (array $namespace, string ... $names)

	deleteParameter (URLBuilderToken $token)
	Delete an acquired parameter if the supplied token is valid. More...

	withParameter (URLBuilderToken $token, $value)
	Change an acquired parameter's value if the supplied token is valid. More...

	renderTokens (array $tokens)
	Renders a Javascript Map of all given tokens. More...

	renderObject (array $tokens)
	Renders a Javascript URLBuilder object with changeable parameters for all given tokens. More...

	buildURI ()
	Get a URI representation of the full URL including query string and fragment/hash. More...

Data Fields
const	URL_MAX_LENGTH = 2048
	A maximum length of 2048 characters should be safe to use in most browsers, even though longer URLs will be supported by some. More...

const	SEPARATOR = '_'
	Separator for parts of a parameter's namespace. More...

Private Member Functions
	buildQuery ()
	Create the query part of the URL from all parameters Claimed parameters overwrite base parameters in array_merge(), numeric indizes of array-parameters are being removed to ensure continous numeration (p[1]=A&p[2]=B –> p[]=A&p[]=B). More...

	buildFragment ()
	Create the fragment/hash part of the URL. More...

	parameterExists (string $name)
	Check if parameter was already acquired. More...

	checkToken (URLBuilderToken $token)
	Check if a token is valid. More...

	checkLength (URI $uri)
	Check the full length of the URI against URL_MAX_LENGTH. More...

Private Attributes
URI	$uri
	Base URI for the URLBuilder. More...

string	$fragment = null
	Stores the URL fragment/hash (#) (always changeable due to its usage) More...

array	$params = []
	Stores all acquired parameters These always take precedence over existing parameters in the base URI. More...

array	$tokens = []
	Stores all generated tokens for acquired parameters. More...

Detailed Description

URLBuilder.

This provides an abstract representation of an URL and its parameters with the option of changing/removing parameters only by providing a token. These tokens are created when a new parameter is acquired and are therefore controlled by the component that added the parameter. This gives us better control over who gets to change which parameter. Besides that, parameters are always given a namespace so that parameters with the same name can exist beside each other. The in- and output of the URLBuilder are objects.

Along with this class, an equivalent Javascript class is provided in UI/Core that offers a similar functionality. The PHP object can be "transferred" to JS in any renderer by using the provided render...() functions to create JS objects/maps.

Definition at line 39 of file URLBuilder.php.

Constructor & Destructor Documentation

◆ __construct()

ILIAS\UI\URLBuilder::__construct ( URI $uri )

Definition at line 73 of file URLBuilder.php.

References ILIAS\UI\URLBuilder\$uri.

     {
         $this->uri = $uri;
     }

Member Function Documentation

◆ acquireParameter()

ILIAS\UI\URLBuilder::acquireParameter	(	array	$namespace,
		string	$name,
		?string	$initial_value = `null`
	)

Add a new parameter with a namespace and get its token for subsequent changes.

The namespace can consists of one or more levels which are noted as an array. They will be joined with the separator (see constant) and used as a prefix for the name, e.g. Namespace: ["ilOrgUnit","filter"] Name: "name" Resulting parameter: "ilOrgUnit_filter_name"

The return value is an array containing both the changed URLBuilder as well as the token for any subsequent changes to the acquired parameter.

Returns: array<URLBuilder,URLBuilderToken>

Exceptions

Definition at line 118 of file URLBuilder.php.

References $name, $token, and ILIAS\UI\URLBuilder\parameterExists().

                                                                                                    : array
     {
         if ($name === '' || empty($namespace)) {
             throw new \InvalidArgumentException("Parameter name or namespace not set");
         }
 
         $parameter = implode(self::SEPARATOR, $namespace) . self::SEPARATOR . $name;
         if ($this->parameterExists($parameter)) {
             throw new \ilException("Parameter '" . $parameter . "' already reserved in URL");
         }
 
         $token = new URLBuilderToken($namespace, $name);
         $clone = clone $this;
         $clone->params[$parameter] = ($initial_value) ?? '';
         $clone->tokens[$parameter] = $token;
 
         return [$clone, $token];
     }

Here is the call graph for this function:

◆ acquireParameters()

ILIAS\UI\URLBuilder::acquireParameters	(	array	$namespace,
		string ...	$names
	)

Definition at line 137 of file URLBuilder.php.

References $name, $token, and ILIAS\UI\URLBuilder\$tokens.

                                                                          : array
     {
         $tokens = [];
         $builder = $this;
         foreach ($names as $name) {
             list($builder, $token) = $builder->acquireParameter($namespace, $name);
             $tokens[] = $token;
         }
         array_unshift($tokens, $builder);
         return $tokens;
     }

◆ buildFragment()

ILIAS\UI\URLBuilder::buildFragment ( )

private

Create the fragment/hash part of the URL.

Definition at line 238 of file URLBuilder.php.

References ILIAS\UI\URLBuilder\$fragment.

Referenced by ILIAS\UI\URLBuilder\buildURI().

                                     : string
     {
         if ($this->fragment !== null) {
             return ($this->fragment !== '') ? '#' . $this->fragment : '';
         }
         $fragment = ($this->uri->getFragment()) ? '#' . $this->uri->getFragment() : '';
         return $fragment;
     }

Here is the caller graph for this function:

◆ buildQuery()

ILIAS\UI\URLBuilder::buildQuery ( )

private

Create the query part of the URL from all parameters Claimed parameters overwrite base parameters in array_merge(), numeric indizes of array-parameters are being removed to ensure continous numeration (p[1]=A&p[2]=B –> p[]=A&p[]=B).

Definition at line 227 of file URLBuilder.php.

References ILIAS\UI\URLBuilder\$params, and $query.

Referenced by ILIAS\UI\URLBuilder\buildURI().

                                  : string
     {
         $params = array_merge($this->uri->getParameters(), $this->params);
         $query = (! empty($params)) ? '?' . http_build_query($params) : '';
         $query = preg_replace('/%5B[0-9]+%5D/simU', '%5B%5D', $query);
         return $query;
     }

Here is the caller graph for this function:

◆ buildURI()

ILIAS\UI\URLBuilder::buildURI ( )

Get a URI representation of the full URL including query string and fragment/hash.

Definition at line 214 of file URLBuilder.php.

References ILIAS\UI\URLBuilder\$uri, ILIAS\UI\URLBuilder\buildFragment(), ILIAS\UI\URLBuilder\buildQuery(), and ILIAS\UI\URLBuilder\checkLength().

Referenced by ILIAS\UI\Implementation\Component\Table\Action\Action\__construct(), and ILIAS\UI\URLBuilder\renderObject().

                               : URI
     {
         $uri = new URI($this->uri->getBaseURI() . $this->buildQuery() . $this->buildFragment());
         $this->checkLength($uri);
         return $uri;
     }

Here is the call graph for this function:

Here is the caller graph for this function:

◆ checkLength()

ILIAS\UI\URLBuilder::checkLength ( URI $uri )

private

Check the full length of the URI against URL_MAX_LENGTH.

Exceptions

Definition at line 277 of file URLBuilder.php.

Referenced by ILIAS\UI\URLBuilder\buildURI().

                                           : void
     {
         if (! (strlen((string) $uri) <= self::URL_MAX_LENGTH)) {
             throw new \LengthException("The final URL is longer than " . self::URL_MAX_LENGTH . " and will not be valid.");
         }
     }

Here is the caller graph for this function:

◆ checkToken()

ILIAS\UI\URLBuilder::checkToken ( URLBuilderToken $token )

private

Check if a token is valid.

Exceptions

Definition at line 261 of file URLBuilder.php.

References ILIAS\UI\URLBuilderToken\getName(), ILIAS\UI\URLBuilderToken\getToken(), and ILIAS\UI\URLBuilder\parameterExists().

Referenced by ILIAS\UI\URLBuilder\deleteParameter(), and ILIAS\UI\URLBuilder\withParameter().

                                                        : void
     {
         if (! in_array($token, $this->tokens)
         || $this->tokens[$token->getName()]->getToken() !== $token->getToken()) {
             throw new \DomainException("Token for '" . $token->getName() . "' is not valid");
         }
         if (! $this->parameterExists($token->getName())) {
             throw new \ilException("Parameter '" . $token->getName() . "' does not exist in URL");
         }
     }

Here is the call graph for this function:

Here is the caller graph for this function:

◆ deleteParameter()

ILIAS\UI\URLBuilder::deleteParameter ( URLBuilderToken $token )

Delete an acquired parameter if the supplied token is valid.

Definition at line 152 of file URLBuilder.php.

References ILIAS\UI\URLBuilder\checkToken(), and ILIAS\UI\URLBuilderToken\getName().

                                                            : self
     {
         $this->checkToken($token);
         $clone = clone $this;
         unset($clone->params[$token->getName()]);
         unset($clone->tokens[$token->getName()]);
 
         return $clone;
     }

Here is the call graph for this function:

◆ parameterExists()

ILIAS\UI\URLBuilder::parameterExists ( string $name )

private

Check if parameter was already acquired.

Definition at line 250 of file URLBuilder.php.

Referenced by ILIAS\UI\URLBuilder\acquireParameter(), and ILIAS\UI\URLBuilder\checkToken().

                                                   : bool
     {
         return array_key_exists($name, $this->params);
     }

Here is the caller graph for this function:

◆ renderObject()

ILIAS\UI\URLBuilder::renderObject ( array $tokens )

Renders a Javascript URLBuilder object with changeable parameters for all given tokens.

Note: By providing only the tokens that need to be changed on the JS side, all other parameters will be passed as unchangeable.

Parameters

array<URLBuilderToken> $tokens

Definition at line 205 of file URLBuilder.php.

References ILIAS\UI\URLBuilder\buildURI(), and ILIAS\UI\URLBuilder\renderTokens().

                                                : string
     {
         $output = 'new il.UI.core.URLBuilder(new URL("' . $this->buildURI() . '"), ' . $this->renderTokens($tokens) . ')';
         return $output;
     }

Here is the call graph for this function:

◆ renderTokens()

ILIAS\UI\URLBuilder::renderTokens ( array $tokens )

Renders a Javascript Map of all given tokens.

Note: Only the tokens needed for changing parameters on the JS side should be used here.

Parameters

array<URLBuilderToken> $tokens

Definition at line 185 of file URLBuilder.php.

References $token.

Referenced by ILIAS\UI\URLBuilder\renderObject().

                                                : string
     {
         $token_render = [];
         foreach ($tokens as $token) {
             $token_render[] = '["' . $token->getName() . '",' . $token->render() . ']';
         }
         $output = 'new Map([' . implode(',', $token_render) . '])';
         return $output;
     }

Here is the caller graph for this function:

◆ withFragment()

ILIAS\UI\URLBuilder::withFragment ( ?string $fragment )

Change the fragment/hash part of the URL.

Definition at line 91 of file URLBuilder.php.

References ILIAS\UI\URLBuilder\$fragment.

                                                    : self
     {
         $clone = clone $this;
         $clone->fragment = $fragment;
         return $clone;
     }

◆ withParameter()

ILIAS\UI\URLBuilder::withParameter	(	URLBuilderToken	$token,
			$value
	)

Change an acquired parameter's value if the supplied token is valid.

Definition at line 165 of file URLBuilder.php.

References ILIAS\UI\URLBuilder\checkToken(), and ILIAS\UI\URLBuilderToken\getName().

                                                                  : self
     {
         if(! is_string($value) && ! is_array($value)) {
             throw new \InvalidArgumentException('Parameter must be of type string or array');
         }
         $this->checkToken($token);
         $clone = clone $this;
         $clone->params[$token->getName()] = $value;
 
         return $clone;
     }

Here is the call graph for this function:

◆ withURI()

ILIAS\UI\URLBuilder::withURI ( URI $uri )

Changes the base URI of the Builder.

Definition at line 81 of file URLBuilder.php.

References ILIAS\UI\URLBuilder\$uri.

                                      : self
     {
         $clone = clone $this;
         $clone->uri = $uri;
         return $clone;
     }

Field Documentation

◆ $fragment

string ILIAS\UI\URLBuilder::$fragment = null

private

Stores the URL fragment/hash (#) (always changeable due to its usage)

Definition at line 58 of file URLBuilder.php.

Referenced by ILIAS\UI\URLBuilder\buildFragment(), and ILIAS\UI\URLBuilder\withFragment().

◆ $params

array ILIAS\UI\URLBuilder::$params = []

private

Stores all acquired parameters These always take precedence over existing parameters in the base URI.

array<string, string>

Definition at line 65 of file URLBuilder.php.

Referenced by ILIAS\UI\URLBuilder\buildQuery().

◆ $tokens

array ILIAS\UI\URLBuilder::$tokens = []

private

Stores all generated tokens for acquired parameters.

array<string, URLBuilderToken>

Definition at line 71 of file URLBuilder.php.

Referenced by ILIAS\UI\URLBuilder\acquireParameters().

◆ $uri

URI ILIAS\UI\URLBuilder::$uri

private

Base URI for the URLBuilder.

Definition at line 53 of file URLBuilder.php.

Referenced by ILIAS\UI\URLBuilder\__construct(), ILIAS\UI\URLBuilder\buildURI(), and ILIAS\UI\URLBuilder\withURI().

◆ SEPARATOR

const ILIAS\UI\URLBuilder::SEPARATOR = '_'

Separator for parts of a parameter's namespace.

Definition at line 49 of file URLBuilder.php.

Referenced by ILIAS\UI\URLBuilderToken\getName(), ILIAS\UI\URLBuilderTest\testAcquireParam(), ILIAS\UI\URLBuilderTest\testAcquireParamWithLongNamespace(), ILIAS\UI\URLBuilderTest\testAcquireParamWithSameName(), ILIAS\UI\URLBuilderTest\testAcquireParamWithValue(), ILIAS\UI\URLBuilderTest\testDeleteParam(), ILIAS\UI\URLBuilderTest\testRenderObject(), ILIAS\UI\URLBuilderTest\testWithUri(), and ILIAS\UI\URLBuilderTest\testWriteParam().

◆ URL_MAX_LENGTH

const ILIAS\UI\URLBuilder::URL_MAX_LENGTH = 2048

A maximum length of 2048 characters should be safe to use in most browsers, even though longer URLs will be supported by some.

Definition at line 45 of file URLBuilder.php.

Referenced by ILIAS\UI\URLBuilderTest\testUrlTooLong().

The documentation for this class was generated from the following file:

src/UI/URLBuilder.php

Public Member Functions

Data Fields

Private Member Functions

Private Attributes

Detailed Description

Constructor & Destructor Documentation

◆ __construct()

Member Function Documentation

◆ acquireParameter()

◆ acquireParameters()

◆ buildFragment()

◆ buildQuery()

◆ buildURI()

◆ checkLength()

◆ checkToken()

◆ deleteParameter()

◆ parameterExists()

◆ renderObject()

◆ renderTokens()

◆ withFragment()

◆ withParameter()

◆ withURI()

Field Documentation

◆ $fragment

◆ $params

◆ $tokens

◆ $uri

◆ SEPARATOR

◆ URL_MAX_LENGTH