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