,
Nocterra provides an application programming interface (API) that can be used on any page. The Nocterra API contains functions to easily enhance and customize the generated web pages on a per-page basis. This documentation is both a user guide for content writers and developers who wish to enrich the generated content and perform tasks such as SEO.
The API reference is not complete; it's an ongoing effort to document the API and provide examples demonstrating the use of the functions. Please also see the Nocterra Manual for a description of the underlying principles and more comprehensive examples.
addKeywords(array|string $newKeywords): void
addKeywords(array|string $keywords, array|string $newKeywords): void
Add new keywords to the keywords already set for the current page.
Or add new keywords to the given keywords and set thiese new keywords to the current page.
Both function variants do not add new keywords to the keywords it alread present. So calling this function like addKeywrds('foo', 'bar'); on a page which already has the foo
keyword set will only add the bar
keyword.
The keywords to add new keyhwords to. Either a comma separated list of keywords or an array of keywords.
The new keywords to add. Either a comma separated list of keywords or an array of keywords.
No value is returned.
addMenuItem(
String $menuItem,
string $language,
string $link,
string $name
): void
Add an item to the menu in the specified language. Menu items are specified by their structure in the menu. foo
would be the foo
menu at the top most level. foo/bat
would be the bar
submenu as a child of the foo
menu.
For multilingual websites an menu can be added for each language. When a language does not have a menu item added for the $menuItem
during URL generation an URL will be generated to the deepest menu item that is present in that language, either by defining it in the configuration or added through this function.
If a menu item has presivously been added for $menuItem
the link
and name
will be overridden other set values will persist.
The menu item to add as a slash separated list.
The language to add an menu item for.
The local or external uRL to link to.
The name to display in the navigation and breadcrumbs.
No value is returned.
addScript(
string $script,
string $type = 'text/javascript'
): void
Add a JavaScript resource to the current page. This function is intended for page-specific additions when a script should not be enabled site-wide.
Site-wide scripts are typically configured in site.php (for example as part of the default configuration, or inside a specific $variants[...] entry). Use addScript() when you need to include an additional script only for the current page or a specific template.
The script
value is the URL/path that will be emitted as a <script> include by the page renderer, using the specified type
.
The script URL (or script path) to add to the current page.
The script MIME type attribute; defaults to text/javascript
.
No value is returned.
addStylesheet(
string $stylesheet,
string $type = 'text/css'
): void
Add a stylesheet resource to the current page. This function is intended for page-specific additions when a stylesheet should not be enabled site-wide.
Site-wide stylesheets are typically configured in site.php (for example as part of the default configuration, or inside a specific $variants[...] entry). Use addStylesheet() when you need to include an additional stylesheet only for the current page or a specific template.
The stylesheet
value is the URL/path that will be emitted as a stylesheet include by the page renderer, using the specified type
.
The stylesheet URL (or stylesheet path) to add to the current page.
The stylesheet MIME type attribute; defaults to text/css
.
No value is returned.
blogGetArtcleUrl(
array $article,
string $language = NULL,
string $scheme = NULL
): mixed
Generate the article URL using the URL scheme configured in site.php. This is useful for addons and custom indexes that need to link to articles without hard-coding the site’s article URL structure.
The article
parameter is expected to be an article entry as returned by the blog TOC/index API. A common pattern is to retrieve a sorted TOC section and iterate its entries:
$sortedToc = &blogGetSortedTOCCache('year', $year);
foreach ($sortedToc['entries'] as &$entry) {
$url = blogGetArtcleUrl($entry, $language);
}The scheme is a template string containing keywords such as {year}
, {month0}
, {title}
, {category}
and {author}
. The function fills these placeholders using fields from the article entry and returns the resulting URL path.
Article entry as produced by the blog TOC/index functions (for example an entry from blogGetSortedTOCCache()).
Target language code. When NULL, the current page language is used.
Optional URL scheme string. When NULL, the default scheme configured for the language in site.php is used.
Returns the generated URL path string, or FALSE when the scheme cannot be parsed.
blogGetArticleDescription(array &$article, string $language): string
Return a suitable article description for the requested language. This is commonly used for metadata generation (for example Open Graph/SEO descriptions) and for displaying short summaries in article indexes.
The article
parameter is expected to be an article entry as returned by the blog TOC/index API. A common pattern is to retrieve a sorted TOC section and iterate its entries:
$sortedToc = &blogGetSortedTOCCache('year', $year);
foreach ($sortedToc['entries'] as &$entry) {
echo '<P>' . blogGetArticleDescription($entry, $language) . '</P>' . PHP_EOL;
}If an explicit description is present in the article data for the language, it is returned. Otherwise the function derives a description from the article body by taking the first paragraph, stripping comments and markup, normalizing whitespace, and then limiting the result to approximately 300 characters (preferring to cut at sentence boundaries where possible). The derived description is cached in the article structure for reuse within the same request.
This function loads the required article parts on-demand.
Article structure as used by the blog system. This is typically an entry from blogGetSortedTOCCache().
Language code to retrieve/generate the description for.
Returns the description text.
blogGetAuthorDef(string $author, string $language = NULL, bool $create = TRUE): mixed
Return the author definition for a given author and language. Author definitions are taken from the blog configuration in site.php and may include metadata used in indexes and structured data (for example type/name/page/relationship templates).
When an author is not explicitly defined and create
is TRUE, Nocterra creates a default definition using the generic author TOC settings. This allows addons and pages to safely request author metadata without hard-coding the configured author list.
Author key/name.
Target language code. When NULL, the current page language is used.
When TRUE, create a default definition when it does not yet exist.
Returns the author definition array, or NULL when not found and create
is FALSE.
blogGetAuthorList(): array
Return the blog author list as known to the blog system. This can be used by addons and pages that generate author-based navigation, indexes, or metadata.
The list is loaded lazily and reused within the request.
This function has no parameters.
Returns the author list.
blogGetAuthorRDFAMeta(
array $authorDef,
string $object = 'author',
bool $meta = TRUE,
string $name = NULL
): string
Generate RDFa markup for an author definition. This is used to include structured author metadata in article output and indexes (for example for search engines and rich previews).
When the author definition includes a page reference, the URL is resolved using langLink(). If the author definition references an organization/employer via at, additional nested RDFa is generated.
Author definition (for example from blogGetAuthorDef()).
RDFa object/property name to use (default author
).
When TRUE, emit a meta-oriented RDFa block; when FALSE, emit inline RDFa markup.
Optional displayed name when meta
is FALSE.
Returns the generated RDFa HTML fragment.
blogGetAuthorUrl(string $author = NULL, string $language = NULL): string
Return the URL for the author index (or a specific author) as configured in site.php. This is useful for author navigation and author-based article indexes in pages and addons.
If you are not certain the author exists in the blog configuration, call blogGetAuthorDef() first to ensure a safe default definition is available.
Author key/name. When NULL, the author index root is returned.
Target language code. When NULL, the current page language is used.
Returns the resolved author URL.
blogGetCategoryDef(string $category, string $language = NULL, bool $create = TRUE): mixed
Return the category definition for a given category and language. Category definitions are taken from the blog configuration in site.php and may include metadata used for article typing and structured data (for example RDFa/type defaults) and for TOC/index templates.
When a category is not explicitly defined and create
is TRUE, Nocterra creates a default definition using the generic category TOC settings. This allows addons and pages to safely request category metadata.
Category key/name.
Target language code. When NULL, the current page language is used.
When TRUE, create a default definition when it does not yet exist.
Returns the category definition array, or NULL when not found and create
is FALSE.
blogGetCategoryList(): array
Return the blog category list as known to the blog system. This is typically used to build category navigation or category-based indexes (for example “latest posts in category X”).
The list is loaded lazily and reused within the request.
This function has no parameters.
Returns the category list.
blogGetCategoryUrl(string $category = NULL, string $language = NULL): string
Return the URL for the category index (or a specific category) as configured in site.php. This is useful for category navigation and category-based article indexes in pages and addons.
If you are not certain the category exists in the blog configuration, call blogGetCategoryDef() first to ensure a safe default definition is available.
Category key/name. When NULL, the category index root is returned.
Target language code. When NULL, the current page language is used.
Returns the resolved category URL.
blogGetLatestYear(): mixed
Return the most recent year from the blog year list, or NULL when no years are available. This is commonly used as a default selection for “current year” blog indexes.
This function has no parameters.
Returns the latest year value, or NULL when unavailable.
blogGetSortedTOCCache(
string $tocType,
string $filterSection,
string $orderby = '-%published% -%seq% %title%'
): array
Return a sorted table-of-contents (TOC) cache section, suitable for building custom article indexes (for example “latest 4 articles in category X” or “articles for year Y”). The returned structure contains the resolved entries plus dependency information so that page caching can remain correct: a page can be cached while still becoming invalid when the underlying blog index sources change.
The result is a structured array containing:
entries: the TOC entries (article entries suitable for sorting and linking),
dependencies: dependency paths relevant for cache invalidation,
cachefile and cachefileTime: the TOC cache backing file and its timestamp.
Sorting is controlled by orderby
. The default sorts newest-first by published date, then sequence, then title.
Common keys in each entry
Each element in $sortedToc['entries'] is an article entry (array). The exact set may vary with configuration and TOC type, but the following keys are commonly available and are the ones used for sorting/linking:
Scalar fields (single value):
published (Unix timestamp)
year, month, month0, date, date0
week, week0
seq (sequence/order within a date)
author (author key/name)
category (category key/name)
List fields:
tags (array of tag keys; often used as $entry['tags'][0] for simple sorting)
Localized text fields (per language code):
title[lang]
title_prefix[lang] and title_postfix[lang] (optional)
description[lang] (optional; may be derived via blogGetArticleDescription())
keywords[lang] / keyword[lang] (optional)
Media fields (optional; may be per language in some setups):
image[lang] or image
Practical usage notes:
Use blogGetArticleDescription($entry, $language) when you need a safe description for display or metadata, because not every entry will have an explicit description populated.
Use blogGetArtcleUrl($entry, $language) to generate the article URL; do not assume a fixed URL structure.
When reading optional keys, use isset() checks.
The %keyword%
names used in orderby
map directly to these entry keys (for example %published%
, %seq%
, %title%
, %tag%
, %description%
).
TOC/cache type to use (for example a list/index type maintained by the blog system).
Section or filter key selecting the subset to return (for example a category/year/tag selection, depending on tocType).
Sort specification using one or more %keyword%
fields with optional +
/-
prefix to control ascending/descending order.
Returns the sorted TOC cache structure.
blogGetTagDef(string $tag, string $language = NULL, bool $create = TRUE): mixed
Return the tag definition for a given tag and language. Tag definitions are taken from the blog configuration in site.php and include TOC/index template settings used when building tag pages and tag-based lists.
When a tag is not explicitly defined and create
is TRUE, Nocterra creates a default definition using the generic tag TOC settings. This allows addons and pages to safely request tag metadata without hard-coding the configured tag list.
Tag key/name.
Target language code. When NULL, the current page language is used.
When TRUE, create a default definition when it does not yet exist.
Returns the tag definition array, or NULL when not found and create
is FALSE.
blogGetTagList(): array
Return the blog tag list as known to the blog system. This is typically used to build tag navigation or tag-based indexes.
The list is loaded lazily and reused within the request.
This function has no parameters.
Returns the tag list.
blogGetTagUrl(string $tag = NULL, string $language = NULL): string
Return the URL for the tag index (or a specific tag) as configured in site.php. This is useful for tag navigation and tag-based article indexes in pages and addons.
If you are not certain the tag exists in the blog configuration, call blogGetTagDef() first to ensure a safe default definition is available.
Tag key/name. When NULL, the tag index root is returned.
Target language code. When NULL, the current page language is used.
Returns the resolved tag URL.
blogGetYearDef(int $year, string $language = NULL, bool $create = TRUE): mixed
Return the year definition for a given year and language. Year definitions are taken from the blog configuration in site.php (toc titles/templates/order settings). When a year is not explicitly defined and create
is TRUE, Nocterra creates a default definition based on the generic year TOC settings.
This allows addons and pages to safely request year metadata without having to know whether a specific year is preconfigured.
The year key.
Target language code. When NULL, the current page language is used.
When TRUE, create a default definition when it does not yet exist.
Returns the year definition array, or NULL when not found and create
is FALSE.
blogGetYearList(): array
Return the list of years known to the blog system. This is typically used to generate year navigation or year-based indexes in addons and dynamic pages.
The list is loaded lazily and reused within the request.
This function has no parameters.
Returns the year list.
blogGetYearUrl(int $year = NULL, string $language = NULL): string
Return the URL for the year index (or a specific year) as configured in site.php. This is useful for building custom year navigation and year-based article indexes in pages and addons.
If you are not certain the year exists in the blog configuration, call blogGetYearDef() first to ensure a safe default definition is available.
The year to link to. When NULL, the year index root is returned.
Target language code. When NULL, the current page language is used.
Returns the resolved year URL.
blogHeading(
int $level,
string $heading,
string $attributes = ''
): string
Generate a heading tag for blog output using the configured top header level. This keeps generated headings consistent across blog pages and addons, without hard-coding absolute H1.. H6 levels.
Heading level relative to the blog top header level. Level 1 maps to the configured top header level.
Heading text/HTML content.
Optional raw attribute string added to the generated <H*> tag (for example id="intro"
).
Returns the generated HTML heading string.
cacheAddDependency(mixed $dependency): void
Register page-level dependencies for the current request. Dependencies represent content sources that influence the rendered output. By recording these, Nocterra can later decide whether a cached entry is still valid by comparing dependency modification times.
This function is useful for pages or addons that incorporate auto-generated content that does not change per request (for example “latest 5 blog articles”), because the page can remain cacheable while still becoming invalid when the underlying sources change.
One dependency path (string) or a list of dependency paths (array) that the current page output depends on.
No value is returned.
cacheAddSystemDependency(mixed $dependency): void
Register one or more “system dependencies” for cache validation. System dependencies represent files that can affect generated output across many pages (for example core logic, routing, addons, or shared data sources). When a system dependency changes, cached output may need to be considered stale even if the page source files themselves did not change.
This function records the modification time (mtime) of each dependency and tracks the latest system-dependency time for the current runtime. Cache validation can then compare a cached entry timestamp against this latest system-dependency time via cacheCheckSystemDependencies().
This API is primarily intended for internal cache logic, but addon developers can use it when an addon’s behaviour depends on external files whose changes should invalidate cached output.
One dependency file path (string) or a list of dependency file paths (array). Paths are relative to the Nocterra installation directory.
No value is returned.
cacheCheckSystemDependencies(int $cachedDataTime): mixed
Validate cached data against the registered system dependencies. If any system dependency has been updated more recently than cachedDataTime
, the cache should be considered stale.
On success, TRUE is returned. On failure, a human-readable string is returned indicating which dependency was updated. This makes the function useful both for decision logic and for diagnostic logging.
The timestamp of the cached data being validated.
Returns TRUE when valid; otherwise a string describing the invalidation reason.
cacheEntryCreate(
string $url,
int $cachedDataTime,
string $contents,
mixed $alternateUrls = NULL,
int $maxage = -1,
int $response = 200,
int $redirect = REDIRECT_PERMANENT
): void
Create a page cache entry (and optional alternate URL entries) in the Nocterra content cache under /cache/. This function is primarily used by Nocterra’s cache logic, but advanced addons may use it for controlled caching flows.
The cache write is intentionally skipped when caching has been disabled for the request (for example via cacheNever()) or when an error/exception was encountered during page generation. In those cases, Nocterra can still render the page normally but will not persist the output to the cache.
The cache entry stores:
the dependency list recorded for the request,
cache max-age metadata,
response/redirect metadata,
and the page contents.
When alternateUrls
is provided, Nocterra also writes alternate cache entries that point to the canonical URL using the specified redirect type.
The canonical URL/path key for the cache entry.
Timestamp to assign to the cache entry (used for validation/ordering).
The page contents to store.
Optional list of alternate URLs that should map to the canonical URL (for example legacy routes). When provided, Nocterra creates lightweight cache entries for these alternates.
Cache max-age value used by Nocterra’s cache logic. A value of -1 indicates “use defaults / not specified”.
HTTP response code associated with this cache entry (200 for normal content).
Redirect status code used when writing alternate URL cache entries (default is permanent).
No value is returned.
cacheGetLatestSystemDependencyTime(): int
Return the latest modification time (mtime) across all registered system dependencies for the current runtime. This timestamp is used when validating whether cached data is still current.
This function has no parameters.
Returns a Unix timestamp (mtime).
cacheGetSystemDependencies(): array
Return the currently registered system-dependency list for this runtime. This is primarily intended for debugging and internal cache logic.
This function has no parameters.
Returns the system-dependency list.
cacheModuleDataCreate(
string $module,
int $cachedDataTime,
string $cacheName,
mixed &$data
): bool
Create or overwrite a module-specific data cache file under /cache/<module>/. This enables addons to maintain their own cached data (similar in concept to the article cache), while keeping the main page cache independent.
The function ensures the required cache directories exist, writes the serialized data to the module cache file, and sets the modification time of both the cache file and its directory to cachedDataTime
.
This API is primarily intended for internal cache logic, but can be used by addons that generate stable derived data (for example indexes, lists, lookups) that should not be recomputed on every request.
Unique module/addon identifier used as a subdirectory under /cache/.
Timestamp to assign to the cache file (used for validation/ordering).
Cache file name within the module cache directory. Subdirectories can be used by including /
.
Data structure to store. The value is serialized before writing.
Returns TRUE on success, or FALSE on failure.
cacheNever(): void
Disable content caching for the current request. This is intended for pages that produce per-visitor or frequently changing output, such as portals, dashboards, contact forms, or pages that include dynamic fragments generated by addons.
When caching is disabled, Nocterra will still render the page normally, but it will skip writing the generated output to the content cache. This avoids serving stale or user-specific output from cache on subsequent requests.
Caching may also be disabled automatically when an error or exception is encountered during page generation. Debug/log output may include state indicators showing that caching is disabled.
This function has no parameters.
No value is returned.
cacheValid(int $cachedDataTime, array $dependencies): mixed
Validate cached data against both page-level dependencies and system dependencies.
Page-level dependencies typically represent content sources that influence the rendered output (for example page source files, included fragments, or generated indexes). If a dependency file has been deleted or has a newer modification time than cachedDataTime
, the cache is considered invalid and a descriptive string is returned.
If all page-level dependencies are valid, the function also validates against system dependencies using cacheCheckSystemDependencies().
This API is commonly used by cache logic to determine whether a cached entry can be served, while still allowing pages with auto-generated content (that does not change per request) to remain cacheable with correct invalidation behaviour.
The timestamp of the cached data being validated.
A list of page-level dependency paths that the cached entry depends on.
Returns TRUE when valid; otherwise a string describing the invalidation reason.
convertException(Exception $exception): string
Convert an exception (including chained previous exceptions) to a readable string representation. The output includes the exception class and message, followed by a formatted stack trace produced by convertStackTrace(). When the exception has previous exceptions, they are appended in order as Caused by
sections.
This function may use PHP standard-library helpers that are only available in newer PHP releases. Nocterra provides internal fallbacks to remain compatible with older PHP versions.
The exception to convert to a string.
Returns the formatted exception string.
convertStackTrace(
array $stack,
string $file,
mixed $line,
string $prefix = ''
): string
Convert a stack trace array to a compact, human-readable string. This function is used by Nocterra’s debug and error reporting to present traces in log output and in the debug footer when debug mode is enabled.
This function may use PHP standard-library helpers that are only available in newer PHP releases. Nocterra provides internal fallbacks to remain compatible with older PHP versions.
A stack trace array, typically returned by debug_backtrace() or an exception trace.
The initial file associated with the trace.
The initial line associated with the trace.
Optional prefix to insert before each formatted trace line.
Returns the formatted stack trace string.
currentPageLink(
string $language = NULL,
bool $strict = FALSE,
bool $return = FALSE
): mixed
Output or return the current page URL for a given language. This is a content-writing helper built on getPathMenuItem() and is typically used when generating links to the current page (for example in templates).
A newer, more automatic mechanism can rewrite href and src attributes found in page content based on configuration in site.php, but currentPageLink() remains useful for dynamic output and addon/template code.
The target language code. When NULL, the current page language is used.
When TRUE, require an exact resolution for the target language; when FALSE, allow loose resolution.
When TRUE, return the generated link string. When FALSE, output is written directly when output buffering mode is enabled.
Returns the URL string when return
is TRUE; otherwise writes the URL to output (when output buffering mode is enabled).
debugException(
Exception $exception,
string $message = NULL
): void
Write an exception as a debug message. This function formats the exception using convertException() and forwards it to debugMessage().
Debug output is only collected when Nocterra debug mode is enabled (controlled by PHP display_errors; keep disabled in production). When enabled, the message is appended to the debug footer block and also written to the PHP error log.
The exception to report.
Optional additional message. When omitted, the exception text is used.
No value is returned.
debugMessage(
string $message,
mixed $value = NULL
): void
Write a debug message for the current request. Debug output is intended for developers and advanced site maintainers when investigating unexpected behaviour and can become very verbose.
Debug messages are only collected when Nocterra debug mode is enabled (controlled by PHP display_errors; in production this should always be disabled). When enabled, Nocterra appends a debug footer block to the end of each page showing collected messages and selected response headers, and also writes the messages to the PHP error log.
Each debug line starts with short state indicators:
<O> indicates output buffering mode is active for this request, and <D> indicates the page is being rendered in “dynamic” mode where cached static output may be combined with runtime-generated fragments (commonly produced by addons). These indicators are useful when interpreting cache and rendering behaviour.
If value
is provided, it is appended in a single line using var_export().
The debug message text.
Optional value to append to the message using var_export().
No value is returned.
debugTrace(string $message): void
Write a debug stack trace for the current request. The trace is derived from debug_backtrace() and formatted using convertStackTrace().
Debug traces are only collected when Nocterra debug mode is enabled (controlled by PHP display_errors; keep disabled in production). When enabled, the trace is appended to the debug footer block and also written to the PHP error log.
Each debug line starts with short state indicators: <O> indicates output buffering mode is active, and <D> indicates the page is being rendered in “dynamic” mode.
Optional label for the trace output. The stack trace is always included.
No value is returned.
debugVar(
string $name,
mixed $value,
bool $singleline = FALSE
): void
Write a debug message that includes a named variable dump. This is a convenience wrapper around debug output using var_export().
Debug messages are only collected when Nocterra debug mode is enabled (controlled by PHP display_errors; keep disabled in production). When enabled, messages are appended to the debug footer block and also written to the PHP error log.
Each debug line starts with short state indicators: <O> indicates output buffering mode is active, and <D> indicates the page is being rendered in “dynamic” mode.
The variable name label to include in the message.
The value to output using var_export().
When TRUE, the exported value is collapsed to a single line; when FALSE, the full var_export() output is used.
No value is returned.
dieException(
Exception $exception,
string $message = NULL
): void
Abort page generation due to an exception. The exception is formatted using convertException() and forwarded to dieMessage().
The exception that caused the abort.
Optional additional message. When omitted, the exception text is used.
No value is returned; the function aborts execution.
dieMessage(
string $message,
int $responseCode = 500,
bool $cacheErrors = FALSE
): void
Abort page generation and send an HTTP error response. The function marks the request as having encountered an error and (when message
is not empty) logs a FATAL
or ERROR
line to the PHP error log.
When Nocterra debug mode is enabled (controlled by PHP display_errors; keep disabled in production), the error message is also collected for the debug footer block. Additionally, the function records the output generated so far as a debug line, clears the output buffer, and then sends the specified HTTP response code.
If cacheErrors
is TRUE, an explicit cache entry is created containing the output generated so far and the response code. This is intended for diagnostics and should be used with care.
Because an error/exception was encountered, normal content caching is typically disabled for the request.
The fatal/error message to record. When empty, no message is logged.
The HTTP response code to send; defaults to 500.
When TRUE, create a cache entry containing the output generated so far (for debugging/diagnostics). When FALSE, no error cache entry is created.
No value is returned; the function aborts execution.
expandDynamicPair(string $text): string
Expand dynamic placeholders in a text by replacing all keys found in the runtime dynamic-pair table. This mechanism is primarily used by addons and internal rendering to weave request-specific (dynamic) fragments into otherwise static (cached) content just before it is sent to the browser.
The replacement mapping is maintained via setDynamicPair() and queried via hasDynamicPair()/getDynamicPair().
Input text that may contain dynamic placeholder keys.
Returns the text with dynamic pairs expanded.
format_bytes(
int $size,
int $precision = 2
): string
Format a byte count as a human-readable value using SI-style suffixes (kB
, MB
, GB
, ...). The value is scaled by powers of 1024 and rounded using the specified precision.
When size
is zero or negative, 0 B
is returned.
The size in bytes.
The number of decimal digits to include; defaults to 2.
Returns the formatted value including a unit suffix.
format_datetime(
mixed $time = NULL,
string $formatDate = FORMAT_SHORT,
string $formatTime = FORMAT_SHORT
): string
Format a combined date and time value using the current language settings from site.php. The date format (date_s/date_m/date_l) and time format (time_s/time_m/time_l) are selected from the active language configuration, concatenated with a space, and expanded using format_sdatetime().
Use this function when you want a localized date+time representation that follows the formats configured for the site.
The time to format. When NULL, the current time is used. Typically a Unix timestamp.
Date detail level. Use FORMAT_SHORT (s
), FORMAT_MEDIUM (m
) or FORMAT_LONG (l
). The date format is taken from the language configuration in site.php (for example date_s, date_m, date_l).
Time detail level. Use FORMAT_SHORT (s
), FORMAT_MEDIUM (m
) or FORMAT_LONG (l
). The time format is taken from the language configuration in site.php (for example time_s, time_m, time_l).
Returns the formatted date/time string.
format_date(
mixed $time = NULL,
string $format = FORMAT_SHORT
): string
Format a date value using the current language settings from site.php. The format string is selected from the active language configuration (date_s, date_m, or date_l) and expanded using format_sdatetime().
Use this function when you want a localized date representation that follows the formats configured for the site.
The time to format. When NULL, the current time is used. Typically a Unix timestamp.
Output detail level. Use FORMAT_SHORT (s
), FORMAT_MEDIUM (m
) or FORMAT_LONG (l
). The selected format is taken from the language configuration in site.php (for example date_s, date_m, date_l).
Returns the formatted date string.
format_dayname(
mixed $time = NULL,
bool $uc = FALSE,
string $language = NULL
): string
Return the localized day name for a given time. The language/locale is derived from the site configuration: when language
is NULL, the current locale is used; otherwise the locale for the specified language is used.
When the PHP Intl extension is available, the function uses IntlDateFormatter with the EEEE pattern to obtain the full day name. When Intl is not available, it falls back to temporarily switching the process locale and using strftime('%A').
The uc
flag controls the capitalization of the returned day name: TRUE returns an uppercase first letter, FALSE returns a lowercase first letter.
The time to format. When NULL, the current time is used. Typically a Unix timestamp.
When TRUE, the day name is returned with an uppercase first letter; when FALSE, the first letter is lowercased.
Optional language key to format in. When NULL, the current site language is used.
Returns the localized day name.
format_monthname(
mixed $time = NULL,
bool $uc = FALSE,
string $language = NULL
): string
Return the localized month name for a given time. The language/locale is derived from the site configuration: when language
is NULL, the current locale is used; otherwise the locale for the specified language is used.
When the PHP Intl extension is available, the function uses IntlDateFormatter with the MMMM pattern to obtain the full month name. When Intl is not available, it falls back to temporarily switching the process locale and using strftime('%B').
The uc
flag controls the capitalization of the returned month name: TRUE returns an uppercase first letter, FALSE returns a lowercase first letter.
The time to format. When NULL, the current time is used. Typically a Unix timestamp.
When TRUE, the month name is returned with an uppercase first letter; when FALSE, the first letter is lowercased.
Optional language key to format in. When NULL, the current site language is used.
Returns the localized month name.
format_sdatetime(
string $formatStr,
mixed $time = NULL
): string
Format a date/time string by expanding Nocterra placeholders. This function replaces tokens in formatStr
with values derived from time
.
Placeholders use one of these forms:%X
where X
is a single letter (for example %Y
), or %keyword%
where keyword
is an alphanumeric identifier (for example %year%
).
Supported placeholders (aliases in parentheses):
year (%year%
, %Y
)
week (%week%
, %W
) as an integer, week0 (%week0%
, %V
) zero-padded
month (%month%
) as an integer, month0 (%month0%
, %m
) zero-padded
month_name (%month_name%
, %B
) full month name, Month_name (%Month_name%
) capitalized
month_abbr (%month_abbr%
, %b
) currently returns the full month name (no separate abbreviation), Month_abbr (%Month_abbr%
) capitalized
date (%date%
, %e
) as an integer, date0 (%date0%
, %d
) zero-padded, date_ord (%date_ord%
) ordinal (English)
day (%day%
, %A
) full day name, Day (%Day%
) capitalized
isodate (%isodate%
) ISO 8601 date/time
hour (%hour%
, %k
) 0-23, hour0 (%hour0%
, %H
) zero-padded
hour12 (%hour12%
, %l
) 1-12, hour012 (%hour012%
, %I
) zero-padded
ampm (%ampm%
, %P
) am/pm, AMPM (%AMPM%
, %p
) AM/PM
minutes (%minutes%
, %M
)
seconds (%seconds%
, %S
)
tz (%tz%
, %Z
) timezone offset in seconds
Unknown placeholders are left unchanged and a message is logged.
The date/time format string containing placeholders to be expanded.
The time to format. When NULL, the current time is used. Typically a Unix timestamp.
Returns the formatted string.
format_time(
mixed $time = NULL,
string $format = FORMAT_SHORT
): string
Format a time value using the current language settings from site.php. The format string is selected from the active language configuration (time_s, time_m, or time_l) and expanded using format_sdatetime().
Use this function when you want a localized time representation that follows the formats configured for the site.
The time to format. When NULL, the current time is used. Typically a Unix timestamp.
Output detail level. Use FORMAT_SHORT (s
), FORMAT_MEDIUM (m
) or FORMAT_LONG (l
). The selected format is taken from the language configuration in site.php (for example time_s, time_m, time_l).
Returns the formatted time string.
getCurrentPath(
string $language = NULL,
bool $strict = FALSE
): string
Return the current page path for a given language, based on the menu and language mapping configured in site.php. This is a convenience wrapper around getPathMenuItem('.') that returns a string.
When strict
is enabled, the function uses strict resolution and may return FALSE when no translated equivalent exists for the requested language.
The target language code. When NULL, the current page language is used.
When TRUE, require an exact resolution for the target language; when FALSE, allow loose resolution.
Returns the resolved current path string (or FALSE when strict resolution fails).
getCurrentPathURL(
string $language = NULL,
bool $strict = FALSE
): string
Return the current page URL for a given language, based on the menu and language mapping configured in site.php. This is a convenience wrapper around getPathMenuItem('.') that returns a URL-form string suitable for use in links and SEO metadata.
When strict
is enabled, the function uses strict resolution and may return FALSE when no translated equivalent exists for the requested language.
The target language code. When NULL, the current page language is used.
When TRUE, require an exact resolution for the target language; when FALSE, allow loose resolution.
Returns the resolved current page URL string (or FALSE when strict resolution fails).
getDynamicPair(
string $key,
mixed $coalesce = NULL
): mixed
Retrieve a dynamic-pair value by key, with an optional fallback. This is primarily used by addons and templates that need to read back the current dynamic-pair mapping for the request.
Note: the current implementation returns coalesce
when the key exists, and returns NULL when it does not. If the intended behaviour is “return value when present, otherwise coalesce”, the conditional should be inverted.
The dynamic-pair key to retrieve.
Fallback value to use when the key is not present.
Returns the configured value or the fallback, depending on the implementation.
getLocalGlobalMeta(string $name): mixed
Resolve the effective meta value by combining the global defaults from site.php with any page-local overrides, using the scope policy configured in $environment. Global defaults are typically defined in $branding (per language), while page-local overrides are usually set by the active page template.
For example, on blog article pages (and blog index pages), blog.php derives meta values from the article definition and context (title, description, image, author, category, tags, keywords and type) and applies them via setArticleMeta(). Templates may also set or override local meta explicitly via API functions such as setTitle(), setDescription() and setKeywords().
The combination behaviour is controlled by $environment[name]:local returns the local value when set; otherwise the global value.prepend places the local value before the global value when both are present and different. For most fields the separator is taken from $environment[name . 'Separator'] (default ,
). For keywords
, values are merged using addKeywords(local, global).extend places the local value after the global value when both are present and different. For keywords
, values are merged using addKeywords(global, local).
If no local value is set (or no rule applies), the global value is returned.
The meta field name to resolve using the site configuration (for example title
, description
, keywords
, author
).
Returns the effective value after applying the configured local/global scope policy.
getLocalGlobalSeparator(string $name): string
Retrieve the separator used when combining local and global values for a given meta field. The separator is configured in site.php via $environment[name . 'Separator'].
When no separator is configured (or the configured value is empty), the default separator ,
(comma + space) is returned.
This separator is used by functions such as getLocalGlobalMeta() when applying scope modes like prepend or extend for non-keyword fields.
The base name of the separator setting. The function reads $environment[name . 'Separator'] from site.php.
Returns the configured separator, or ,
when not set.
getLocalizedPath(
string $resource,
string $language = NULL,
int $mode = 0
): string
Resolve resource
to a localized link for a specific language using the configuration in site.php. This is a convenience wrapper around getPathMenuItem() that always returns a string.
Use this when you need the translated path for a menu item or page in a specific language.
The resource/path to resolve.
The target language code. When NULL, the current page language is used.
Optional getPathMenuItem() mode flags. The result is always returned as a string.
Returns the resolved link string (or FALSE in strict mode when the target cannot be resolved).
getLocalMeta(string $name): mixed
Retrieve a meta value with a page-local override. Nocterra distinguishes between global defaults (typically configured in site.php) and page-local values that are applied for the current page.
Page-local values are usually set by the active page template. For example, on blog pages, the template derives meta values from the article definition and applies them via functions such as setArticleMeta(). A template (or a page script) may also set a local value explicitly via API functions such as setTitle(), setDescription() and setKeywords().
If a local value for name
is set and not empty, it is returned. Otherwise, the function returns the global default for that field. If neither is set, an empty string is returned.
The meta field name to retrieve. The function first checks the page-local value for that field and then falls back to the global default configured in site.php.
Returns the page-local value when present; otherwise the global default; otherwise an empty string.
getPathMenuItem(
mixed $path,
string $language = NULL,
int $mode = 0
): mixed
Resolve a resource/path using the menu mapping and language configuration from site.php. This function underpins language switching, breadcrumbs, canonical URL metadata, and safe link generation in both static pages and addons.
Return forms overview
The return type depends on:
Whether language
is a language code or NULL (all languages)
Whether PATH_ASSTRING is set (string vs structured array)
Whether PATH_COMPONENTS is set (final result vs per-level components)
String return (PATH_ASSTRING)
1a) language
is a language code:
Returns a string URL/path (or FALSE when strict mode fails).
Example:
"documentation/manual"1b) language
is NULL (all languages):
Returns an associative array mapping language code to URL/path (or FALSE per language in strict mode).
Example:
array(
'en' => 'documentation/manual',
'nl' => 'documentatie/handleiding'
)Structured return (default; without PATH_ASSTRING)
This form returns a metadata array. The most important keys are:
links
language code: string URL/path (or FALSE in strict failure)
language NULL: array(lang => string|FALSE)
names
language code: string|NULL
language NULL: array(lang => string|NULL)
titles
language code: string|NULL
language NULL: array(lang => string|NULL)
nearest
Only meaningful in strict mode.
When a translation cannot be resolved and PATH_STRICT is set:
links becomes FALSE
nearest may hold the nearest resolvable parent path
(string, or array(lang => string) when language is NULL)
hidden, nolink, robots, rdfa, type, variant
Metadata inherited while traversing the menu tree; final values represent the target’s effective settings.
Example (single language, not strict):
array(
'links' => 'documentatie/handleiding',
'names' => 'handleiding',
'titles' => 'Handleiding',
'nearest' => NULL,
'hidden' => NULL,
'nolink' => NULL,
'robots' => NULL,
'rdfa' => NULL,
'type' => NULL,
'variant' => NULL
)Example (all languages):
array(
'links' => array(
'en' => 'documentation/manual',
'nl' => 'documentatie/handleiding'
),
'names' => array(
'en' => 'manual',
'nl' => 'handleiding'
),
'titles' => array(
'en' => 'Manual',
'nl' => 'Handleiding'
),
'nearest' => NULL,
...
)Component list return (PATH_COMPONENTS)
When PATH_COMPONENTS is set, the function returns an array with one element per traversed path level.
Each element is:
a structured component array (as in section 2), or
a string (if combined with PATH_ASSTRING)
This form is intended for breadcrumbs and similar UI.
Example (conceptual):
array(
0 => array('links' => 'documentatie', ...),
1 => array('links' => 'documentatie/handleiding', ...)
)URL placeholder note (PATH_URL/PATH_CANONICALURL)
When URL mode is enabled and the resolved link is not an external URL (://
), Nocterra returns a placeholder such as:
<!--nocterra-currentdomain-base-nl-->documentatie/handleidingThis placeholder is later expanded to a full URL for the current or canonical domain.
Path to resolve. This can be a string (for example documentation/manual
, /documentation/manual
, #fragment
, .
) or an array of path components.
Target language code. When NULL, the function resolves for all configured languages and returns per-language results.
Bitmask controlling strictness and output form. Combine:
PATH_STRICT Require translations to exist; otherwise return FALSE for missing languages.
PATH_COMPONENTS Return intermediate path components instead of only the final result.
PATH_URL Wrap internal paths as URL placeholders for later domain expansion.
PATH_CANONICALURL Like PATH_URL but using the canonical domain placeholder.
PATH_ASSTRING Return link(s) as string(s) instead of a structured array.
PATH_EXPAND Expand dynamic pairs in the result.
PATH_SILENT Suppress URL-generation debug logging.
Returns a string, a structured array, or a component list depending on language
and mode
.
getUniqueId(string $template = '', string $source = ''): string
Generates a unique id for the current page render, based on the provided template, and registers it in $GLOBALS['page_ids'] to avoid duplicates.
If the template is already in use, an incrementing numeric suffix is appended using the format "<template>-<n>" until a free id is found.
The source value is stored alongside the id for debugging purposes, enabling identification of where an id was generated.
Base id template; if empty, "id" is used. The template is normalized using stringToId().
Optional debug label describing the caller; if empty, a caller label is derived (e.g. via debugGetCallerFunction()).
Returns the generated unique id.
hasDynamicPair(string $key = NULL): bool
Check whether dynamic pairs are available. When called without a key, this returns whether the dynamic-pair table contains any entries. When called with a key, it returns whether that key exists.
This is typically used by addons or templates to decide whether expansion work is needed for the current request.
Optional dynamic-pair key to test. When NULL, the function tests whether any dynamic pairs are currently defined.
Returns TRUE when the requested condition holds; otherwise FALSE.
imageTitled(
string $resource,
string $alt,
string $title,
string $class = '',
string $language = '',
bool $return = FALSE
): mixed
Generate an <IMG> element for a resource and include both alt and title attributes. The image src is generated using the site’s URL/linking rules (via noLangLink()), so the correct base path is used regardless of the current page location.
This helper is intended for content authors and templates. It can either return the generated HTML string or write it directly to the output, depending on return
and the current output mode.
The image resource path/URL.
The alternative text (alt attribute).
The tooltip text (title attribute).
Optional CSS class name(s) for the class attribute.
Optional language code for the lang attribute.
When TRUE, return the generated HTML string. When FALSE, output is written directly when output buffering mode is enabled.
Returns the generated HTML string when return
is TRUE; otherwise the HTML is written to the output (when output buffering mode is enabled).
image(
string $resource,
string $alt,
string $class = '',
string $language = '',
bool $return = FALSE
): mixed
Generate an <IMG> element for a resource with an alt attribute. The image src is generated using the site’s URL/linking rules (via noLangLink()), so the correct base path is used regardless of the current page location.
This helper is intended for content authors and templates. It can either return the generated HTML string or write it directly to the output, depending on return
and the current output mode.
The image resource path/URL.
The alternative text (alt attribute).
Optional CSS class name(s) for the class attribute.
Optional language code for the lang attribute.
When TRUE, return the generated HTML string. When FALSE, output is written directly when output buffering mode is enabled.
Returns the generated HTML string when return
is TRUE; otherwise the HTML is written to the output (when output buffering mode is enabled).
langLink(
string $resource,
string $language = NULL,
bool $return = FALSE,
bool $expand = FALSE
): mixed
Resolve resource
to a language-specific URL using the menu and language mapping configured in site.php, and then output or return that URL. This helper is commonly used in content pages and templates for generating correct localized links.
A newer, more automatic mechanism can rewrite href and src attributes found in page content based on configuration in site.php, but langLink() remains useful for dynamic output and addon/template code.
The resource/path to resolve.
The target language code. When NULL, the current page language is used.
When TRUE, return the generated URL string. When FALSE, output is written directly when output buffering mode is enabled.
When TRUE, expand dynamic placeholders in the generated URL.
Returns the URL string when return
is TRUE; otherwise writes the URL to output (when output buffering mode is enabled).
logException(
Exception $exception,
string $message = NULL
): void
Log an exception to the PHP error log. The exception is formatted using convertException() and logged via logMessage(). When debug mode is enabled, the message is also appended to the debug footer block.
The exception to log.
Optional additional message. When omitted, the exception text is used.
No value is returned.
logMessage(
string $message,
string $tag = 'Log: '
): void
Write a log message to the PHP error log. Unlike debug functions, logging is always written to the error log regardless of debug mode.
When Nocterra debug mode is enabled (controlled by PHP display_errors; keep disabled in production), log messages are also collected and appended to the debug footer block at the end of the page. When debug mode is disabled, the message is still written to the error log but is not included in the page footer.
Each log line starts with short state indicators: <O> indicates output buffering mode is active, and <D> indicates the page is being rendered in “dynamic” mode.
The message to log.
A prefix tag used in the log line (for example Log:
or ERROR:
).
No value is returned.
noLangLink(
string $resource,
bool $return = FALSE,
bool $expand = FALSE
): mixed
Resolve resource
to a URL using the current page language and the menu mapping configured in site.php, and then output or return that URL. This is a convenience wrapper for resolving links in the context of the current page language (without switching languages), including language-independent resources such as images, scripts and stylesheets.
A newer, more automatic mechanism can rewrite href and src attributes found in page content based on configuration in site.php, but noLangLink() remains useful for dynamic output and addon/template code.
The resource/path to resolve.
When TRUE, return the generated URL string. When FALSE, output is written directly when output buffering mode is enabled.
When TRUE, expand dynamic placeholders in the generated URL.
Returns the URL string when return
is TRUE; otherwise writes the URL to output (when output buffering mode is enabled).
redirect(
mixed $path,
string $language = NULL,
mixed $type = REDIRECT_INTERNAL
): void
Redirect page generation to another path and/or language. This function is used by Nocterra routing, templates, and addons to send the visitor to the correct page, to enforce canonical paths, or to forward legacy URLs.
There are two redirect modes:
Internal redirect (REDIRECT_INTERNAL) re-routes the request inside Nocterra without sending an HTTP redirect response to the client. This is typically used when Nocterra decides to render a different page than originally requested (for example canonicalization or internal routing decisions).
HTTP redirect (REDIRECT_PERMANENT / REDIRECT_TEMPORARY) instructs the client to navigate to the new location using the specified HTTP status code. This is typically used for SEO-friendly permanent redirects or temporary maintenance flows.
Calling redirect() aborts further processing of the current page.
Target path to redirect to. This can be a string path (for example documentation/manual
or /documentation/manual
) or an array of path components.
Target language code. When NULL, the current page language is used.
Redirect type. Use:REDIRECT_INTERNAL for an internal redirect (default),REDIRECT_PERMANENT (301) for a permanent HTTP redirect,REDIRECT_TEMPORARY (307) for a temporary HTTP redirect.
No value is returned; the function aborts execution.
setArticleMeta(
string $title,
string $description,
mixed $image,
string $author,
string $category,
mixed $tags,
string $keywords,
string $type = 'BlogPosting'
): void
Set multiple article-level meta fields in one call. This function updates the branding/meta fields for the current page to describe an article, including the content type, title, description, keywords, author, category and tags.
If image
is not NULL, it also updates the site image value. When image
is NULL, the existing site image is left unchanged.
The article title to set for the current page.
The article description to set for the current page.
Optional image to set as the site/article image; if NULL, the current value is kept.
The author name to set for the current article.
The category name to set for the current article.
The tags to set for the current article; typically an array of tag strings.
The keywords string to set for the current page.
The schema.org type for the article; defaults to BlogPosting
.
No value is returned.
setContentSecurityPolicy(
string $directive,
string $value
): void
Set or override a Content Security Policy (CSP) directive for the current page. Nocterra collects CSP settings from the site configuration (typically in site.php) and can apply page-specific overrides when needed.
This function accepts the standard CSP directive names and maps them to the keys used by Nocterra’s configuration. For example, script-src
is stored under scripts
, style-src
under styles
, and img-src
under images
. The provided value
is stored for that directive and will be emitted by the page renderer when generating the CSP header.
The Content-Security-Policy directive to set. Standard CSP directive names are accepted (for example script-src
, style-src
, img-src
) and are mapped to Nocterra’s internal CSP keys.
The directive value to apply (for example a source list such as 'self' https://example.org
).
No value is returned.
setCookieNocterra(
string $name,
string $value,
mixed $expire_or_options = 0,
string $path = '',
bool $secure = FALSE,
bool $httponly = FALSE
): bool
Set a cookie using the cookie domain configured for the current domain in site.php. This helper ensures cookies are consistently scoped to the correct cookie domain when a site is served under multiple domains or domain variants.
All parameters are passed through to PHP setcookie(), except that the cookie domain is taken from the current domain configuration.
The cookie name.
The cookie value.
Expiration time or options parameter, passed through to PHP setcookie().
Cookie path; defaults to an empty string.
When TRUE, the cookie is only sent over HTTPS.
When TRUE, the cookie is not accessible to JavaScript (HTTP-only).
Returns TRUE on success, or FALSE on failure.
setDescription(string $description): void
Sets the meta description for the current page. This description is used for SEO, as the text when people link to the page in Facebook and for Twitter cards.
The description to set.
No value is returned.
setDynamicPair(
string $key,
string $value,
bool $expand = FALSE
): void
Define or override a dynamic pair for the current request. Dynamic pairs are used to inject request-specific output into static (cached) content by placing placeholders in the cached HTML and replacing them just before sending the response.
When expand
is TRUE, the provided value is first expanded using the current dynamic-pair table. This allows composing dynamic values from other dynamic pairs.
The placeholder key to set (the text to be replaced).
The replacement value for the key.
When TRUE, expand any existing dynamic pairs inside value
before storing it.
No value is returned.
setEpilogue(string $epilogue): void
setEpilogue(string $epilogue, string $location): void
Sets the epilogue for the current page.
An epilogue is a user defined piece of HTML that will be inserted at the end of a page element. It is inserted after the content generated by Nocterra.
The location parameter specifies which element in the page the epilogue will be inserted. When not specified, it's at the end of the page body.
The epilogue to set.
The location in the page to set the epilogue to.
No value is returned.
setKeywords(string $keywords): void
Sets, as in replaces, the keywords for the current page.
The keywords to set.
No value is returned.
setMenuItem(
string $menuItem,
string $attribute,
mixed $value
): void
Set an attribute on an existing menu item, or create the menu item structure if it does not yet exist. Menu items are specified by their structure in the menu. foo
refers to the foo
item at the top-most level. foo/bar
refers to the bar
submenu item as a child of foo
.
The specified attribute
is stored directly on the deepest menu item node and will overwrite any previously set value for that key. Any other existing keys on the menu item remain unchanged.
The menu item to modify as a slash-separated list.
The attribute key to set on the menu item.
The value to assign to the attribute.
No value is returned.
setPrologue(string $prologue): void
setPrologue(string $prologue, string $location): void
Sets the prologue for the current page.
An prologue is a user defined piece of HTML that will be inserted at the start of an page element. It is inserted before the content generated by Nocterra.
The location parameter specifies which element in the page the prologue will be inserted. When not speicifed, its at the start of the page body.
The prologue to set.
The location in the page to set the prologue to.
No value is returned.
setSubtitle(string $subtitle): void
Sets the subtitle for the current page.
The subtitle to set.
No value is returned.
setTitle(string $title): void
Sets the title for the current page.
The title to set.
No value is returned.
setVariant(string $variant): void
Select a rendering variant for the current page. A variant is a named set of configuration overrides defined in site.php under $variants. Variants are typically used to apply different styling or page behaviour for specific sections of a site (for example the manual/documentation section).
When a variant exists in the configuration, Nocterra applies that variant’s overrides on top of the normal site configuration. If the requested variant does not exist, the default site configuration is used.
Example: the Nocterra website configuration defines a manual
variant which overrides the stylesheet list for the manual pages and can set additional page options. See $variants['manual'] in site.php.
The name of the variant to select, as defined in the site configuration.
No value is returned.
setWebsiteMeta(
string $title,
string $description,
mixed $image,
string $keywords
): void
Set multiple page-level meta fields in one call. This function updates the local branding/meta fields used for the current page, including the title, description and keywords.
If image
is not NULL, it also updates the site image value. When image
is NULL, the existing site image is left unchanged.
The page title to set for the current page.
The page description to set for the current page.
Optional image to set as the site/page image; if NULL, the current value is kept.
The keywords string to set for the current page.
No value is returned.
stringToId(string $string): string
Converts free-form text to a stable identifier suitable for use in HTML id/name attributes and fragment links.
The input is stripped of HTML tags, HTML entities are decoded as UTF-8, and the result is transliterated to ASCII where possible.
Characters other than a-z and 0-9 are converted to hyphens, repeated hyphens are collapsed, and leading/trailing hyphens are removed.
If the resulting identifier is empty, the fallback "id" is returned; if it starts with a digit, the prefix "id-" is added to keep the identifier HTML 4.01-friendly.
Input text to convert into an HTML id-safe identifier.
Returns the generated identifier as a string.
stringToValue(mixed $string): string
Normalize a value into safe plain text for HTML attribute usage and short inline output. The function:
strips HTML tags,
decodes HTML entities to characters (UTF-8),
trims whitespace,
escapes special characters for HTML 4.01 output.
This is useful when you want to safely reuse user-provided or content-derived text as an attribute value (for example title, alt, or value) without allowing embedded markup.
The output is encoded using ENT_COMPAT, which escapes double quotes but not single quotes. Use this when you generate double-quoted HTML attributes (the Nocterra default).
Input value to normalize. Non-string values are converted to string first.
Returns a normalized, HTML-escaped string.