Eloquent Model Foundation

Overview

The Hypervel\Database\Eloquent\Model class serves as the foundation for all Eloquent models in Hypervel, extending Hyperf\DbConnection\Model\Model with Laravel-compatible features optimized for coroutine execution. This foundation layer provides:

• Context-based event suppression - withoutEvents() and "quietly" methods with nested call support for coroutine-safe operation
• Custom builder resolution - Declarative builder specification via #[UseEloquentBuilder] attribute with static caching
• Broadcasting integration - Automatic channel name generation for real-time event broadcasting via HasBroadcastChannel interface
• Route model binding - Implicit route binding support via UrlRoutable interface
• Trait-based architecture - Modular functionality through 10+ concern traits

This page documents the core Model class foundation. For attribute casting and date handling, see page 5.2. For custom collections, see page 5.3. For pivot model enhancements, see page 5.4.

Sources: src/core/src/Database/Eloquent/Model.php1-307

---

Model Class Structure

The Hypervel\Database\Eloquent\Model class extends Hyperf's base model and implements two key interfaces for framework integration.

Class Hierarchy and Interfaces

Sources: src/core/src/Database/Eloquent/Model.php28-75

Trait Composition

The Model class composes functionality through traits. The table below lists the traits and their primary responsibilities:

Trait	Purpose	Related Page
HasAttributes	Type casting, custom casters, Date facade integration	5.2
HasBootableTraits	Trait initialization via boot{TraitName}() methods	Inherited from Hyperf
HasCallbacks	Model lifecycle event callbacks	-
HasCollection	Custom collection class resolution	5.3
HasGlobalScopes	Global scope registration and application	-
HasLocalScopes	Local scope method resolution	-
HasObservers	Observer pattern for model events	-
HasRelations	Relationship metadata and eager loading	-
HasRelationships	Relationship definition methods	5.4
HasTimestamps	Auto-managed timestamps using Date facade	5.2
TransformsToResource	API resource transformation	5.3

Sources: src/core/src/Database/Eloquent/Model.php77-87

---

Custom Builder Resolution

Models can specify custom query builder classes using the #[UseEloquentBuilder] attribute. The builder class is resolved once per model and cached statically to avoid repeated reflection calls.

Builder Resolution Flow

Sources: src/core/src/Database/Eloquent/Model.php119-131 src/core/src/Database/Eloquent/Model.php138-149

Using the #[UseEloquentBuilder] Attribute

The #[UseEloquentBuilder] attribute is applied at the class level to specify a custom builder:

Resolution Implementation

The newModelBuilder() method implements the resolution logic:

1. Check static cache $resolvedBuilderClasses[static::class] src/core/src/Database/Eloquent/Model.php121-122
2. If not cached, call resolveCustomBuilderClass() src/core/src/Database/Eloquent/Model.php121-122
3. Use reflection to read #[UseEloquentBuilder] attributes src/core/src/Database/Eloquent/Model.php140-141
4. Cache the result as class-string<Builder> or false src/core/src/Database/Eloquent/Model.php104
5. Instantiate the custom builder or fall back to default Builder src/core/src/Database/Eloquent/Model.php124-130

Static Cache Structure

The cache maps model class names to their builder class names (or false if no custom builder is defined). This avoids repeated reflection calls during the application lifecycle.

Sources: src/core/src/Database/Eloquent/Model.php100-149 src/core/src/Database/Eloquent/Attributes/UseEloquentBuilder.php1-33

---

Event Suppression System

Hypervel's Model provides a coroutine-safe event suppression system using Swoole Context. This allows executing model operations without triggering observers or event listeners, with support for nested calls.

Event Suppression Architecture

Sources: src/core/src/Database/Eloquent/Model.php186-214 src/core/src/Database/Eloquent/Model.php219-282 src/core/src/Database/Eloquent/Model.php303-306

Context-Based Depth Tracking

The withoutEvents() method uses a depth counter to support nested calls:

Implementation Details:

1. Context Key Generation: Each model class has a unique context key src/core/src/Database/Eloquent/Model.php303-306
2. Depth Increment: Store current depth + 1 in context src/core/src/Database/Eloquent/Model.php200-202
3. Callback Execution: Run user callback while events are suppressed src/core/src/Database/Eloquent/Model.php204-205
4. Depth Decrement: In finally block, decrement or destroy context src/core/src/Database/Eloquent/Model.php207-213

Event Dispatcher Override

The getEventDispatcher() method checks the context to determine if events should fire:

When the method returns null, Hyperf's event system skips firing any model events (creating, created, updating, updated, deleting, deleted, etc.).

Sources: src/core/src/Database/Eloquent/Model.php186-193

Quietly Methods

Each "quietly" method provides a convenient wrapper around withoutEvents():

Method	Operation	Return Type	Line Reference
saveQuietly()	save()	bool	src/core/src/Database/Eloquent/Model.php227-230
updateQuietly()	fill() + save()	bool	src/core/src/Database/Eloquent/Model.php238-245
deleteQuietly()	delete()	bool	src/core/src/Database/Eloquent/Model.php271-274
incrementQuietly()	incrementOrDecrement()	int	src/core/src/Database/Eloquent/Model.php251-256
decrementQuietly()	incrementOrDecrement()	int	src/core/src/Database/Eloquent/Model.php261-266
replicateQuietly()	replicate()	static	src/core/src/Database/Eloquent/Model.php279-282
pushQuietly()	push()	bool	src/core/src/Database/Eloquent/Model.php219-222

Usage Example:

Sources: src/core/src/Database/Eloquent/Model.php219-282

Coroutine Isolation

The Swoole Context API ensures that event suppression in one coroutine does not affect other concurrent coroutines:

Each coroutine has isolated context storage, so operations in Coroutine 1 with events suppressed do not affect Coroutine 2 where events fire normally.

Sources: tests/Database/Eloquent/EloquentModelWithoutEventsTest.php52-88 tests/Database/Eloquent/EloquentModelWithoutEventsTest.php90-113

Nested Call Support

The depth counter enables nested withoutEvents() calls:

The context is only destroyed when the depth reaches 0, ensuring events remain suppressed throughout the entire call stack.

Sources: tests/Database/Eloquent/EloquentModelWithoutEventsTest.php72-88

---

Broadcasting and Routing Integration

The Model class implements two interfaces for framework integration:

UrlRoutable Interface

Enables implicit route model binding:

Sources: src/core/src/Database/Eloquent/Model.php96-99

HasBroadcastChannel Interface

Generates broadcasting channel names for model instances:

Sources: src/core/src/Database/Eloquent/Model.php148-156

---

Summary

The Eloquent Model System provides:

1. Trait-based composition - 10 traits for modular functionality src/core/src/Database/Eloquent/Model.php76-85
2. Custom builder resolution - Via #[UseEloquentBuilder] attribute with static caching src/core/src/Database/Eloquent/Model.php88-137
3. Coroutine-safe event suppression - Context-based withoutEvents() and "quietly" methods src/core/src/Database/Eloquent/Model.php183-279
4. PHP 8 attributes - #[Scope] and #[ScopedBy] for declarative configuration
5. Date facade integration - Configurable date classes throughout the model lifecycle src/core/src/Database/Eloquent/Concerns/HasTimestamps.php src/core/src/Database/Eloquent/Concerns/HasAttributes.php
6. Enhanced pivot models - Event-aware deletion for composite key pivots src/core/src/Database/Eloquent/Relations/Pivot.php

This architecture maintains Laravel compatibility while leveraging Swoole coroutines and PHP 8 features for improved performance and developer experience.