README

MasterDetailMapper is a lightweight PHP utility class for extracting master-detail relationships from a flat array of associative data.
It helps you identify unique “master” rows based on one or more key fields, and then retrieve all related “detail” rows for a given master.

Designed for PHP 8.

Features

• Extract unique master rows from flat data
• Track the original indexes of master rows
• Retrieve detail rows for a specific master
• No external dependencies
• Simple, predictable API

Use Case

This class is useful when you have denormalized data such as:

• Database query results with repeated master data
• CSV or Excel imports
• API responses with flattened relational data

Example scenario:

You want:

• Masters → unique orders
• Details → products per order

Installation

Install via Composer:

composer require borwita-packages/master-detail-mapper

Constructor

public function __construct(array $data, array $masterKeyFields)

Parameters

Public Methods

getMasterRows(): array

Returns rows that represent unique master records.

getMasterIndexes(): array

Returns the original indexes of the master rows in the input data.

getDetailsByMasterData(array $masterData): array

Returns all rows related to the given master row.

Example Usage

use BorwitaPackages\MasterDetailMapper\MasterDetailMapper;

// Define the data
$data = [
    ['order_id' => 1001, 'customer_id' => 'C01', 'product' => 'Apple',  'qty' => 2],
    ['order_id' => 1001, 'customer_id' => 'C01', 'product' => 'Banana', 'qty' => 1],
    ['order_id' => 1002, 'customer_id' => 'C02', 'product' => 'Orange', 'qty' => 5],
];
// Define the master key fields
$masterKeyFields = ['order_id', 'customer_id'];
// Create class intance
$mapper = new MasterDetailMapper($data, $masterKeyFields);

// Retrieve master data
$masters = $mapper->getMasterRows();
print_r($masters);

// Retrieve details data
$details = $mapper->getDetailsByMasterData($masters[0]);
print_r($details);

Notes & Considerations

• Master keys are created by concatenating field values. Ensure field combinations are unique to avoid collisions.
• Input data must be associative arrays with consistent keys.
• The first occurrence of a master row is preserved.

Author

Andrias Melianus S
Email: andriasmelianus@gmail.com