APPNETOS is under active development This website and its documentation are being prepared for public launch. Content and features may change.
Select Theme
Loading

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.

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.

Two configuration orders produce different APPNETOS class extension chains. Registry resolution selects the effective implementation; parent method calls continue through the inheritance chain.
Illustrative chain: the first active extension listed for a target becomes the outermost effective implementation when all configured source files are present.

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.
}

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.

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

Configuration order is part of application behavior. Review the complete inheritance chain whenever adding, removing, disabling or reordering extension definitions.

Next Steps

Previous

Autoload

Explore Autoload

Next

Class Mapping

Explore Class Mapping