Feature: Rebuilt relationship structure (#32)

Author: JasonTheAdams

README.md

@@ -328,6 +328,173 @@ class Breakfast_Model extends Model {
 }
 ```
 
+## Model Relationships
+
+Models can define relationships to other models, similar to how properties are defined. Relationships support lazy loading and caching.
+
+### Defining Relationships
+
+Relationships can be defined using either shorthand syntax or the fluent `ModelRelationshipDefinition` API:
+
+#### Using shorthand syntax:
+
+```php
+namespace Boomshakalaka\Whatever;
+
+use Boomshakalaka\StellarWP\Models\Model;
+use Boomshakalaka\StellarWP\Models\ValueObjects\Relationship;
+
+class Product_Model extends Model {
+	/**
+	 * @inheritDoc
+	 */
+	protected static $relationships = [
+		'category' => Relationship::BELONGS_TO,
+		'reviews' => Relationship::HAS_MANY,
+		'tags' => Relationship::MANY_TO_MANY,
+	];
+
+	/**
+	 * Define how to load the category relationship.
+	 */
+	protected function category() {
+		return Category_Model::query()->where('id', $this->category_id);
+	}
+
+	/**
+	 * Define how to load the reviews relationship.
+	 */
+	protected function reviews() {
+		return Review_Model::query()->where('product_id', $this->id);
+	}
+
+	/**
+	 * Define how to load the tags relationship.
+	 */
+	protected function tags() {
+		return Tag_Model::query()
+			->select('tags.*')
+			->join('product_tags', 'product_tags.tag_id', 'tags.id')
+			->where('product_tags.product_id', $this->id);
+	}
+}
+```
+
+#### Using relationship definitions for more control:
+
+```php
+namespace Boomshakalaka\Whatever;
+
+use Boomshakalaka\StellarWP\Models\Model;
+use Boomshakalaka\StellarWP\Models\ModelRelationshipDefinition;
+
+class Product_Model extends Model {
+	/**
+	 * @inheritDoc
+	 */
+	protected static function relationships(): array {
+		return [
+			'category' => (new ModelRelationshipDefinition('category'))
+				->belongsTo(),
+			'reviews' => (new ModelRelationshipDefinition('reviews'))
+				->hasMany(),
+			'tags' => (new ModelRelationshipDefinition('tags'))
+				->manyToMany()
+				->disableCaching(), // Don't cache this relationship
+		];
+	}
+
+	// Define relationship loaders as above...
+}
+```
+
+### Relationship Types
+
+Five relationship types are available:
+
+- `Relationship::HAS_ONE` - Model has one related model
+- `Relationship::HAS_MANY` - Model has many related models
+- `Relationship::BELONGS_TO` - Model belongs to another model
+- `Relationship::BELONGS_TO_MANY` - Model belongs to many related models
+- `Relationship::MANY_TO_MANY` - Many-to-many relationship
+
+### Accessing Relationships
+
+Relationships are loaded lazily when accessed as properties:
+
+```php
+$product = Product_Model::find(1);
+
+// First access loads from database and caches result
+$category = $product->category;
+
+// Subsequent accesses use cached value (if caching enabled)
+$category = $product->category; // No additional query
+
+// Access multiple relationship
+$reviews = $product->reviews; // Returns array of Review_Model instances
+```
+
+### Relationship Caching
+
+By default, relationships are cached after the first load. You can control caching behavior:
+
+```php
+class Product_Model extends Model {
+	protected static function relationships(): array {
+		return [
+			// Cached (default)
+			'category' => (new ModelRelationshipDefinition('category'))
+				->belongsTo(),
+
+			// Not cached - always loads fresh
+			'stock' => (new ModelRelationshipDefinition('stock'))
+				->hasOne()
+				->disableCaching(),
+		];
+	}
+}
+```
+
+### Managing Relationship Cache
+
+Models provide methods to manage relationship caching:
+
+```php
+$product = Product_Model::find(1);
+
+// Manually set a cached relationship value
+$product->setCachedRelationship('category', $newCategory);
+
+// Clear a specific relationship cache
+$product->purgeRelationship('category');
+$category = $product->category; // Reloads from database
+
+// Clear all relationship caches
+$product->purgeRelationshipCache();
+```
+
+### Customizing Relationship Loading
+
+Override the `fetchRelationship()` method to customize how relationships are loaded:
+
+```php
+class Product_Model extends Model {
+	/**
+	 * Custom relationship loading logic.
+	 */
+	protected function fetchRelationship(string $key) {
+		// Add custom logic before loading
+		if ($key === 'category' && !$this->category_id) {
+			return null;
+		}
+
+		// Default loading behavior
+		return parent::fetchRelationship($key);
+	}
+}
+```
+
 ## Attribute validation
 
 Sometimes it would be helpful to validate attributes that are set in the model. To do that, you can create `validate_*()`

UPGRADING.md

@@ -460,7 +460,87 @@ $product = Product_Model::query()->where('id', 1)->get();
 $products = Product_Model::query()->where('active', 1)->getAll();
 ```
 
-### 9. Relationship Cache Control
+### 9. Enhanced Relationship System
+
+The relationship system has been completely redesigned to work like the property system with better type safety and flexibility.
+
+#### Relationship Definitions
+
+You can now define relationships using `ModelRelationshipDefinition` for more control:
+
+```php
+use StellarWP\Models\ModelRelationshipDefinition;
+use StellarWP\Models\ValueObjects\Relationship;
+
+class Product_Model extends Model {
+    // Shorthand syntax (still supported)
+    protected static $relationships = [
+        'category' => Relationship::BELONGS_TO,
+        'reviews' => Relationship::HAS_MANY,
+    ];
+
+    // Or use the fluent API for more control
+    protected static function relationships(): array {
+        return [
+            'category' => (new ModelRelationshipDefinition('category'))
+                ->belongsTo(),
+            'reviews' => (new ModelRelationshipDefinition('reviews'))
+                ->hasMany()
+                ->disableCaching(), // Disable caching for this relationship
+            'tags' => (new ModelRelationshipDefinition('tags'))
+                ->manyToMany(),
+        ];
+    }
+
+    // Define relationship loaders
+    protected function category() {
+        return Category_Model::query()->where('id', $this->category_id);
+    }
+
+    protected function reviews() {
+        return Review_Model::query()->where('product_id', $this->id);
+    }
+
+    protected function tags() {
+        return Tag_Model::query()
+            ->join('product_tags', 'product_tags.tag_id', 'tags.id')
+            ->where('product_tags.product_id', $this->id);
+    }
+}
+```
+
+#### Relationship Type Value Object
+
+The `Relationship` class is now a proper value object with instance caching (flyweight pattern):
+
+```php
+use StellarWP\Models\ValueObjects\Relationship;
+
+// Factory methods return cached instances
+$hasMany1 = Relationship::HAS_MANY();
+$hasMany2 = Relationship::HAS_MANY();
+$hasMany1 === $hasMany2; // true - same instance
+
+// Create from string
+$relationship = Relationship::from('has-many');
+
+// Type checking methods
+$relationship->isHasMany(); // true
+$relationship->isSingle(); // false
+$relationship->isMultiple(); // true
+
+// Get all relationship types
+$all = Relationship::all(); // Returns array of all 5 relationship types
+```
+
+Available relationship types:
+- `Relationship::HAS_ONE` - Single related model
+- `Relationship::HAS_MANY` - Multiple related models
+- `Relationship::BELONGS_TO` - Single parent model
+- `Relationship::BELONGS_TO_MANY` - Multiple parent models
+- `Relationship::MANY_TO_MANY` - Many-to-many relationship
+
+#### Relationship Cache Control
 
 New protected methods for managing relationship caching within your model subclasses:
 
@@ -489,13 +569,23 @@ class Product_Model extends Model {
         // Clear all cached relationships
         $this->purgeRelationshipCache();
     }
+
+    // Override to customize relationship loading
+    protected function fetchRelationship(string $key) {
+        if ($key === 'category' && !$this->category_id) {
+            return null; // No category to load
+        }
+
+        return parent::fetchRelationship($key);
+    }
 }
 ```
 
 Available methods:
 - `setCachedRelationship(string $key, $value)` - Manually set a cached relationship value
 - `purgeRelationship(string $key)` - Clear a specific relationship from cache
 - `purgeRelationshipCache()` - Clear all relationship caches
+- `fetchRelationship(string $key)` - Override to customize relationship loading logic
 
 ## Getting Help