Application Paths and Deployment

ApplicationPaths selects the filesystem locations an application uses at bootstrap. It lets a deployment replace application files while retaining configuration, secrets, logs, uploads and sessions in directories owned by the deployment.

Existing calls to AssegaiFactory keep their defaults. Pass an explicit paths value when you need to choose these locations independently.

Select the application locations

Create the directories before starting the application. Explicit directory arguments must be absolute paths to existing directories.

<?php

use Assegai\Core\ApplicationPaths;
use Assegai\Core\AssegaiFactory;
use MyApp\AppModule;

require '/srv/my-app/dependencies/vendor/autoload.php';

$paths = new ApplicationPaths(
    applicationRoot: '/srv/my-app/releases/current',
    configurationDirectory: '/etc/my-app/config',
    secretsDirectory: '/etc/my-app/secrets',
    stateDirectory: '/var/lib/my-app',
    composerDirectory: '/srv/my-app/dependencies',
    environmentFile: '/etc/my-app/secrets/.env',
);

AssegaiFactory::createFromProject(AppModule::class, paths: $paths)->run();

The autoloader must map application classes to the selected application directory. composerDirectory selects Composer metadata; it does not load or rewrite an autoloader. Configure the autoloader before creating the app.

The same paths argument is accepted by AssegaiFactory::create() and createWithRuntime(). When you also pass a working directory to createFromProject(), it must resolve to the selected application root.

Argument Purpose Default when omitted
applicationRoot Application files, assegai.json and public assets Required for an explicit paths value
configurationDirectory Shared configuration fragments config inside the application root
secretsDirectory local.php and secure.php The configuration directory
stateDirectory Default logs, uploads and PHP file sessions The application root
composerDirectory composer.json metadata The application root
environmentFile The selected dotenv file .env inside the application root
readOnly Guard Core's runtime configuration persistence true

An explicitly selected state directory lets the default log, upload and PHP file-session paths survive replacement of the application directory. Custom session handlers retain their own storage policy.

Source files and resources

The selected application contains its public directory, project metadata and source resources. sourceRoot in assegai.json selects the source directory:

{
  "sourceRoot": "app"
}

An explicit source root must be an existing directory contained within the application root. Use forward-slash relative paths without empty, . or .. segments. Absolute paths, escaping symlinks and backslashes are rejected. The default is src.

PHP views, Twig templates and adjacent component resources use the selected source directory. Public assets use the selected application's public directory. Include those resources in a deployment alongside the application classes.

Environment and configuration

local.php and secure.php are read from the secrets directory. Other configuration fragments use the configuration directory. Keep secrets and writable state outside the public document root.

An absolute environmentFile selects that file directly. A relative filename resolves against the application root. A missing selected environment file fails bootstrap; it does not fall back to another application directory.

Set environmentFile: null to use the process environment without loading a dotenv file:

$paths = new ApplicationPaths(
    applicationRoot: '/srv/my-app/releases/current',
    environmentFile: null,
);

Explicit paths default to readOnly: true. Runtime configuration commits and implicit workspace-configuration writes are rejected. Config::set() remains available for in-memory request overrides. Change authored configuration through your deployment or maintenance workflow.

The read-only option guards Core's configuration writes. Use filesystem permissions to enforce the deployment's complete access policy.

Access the selected paths

The app exposes the immutable selection through App::getPaths(). Providers can inject it:

use Assegai\Core\ApplicationPaths;
use Assegai\Core\Attributes\Injectable;

#[Injectable]
final readonly class ExportService
{
    public function __construct(private ApplicationPaths $paths)
    {
    }
}

Assegai\Core\Util\Paths also provides getStateDirectory(), getLogDirectory(), getCacheDirectory(), getSessionDirectory() and getUploadDirectory(). These helpers select locations; a returned cache path does not establish that a cache has been created or warmed.

Replace a deployment

Validate the new application files and Composer mappings before routing traffic to them. Retain the external configuration, secrets and state directories. Restart long-lived workers after application code, configuration or secrets change.

App::boot() prepares the application graph and invokes initialization hooks. It does not create a persistent discovery cache or prove deployment readiness. Worker draining, generation switching and rollback require deployment orchestration. Environment values retain their process-wide scope.

Continue with Architecture and Lifecycle and OpenSwoole Runtime for the application and worker lifecycle.