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

Functions Bootstrap

The Functions Bootstrap loads built-in APPNETOS Core functions and optional application-specific PHP function files before Core initialization. It provides a straightforward way to add globally callable helpers to an application without creating additional service classes.

Purpose and Execution

The Functions Bootstrap is step 12 of the APPNETOS bootstrap sequence. It executes after the Registry Bootstrap and before the Core Bootstrap. It first obtains the built-in Core function configuration and then, if an application is active, its optional function configuration. For each configuration, it selects the shared definitions followed by the definitions for the active base context. Existing files are included using require_once.

Core function files are always part of the configuration, even when an application has no function configuration of its own. The application configuration adds files; it does not replace the built-in Core function definitions.

Built-in Core Functions

The Core definitions are provided directly by Bootstrap\Function\FunctionBootstrap:

protected function loadCoreFunctions(): array
{
    return [
        'application' => 'appnetos',
        'contexts' => [
            'shared' => [
                'appnetos/shared/function/base.php',
                'appnetos/shared/function/debug.php',
            ],
            'app' => [],
            'admin' => [],
        ],
    ];
}
File Responsibility Examples
appnetos/shared/function/base.php Lightweight runtime-state and path helpers. runtime(), get_environment(), get_application(), get_context(), get_base_context(), get_runtime_id(), get_root_dir()
appnetos/shared/function/debug.php Global debug helpers, including temporary buffering of early debug values. dump(), dump_flush(), is_debug()

The base helpers read the existing runtime state or bootstrap path constants; they do not maintain a second runtime state. The debug helpers can buffer dump values before the Debug controller is available and forward them later using dump_flush(). The detailed behavior of individual helpers belongs in the Core function reference.

Application Function Configuration

An application can register additional files using platform/function/<application>.php. The following example uses the application example-application:

<?php

declare(strict_types=1);

return [
    'application' => 'example-application',
    'contexts' => [
        'shared' => [
            'example-application/shared/function/helpers.php',
        ],
        'app' => [
            'example-application/app/function/storefront.php',
        ],
        'admin' => [
            'example-application/admin/function/administration.php',
        ],
    ],
];

Shared functions are loaded in every active base context. The app and admin groups are loaded only when the corresponding base context is active. Specialized runtime contexts use their resolved base context: for example, an admin-rest runtime mapped to the admin base context uses the admin function group.

Recommended Directory Structure

example-application/
├── shared/
│   └── function/
│       └── helpers.php
├── app/
│   └── function/
│       └── storefront.php
└── admin/
    └── function/
        └── administration.php

Place shared functions in shared/function/ and base-context-specific functions in <application>/<context>/function/. This is the recommended project organization, not a directory constraint enforced by the bootstrap. Configured file paths are resolved relative to APPNETOS_ROOT.

Defining and Calling a Function

Example file: example-application/shared/function/helpers.php

<?php

declare(strict_types=1);

if (!function_exists('example_format_reference')) {
    function example_format_reference(string $reference): string
    {
        return strtoupper(trim($reference));
    }
}

After the file has been loaded, application code in the active runtime can call the helper directly:

$reference = example_format_reference(' order-123 ');
// ORDER-123

No Registry lookup or service instantiation is needed for a global function.

Loading Sequence

Functions Bootstrap loads built-in Core function files first, then application shared functions and functions for the active base context, making the functions available in the PHP runtime.
Core functions are always included. Application shared functions and functions for the active base context are optional.

The bootstrap processes the Core configuration before the application configuration. Within each configuration, shared entries precede entries for the resolved base context. Each existing configured file is loaded once through require_once.

Environment-Specific Configuration

When an environment-specific configuration exists, it replaces the entire default application function configuration; it is not merged with the default file.

platform/function/example-application.php
platform/function/example-application.production.php

In this example, the second file is used when APPNETOS_ENVIRONMENT is production. The built-in Core function configuration remains active regardless of this override.

Validation and Missing Files

Condition Behavior
No application function configuration Allowed; only the built-in Core function files are configured.
Configuration does not return an array Throws an exception.
Missing or mismatched application key Throws an exception.
Missing or invalid contexts structure Throws an exception.
Active function group is not an array Throws an exception.
Configured function file entry is not a non-empty string Throws an exception.
Configured function file does not exist Skipped without loading.

Global Function Scope and Development Guidance

Function groups determine which files are included in the active PHP runtime. They do not create isolated PHP function namespaces. Once declared, global functions are available throughout that runtime. Use unique, descriptive, application-prefixed names to prevent collisions with Core helpers or other included functions.

Guarding declarations with function_exists() can prevent a redeclaration error, but it does not make conflicting function names safe: the first definition remains active. Keep helpers lightweight, avoid side effects during file inclusion, and use classes or services when behavior requires object state or more complex dependencies.

The Functions Bootstrap runs before Core initialization. Although the Registry Bootstrap has already run, function files should not assume that all Core services or application runtime services have been created.

See Registry Bootstrap for the preceding initialization step and Core Bootstrap for the next stage of the bootstrap sequence.

Next Steps

Previous

Registry

Explore Registry

Next

Core

Explore Core