Environment Configuration

Purpose and Scope

This document covers environment-specific configuration through environment variables and the .env file. These settings include sensitive credentials, deployment-specific parameters, and secrets that should not be committed to version control.

For runtime application settings stored in the database (such as mode, mail configuration, and feature flags), see Application Settings. For dependency and package management, see Dependencies and Package Management.

Sources: README.md1-40

---

Configuration Architecture

The Light framework loads environment variables during application bootstrap to configure critical infrastructure components. These variables are read from a .env file in the application root directory and accessed through PHP's $_ENV superglobal.

Environment Variable Flow Diagram

Sources: src/App.php64-66 src/App.php616-629 src/App.php647 src/App.php671-684 src/App.php810-813 README.md6-17 README.md20-27 README.md29-39

---

Required Environment Variables

Database Connection Configuration

The Light framework requires six database environment variables to establish MySQL connectivity. These variables are consumed by the Light\DB database abstraction layer.

Variable	Required	Description	Example
DATABASE_HOSTNAME	Yes	MySQL server hostname or IP address	localhost, db.example.com
DATABASE_DATABASE	Yes	Database name to connect to	light_production
DATABASE_USERNAME	Yes	Database user with appropriate privileges	light_user
DATABASE_PASSWORD	Yes	Database user password	secure_password_123
DATABASE_PORT	No	MySQL port number (defaults to 3306)	3306
DATABASE_CHARSET	No	Character set for database connection	utf8mb4

Configuration Example:

Sources: README.md9-17

---

JWT Secret Configuration

The JWT_SECRET environment variable is a cryptographically secure random string used for signing and verifying JSON Web Tokens (JWT). This secret is critical for the security of the authentication system.

Variable	Required	Description	Security Notes
JWT_SECRET	Yes	Random string for JWT token signing	Must be at least 32 characters; use cryptographically secure random generation

Purpose:

• Signs access tokens generated by User.login()
• Validates tokens in Auth\Service during request authentication
• Prevents token forgery and tampering

Generation Example:

Configuration Example:

Security Considerations:

• Never commit the actual secret to version control
• Rotate the secret periodically (requires re-authentication of all users)
• Use different secrets for development, staging, and production environments
• Store production secrets in secure vault systems (e.g., AWS Secrets Manager, HashiCorp Vault)

Sources: README.md20-27

---

OAuth Provider Configuration

The Light framework supports OAuth-based social authentication. Each OAuth provider requires provider-specific credentials obtained from their developer consoles.

Google OAuth Configuration

To enable Google Sign-In, install the Google API client library and configure the client ID:

Installation:

Environment Variable:

Variable	Required	Description	Obtain From
GOOGLE_CLIENT_ID	No*	OAuth 2.0 client ID from Google Cloud Console	Google Cloud Console → APIs & Services → Credentials

*Required only if Google authentication is enabled.

Configuration Example:

Usage Flow:

1. Client calls googleAuth mutation in AuthController with OAuth token
2. AuthController validates token using GOOGLE_CLIENT_ID
3. User is authenticated or registered based on Google account information

Sources: README.md29-39

---

Cookie Configuration

The framework uses HTTP-only cookies to store JWT tokens. Cookie behavior is controlled by several environment variables that affect security, cross-site access, and partitioning.

Variable	Required	Default	Description
COOKIE_DOMAIN	No	"" (empty)	Domain scope for cookies; empty allows subdomain sharing
COOKIE_SECURE	No	false	Requires HTTPS for cookie transmission
COOKIE_SAMESITE	No	"Lax"	Controls cross-site cookie behavior (Strict, Lax, or None)
COOKIE_PARTITIONED	No	false	Enables partitioned cookies for third-party context (HTTPS only)

Configuration Example:

Cookie Partitioning: When COOKIE_PARTITIONED=true and HTTPS is enabled ($_SERVER["HTTPS"] == "on"), the framework appends ;Partitioned to the SameSite attribute, enabling CHIPS (Cookies Having Independent Partitioned State) for third-party contexts.

Implementation Details:

The App::setAccessTokenCookie() method src/App.php614-629 constructs the cookie with these settings:

Refresh Token Cookies: The refresh token uses a path-restricted cookie src/App.php671-684 with scope limited to /refresh_token (or {API_PREFIX}/refresh_token if API_PREFIX is set).

Sources: src/App.php614-629 src/App.php671-684

---

Timezone Configuration

The framework supports timezone configuration via the TZ environment variable, which sets the default timezone for all date/time operations.

