Docs WIP: Add more TOC.

tabennett · tabennett · commit 8291267f66d1 · 2025-10-11T20:23:44.000-05:00
diff --git a/docs/advanced/caching.md b/docs/advanced/caching.md
@@ -2,6 +2,20 @@
 
 Holloway's entity caching system is a critical performance optimization that implements the Identity Map pattern. It ensures that each database record creates only one entity instance per request, provides dirty tracking for efficient updates, and eliminates redundant entity creation.
 
+## Table of Contents
+
+- [How Entity Caching Works](#how-entity-caching-works)
+- [Entity Cache Architecture](#entity-cache-architecture)
+- [Cache Benefits](#cache-benefits)
+- [Cache Management](#cache-management)
+- [Cache Configuration](#cache-configuration)
+- [Performance Characteristics](#performance-characteristics)
+- [Cache in Relationships](#cache-in-relationships)
+- [Cache Debugging](#cache-debugging)
+- [Best Practices](#best-practices)
+- [Cache Limitations and Considerations](#cache-limitations-and-considerations)
+- [Next Steps](#next-steps)
+
 ## How Entity Caching Works
 
 ### The Identity Map Pattern
diff --git a/docs/api/reference.md b/docs/api/reference.md
@@ -2,6 +2,15 @@
 
 Complete reference documentation for Holloway's core classes and interfaces. This reference covers all public methods, properties, and configuration options.
 
+## Table of Contents
+
+- [Core Classes](#core-classes)
+- [Configuration Options](#configuration-options)
+- [Events](#events)
+- [Exceptions](#exceptions)
+- [Constants](#constants)
+- [Next Steps](#next-steps)
+
 ## Core Classes
 
 ### Mapper
diff --git a/docs/architecture.md b/docs/architecture.md
@@ -1,9 +1,21 @@
 # Architecture Overview
 
-This document explains how Holloway works under the hood: the design patterns, lifecycle hooks, and infrastructure that power the data mapper. You do **not** need any of this to ship your first feature—treat it as the engineering manual once you’re comfortable with the basics.
+This document explains how Holloway works under the hood: the design patterns, lifecycle hooks, and infrastructure that power the data mapper. You do **not** need any of this to ship your first feature—treat it as the engineering manual once you're comfortable with the basics.
 
 > **Audience:** framework contributors, senior engineers integrating Holloway deeply, or anyone debugging advanced scenarios.  
-> **Prerequisites:** you’ve completed the [Getting Started](./getting-started.md) tutorial and shipped at least one mapper in your application.
+> **Prerequisites:** you've completed the [Getting Started](./getting-started.md) tutorial and shipped at least one mapper in your application.
+
+## Table of Contents
+
+- [Before you dive in](#before-you-dive-in)
+- [The Datamapper Pattern](#the-datamapper-pattern)
+- [Core Components](#core-components)
+- [Data Flow](#data-flow)
+- [Advanced Architecture Features](#advanced-architecture-features)
+- [Performance Considerations](#performance-considerations)
+- [Laravel Integration Points](#laravel-integration-points)
+- [Design Patterns Used](#design-patterns-used)
+- [Next Steps](#next-steps)
 
 ## Before you dive in
 
diff --git a/docs/core-concepts/base-classes.md b/docs/core-concepts/base-classes.md
@@ -4,6 +4,18 @@ This guide documents a reference implementation of base `Entity` and `Mapper` cl
 
 > **Note**: This is ONE approach to implementing Holloway entities and mappers. Holloway is flexible and doesn't require these patterns, but they represent a battle-tested approach used in a production multi-tenant SaaS application.
 
+## Table of Contents
+
+- [Overview](#overview)
+- [Base Entity Class](#base-entity-class)
+- [Base Mapper Class](#base-mapper-class)
+- [Entity Traits](#entity-traits)
+- [Example Child Mapper](#example-child-mapper)
+- [Example Child Entity](#example-child-entity)
+- [Integration Example](#integration-example)
+- [When to Use These Base Classes](#when-to-use-these-base-classes)
+- [Next Steps](#next-steps)
+
 ## Overview
 
 This reference implementation extends Holloway's base classes to provide:
diff --git a/docs/core-concepts/entity-hydration.md b/docs/core-concepts/entity-hydration.md
@@ -2,6 +2,20 @@
 
 Entity hydration is the process of converting database records (raw data) into domain entity instances. This is one of the core responsibilities of the datamapper pattern, and Holloway gives you complete control over how this process works.
 
+## Table of Contents
+
+- [Understanding the Core Contract](#understanding-the-core-contract)
+- [The Challenge](#the-challenge)
+- [Approach 1: Simple Manual Hydration](#approach-1-simple-manual-hydration)
+- [Approach 2: Magic Accessor Pattern (Recommended for PHP 8.0-8.3)](#approach-2-magic-accessor-pattern-recommended-for-php-80-83)
+- [Approach 3: Named Constructors](#approach-3-named-constructors)
+- [Approach 4: Reflection-Based](#approach-4-reflection-based)
+- [Comparison Table](#comparison-table)
+- [Recommendations](#recommendations)
+- [Key Principles](#key-principles)
+- [Next Steps](#next-steps)
+- [Further Reading](#further-reading)
+
 ## Understanding the Core Contract
 
 At its heart, Holloway requires mappers to implement two critical methods:
diff --git a/docs/core-concepts/entity-lifecycle.md b/docs/core-concepts/entity-lifecycle.md
@@ -7,6 +7,19 @@ One of the most important concepts in the datamapper pattern is understanding th
 
 Understanding this distinction is critical for proper validation, initialization, and domain logic placement.
 
+## Table of Contents
+
+- [The Two Lifecycles](#the-two-lifecycles)
+- [Why Separate These?](#why-separate-these)
+- [Implementation Patterns](#implementation-patterns)
+- [Real-World Example](#real-world-example)
+- [Validation Placement](#validation-placement)
+- [Common Pitfalls](#common-pitfalls)
+- [Decision Matrix](#decision-matrix)
+- [Key Principles](#key-principles)
+- [Next Steps](#next-steps)
+- [Further Reading](#further-reading)
+
 ## The Two Lifecycles
 
 ### Creation Lifecycle
diff --git a/docs/examples/best-practices.md b/docs/examples/best-practices.md
@@ -2,6 +2,19 @@
 
 This guide covers advanced patterns, performance optimizations, and proven techniques for building robust applications with Holloway's datamapper architecture.
 
+## Table of Contents
+
+- [Architecture Best Practices](#architecture-best-practices)
+- [Performance Optimization](#performance-optimization)
+- [Error Handling](#error-handling)
+- [Testing Strategies](#testing-strategies)
+- [Security Best Practices](#security-best-practices)
+- [Monitoring and Debugging](#monitoring-and-debugging)
+- [Code Organization](#code-organization)
+- [Performance Benchmarking](#performance-benchmarking)
+- [Production Deployment](#production-deployment)
+- [Next Steps](#next-steps)
+
 ## Architecture Best Practices
 
 ### Entity Design
diff --git a/docs/examples/complete-examples.md b/docs/examples/complete-examples.md
@@ -2,6 +2,12 @@
 
 This guide provides comprehensive, real-world examples of Holloway datamapper implementations. Each example demonstrates best practices, proper architecture, and practical patterns you can adapt for your own projects.
 
+## Table of Contents
+
+- [Example 1: Blog Management System](#example-1-blog-management-system)
+- [Example 2: E-commerce Order Management](#example-2-e-commerce-order-management)
+- [Next Steps](#next-steps)
+
 ## Example 1: Blog Management System
 
 A complete blog system with users, posts, comments, and categories.
diff --git a/docs/getting-started.md b/docs/getting-started.md
@@ -2,6 +2,19 @@
 
 This quick tour shows how to install Holloway in a fresh Laravel project, register your first mapper, and perform real CRUD using rich domain entities. Follow the steps in order—each one builds on the last.
 
+## Table of Contents
+
+- [Prerequisites](#prerequisites)
+- [1. Install the package](#1-install-the-package)
+- [2. Create a Holloway service provider](#2-create-a-holloway-service-provider)
+- [3. Add base classes for entities and mappers](#3-add-base-classes-for-entities-and-mappers)
+- [4. Build your first entity and mapper](#4-build-your-first-entity-and-mapper)
+- [5. Wire it into Laravel](#5-wire-it-into-laravel)
+- [6. Smoke-test the setup](#6-smoke-test-the-setup)
+- [Laravel integration tips](#laravel-integration-tips)
+- [Troubleshooting](#troubleshooting)
+- [Where next?](#where-next)
+
 ## Prerequisites
 
 - Laravel 10 or 11 project with a working database connection.
diff --git a/docs/laravel/service-provider.md b/docs/laravel/service-provider.md
@@ -2,6 +2,15 @@
 
 Holloway includes a Laravel service provider that handles integration with Laravel's service container and database connections.
 
+## Table of Contents
+
+- [What the Service Provider Does](#what-the-service-provider-does)
+- [Registration](#registration)
+- [Database Integration](#database-integration)
+- [Event Integration](#event-integration)
+- [Extending the Service Provider](#extending-the-service-provider)
+- [Next Steps](#next-steps)
+
 ## What the Service Provider Does
 
 The `HollowayServiceProvider` performs two key functions:
diff --git a/docs/mappers/persistence.md b/docs/mappers/persistence.md
@@ -1,4 +1,20 @@
 # Persistence Operations
+
+## Table of Contents
+
+- [Timestamp Handling](#timestamp-handling)
+- [Core Persistence Methods](#core-persistence-methods)
+- [Persistence Lifecycle](#persistence-lifecycle)
+- [Implementing Persistence Methods](#implementing-persistence-methods)
+- [Timestamp Management](#timestamp-management)
+- [Transaction Support](#transaction-support)
+- [Factory Integration](#factory-integration)
+- [Advanced Persistence Patterns](#advanced-persistence-patterns)
+- [Persistence Events](#persistence-events)
+- [Error Handling](#error-handling)
+- [Best Practices](#best-practices)
+- [Next Steps](#next-steps)
+
 ## Timestamp Handling
 
 When persisting entities, Holloway uses the `currentTime()` method on your mapper to set `created_at`, `updated_at`, and (if using soft deletes) `deleted_at` columns. You can override this method to control how timestamps are generated (e.g., for custom time zones or deterministic tests).
diff --git a/docs/mappers/query-building.md b/docs/mappers/query-building.md
@@ -2,6 +2,22 @@
 
 Holloway's query builder provides a fluent, Laravel-compatible interface for constructing database queries while maintaining the datamapper pattern's benefits. This guide covers everything from basic queries to advanced optimization techniques.
 
+## Table of Contents
+
+- [Basic Query Operations](#basic-query-operations)
+- [Ordering and Limiting](#ordering-and-limiting)
+- [Aggregates and Calculations](#aggregates-and-calculations)
+- [Pagination](#pagination)
+- [Chunking Large Datasets](#chunking-large-datasets)
+- [Query Scopes](#query-scopes)
+- [Global Scopes](#global-scopes)
+- [Raw Queries and Advanced Operations](#raw-queries-and-advanced-operations)
+- [Performance Optimization](#performance-optimization)
+- [Query Builder with Relationships](#query-builder-with-relationships)
+- [Error Handling and Debugging](#error-handling-and-debugging)
+- [Best Practices](#best-practices)
+- [Next Steps](#next-steps)
+
 ## Basic Query Operations
 
 ### Simple Queries
diff --git a/docs/references/mapper-api.md b/docs/references/mapper-api.md
@@ -1,6 +1,13 @@
 # Mapper API Reference
 
-A concise summary of the methods you’ll call most often when working with Holloway mappers and their query builders. Pair this with the full guides in `docs/mappers/` when you need more context.
+A concise summary of the methods you'll call most often when working with Holloway mappers and their query builders. Pair this with the full guides in `docs/mappers/` when you need more context.
+
+## Table of Contents
+
+- [Mapper lifecycle](#mapper-lifecycle)
+- [Query builder shortcuts](#query-builder-shortcuts)
+- [Relationship helpers](#relationship-helpers)
+- [Scope conventions](#scope-conventions)
 
 ## Mapper lifecycle
 
diff --git a/docs/references/relationship-cheatsheet.md b/docs/references/relationship-cheatsheet.md
@@ -2,6 +2,14 @@
 
 Quick reference for defining and consuming relationships with Holloway mappers.
 
+## Table of Contents
+
+- [Defining relationships in `defineRelations()`](#defining-relationships-in-definerelations)
+- [Eager loading syntax](#eager-loading-syntax)
+- [Handling pivot data with `belongsToMany`](#handling-pivot-data-with-belongstomany)
+- [Default eager loads](#default-eager-loads)
+- [Troubleshooting](#troubleshooting)
+
 ## Defining relationships in `defineRelations()`
 
 | Relationship | Example | Notes |
diff --git a/docs/relationships/nested.md b/docs/relationships/nested.md
@@ -2,6 +2,21 @@
 
 Holloway provides powerful support for handling complex nested relationships, allowing you to efficiently work with deeply related data structures while maintaining clean architecture and optimal performance.
 
+## Table of Contents
+
+- [Understanding Nested Relationships](#understanding-nested-relationships)
+- [Deep Loading with Constraints](#deep-loading-with-constraints)
+- [Conditional Nested Loading](#conditional-nested-loading)
+- [Polymorphic Nested Relationships](#polymorphic-nested-relationships)
+- [Tree Structures and Hierarchical Data](#tree-structures-and-hierarchical-data)
+- [Aggregation in Nested Relationships](#aggregation-in-nested-relationships)
+- [Performance Optimization for Nested Relationships](#performance-optimization-for-nested-relationships)
+- [Advanced Nested Patterns](#advanced-nested-patterns)
+- [Testing Nested Relationships](#testing-nested-relationships)
+- [Best Practices](#best-practices)
+- [Common Pitfalls](#common-pitfalls)
+- [Next Steps](#next-steps)
+
 ## Understanding Nested Relationships
 
 Nested relationships occur when entities have relationships that themselves contain relationships, creating hierarchical or interconnected data structures.
diff --git a/docs/relationships/overview.md b/docs/relationships/overview.md
@@ -2,6 +2,20 @@
 
 Holloway's relationship system provides powerful and flexible ways to define connections between your entities. Unlike Active Record patterns, relationships in Holloway are explicitly defined in mappers and loaded through an optimized query system.
 
+## Table of Contents
+
+- [Relationship Types](#relationship-types)
+- [How Relationships Work](#how-relationships-work)
+- [Relationship Loading Strategy](#relationship-loading-strategy)
+- [Relationship Tree System](#relationship-tree-system)
+- [Relationship Configuration](#relationship-configuration)
+- [Relationship Constraints](#relationship-constraints)
+- [Performance Characteristics](#performance-characteristics)
+- [Advanced Relationship Features](#advanced-relationship-features)
+- [Best Practices](#best-practices)
+- [Debugging Relationships](#debugging-relationships)
+- [Next Steps](#next-steps)
+
 ## Relationship Types
 
 Holloway supports all standard relationship types plus custom relationships for complex scenarios:
diff --git a/docs/relationships/standard.md b/docs/relationships/standard.md
@@ -2,6 +2,19 @@
 
 Holloway supports four standard relationship types that mirror common database relationship patterns. This guide provides comprehensive coverage of HasOne, HasMany, BelongsTo, and BelongsToMany relationships.
 
+## Table of Contents
+
+- [HasOne Relationships](#hasone-relationships)
+- [HasMany Relationships](#hasmany-relationships)
+- [BelongsTo Relationships](#belongsto-relationships)
+- [BelongsToMany Relationships](#belongstomany-relationships)
+- [Advanced Relationship Configurations](#advanced-relationship-configurations)
+- [Relationship Loading Patterns](#relationship-loading-patterns)
+- [Common Patterns and Use Cases](#common-patterns-and-use-cases)
+- [Troubleshooting Common Issues](#troubleshooting-common-issues)
+- [Best Practices](#best-practices)
+- [Next Steps](#next-steps)
+
 ## HasOne Relationships
 
 A HasOne relationship represents a one-to-one connection where one entity "has one" related entity.
