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 Mapping Bootstrap

Select application-specific Core implementations for the active application and context, without changing the shared Core source code.

Purpose and Bootstrap Position

The Class Mapping Bootstrap is the tenth stage of the APPNETOS system bootstrap sequence. It prepares the active application's class replacement definitions after the Autoload and Class Extension bootstraps and before the Registry Bootstrap.

A mapping associates a requested class with a replacement runtime class. It does not rewrite the original PHP class, change its inheritance declaration, instantiate objects, or register autoload directories. Resolved mappings are stored in the shared RuntimeState for later use by the Registry.

The Registry Bootstrap subsequently calls Registry::init(), which copies both the prepared class mappings and class extensions from RuntimeState. During runtime, Registry::get() and Registry::getNew() apply those definitions when resolving objects.

Application and Context-Specific Core Customization

Every application can define its own mappings for predefined APPNETOS Core implementations. Context-specific mappings allow the same Core class to resolve to different application implementations depending on the active context. This keeps application behavior independent while retaining the shared Core as a common foundation.

Typical mapped components include Core Documents, Collections, services, rendering-related classes, and Core App controllers. For example, an application can select its own Collection implementation or replace a reusable Core App controller with an application-specific controller. Mapping a Collection selects an implementation; it does not, by itself, implement a complete domain subsystem or change persistence behavior.

The application-specific implementation may extend an existing Core base class and use the relevant APPNETOS annotations where required. The mapping determines which implementation the Registry selects; the implementation itself defines its behavior.

Cross-Application Domain Sharing

Class Mapping also supports the reuse of business-domain implementations across independent APPNETOS applications. Following Domain-Driven Design principles, a domain can provide reusable Documents and Collections that multiple applications select through their own class mapping configurations.

For example, a CRM application and an e-commerce application can both map their relevant Core Collection classes to the same Customer Collection implementation. The Customer Document and its domain behavior can be reused as well, avoiding duplicated business logic and inconsistent domain models. Each application retains its own configuration and can choose which domain components to integrate for its active context.

A CRM application and an e-commerce application each use Class Mapping to select the same shared Customer Collection and Customer Document implementations from a reusable business domain.
Two independent applications select the same reusable domain implementations through their own mappings.

Shared implementation does not automatically mean shared persisted data. Mapping both applications to the same Document and Collection classes reuses their PHP implementations; whether both applications access the same MongoDB database and collection depends on the effective database and Collection configuration. Class Mapping alone does not merge or migrate data.

Configuration

Application mappings are defined in platform/class_mapping/<application>.php. The configuration returns an array containing the application identifier and context mapping definitions.

<?php

use Core\Collection\AppUserCollection;
use Core\Collection\AdminUserCollection;
use MyApplication\Core\Collection\MyAppUserCollection;
use MyApplication\Core\Collection\MyAdminUserCollection;
use Core\Debug;
use MyApplication\Core\Debug as MyDebug;

return [
    'application' => 'my-application',
    'contexts' => [
        'shared' => [
            Debug::class => MyDebug::class,
        ],
        'app' => [
            AppUserCollection::class => MyAppUserCollection::class,
        ],
        'admin' => [
            AdminUserCollection::class => MyAdminUserCollection::class,
        ],
    ],
];

Illustrative configuration: class names under MyApplication represent application-owned implementations, not built-in APPNETOS classes.

Each mapping uses OriginalClass::class => ReplacementClass::class. The shared section supplies common mappings; mappings for the active context can override a shared entry for the same source class. Define context-specific behavior in the appropriate context section rather than applying it globally.

If an environment-specific configuration file such as platform/class_mapping/my-application.production.php is selected, it replaces the default configuration file rather than merging with it. Missing configuration or context sections are ignored; invalid mapping structures cause a bootstrap exception.

Resolution Flow

The Class Mapping Bootstrap prepares configuration; the Registry performs the actual runtime class resolution. The following diagram distinguishes these responsibilities and shows where Class Extension participates.

Class Mapping configuration for an application and context is stored in RuntimeState; Registry Bootstrap imports mappings and extensions; Registry resolves mapping first, then an optional class extension, before constructing and autowiring runtime objects.
Class Mapping selects the implementation. Class Extension is an optional subsequent resolution step; object creation and lifecycle management belong to the Registry.

Registry Resolution and Object Creation

In the Registry implementation, the requested class is mapped first. The Registry then checks for an extension of the mapped class, followed by an extension of the original class, and otherwise uses the mapped class.

$mappedClass = self::$classMappings[$class] ?? $class;

return self::$classExtensions[$mappedClass] ??
    self::$classExtensions[$class] ??
    $mappedClass;

Use the Registry when obtaining objects that must honor application mappings and extensions:

$users = Registry::get(AdminUserCollection::class);
$newObject = Registry::getNew(MyDocument::class);

Registry::get() may reuse a registered object or a shared instance. Registry::getNew() creates a new non-shared instance by default; classes marked #[Shared] still resolve to their shared instance. Newly created objects receive APPNETOS property autowiring. Direct instantiation with new bypasses Registry class resolution.

Best Practice: Prefer Class Mapping

Prefer Class Mapping over Class Extension whenever the required customization can be expressed through an explicit application-specific implementation. Mapping makes the relationship between a Core class and its replacement visible in configuration, while ordinary PHP inheritance remains easy to inspect and maintain.

Use Class Extension when the APPNETOS extension chain is specifically required to augment existing class behavior. Avoid introducing dynamic inheritance layers merely to select a different implementation. Class Mapping and Class Extension remain compatible when both are genuinely needed.

Application Development with Class Mapping

APPNETOS provides predefined Documents, Collections, services, and Core Apps that applications can adapt through explicit mappings. Combined with conventional inheritance and annotations, this reduces repetitive implementation work and lets developers focus on application-specific data and business behavior.

Class Mapping is an option, not an architectural requirement. Applications can also initialize independent components and implement their own runtime behavior through the Core Bootstrap and Application Runtime Bootstrap when the predefined Core components are not suitable.

Autoload Dependency and Failure Behavior

Class Mapping does not register autoload paths. Every replacement class must be available through the active Autoload configuration. For context isolation and class availability rules, see Autoload Bootstrap.

Configuration validation and runtime class existence are separate concerns. A structurally valid mapping may reference a class that cannot be loaded; the Registry checks the resolved class with class_exists() when it is requested and throws a Registry exception if the class is unavailable.

Do not modify the shared Core source to implement an application mapping. Maintain application-specific classes and the installed platform configuration in their designated locations.

Next Steps

Previous

Class Extension

Explore Class Extension

Next

Registry

Explore Registry