Variable	Required	Description	Example Values
TZ	No	PHP timezone identifier	UTC, America/New_York, Asia/Tokyo

Configuration Example:

Implementation: The App constructor checks for $_ENV["TZ"] and calls date_default_timezone_set() during initialization src/App.php64-66

Sources: src/App.php64-66

---

API Path Prefix Configuration

The API_PREFIX environment variable allows mounting the API under a custom path prefix, affecting the refresh token cookie path.

Variable	Required	Description	Example
API_PREFIX	No	Path prefix for API endpoints	/api, /v1

Configuration Example:

Effect on Refresh Token: When set, the refresh token cookie is scoped to {API_PREFIX}/refresh_token instead of the script directory src/App.php671-674

Sources: src/App.php671-674

---

WebAuthn Configuration

WebAuthn (FIDO2) authentication requires configuration of the Relying Party identifier, which must match the domain serving the application.

Variable	Required	Description	Default
RP_ID	No	WebAuthn Relying Party ID (domain)	$_SERVER["SERVER_NAME"]

Configuration Example:

Implementation: The App::getRpId() method src/App.php804-814 returns $_ENV["RP_ID"] if set, otherwise falls back to the server name. The special case "0.0.0.0" is converted to "localhost" for local development.

WebAuthn Entity Creation:

Sources: src/App.php804-814 src/App.php816-832

---

Environment File Setup

Creating the .env File

The .env file should be created in the application root directory (same level as composer.json). This file is typically excluded from version control via .gitignore.

Minimal .env Template:

Environment-Specific Configuration

Development Environment (.env.development):

Production Environment (.env.production):

Security Best Practices

Environment Variable Security Checklist:

Practice	Description	Critical
Version Control Exclusion	Add .env to .gitignore to prevent committing secrets	✓ Yes
File Permissions	Set .env to 0600 (read/write owner only) on Unix systems	✓ Yes
Secret Rotation	Rotate JWT_SECRET and database passwords periodically	Recommended
Environment Separation	Use different credentials for dev/staging/production	✓ Yes
Vault Integration	Use secret management services for production	Recommended
Minimal Access	Grant database users only necessary privileges	✓ Yes

File Permission Commands:

Configuration Loading

The framework loads environment variables during application bootstrap in Light\App. Variables are accessed using PHP's $_ENV superglobal array:

Implementation Reference:

• Timezone: src/App.php64-66
• JWT Secret: src/App.php647 src/App.php676 src/App.php884 src/App.php904
• Cookie Settings: src/App.php616-629 src/App.php677-684
• Database: Handled by Light\Db\Adapter (see Dependencies and Package Management)

Sources: src/App.php64-66 src/App.php614-629 src/App.php647 README.md1-40

---

Environment Variable Validation

Missing Variable Detection

The Light framework performs validation during bootstrap to ensure required environment variables are set. Missing critical variables will prevent application startup.

Critical Variables Checked:

• Database connection parameters (DATABASE_HOSTNAME, DATABASE_DATABASE, DATABASE_USERNAME)
• JWT secret (JWT_SECRET)

Validation Recommendations:

Create a validation script to check configuration before deployment:

Production Checklist:

Variable	Check	Notes
JWT_SECRET	✓ Minimum 32 characters	Validate strength
COOKIE_SECURE	✓ Set to true for HTTPS	Required for production
COOKIE_SAMESITE	✓ Set to Strict or Lax	Prevents CSRF attacks
DATABASE_PASSWORD	✓ Strong password	Avoid default/weak passwords
RP_ID	✓ Matches domain	Required if using WebAuthn
TZ	✓ Set explicitly	Avoid server timezone differences

Sources: src/App.php64-66 src/App.php614-629 src/App.php647 src/App.php804-814

---

Configuration Reference Summary

Complete Environment Variable Reference Table:

Category	Variable	Type	Required	Purpose
Database	DATABASE_HOSTNAME	String	Yes	MySQL server address
DATABASE_DATABASE	String	Yes	Database name
DATABASE_USERNAME	String	Yes	Database user
DATABASE_PASSWORD	String	Yes	Database password
DATABASE_PORT	Integer	No	MySQL port (default: 3306)
DATABASE_CHARSET	String	No	Character encoding (default: utf8mb4)
Authentication	JWT_SECRET	String	Yes	JWT signing key (min 32 chars)
OAuth	GOOGLE_CLIENT_ID	String	Conditional	Google OAuth client ID

Sources: README.md1-40