Dict Laravel Package

Product Decisions This Supports

• Standardization of Data Structures: Replace ad-hoc associative arrays with a structured Dict class to enforce consistency across configuration, request payloads, and dynamic attributes (e.g., user metadata). Reduces ambiguity in key access and improves maintainability.
• Configuration Management: Centralize app settings, feature flags, or environment variables into type-safe Dict instances with built-in merging, defaults, and validation. Aligns with Laravel’s config() but adds explicit intent (e.g., dict->get('key', default)).
• Attribute Stores: Model dynamic entity attributes (e.g., Eloquent model metadata, API request extensions) with a unified CRUD API, reducing boilerplate for get()/set() operations.
• Bulk Data Transformations: Simplify complex array manipulations (e.g., merging user preferences with defaults, filtering nested structures) using Dict methods like merge(), update(), or filter().
• Laravel Ecosystem Alignment: Leverage Laravel-friendly patterns (e.g., collection-like iteration, service container integration) while avoiding the overhead of full Collection classes for simple key-value operations.
• Build vs. Buy: Avoid reinventing dictionary abstractions (e.g., custom array wrappers) when this package offers a lightweight, MIT-licensed solution with minimal dependencies.
• Roadmap Priorities:
  • High: Adopt for new Laravel projects or modules where data consistency is critical.
  • Medium: Pilot in legacy codebases for configuration/request handling.
  • Low: Replace raw arrays in high-performance paths (e.g., real-time systems) unless benchmarked.

When to Consider This Package

• Adopt if:

  • Your codebase relies on raw arrays for associative data but lacks consistency (e.g., mixed isset()/?? patterns, no defaults).
  • You need a lightweight alternative to Laravel’s Collection for simple key-value operations (lower memory/CPU overhead).
  • Configuration or attribute management is fragmented across arrays/objects, and you want a unified API with merging/validation.
  • Your team prioritizes explicit intent over implicit array access (e.g., dict->set('key', $value) vs. $array['key'] = $value).
  • You’re using PHP 8.2+ and want to migrate toward stricter type safety without adopting heavy frameworks (e.g., Symfony’s OptionsResolver).
  • You’re building a new Laravel module where data structure consistency is a priority.

• Look elsewhere if:

  • You need advanced collection features (e.g., complex aggregations, lazy loading) → Use Laravel’s Collection or Illuminate\Support\Enumerable.
  • Your use case requires immutability or functional programming (e.g., pure transformations) → Consider spatie/array-to-object or league/arrayobjects.
  • Performance is critical for high-frequency operations (e.g., real-time systems) → Benchmark against raw arrays first.
  • You’re already using a dedicated config package (e.g., Laravel’s Config facade) that handles merging/validation natively.
  • The team prefers native PHP arrays for flexibility and rejects abstraction overhead (e.g., junior devs or performance-sensitive teams).

How to Pitch It (Stakeholders)

For Executives:

"This package standardizes how we handle associative data in PHP—replacing raw arrays with a structured Dict class. For example, instead of scattered isset() checks or ?? operators, we’d use dict->get('key', default), which reduces bugs and improves code readability. It’s especially valuable for configuration management and dynamic data stores, where consistency saves development time and reduces technical debt. With no dependencies and minimal overhead, it’s a low-risk way to modernize our data handling without disrupting existing workflows."

For Engineering:

*"php-standard-library/dict provides a thin, Laravel-compatible wrapper for arrays with key benefits:

• Type-safe access: Methods like get(), set(), and has() with defaults eliminate isset() spaghetti.
• Bulk operations: Merge, update, or filter dictionaries in one call (e.g., dict->merge($overrides)).
• Iteration support: Works seamlessly with foreach and collection-style loops.
• Zero dependencies: Drop it into Laravel or plain PHP without bloat.

Ideal for:

• Replacing raw arrays in config files or feature flags.
• Standardizing attribute stores (e.g., user metadata, plugin settings).
• Simplifying data transformations where merging/updating is common.

Tradeoffs:

• Slightly slower than raw arrays (but negligible for most use cases).
• Not a replacement for Laravel’s Collection—this is for simple key-value needs.

Proposal: Pilot it in one module (e.g., config management) to measure readability gains before rolling out broadly. Start with new features to avoid legacy code friction."*

For Developers:

*"Why use Dict instead of arrays?

• Safer access: dict->get('key', default) vs. $array['key'] ?? default.
• Cleaner merges: dict->merge($newData) instead of manual loops.
• Consistent iteration: Works like arrays but with built-in safety.
• Laravel-friendly: Integrates with service containers, requests, and config.

Example:

// Before (raw array)
$config = config('app');
$theme = $config['theme'] ?? 'light';

// After (Dict)
$dict = new Dict(config('app'));
$theme = $dict->get('theme', 'light');

When to avoid:

• High-performance paths (benchmark first).
• Complex collections (use Laravel’s Collection instead).
• Teams resistant to abstraction.

Next steps:

1. Try it in a new feature (e.g., config or request handling).
2. Add PHPStan rules to enforce adoption in critical paths.
3. Measure impact on readability and bug rates."*