Skip to content

CLAUDE.md

Latest commit

 

History

History
140 lines (100 loc) · 5.21 KB

CLAUDE.md

File metadata and controls

140 lines (100 loc) · 5.21 KB

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

A PHP configuration management library that loads and manages configuration files from a directory. The library provides two main classes:

  • Config: Static configuration loader and accessor
  • ConfigEditor: Extends Config to allow appending new configuration values to files

Key Architecture Concepts

Configuration Loading System

The Config class loads all .php files from a specified directory on instantiation. Each file should return an associative array. Files are keyed by their lowercase filename (without extension).

Default File Handling: The system now uses config.php as the default configuration file (changed from default.php). The default file is:

  • Loaded first before other configuration files
  • Accessible via Config::get() without specifying the config file parameter
  • Defined by the $default parameter in the constructor (defaults to 'config')

Fallback Behavior: For backward compatibility, if config.php doesn't exist, the system will fall back to looking for default.php (see Core/Config.php:75-76).

Static Storage Pattern

Both classes use static properties to store configurations globally:

  • $configs - Stores all loaded configuration arrays keyed by filename
  • $configFilePaths - Maps config keys to their file paths
  • $configDirPath - Stores the configuration directory path

This means once initialized, configs are accessible statically throughout the application without passing instances.

Configuration File Editing Constraints

The ConfigEditor::addToConfig() method has important limitations:

  • Append-only: Currently disabled editing existing keys due to key duplication issues (Core/ConfigEditor.php:33-34)
  • File format requirements: Config files must end with ]; or a RuntimeException is thrown
  • String values only: The current implementation only handles string values in the format 'key' => 'value' (Core/ConfigEditor.php:104)

Development Commands

Documentation Generation

Generate API documentation from PHPDoc comments:

composer require --dev clean/phpdoc-md
vendor/bin/phpdoc-md generate Core > docs/README.md

The project uses clean/phpdoc-md to generate markdown documentation from class PHPDoc comments. Generated docs are stored in the docs/ directory.

Running Examples

Test the library using the example file:

php Example.php

This demonstrates:

  • Loading configs from lib/Config/ directory
  • Retrieving values with Config::get()
  • Setting custom runtime values with Config::set()
  • Adding new config entries with ConfigEditor::addToConfig()
  • Reloading configs with Config::reload()

Lang\Text Integration

The Yohns\Lang\Text class has been refactored to use Config internally for language file management, eliminating code duplication.

How It Works

  • Text creates a separate Config instance pointing to the language directory (e.g., lib/Lang/)
  • Language files (en.php, es.php, etc.) are loaded into the same static Config::$configs array
  • Both config and language data coexist in the same Config storage

Important Considerations

Shared Static Storage: Since Config uses static properties, both application configs and language files share the same storage. This means:

  • Language files are accessible via Config::get('key', 'en') or Config::get('key', 'es')
  • The $default parameter changes when Text is initialized, affecting which config is used for Config::get('key') calls without a second parameter
  • Always specify the config file explicitly when mixing Text and Config: Config::get('siteName', 'config')

Auto-Update Feature: When a phrase is missing from the English language file, ConfigEditor automatically appends it using the same append-only mechanism as regular configs.

Directory Structure

Recommended structure for language files:

lib/
  ├── Config/          # Application configs
  │   ├── config.php
  │   └── db_tables.php
  └── Lang/            # Language files (separate directory)
      ├── en.php
      ├── es.php
      └── fr.php

Usage Example

use Yohns\Core\Config;
use Yohns\Lang\Text;

// Load application configs
new Config(__DIR__ . '/lib/Config');

// Load language files
new Text(__DIR__ . '/lib/Lang', 'es');

// Use translations
echo Text::L('welcome');                    // Gets from Spanish
echo Text::L('hello', [':name' => 'Juan']); // With replacements

// Access configs (specify file explicitly)
echo Config::get('siteName', 'config');

Namespace and Autoloading

  • Namespace: Yohns\Core and Yohns\Lang
  • PSR-4 Autoload: Yohns\ maps to Yohns/ directory
  • PHP Requirement: ^8.0

Configuration File Structure

Configuration files in lib/Config/ should return arrays:

<?php
return [
    'key' => 'value',
    'another_key' => 'another_value'
];

Multiple config files are supported (e.g., db_tables.php, language.php, config.php). Access them by filename without extension:

Config::get('key', 'db_tables');  // From db_tables.php
Config::get('key');               // From config.php (default)