Download the PHP package akosnoavek/models-data-extractor without Composer

Laravel Models Data Extractor

Extract information from Eloquent models, plain PHP arrays, or generic objects, based on a declarative schema, and render the result as an IteratorElement tree, a plain array, JSON, HTML, CSV, or XLSX.

Installation

The package ships a Laravel service provider (AkosNoavek\DataExtractor\Support\ServiceProvider) and a DataExtractor facade, both auto-discoverable via the laravel.providers / laravel.aliases entries in composer.json.

Configuration

Publish the config file to customize it:

This creates config/data_extractor.php:

• model_classes — a root section decides whether it points at a single related model or a collection by inspecting the parent class of the resolved value: Illuminate\Database\Eloquent\Model is always recognized. If your application extends a shared intermediate base class (e.g. App\Models\BaseModel extends Model), list that class's FQCN here so a root resolving to one of its instances is treated as a single model instead of being (mis-)treated as a collection.

  This matters because the failure mode is silent: an Eloquent model instance is not iterable and exposes no public properties, so if its base class isn't recognized, the root section's foreach produces zero clones and the entire section silently disappears from the output — no error is raised.

• date_format — the date()/Carbon::format() pattern applied to any field declared with "date" => true (default d/m/Y).

Core concepts

Every extraction involves two independent things:

1. The target — the data you are extracting from. It can be an Eloquent Model, a plain PHP array, or a generic object (e.g. the result of json_decode).
2. The schema — a declarative description of what to extract and how to label it: which fields to pull out, how to group them into sections, and how to format them.

DataExtractor::make($target) binds the target; the terminal method (toArray, toJson, toHtml, toCsv, toXlsx, extract) binds the schema and runs the extraction.

The schema data structure

A schema is a nested associative array (or its JSON equivalent) built from two kinds of nodes: fields and sections.

Field

A leaf node that reads a single value out of the target.

• path supports dot notation for nested properties/relations, e.g. "path" => "address.city".
• date parses the resolved value with Carbon and formats it as d/m/Y (falls back to an empty string if it can't be parsed).
• evaluate_when_empty: false removes the field from the output entirely when its resolved value is empty — useful for optional data.

Section

A node that groups other fields/sections together under a label.

Sections can be nested arbitrarily deep — a section's fields array can itself contain other sections.

Internally, every node (field or section) is parsed into an AkosNoavek\DataExtractor\Iterators\IteratorElement. The keys of the fields array are only used as PHP array keys while you author the schema; they are not part of the output. If a child node doesn't declare its own label, its schema key is used as the label.

Root sections (relations / collections)

A section can pull its target from a relation or nested collection on the parent target, instead of the outer target, via root:

• If root resolves to a single related model (or a plain array/object), the section's fields are simply resolved against that related record.
• If root resolves to a collection (e.g. a hasMany relation, or an array of arrays), the section is cloned once per item, in order, and each clone's fields are resolved against that item. This means a schema with a single root section template can expand into N sections/rows in the output.

A resolved Eloquent model is only recognized as a "single related model" if its base class is Illuminate\Database\Eloquent\Model or is registered via data_extractor.model_classes — otherwise it is (mis-)treated as an empty collection and the whole section silently disappears from the output. If your models extend a shared base class, make sure to register it.

• toArray() / toJson() / toHtml() / extract() reflect this naturally: you get one section/row per related record.
• toCsv() / toXlsx() produce one row per resolved section instance: a root pointing at a collection of N records generates N rows, each sharing the same set of columns. Fields declared directly on an outer section (not inside a root section) are constant and get repeated onto every row generated by its nested root sections.
• Because of this, every nested section in a CSV/Excel schema must declare a root — a plain nested section (no root) only ever produces a single, non-repeating set of values, which is redundant in a flat export: declare those fields directly on the parent section instead. toCsv()/toXlsx() throw an exception if they encounter a nested section without root.
• Multiple direct fields on the same section that resolve to the same label (e.g. two schema entries pointing at different paths but sharing a label) are still merged into a single column, joined with "; ".

Multi-value fields (.*. path syntax)

A single field can also flatten a to-many relation into one value, without declaring a nested section, using .*. in its path:

This resolves name on every item of the children relation/collection and joins them into one string, using the separator configured for the output format (toHtml/toCsv/toXlsx/toArray use "<br>").

Providing the schema: inline array vs. JSON file

Every terminal method (extract, toArray, toJson, toHtml, toCsv, toXlsx) accepts the schema in one of two equivalent ways:

1. As an inline PHP array, via the data argument:

Under the hood, the array is json_encoded to a temporary file and read back as JSON — so an inline array and a JSON file are handled identically.

2. As a path to a JSON schema file, via the filename argument:

You must pass at least one of data or filename — an exception is thrown if neither is provided. If both are given, data takes precedence.

A JSON file can also contain multiple named schemas (top-level keys), and you extract a specific one via the section argument:

Working with different target types

The same schema works unchanged against any of the three supported target shapes — only how path is resolved differs internally (array key lookup vs. object/model property access):

Output formats

• extract() returns the raw IteratorElement tree (each element exposes type, label, data, path, fields, root, etc.) — useful when you want to post-process the result yourself.
• toArray() / toJson() return a nested structure of {label, value, ...} leaves grouped under {label, data: [...]} sections, mirroring the schema's shape (including root-generated clones).
• toHtml() renders an unordered list per section by default; a field/section can opt into a custom Blade view for full control over its markup.
• toCsv() / toXlsx() flatten the whole tree into a header row and one or more data rows — one column per unique label, one row per resolved root instance. See Root sections above: every nested section must declare a root, and duplicate labels within the same section are merged.

Running the tests