Class Extension Bootstrap
The ninth bootstrap step resolves configurable, backward-recursive PHP inheritance chains for the active application and runtime context.
Purpose and Execution
Bootstrap\ClassExtension\ClassExtensionBootstrap runs after Autoload
Bootstrap and before Class
Mapping Bootstrap. It reads the active application's class extension configuration, selects the
applicable context, validates and groups active definitions, and constructs the effective inheritance
chains.
For each resolved target class, the final concrete implementation is stored as a mapping in RuntimeState.
The original implementation remains unchanged.
The complete class extension mechanism is available only after Class Extension Bootstrap has successfully completed. Earlier bootstrap components must not assume that Registry-based extension resolution is already operational.
Configurable Inheritance Chain
Definitions are grouped by target class and processed in reverse configuration order. APPNETOS creates
intermediate <ChildClass>Parent classes so that every child extends the previous
layer. Reordering the definitions changes which extension becomes the effective outermost class and
therefore changes method precedence.
Configuration and Environment Resolution
The installed configuration is read from platform/class_extension/<application>.php.
If APPNETOS_ENVIRONMENT is set and a matching <application>.<environment>.php
exists, the environment-specific file replaces the default configuration; definitions
are not merged. A missing configuration is permitted and produces an empty extension mapping.
<?php
return [
'application' => 'example-application',
'contexts' => [
'admin' => [
[
'class' => 'Core\Document\AdminGroup',
'parent' => 'appnetos/shared/src/Core/Document/AdminGroup.php',
'child' => 'example-application/admin/src/Core/Document/MyAdminGroupOne.php',
'active' => true,
],
[
'class' => 'Core\Document\AdminGroup',
'parent' => 'appnetos/shared/src/Core/Document/AdminGroup.php',
'child' => 'example-application/admin/src/Core/Document/MyAdminGroupTwo.php',
],
[
'class' => 'Core\Document\AdminGroup',
'parent' => 'appnetos/shared/src/Core/Document/AdminGroup.php',
'child' => 'example-application/admin/src/Core/Document/MyAdminGroupThree.php',
],
],
],
];
Illustrative paths only: Replace the parent and child paths with the actual paths in
your installation. The class is the fully qualified target name; parent
identifies the original source file; child identifies one extension source file. Every
definition for the same target must use the same original parent. The optional active flag
defaults to true.
The order is significant. For the example above, APPNETOS reverses the configured entries while building
the chain: original parent → MyAdminGroupThree → MyAdminGroupTwo → MyAdminGroupOne.
The final mapping points to Core\Document\MyAdminGroupOne. Changing the order changes the
effective implementation.
Backward-Recursive Resolution
For each available child source, the bootstrap loads the current parent, creates an intermediate class
named <ChildClass>Parent in the target namespace, then loads and validates the child
implementation. Each child must directly extend its generated intermediate parent class.
namespace Core\Document;
class MyAdminGroupOne extends MyAdminGroupOneParent
{
public function __construct()
{
parent::__construct();
}
}
The intermediate parent is a real generated PHP class, not merely a naming convention. For example, the
generated MyAdminGroupOneParent extends the next implementation in the chain. The original
class and extension classes remain separate source files.
Methods, Parent Calls and Constructors
Standard PHP inheritance rules continue to apply. Methods that a child does not override remain
inherited. If a child defines the same method, its implementation takes precedence; call parent::method()
to deliberately preserve and extend the next implementation in the chain.
public function save(): bool
{
// Custom behavior before the inherited implementation.
$result = parent::save();
// Custom behavior after the inherited implementation.
return $result;
}
public function __construct()
{
parent::__construct();
// Additional initialization.
}
A
same-named child method replaces the inherited method unless it explicitly calls
parent::method(). A constructor is inherited if the child does not define one; if it
does
define one, the parent constructor is not invoked automatically. Call parent::__construct()
whenever the preceding layer must be initialized. Omit parent calls only when replacing the behavior
is
intentional.
Registry-Based Class Resolution
APPNETOS application code must obtain extensible runtime classes through the Registry, using Registry::get()
or Registry::getNew() as appropriate. These are the supported entry points for resolving
the effective runtime implementation.
// Resolve through the APPNETOS Registry.
$group = Registry::get(Core\Document\AdminGroup::class);
// Request a new instance through the APPNETOS Registry.
$newGroup = Registry::getNew(Core\Document\AdminGroup::class);
// Do not bypass APPNETOS class extension resolution:
$directGroup = new Core\Document\AdminGroup();
The last statement uses PHP's direct constructor lookup and does not request the effective APPNETOS
extension mapping. Use the Registry consistently throughout application code. The exact lifecycle and
caching semantics of get() and getNew() are described in the Registry
documentation.
Runtime Context Selection and Source Precedence
The bootstrap first selects definitions for the exact runtime context. In HTTP runtimes,
it may fall back to the mapped APPNETOS base context if no exact context definition exists. Process
runtimes do not fall back from cmd or worker to
admin.
When resolving a configured source path, APPNETOS checks the corresponding path under APPNETOS_CUSTOM
first, then under APPNETOS_ROOT. This allows custom source files to take precedence without
modifying the originals. Class extension definitions are context-specific and must not be used to
introduce classes from unrelated security contexts.
Validation and Failure Conditions
| Condition | Behavior |
|---|---|
| Missing configuration or no applicable active definitions | Empty class extension mapping. |
active: false |
Definition is excluded. |
| Missing original parent source | Target chain is skipped. |
| Missing child source | That extension is skipped; other available layers can still be resolved. |
| Conflicting original parents or duplicate definitions | Bootstrap exception. |
| Invalid child inheritance, final parent or abstract final implementation | Bootstrap exception. |
All resolved extensions for one target must share the same original parent. The final implementation must be concrete. Invalid or conflicting definitions can prevent the active runtime from booting.
Recommended Use for Documents
Class Extension is the recommended approach for customizing existing APPNETOS Documents. It allows developers to add properties, methods and application-specific business logic without modifying the original document implementation.
Extensions preserve the configured inheritance chain when overridden methods and constructors explicitly
continue required parent behavior. Resolve extended Documents through Registry::get() or
Registry::getNew() so the effective implementation is selected.
Practical examples—including extending Core and Business Core Documents, document annotations, MongoDB mapping, Collections, extension ordering and update-safe customization—belong in the dedicated developer guide Extending Documents. This bootstrap reference describes the underlying class resolution mechanism.
Customization and Update Safety
Place custom implementations in the appropriate
./custom/ source tree, or maintain the effective installed definitions under ./platform/class_extension/.
Do not edit the original application files or <application>/.files/; updates may
overwrite them.
Configuration order is part of application behavior. Review the complete inheritance chain whenever adding, removing, disabling or reordering extension definitions.