Path & Environment Management

Overview

This document focuses on how the DomainFlow Core package handles application paths (such as the base and config directories) and manages the current environment (e.g., production or development).

Key Concepts

• Base Path: A designated root directory for the application, from which other paths can be derived.
• Config Path: A dedicated directory where configuration files typically reside.
• Environment: A setting that indicates if the application is running in production, development, or other contexts. This can affect logging, error reporting, and more.

---

Method Descriptions

Below are the primary methods you’ll use to set or retrieve paths and manage the environment.

setBasePath($path)

Signature

public function setBasePath(string $path): static

Purpose Sets the base path for your application. All relative paths (e.g., configuration or storage directories) can be derived from this base.

Parameter	Type	Required?	Description
$path	string	Yes	File-system path to be set as the base.

• Throws an exception if the directory doesn’t exist.
• Internally fires events for success or failure.

Usage Example

$app = new Application();
$app->setBasePath(__DIR__ . '/..'); // sets the base path to the parent directory

---

basePath($subPath = '')

Signature

public function basePath(string $subPath = ''): string

Purpose Retrieves the current base path (as set by setBasePath()). Optionally appends a subdirectory or file name.

Parameter	Type	Required?	Description
$subPath	string	No	Subdirectory or file to append to the base path (e.g. '/config').

Usage Example

// Assuming the base path is "/var/www/app"
$configDirectory = $app->basePath('config');
// Result: "/var/www/app/config"

---

setConfigPath($path)

Signature

public function setConfigPath(string $path): static

Purpose Sets where your configuration files are located. This is helpful if config files live outside the main application directory.

Parameter	Type	Required?	Description
$path	string	Yes	Directory where configuration files reside.

• Throws an exception if the path does not exist.
• Fires an internal event upon success or error.

Usage Example

$app->setConfigPath(__DIR__ . '/config');

---

configPath($subPath = '')

Signature

public function configPath(string $subPath = ''): string

Purpose Retrieves the main configuration directory, optionally appending a subdirectory or file name.

Parameter	Type	Required?	Description
$subPath	string	No	Subdirectory or file under the config directory (e.g. 'database.php').

Usage Example

$dbConfigFile = $app->configPath('database.php');
// Might yield "/var/www/app/config/database.php"

---

setEnvironment($environment)

Signature

public function setEnvironment(EnvironmentEnum $environment): static

Purpose Defines which environment the application is running in (e.g., Production, Development, Staging, etc.).

Parameter	Type	Required?	Description
$environment	EnvironmentEnum	Yes	Enum-like value representing the environment (e.g., EnvironmentEnum::DEVELOPMENT).

• Typically called at startup based on system or config checks.
• Fires an event signaling an environment change.

Usage Example

use DomainFlow\Application\Enum\EnvironmentEnum;

$app->setEnvironment(EnvironmentEnum::ENVIRONMENT_DEVELOPMENT);

---

environment()

Signature

public function environment(): EnvironmentEnum

Purpose Retrieves the current environment setting, allowing environment-specific logic elsewhere.

Parameter	Type	Required?	Description
None	N/A	N/A	Returns the current environment enum

Usage Example

if ($app->environment() === EnvironmentEnum::ENVIRONMENT_PRODUCTION) {
    // Production-specific logic
}

---

isEnvironment($environment)

Signature

public function isEnvironment(EnvironmentEnum $environment): bool

Purpose Checks if the current environment matches the provided enum value.

Parameter	Type	Required?	Description
$environment	EnvironmentEnum	Yes	Which environment to compare against

• Returns true if it matches, otherwise false.

Usage Example

if ($app->isEnvironment(EnvironmentEnum::ENVIRONMENT_TESTING)) {
    // Testing-specific logic
}

---

Comparative Descriptions

• setBasePath() vs. basePath()

• setBasePath() defines the root directory.

• basePath() reads that directory, with an optional subdirectory appended.

• setConfigPath() vs. configPath()

• setConfigPath() configures where the application’s config files live.

• configPath() returns that location, optionally appending further subpaths.

• setEnvironment() vs. environment() and isEnvironment()

• setEnvironment() modifies which environment you’re running in.

• environment() reads the current environment.

• isEnvironment() is a convenience checker for quick environment comparisons.

---

Practical Examples

Below is a small workflow showing how you might combine these calls in real code:

$app = new Application();

// Set the base path to your project directory
$app->setBasePath(__DIR__ . '/../');

// Set the config path to a folder named "config"
$app->setConfigPath($app->basePath('config'));

// Choose an environment based on a condition
if (file_exists($app->basePath('.env.dev'))) {
    $app->setEnvironment(EnvironmentEnum::ENVIRONMENT_DEVELOPMENT);
} else {
    $app->setEnvironment(EnvironmentEnum::ENVIRONMENT_PRODUCTION);
}

// Later...
if ($app->isEnvironment(EnvironmentEnum::ENVIRONMENT_DEVELOPMENT)) {
    // Perhaps enable verbose logging here
}

---

Extensibility

• Advanced Path Logic: You could dynamically set the base path in various contexts (CLI vs. web) or store multiple config paths for modular applications.
• Environment-based Boot: Use environment checks to toggle different providers, disable caches, or load special debugging tools.