Basic utilities
"uweb/utils.php"
Uray Web Library (UWeb)
This file contains several basic helper functions and classes. This is the most fundamental part of UWeb, as it is included and built upon by almost all other UWeb files.
This section contains several basic HTML generator functions, i.e. functions that return HTML code, and also some other functions that help in generating and formatting HTML code. This file (utils.php) contains only the most basic such functions. For others, see html.php and active.php, and for generating whole HTML pages, see page.php.
function bold ($text);
Make $text bold, i.e. return it inside the HTML tags <b>.
function italic ($text);
Make $text italic, i.e. return it inside the HTML tags <i>.
function nobreak ($text);
Make $text a non-breaking block, i.e. convert its spaces to HTML non-breaking spaces, and return the result.
function indent ($text); function indent ($indent, $text);
Indent $text, i.e. prefix all lines of $text with a tab character "\t" (first version) or $indent (second version), and return the result.
In this function, line means a segment of the string between newline characters "\n" and/or the beginning/end of the string, except the last one if that is empty.
Examples:
indent("abc\ndef\n") == "\tabc\n\tdef\n" indent("\t\t", "abc\ndef") == "\t\tabc\n\t\tdef" indent(" ", "abc") == " abc" indent("") == "" Note: this function helps to produce nicely formatted HTML code.
function alink ($text, $href, $attrs = []); function alink ($href, $attrs = []);
Create (return) an HTML link (<a>).
$text: the text content of the link. If omitted, it will be the same as $href.
$href: the URL (href attribute) of the link.
$attrs: optional additional attributes of the <a> element (see: attrs()).
Note: this function would be called link() if that were not an existing built-in PHP function.
function image ($src, $attrs = []); function image ($src, $alt, $attrs = []);
Create (return) an HTML image (<img>).
$src: the URL (src attribute) of the image.
$alt: alternative text (alt attribute) of the image.
$attrs: optional additional attributes of the <img> element (see: attrs()).
function span ($text, $attrs = []); function span ($text, $class, $attrs = []);
Create (return) an HTML <span> element.
$text: the content of the <span> element.
$class: the class attribute of the <span>.
$attrs: optional additional attributes of the <span> element (see: attrs()).
function attrs ($attrs);
Convert an associative array (key/value pairs) of HTML attributes to a string that can be inserted into an HTML opening tag between the tag name and the closing >. The order of the attributes is preserved. A key with an empty value is converted to an empty HTML attribute (e.g. attr instead of the equivalent attr=''). Special characters in attribute values (such as quotes) will be escaped properly. The attributes will be separated by single spaces, and the first one will also be preceded by a space (unless $attrs is empty).
Example:
attrs(["key" => "value", "empty" => "", "spec" => "a < 'b'"]) == " key='value' empty spec='a < 'b''"
Note: many HTML generator functions (e.g. image()) also have an $attrs argument, and they expect them in the same format as described here.
function html_escape ($string);
Make the string safe and convenient in HTML context, i.e. replace all HTML-unsafe characters (<, >, &, ', ") with their respective HTML entity reference (< etc.), and all newlines (of any type, e.g. \n, \r\n) with <br/>.
function html_unescape ($string);
Revert the effects of html_escape(), i.e. replace all entity references introduced by html_escape() (< etc.) with their original character, and all occurances of <br/> with a newline character.
Note: this function is only the exact inverse of html_escape() if the original string contains no special newline combinations (like \r\n).
function attr_escape ($string);
Make the string safe in HTML attributes, i.e. replace all HTML-unsafe characters (<, >, &, ', ") with their respective HTML entity reference (< etc.).
This is similar to html_escape(), but attr_escape() does not affect newlines.
function check_int ($string);
Check whether $string contains an unsigned integer value, and return true if it does, otherwise false. The string is accepted if it contains only digits, it is not empty, and it does not start with a zero digit (e.g. "0123"), except of course in the string "0".
This is different from the built-in is_int(), which checks only the type of the value, and it gives false for any string. This is also different from the built-in is_numeric(), which also accepts floating-point string values like "3.14" and "3e2", and signed integers like "-123" and "+123".
function check_email_address ($string);
Return whether $string is a valid e-mail address (syntactically). The local name can have any case, but the domain name must be lowercase.
function check_domain_name ($string);
Return whether $string is a valid domain name (syntactically). Only lowercase domain names are accepted.
function finish_year_range ($years);
Extend the given year range with the current year if necessary.
$years: either a single year (e.g. "2020") or a range of years (e.g. "2018-2024"), as a string. In the latter case, the end year may be omitted (e.g. "2018-").
Return value: the same year range, but if the end year was omitted, it is extended with the current year (e.g. in 2024, "2018-" becomes "2018-2024"). But if the two years were the same, they are collapsed into a single year (e.g. in 2024, "2024-" becomes just "2024").
This function can be useful for copyright dates on a website, which have a fixed start year, but the end year is always the current year.
Language classes are a fundamental concept in UWeb for multi-language HTML generation. They are simple classes that contain consts and functions for each word or phrase in a specific page or context, one class for each language.
For example:
class fruits_en = {
const apple = "apple";
const pear = "pear";
}
class fruits_hu = {
const apple = "alma";
const pear = "körte";
}
The language class for the current language can be instantiated using the lng_obj() function, e.g.:
$lng = lng_obj("fruits");
Here the language was determined by the global constant lang, being either "en" or "hu". The created language object ($lng) can be used either directly, e.g. $lng::apple, or by passing it to one of the many UWeb functions that accept language objects (e.g. get_lng_text()).
function lng_obj ($name, $include = null, $lang = null);
Return a language object, i.e. an instance of a language class.
$name: the name of the language class without the language suffix. E.g. lng_obj("name", …, "en") returns an instance of name_en.
$include: the name of the include file containing the language class, without pathname and language suffix. If it is null or missing, then no file is included, and the language class must be already available. For example if $include == "file" and $lang == "en", then the language class is searched in file-en.php. By default, the file is searched in the directory of the UWeb files (e.g. uweb/utils.php), but the path can be modified by defining the global constant lang_dir (also relative to the UWeb files). It must end in a trailing slash (unless it is empty), e.g.: const lang_dir = "../lang/";
$lang: the language code, e.g. "en". If it is null or missing, the global lang constant is used, which must then be defined. The language code is appended to both the class name ($name) and the include file name ($include).
function lng_obj_const ($name, $const, $include = null, $lang = null);
Return a language class constant without creating a language object.
$name, $include, $lang: same as in lng_obj().
$const: the name of the constant in the language class.
For example if $const == "xyz", the result of this function is equivalent to $lng::xyz with $lng = lng_obj($name, $include, $lang), but without actually creating the language object.
function get_lng_text ($lng, $lng_text);
Return a text in the appropriate language, using a language object.
$lng: the language object.
$lng_text: any of the following:
"some text" – it is returned without modification. "#xyz" – either the constant $lng::xyz or the result of calling $lng->xyz() is returned. The latter method can either return a value, which is directly returned, or print the value with echo, in which case the output will be captured and returned. If neither the method nor the constant exists, get_lng_text() returns the empty string (""). If both exists, the method takes precedence. "#func(a,b)" – the method $lng->func("a", "b") is called, and its result (as described above) is returned. The parameters are extracted recursively using get_lng_text(), i.e. they can also be in the form of $lng_text. Spaces around the parameters are ignored. null or "" – the empty string ("") is returned. function print_lng_text ($lng, $lng_text);
Print a text in the appropriate language, using a language object.
This is very similar to get_lng_text(), but it prints the text instead of returning it, thus it is equivalent to echo get_lng_text($lng, $lng_text), but print_lng_text() is more efficient if $lng_text is likely to refer to a method that outputs a value (instead of returning it).
abstract class basic_error
→ Exception (PHP)
This is the base of all exception classes in UWeb. See Error handling.
abstract class internal_error
→ basic_error
→ Exception
This is the base class of the so called internal errors, which is a semantic category of the exception classes that represent programming errors (as opposed to user errors like page_not_found). They should not be reported to the user (in details) for security reasons, but they should be logged instead.
Examples in UWeb are ajax_query_error and post_parameter_error.
class page_not_found
→ basic_error
→ Exception
This exception class can be used by websites to report "page not found" errors (404 errors).
This is not used by UWeb itself.
class access_denied
→ basic_error
→ Exception
This exception class can be used by websites to report "access denied" errors (403 errors).
This is not used by UWeb itself.