💾 Database System Manual

1. System Overview

The Database System provides a robust and maintainable abstraction layer for all database operations in LineagePress. It is designed to be the single source of truth for database schema and queries, ensuring that raw SQL is not scattered throughout the plugin.

The system follows a “one class per table” (or group of related tables) philosophy, where each class is responsible for managing its own schema and providing methods for data access.

Key Responsibilities

• Schema Management: Defines, creates, and updates all custom database tables used by the plugin.
• Data Abstraction: Provides a clean, object-oriented API for other parts of the plugin to perform CRUD (Create, Read, Update, Delete) operations.
• Centralized Control: Manages high-level database operations like installation and uninstallation via a central manager class.
• WordPress Integration: Uses the global \$wpdb object for all database interactions, adhering to WordPress best practices.

---

2. Core Components

The system is composed of two main types of classes: a central manager and individual table classes.

HP_Database_Manager (The Conductor)

• File: includes/database/class-hp-database-manager.php
• Purpose: This class acts as the central controller for all database tables. It does not contain any query logic itself.
• Functionality:
  • Holds a static registry (\$table_modules) of all individual table classes.
  • Orchestrates the creation of all tables during plugin activation by iterating through the registered modules and calling their create_tables() methods.
  • Provides a “nuclear option” (drop_tables_nuclear()) to remove all plugin tables, used for uninstallation or complete resets.

Individual Table Classes (The Workers)

• Location: includes/database/
• Pattern: class-hp-database-*.php (e.g., class-hp-database-individuals.php)
• Purpose: Each class is responsible for a single database table or a small group of tightly related tables. This class is the only place where SQL queries for that table should reside.
• Standard Methods:
  • __construct(): Initializes the class and gets the global \$wpdb instance.
  • create_tables(): Contains the dbDelta() call to create or update the table based on its schema.
  • get_table_structures(): A private method that returns the CREATE TABLE SQL string for its table(s).
  • tables_exist(): Checks if the table(s) it manages exist in the database.
  • get_table_names(): A static method that returns an array of table names (without prefix) that the class manages.

---

3. How to Use It

Querying Data

To query data, you should first identify the correct table class for the data you need. Then, instantiate that class and use its data access methods. If a method you need doesn’t exist, you should add it to the class.

Example: Get an individual’s data (hypothetical method)

php Copy Code

// This method would be added to class-hp-database-individuals.php public function get_individual(\$person_id, \$tree_id) { \$table_name = \$this->wpdb->prefix . 'hp_individuals'; return \$this->wpdb->get_row( \$this->wpdb->prepare( "SELECT * FROM {\$table_name} WHERE personID = %s AND gedcom = %s", \$person_id, \$tree_id ) ); } // How to use it elsewhere in the plugin: \$db_individuals = new \LineagePress\Database\HP_Database_Individuals(); \$person = \$db_individuals->get_individual('I123', 'my_tree'); if (\$person) { echo "Found: " . \$person->firstname; }

DO NOT use \$wpdb to query LineagePress tables directly from outside a database class. Always add a dedicated method to the appropriate class.

Adding a New Table

1. Create the Class File: Create a new file in includes/database/ named class-hp-database-mynewtable.php.
2. Define the Class: Create the class HP_Database_MyNewTable inside the \LineagePress\Database namespace.
3. Implement Standard Methods:
   • Copy the structure from an existing class like HP_Database_Individuals.
   • Update get_table_structures() with your new table’s CREATE TABLE SQL.
   • Update get_table_names() to return your new table’s name.
4. Register the Class: Open includes/database/class-hp-database-manager.php and add your new class to the \$table_modules array.

php Copy Code

// in class-hp-database-manager.php private static \$table_modules = [ // ... other modules ['file' => 'class-hp-database-mynewtable.php', 'class' => 'HP_Database_MyNewTable'], ];

Add Data Access Methods: Add public methods to your new class for any queries you need to perform (e.g., get_record(), insert_record(), update_record()).

---

4. List of Database Tables

The following is a list of the primary database classes and the tables they manage.

Class Name	Manages Table(s)	Description
HP_Database_Individuals	hp_individuals	Stores core data for each person.
HP_Database_Family	hp_family	Stores data about family units (e.g., marriages).
HP_Database_Children	hp_children	Links children to family records.
HP_Database_Events	hp_events	Stores events like birth, death, marriage, etc.
HP_Database_Sources	hp_sources	Stores citation sources.
HP_Database_Citations	hp_citations	Links sources to events and people.
HP_Database_Places	hp_places	Stores location data.
HP_Database_Media	hp_media	Stores information about media objects.
HP_Database_MediaLinks	hp_medialinks	Links media to people, families, and events.
HP_Database_Notes	hp_notes	Stores notes attached to records.
HP_Database_Trees	hp_trees	Manages the different GEDCOM trees imported.
HP_Database_BatchWriter	(Utility)	Not a table class; provides methods for efficient bulk data insertion during import.
(…and others)

---

This revision aims for clear sections, headings, and consistent formatting to enhance readability in a WordPress document. Elements like tables and code blocks are maintained for clarity and comprehension.