Expander Laravel Package

Getting Started

Start by installing via Composer: composer require grasmash/expander. Create an expander instance (usually in a service or controller) and define expanders for each type you want to resolve—e.g., a UserExpander that fetches full user models from an ID. A minimal example:

use Grasmash\Expander\Expander;

$expander = new Expander();
$expander->addExpander('user', fn ($id) => User::find($id));

$payload = ['author' => ['type' => 'user', 'id' => 5]];
$expanded = $expander->expand($payload);
// Returns ['author' => User::find(5)]

First use case: transforming API request bodies that contain references (e.g., {"post": {"author": 123}}) into full hydrated objects before saving or processing.

Implementation Patterns

• Centralize expanders in a service provider or dedicated expander class, registering them via addExpander() or batching with addExpanders().
• Use expanders for common patterns: resolving Eloquent models (ModelExpander), API resources, config-driven lookups, or computed fields (e.g., full_name from first_name + last_name).
• Chain nested expansions: ensure related fields (author.posts) have their own expanders defined; the library handles recursive expansion automatically.
• Laravel integration: inject Expander into jobs, actions, or controllers. For APIs, expand payloads before returning JSON resources.
• Configuration-as-code: define expanders in config files or factories for maintainability and testing.

Gotchas and Tips

• Avoid side effects in expanders: keep them pure (e.g., fn ($id) => Model::find($id) not fn ($id) => DB::table('users')->increment('views')). Expanding may be called multiple times during recursion.
• Null safety: if an expander returns null, the field is omitted or remains null—explicitly handle missing references using ?? or fail-fast strategies.
• Type hints matter: expander keys should match the 'type' field in your payload precisely (case-sensitive). Use constants or enums for types to avoid typos.
• Performance: for high-volume payloads, cache expanders or use closures that defer expensive I/O (e.g., Laravel’s DB::connection()->enableQueryLog() helps profile expansion cost).
• Extensibility: extend Expander to override behavior (e.g., custom handling for circular refs or ExpansionException logging).
• Debugging tip: call $expander->expand($payload, true) (second arg = true) to get metadata about expansion steps—useful for tracing unexpected output.