Twig
APPNETOS extends Twig with application-aware template resolution, reusable app inclusion and integrated debugging.
Purpose
APPNETOS uses Twig to render application templates and content views. The shared rendering layer
configures Twig with APPNETOS-specific functions, custom-first template lookup, an enhanced include
tag and optional profiling.
Application and alias templates can be customized without changing the original template references. Standard Twig functionality remains available alongside the APPNETOS integrations.
APPNETOS Twig functions
Core\Twig\FunctionLoader explicitly registers four functions on the Twig environment.
| Function | Behavior |
|---|---|
dump(...) |
Forwards each supplied value to Core\Debug::addDump() when the debug
controller
is available. Returns no output.
|
get_debug_bar_head() |
Returns the DebugBar head resources as a string, or null when unavailable.
|
get_debug_bar_body() |
Returns the DebugBar body output as a string, or null when unavailable.
|
include_app(id) |
Accepts a MongoDB ObjectId, its string representation or null;
delegates inclusion to Core\Render::includeApp(). Returns no direct string
value.
|
Debug functions are fault-tolerant and suppress errors from the optional debug infrastructure. include_app()
belongs to the normal rendering pipeline and does not suppress resolution or rendering errors.
Invalid
ObjectId strings can also raise errors.
{% set appId = '507f1f77bcf86cd799439011' %}
{{ dump(appId) }}
{{ include_app(appId) }}
{# Use in the layout when DebugBar resources are needed #}
{{ get_debug_bar_head()|raw }}
{{ get_debug_bar_body()|raw }}
The ObjectId above is illustrative; use an existing app document
ID.
The debug functions return null when debugging is unavailable. Apply |raw
only
to trusted framework-generated DebugBar markup.
Custom-first template resolution
Core\Twig\AliasFilesystemLoader extends Twig's filesystem loader. For application
templates
it obtains candidate paths from ApplicationResolver::getApplicationTemplatePaths() and
selects the first existing file. This supports custom overrides for the active application or alias
and
fallback to original application templates. Shared Core templates without an application mapping use
Twig's normal filesystem lookup.
The same loader applies to direct template rendering and native Twig template operations such as
include
and extends. The exact directory candidates and their precedence are determined by
ApplicationResolver,
rather than being hard-coded in this loader.
Enhanced include tag
APPNETOS registers CustomIncludeTokenParser for the standard include tag.
Its
CustomIncludeNode first resolves string template names ending in .twig
through
Core\Files::getTemplate(). Resolved absolute paths below APPNETOS_ROOT are
converted to relative loader paths. When a different template is selected and
Core\Debug is
available, the replacement is logged as a debug message.
The tag preserves familiar Twig options, including fallback template arrays, with
variables,
only and ignore missing.
{% include 'application/templates/header.html.twig' %}
{% include ['application/templates/custom.html.twig', 'application/templates/default.html.twig'] %}
{% include 'application/templates/card.html.twig' with {'title': 'Example'} only %}
{% include 'application/templates/optional.html.twig' ignore missing %}
Template candidates are attempted in order. A Twig LoaderError allows the next candidate
to
be tried; without ignore missing, a missing template raises a loader error. Errors from
APPNETOS path resolution are not intentionally suppressed. Only string names ending in
.twig receive the explicit Core\Files resolution step.
Debug mode and profiling
Core\Render configures Twig with its cache directory, debug and auto_reload
according to the active debug setting; strict_variables is disabled. When debug mode is
enabled, APPNETOS registers Twig's DebugExtension and ProfilerExtension,
creates a Twig\Profiler\Profile and forwards that profile to StandardDebugBar::addTwigProfileCollector().
This makes Twig rendering and template profiling available to the APPNETOS DebugBar. The environment
also
registers Twig's StringLoaderExtension, the APPNETOS function loader and the custom
include
parser. Context-specific extensions can be registered through the protected
initTwigExtensions() hook.
Relevant source files
Core\Render\Base— Twig environment, debug profiling and extension registrationCore\Twig\FunctionLoader— APPNETOS Twig functionsCore\Twig\AliasFilesystemLoader— application-aware template lookupCore\Twig\TokenParser\CustomIncludeTokenParser— customincludesyntax parsingCore\Twig\Node\CustomIncludeNode— include resolution and rendering
Framework-neutral base templates
The shared base.html.twig and default.html.twig are Bootstrap-neutral.
Bootstrap-specific components choose versioned templates in their own controllers. Dynamic HTML root
attributes come from ui.html_attributes and must be HTML-attribute escaped.
<html{% if ui.html_attributes is defined %}
{% for name, value in ui.html_attributes %
{{ name|e('html_attr') }}="{{ value|e('html_attr') }}"
{% endfor %}
{% endif %}>
JavaScript constants in Twig must be complete statements, including semicolons, particularly when output is compressed. For dynamic JavaScript strings, JSON-safe encoding should be reviewed rather than relying on raw output.