Download the PHP package nabeghe/confix without Composer

Confix

Static-architecture PHP configuration library.
Simple, file-backed, class-based configuration with parent/child partitioning and dot-notation support.

Table of Contents

• Overview
• Installation
• Core Concepts
  • Standalone Config (own file)
  • Child Config (shared file)
  • Dynamic Method Calls
  • Nested Dot-Notation
  • Custom Validation
• Constants Reference
• API Reference
  • Reading Values
  • Writing Values
  • Removing Values
  • Bulk Data Operations
  • File Persistence
  • Overridable Hooks
• Running Tests
• License

Overview

Confix is designed with the goal that your configuration system should not require instantiating a class; it works in a fully static manner. You can have static configuration classes whose data source is a file; a file that returns the configuration as an array. Each class can have its own dedicated config file, or it can be a section within a parent config file.

In fact, two types of classes can be implemented using Confix:

1. Parent classes (Standalone configs) that have their own dedicated config file. For example, AppSettings, whose file could be app.php.
2. Child (nested) classes that are linked to a parent class. For example, DatabaseSettings, which can be linked to app.php and whose configuration is stored within a section (key) named database.

The purpose of having dedicated classes for configs is to use dynamic static methods, handled by __callStatic; for getting and setting config keys, so there is no need to write keys as raw strings. There is also no need to actually implement the static methods; it is sufficient to declare them in the class docblock as @method annotations to assist the IDE. That said, methods for accessing keys as plain strings or via dot-notation are also available.

Installation

Requires PHP ≥ 8.3.

Core Concepts

Base Config class

By default, Confix uses the config directory in your project root. It is recommended to configure this path yourself, even if you do not intend to change it. Therefore, you should have a base class, and all other config classes should extend this class instead of extending Confix directly. So:

You can also override methods such as mkdir, filePutContents, and varExport to implement your own logic. I recommend using Symfony\Component\VarExporter for varExport, and Symfony\Component\Filesystem\Filesystem for mkdir and filePutContents.

Standalone Config (own file)

A standalone config declares protected static array $_; which signals that it owns its own config file.

The directory defaults to <project-root>/config/. Override getDirectory() to customise it.

Child Config (shared file)

A child config sets PARENT to point at another config class. It lives as a keyed section inside the parent's file; no separate file is created.

The resulting app.php file will look like:

Chains of any depth work: GrandChildConfig::PARENT = CacheConfig::class delegates all the way up to AppConfig.

Dynamic Method Calls

Any method name that is not defined on Confix is intercepted by __callStatic() and treated as a config key:

Document these in your config's docblock for IDE autocompletion:

Nested Dot-Notation

Set const bool NESTED = true to enable accessing multi-level arrays with dot-notation strings.

Notice: Without NESTED = true, dot-notation keys are treated as literal strings.

Custom Validation

Override the protected validate() method to guard individual keys:

Pass false as the third argument to set() to skip validation:

Constants Reference

API Reference

Reading Values

get(string $name, bool $includeDefault = true): mixed

Returns the runtime value for $name. If not set, falls back to DEFAULTS[$name] when $includeDefault is true; returns null otherwise.

getDefault(string $name): mixed

Returns the value from DEFAULTS directly, bypassing runtime data.

has(string $name, bool $includeDefault = true): bool

Returns true when a non-null value exists for $name.

hasDefault(string $name): bool

Returns true if the key is declared in DEFAULTS.

Writing Values

set(string $name, mixed $value, bool $validate = true): bool

Stores $value for $name. Runs validate() first unless $validate is false. Returns true on success, false if validation fails or $value is null (which triggers removal).

Removing Values

forget(string $name): void

Removes $name from the runtime data. The default value is still accessible afterwards.

clear(?string $name = null): void

Clears all runtime data in the config.

Bulk Data Operations

getData(bool $default = false): array|bool

Returns the current runtime data array (or the child partition for child configs).

getDataByRef(): array (reference)

Returns a reference to the internal data array, allowing direct mutation.

setData(?array $newData = null, bool $save = false): bool

Replaces the entire runtime data array. Pass $save = true to immediately persist to file.

File Persistence

load(): bool

Loads data from the config file into memory. Auto-called on first access; you rarely need to call this manually.

reload(): bool

Forces a fresh read from the filesystem, discarding any in-memory changes.

reloadAllLoadedClasses(): array

Reloads every config class that has been accessed in the current request. Returns an array of [class => bool].

save(): bool

Serialises the runtime data to the config file using flock() for safe concurrent writes. Child configs delegate to the parent.

remove(): bool

Deletes the config file from disk.

Overridable Hooks

These protected static methods can be overridden in your base config class:

📜 License

Created with ❤️ by Nabeghe. Licensed under the MIT License. Free to use, modify, and distribute!