Registry Laravel Package

Getting Started

Start by installing the package via Composer with composer require joomla/registry "^4.0", ensuring you meet the minimum PHP 8.3 requirement. The Registry class is the core interface—create instances with new Registry($data) where $data can be a string (JSON/XML/YAML/INI), array, or object. For immediate use, load config from files or strings:

$registry = new Registry();
$registry->loadFile('config.json'); // default JSON format
$registry->loadString('<root><node name="key">value</node></root>', 'xml');

Then access values using dot-notation paths like $registry->get('parent.child.key') or via array syntax ($registry['parent']['child']['key']). The fastest first use case: replacing a hardcoded config array with a JSON file and using loadFile() for centralized configuration management.

Implementation Patterns

• Configuration Management: Store app settings in JSON/YAML files and load them into a singleton-like Registry instance (not a true singleton—create per-request), e.g., $registry->loadFile(__DIR__ . '/config/app.yaml') and access via $registry->get('database.host').
• Config Merging: Chain multiple load*() calls to merge configs (later loads override earlier) or use merge($otherRegistry) for structured overrides—e.g., merge base config + environment-specific overrides (config.json + config.local.json).
• Flattening & Iteration: Use flatten() for simple iteration (returns ['nested.key' => 'value']) or iterate directly via ArrayAccess.
• Type Safety: Rely on native type handling—no string conversion needed (unlike v1). Pass typed data via loadObject($typedObject) or loadArray($typedArray).
• Custom Formats: Implement FormatInterface for bespoke formats (e.g., TOML) and register via Factory::getFormat('toml', ['format_namespace' => 'App\\Format']).

Gotchas and Tips

• Nested Key Consistency: Use dot-notation consistently ('parent.child') for paths—set('parent.child', $val) expects dot-delimited strings, not arrays. Avoid mixing array access with dot paths in the same workflow to prevent confusion.
• XML Formatting Strictness: XML imports require <node name="..."> structure; misformatted XML (e.g., missing name attributes) causes silent failures. Use loadString($xml, 'xml', ['nodeName' => 'custom']) to customize element names.
• Merging Depth: merge($source) is recursive by default; pass false for flat (only top-level) merging. Verify behavior with print_r($registry->toArray()) after merging.
• Type Coercion: JSON/YAML/INI formats preserve types in v4+, but malformed values (e.g., "false" as string in INI) may still coerce—test edge cases like empty strings vs null.
• PHP 8.3+ Requirement: v4.0+ drops support for older PHP; ensure CI/CD environments match. Breaking changes include removal of separator parameter in set()/loadArray() and strict string input for stringToObject().
• No Caching: Unlike v1, Registry has no getInstance()—each instance is standalone. Avoid repeated file loads in tight loops; cache parsed data externally if performance-critical.