<?php
# Lifter007: TODO
# Lifter003: TODO
# Lifter010: TODO
/**
* URLHelper.php - utility functions for URL parameter handling
*
* Copyright (c) 2008 Elmar Ludwig
*
* This program is free software; you can redistribute it and/or
* modify it under the terms of the GNU General Public License as
* published by the Free Software Foundation; either version 2 of
* the License, or (at your option) any later version.
*/
/**
* The URLHelper class provides several utility functions (as class
* methods) to ease the transition from using session data to URL
* parameters.
*
* The most important method is URLHelper::getLink(), which appends
* a number of additional parameters to a given URL. The parameters
* can be set using the addLinkParam() or bindLinkParam() methods.
*/
class URLHelper
{
/**
* array of registered parameter values (initially empty)
*/
private static $params = [];
/**
* base URL for all links generated from relative URLs
*/
private static $base_url;
/**
* Set a base URL to be used when resolving relative URLs passed
* to URLHelper::getLink() and URLHelper::getURL(). Set this to
* NULL to use no base URL and skip the URL resolving step.
*
* @param string $url relative or absolute URL (or NULL)
* @return string old URL
*/
static function setBaseURL ($url)
{
$old = self::$base_url;
self::$base_url = $url;
return $old;
}
/**
* Resolve the given relative or absolute URL relative to the
* currently defined base URL (if set). This is a private method.
*
* @param string $url relative or absolute URL
*
* @return string modified URL
*/
private static function resolveURL ($url)
{
$base_url = self::$base_url;
if (!isset($base_url) ||
preg_match('%^[a-z]+:%', $url)) {
return $url;
}
if ($url[0] === '/') {
preg_match('%^[a-z]+://[\w:.-]+%', $base_url, $host);
$base_url = isset($host) ? $host[0] : '';
}
return $base_url.$url;
}
/**
* Add a new link parameter. If a parameter with this name already
* exists, its value will be replaced with the new one. All link
* parameters will be included in the link returned by getLink().
*
* @param string $name parameter name
* @param mixed $value parameter value
*/
static function addLinkParam ($name, $value)
{
self::$params[$name] = $value;
}
/**
* Bind a new link parameter to a variable. If a parameter with this
* name already exists, its value will re replaced with the binding.
*
* This method differs from addLinkParam() in two respects:
*
* - The bound variable is initialized with the parameter value in
* the current request.
* - The parameter value is the value of the bound variable at the
* time getLink() is called.
*
* @param string $name parameter name
* @param mixed $var variable to bind
*/
static function bindLinkParam ($name, &$var)
{
if (isset($_REQUEST[$name])) {
$var = $_REQUEST[$name];
}
self::$params[$name] = &$var;
}
/**
* Get the list of currently registered link parameters.
*
* @return array list of registered link parameters
*/
static function getLinkParams ()
{
return self::$params;
}
/**
* Remove a link parameter.
*
* @param string $name parameter name
*/
static function removeLinkParam ($name)
{
unset(self::$params[$name]);
}
/**
* Augment the given URL by appending all registered link parameters.
* Note that for each bound variable, its current value is used. You
* can use the second parameter to add futher URL parameters to this
* link without adding them globally. Any parameters included in the
* argument list take precedence over registered link parameters of
* the same name. This method is identical to getURL() except that it
* returns an entity encoded URL suitable for use in HTML attributes.
*
* @param string $url relative or absolute URL
* @param array $params array of additional link parameters to add
* @param bool $ignore_registered_params do not add registered params
*
* @return string modified URL (entity encoded)
*/
static function getLink ($url = '', $params = NULL, $ignore_registered_params = false)
{
return htmlReady(self::getURL($url, $params, $ignore_registered_params));
}
/**
* Augment the given URL by appending all registered link parameters.
* Note that for each bound variable, its current value is used. You
* can use the second parameter to add futher URL parameters to this
* link without adding them globally. Any parameters included in the
* argument list take precedence over registered link parameters of
* the same name.
*
* @param string $url relative or absolute URL
* @param array $params array of additional link parameters to add
* @param bool $ignore_registered_params do not add registered params
*
* @return string modified URL
*/
static function getURL ($url = '', $params = NULL, $ignore_registered_params = false)
{
$link_params = $ignore_registered_params ? [] : self::$params;
list($url, $fragment) = explode('#', $url);
list($url, $query) = explode('?', $url);
if ($url !== '') {
$url = self::resolveURL($url);
}
if (isset($query)) {
parse_str($query, $query_params);
$link_params = array_merge($link_params, $query_params);
}
if (isset($params)) {
$link_params = array_merge($link_params, $params);
}
$query_string = http_build_query($link_params);
if (mb_strlen($query_string) || $url === '') {
$url .= '?'.$query_string;
}
if (isset($fragment)) {
$url .= '#'.$fragment;
}
return $url;
}
/**
* Augment the given URL by adding URL parameters from the second parameter,
* without bound parameters
*
* @param string $url relative or absolute URL
* @param array $params array of additional link parameters to add
*
* @return string modified URL
*/
static function getScriptURL ($url = '', $params = NULL)
{
return self::getURL($url, $params, true);
}
/**
* This method is identical to getScriptURL() except that it
* returns an entity encoded URL suitable for use in HTML attributes.
*
* @param string $url relative or absolute URL
* @param array $params array of additional link parameters to add
*
* @return string modified URL (entity encoded)
*/
static function getScriptLink ($url = '', $params = NULL)
{
return self::getLink($url, $params, true);
}
}
?>