Download the PHP package detain/dbrel-data-php without Composer

TL;DR — Give it a JSON schema describing your tables and how they relate, pass it a database handle, and it produces a visualization-ready payload. No ORM, no AST parsing, no code generation.

Table of Contents

• Why dbrel-data-php?
• Features
• Installation
• Quick Start
• Schema JSON Format
• API Reference
• Relationship Types
• Integration Example
• Adapting Your Database Layer
• Architecture
• Companion Packages
• Requirements
• Contributing
• License

Why dbrel-data-php?

Information-schema joins tell you about foreign keys. Your application knows about everything else — the FIND_IN_SET column that binds hosts to groups, the cross-database references between your primary DB and your helpdesk DB, the polymorphic module_id column that points at different tables depending on a module_type value.

dbrel-data-php lets you describe those relationships in one JSON file, then computes the actual row matches between them so your frontend can draw edges without ever looking at the raw data itself.

Features

• JSON-defined schema — one file describes your modules, prefixes, primary keys, and every kind of relationship
• Three relationship types out of the box — direct foreign-key matches, find_in_set CSV column bridges, cross_db cross-database refs
• Works with any database layer — implement a 5-method DbInterface around your existing mysqli/PDO/custom wrapper
• Pivot filtering — re-center the payload on a specific table/row and auto-trim to tables within 2 hops
• Row-level match arrays — not just "accounts links to vps", but exactly which rows link to which
• Virtual tables — synthesize tables from pivoted rows (e.g. accounts_ext built from a key/value accounts_extra table)
• Metadata baked in — query time, table / row counts, database list, pivot state
• Zero framework lock-in — vanilla PHP 7.4+ with PSR-4 autoloading, no Laravel/Symfony assumptions
• Stable JSON output — byte-compatible with the Node.js sister package dbrel-data-js

Installation

Then require Composer's autoloader and use the classes:

Quick Start

A minimal endpoint that returns the payload for a given customer:

Hand that JSON to dbrel-viz and you're done.

Schema JSON Format

The schema is a single JSON file with these top-level keys. The library only strictly requires relationships; everything else is for metadata and display.

API Reference

DbRel\Data\RelationshipSchema

Loads and normalizes the relationship schema JSON.

DbRel\Data\DataCollector

Accumulates rows from SQL queries into a normalized structure.

DbRel\Data\RelationshipMatcher

Given collected data and schema rules, computes row-level match arrays.

Algorithmic behavior:

• direct / cross_db — strict string-equality match on source_field value vs. target_field value
• find_in_set — source field is split on , and compared to target field by in_array()
• Source values of null, '', '0' are skipped to avoid noise (you rarely want to connect every row with a zero FK)
• Only relationships with at least one match are returned

DbRel\Data\DataProvider

Ties everything together and emits the final payload.

DbRel\Data\DbInterface

A 5-method contract your database wrapper must satisfy.

If you use MyAdmin's \MyDb\Mysqli\Db, it already matches — no adapter needed. For other stacks see Adapting Your Database Layer.

Relationship Types

The schema supports several type values. Internally the matcher collapses them down to three behaviors.

direct

Classic FK join. Cheap, O(N×M) with early-exit on null/zero/empty source values.

find_in_set

Source column is CSV. The matcher splits it on ,, trims each token, and checks each target row's value against the set.

cross_db

Same matching logic as direct, but the frontend draws the edge in a different style so you can see DB boundaries at a glance.

Integration Example

Drop-in AJAX endpoint using a procedural entry point:

Point dbrel-viz's ajaxUrl at this script and you have a working, swappable-renderer database explorer.

Adapting Your Database Layer

You only need to implement the 5-method DbInterface. Example wrapping PDO:

Collectors expect DbInterface::next_record() to leave the current row on a $db->Record public property — this matches the MyAdmin and PHPLIB tradition. If your wrapper returns rows differently, either set $this->Record in next_record() (as above) or expose getRecord(): array which DataCollector will call via method_exists().

Architecture

Companion Packages

This package is half of a two-package system:

Payload parity — dbrel-data-php and dbrel-data-js emit byte-identical JSON given the same schema and data. Swap backends freely; the frontend won't notice.

Requirements

• PHP ≥ 7.4 (tested on 7.4, 8.0, 8.1, 8.2, 8.3)
• ext-mysqli (for the default DbInterface shape — or adapt to PDO, see above)
• ext-json
• MySQL or MariaDB — any version supporting the queries you write

Contributing

PR guidelines

1. One feature or fix per PR
2. New relationship types go on RelationshipMatcher; schema format is frozen
3. All public APIs must carry PHPDoc
4. PHPUnit tests for any behavior change
5. PSR-12 code style

Ideas we'd love help with

• PostgreSQL adapter — the matcher is DB-agnostic, but we don't ship adapters yet
• Schema generator — scan information_schema and build the JSON automatically
• Caching layer — the matcher is deterministic, so compute() results can be cached
• Symfony / Laravel integration packages

License

Joe Huss / InterServer