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

Development & Production

Use APPNETOS environment-specific configuration overlays to keep development convenient and production predictable, secure, and efficient.

Development and production are not separate configuration systems. Both use the same Core\Config\Base loader, typed properties, and validation rules. The active runtime environment determines which additional configuration files are loaded.

Environment Resolution and Precedence

The configuration controller obtains the environment name from runtime()->getEnvironment(). APPNETOS then searches platform/config/ for the corresponding environment-specific files and merges all existing files in the following order:

Four configuration layers: core defaults, core environment overlay, application defaults, and application environment overlay.
Later configuration files override matching values from earlier files. The same sequence applies to any runtime environment name.
  1. platform/config/appnetos.php
  2. platform/config/appnetos.<environment>.php
  3. platform/config/<application>.php
  4. platform/config/<application>.<environment>.php

At least one global APPNETOS configuration file must exist. Application-specific configuration files are optional. If no environment-specific file exists, APPNETOS continues with the available configuration rather than requiring a separate file for every environment.

Environment names

The examples below use development and production for readability. The actual filename suffix must match the environment name returned by the runtime; do not assume that the loader translates or aliases environment names.

Environment-specific Overlays

Keep common settings in the base configuration and override only values that differ between environments. The files return PHP arrays with the same contexts structure.

Base configuration

<?php

return [
    'contexts' => [
        'app' => [
            'database_cache' => false,
            'app_cache' => false,
            'twig_cache' => false,
            'session_timeout' => 2592000,
        ],
        'admin' => [
            'database_cache' => false,
            'twig_cache' => false,
            'session_timeout' => 3600,
        ],
    ],
];

Example production overlay

<?php

return [
    'contexts' => [
        'app' => [
            'database_cache' => true,
            'app_cache' => true,
            'twig_cache' => true,
            'js_cache' => true,
            'css_cache' => true,
            'js_minify' => true,
            'css_minify' => true,
        ],
        'admin' => [
            'database_cache' => true,
            'twig_cache' => true,
            'js_cache' => true,
            'css_cache' => true,
        ],
    ],
];

These are illustrative settings, not universal deployment defaults. Enable app_cache only for Apps that support caching and whose rendered output can safely be reused.

APPNETOS combines arrays with array_replace_recursive(). This means nested keys can be overridden individually, but numeric-indexed arrays are merged by index rather than automatically replaced as whole lists. Review connection endpoint lists and similar arrays carefully when changing them per environment.

Development Recommendations

During development, prioritize visible changes, repeatable tests, and transparent error reporting. The exact runtime debug state is supplied by the runtime and exposed by getDebug(); it is not a contexts.app.debug or contexts.admin.debug property in the current configuration classes.

Area Development approach Reason
Class and directory caches Disable while modifying class locations and mappings Keep changes visible without stale path metadata
Twig cache Disable while editing templates Reduce stale compiled template behavior
JavaScript and CSS caches Disable during active asset development Inspect current assets without generated-file reuse
Rendered App and content caches Disable when editing render logic or content Avoid stale static HTML during testing
REST registry cache Disable when changing REST annotations or exposed resources Allow metadata to be rediscovered
Database and Redis Use isolated development instances or databases Avoid affecting production data and cache keys
Mailer Use a test SMTP relay or local mail capture service Avoid sending test messages to real recipients

Production Recommendations

In production, enable only caches whose invalidation behavior is understood, protect administrative operations, and keep infrastructure connections appropriately secured.

Caching and content updates

database_cache_expire and app_cache_expire are TTL values in seconds. By contrast, content_cache and content_element_cache store rendered static HTML without TTL. The application must explicitly invalidate these caches when the underlying content changes.

Asset caching generates uniquely named JavaScript and CSS files. After cache clearing and regeneration, new hashed filenames cause browsers to request the updated assets. rest_cache caches REST resource registry metadata, not generic HTTP API responses.

Sessions and access controls

Review session_timeout and session_persistent independently for app and admin. When persistence is disabled, the session cookie is a browser-session cookie; when enabled, it receives a lifetime based on the configured timeout. The server-side session lifetime remains a separate concern.

The default clear_all_caches_parameter is appnetos-clear-cache. Change this value in production and restrict access to the cache-clearing operation. Renaming a query parameter is not, by itself, an authorization mechanism.

Infrastructure and credentials

MongoDB connection configuration is mandatory, including for command and worker processes. Use appropriate credentials and connection settings for production MongoDB and Redis. Redis prefixes help distinguish key namespaces but are not a substitute for instance or access isolation.

Store credentials outside publicly served paths and restrict filesystem access to deployed configuration files. Treat application and environment configuration as sensitive operational material.

SMTP certificate verification

Prefer a trusted SMTP certificate whose hostname matches the configured host. For an internal SMTP server running on another VM, connecting through its private IP may produce a hostname mismatch. Setting ignore_certificate to true can accommodate that deployment, but it disables certificate and hostname verification and therefore weakens transport authentication. Prefer internal DNS and trusted certificates whenever feasible.

Statistics and storage

Enable statistics deliberately. Collected statistics can grow significantly in MongoDB; plan retention and storage capacity according to application requirements.

Deploying Configuration Changes

APPNETOS loads its active runtime configuration from platform/config/. Changes to files in custom/<application>/.files/platform/ are installation-source changes and do not automatically change the runtime configuration.

  1. Prepare the correct environment-specific files and review their merged values.
  2. Back up the existing target configuration before reinstallation or replacement.
  3. Deploy the updated files to platform/config/ using the intended installation or deployment workflow.
  4. Remember that normal installation skips existing files; reinstallation overwrites target files present in the selected source but does not remove unrelated files.
  5. Clear or regenerate affected caches when configuration or resource changes require it.
  6. Verify the application, admin, REST, command, and worker contexts relevant to the deployment.

Environment Checklist

Check Development Production
Correct runtime environment and overlay files Verify Verify
MongoDB and Redis connectivity Isolated test services Secured production services
Template, asset, and class caching Usually disabled during active edits Enable selectively
Static content cache invalidation Test behavior Required when enabled
Mailer recipients and transport Test relay or mail capture Verified SMTP or selected transport
Cache-clearing request parameter Controlled local access Change default and restrict access
Worker process configuration Restart after changes as needed Managed restart on deployment

Next Steps

Previous

Custom Configuration & Installation

Explore Custom Configuration & Installation

Next

Core Components

Explore Core Components