Model Attributes and Type Casting

This document covers the attribute casting system in Eloquent models, including cast declaration, custom cast classes, date handling with the Date facade, and cast caching. Attribute casting automatically converts database values to appropriate PHP types when reading from or writing to the database.

For information about model relationships and pivot tables, see Relationships and Pivot Models. For collection-level operations, see Model Collections. For the base model system, see Eloquent Model System.

---

Cast Declaration

Models can declare attribute casts in two ways: via the $casts property or the casts() method. Both approaches are merged together, with the casts() method taking precedence.

The $casts Property

The traditional approach uses a protected array property:

The casts() Method

The programmatic approach uses a method that returns an array:

Cast Resolution Order

The getCasts() method src/core/src/Database/Eloquent/Concerns/HasAttributes.php61-72 merges casts from multiple sources:

Priority	Source	Notes
1	Primary key cast	Auto-added for incrementing models
2	$casts property	Declared on model class
3	casts() method	Returned by method

Sources: src/core/src/Database/Eloquent/Concerns/HasAttributes.php61-72 tests/Core/Database/Eloquent/Concerns/HasAttributesTest.php17-51

---

Custom Cast Classes

Hypervel supports three interfaces for custom cast implementations:

CastsAttributes Interface

Full bidirectional casting with access to model instance:

CastsInboundAttributes Interface

Write-only casting (no retrieval transformation):

Castable Interface

Self-describing classes that specify their own caster:

Cast Class Resolution

Sources: src/core/src/Database/Eloquent/Concerns/HasAttributes.php30-56

---

Date Casting with the Date Facade

Hypervel extends Hyperf's date handling to integrate with the Date facade, allowing applications to configure a custom date class globally (e.g., CarbonImmutable).

Date Transformation Methods

The HasAttributes trait overrides date transformation to use the Date facade:

Method	Purpose	Returns
asDateTime($value)	Convert to datetime with time	CarbonInterface
asDate($value)	Convert to date (00:00:00)	CarbonInterface

Supported Value Types

The asDateTime() method src/core/src/Database/Eloquent/Concerns/HasAttributes.php101-142 handles multiple input formats:

Date Facade Configuration

Applications can configure the date class globally:

All model date operations respect this configuration:

Operation	Method/Property	Uses Date Facade
Timestamp creation	freshTimestamp()	Yes (via HasTimestamps trait)
Date casting	$casts = ['date' => 'date']	Yes (via asDate())
Datetime casting	$casts = ['datetime' => 'datetime']	Yes (via asDateTime())
Date attribute access	$model->published_at	Yes (via asDateTime())

Sources: src/core/src/Database/Eloquent/Concerns/HasAttributes.php85-142 src/core/src/Database/Eloquent/Concerns/HasTimestamps.php18-28 tests/Core/Database/Eloquent/Concerns/DateFactoryTest.php1-352

---

Cast Caching

The casting system uses two levels of caching for performance:

Cast Array Cache

Stores the merged cast array per model class src/core/src/Database/Eloquent/Concerns/HasAttributes.php23-25 Populated by getCasts() on first access.

Caster Instance Cache

Stores instantiated caster objects per model class and cast type src/core/src/Database/Eloquent/Concerns/HasAttributes.php18-20 Avoids repeated instantiation of custom cast classes.

Cache Structure

Sources: src/core/src/Database/Eloquent/Concerns/HasAttributes.php18-26

---

Pivot Model Casting

Both Pivot and MorphPivot classes include the HasAttributes trait, enabling full casting support on pivot models:

Example: Pivot with Casts

Pivot casts work seamlessly with relationship operations:

Operation	Cast Behavior
attach() with attributes	Casts applied on save
updateExistingPivot()	Casts applied on update
sync() with pivot data	Casts applied to new/updated records
Accessing $model->pivot->attribute	Casts applied on retrieval

Sources: src/core/src/Database/Eloquent/Relations/Pivot.php19 src/core/src/Database/Eloquent/Relations/MorphPivot.php19 tests/Core/Database/Eloquent/Relations/BelongsToManyPivotEventsTest.php326-328 tests/Core/Database/Eloquent/Relations/MorphToManyPivotEventsTest.php357-359

---

Cast Type System

Built-in Cast Types (Hyperf)

Hypervel inherits these from Hyperf's base model:

• Scalar: int, integer, real, float, double, decimal:X, string, bool, boolean
• Array/Object: array, json, object, collection
• Dates: date, datetime, timestamp (enhanced with Date facade)
• Encrypted: encrypted, encrypted:array, encrypted:collection, encrypted:json, encrypted:object

Custom Cast Syntax

Custom casts support argument passing:

Arguments are parsed and passed to the constructor src/core/src/Database/Eloquent/Concerns/HasAttributes.php38-44

Sources: src/core/src/Database/Eloquent/Concerns/HasAttributes.php30-82

---

Summary

The Hypervel attribute casting system provides:

1. Flexible Declaration: Use $casts property or casts() method
2. Custom Casts: Implement CastsAttributes, CastsInboundAttributes, or Castable
3. Date Facade Integration: Global date class configuration via Date::use()
4. Performance Caching: Two-tier cache for cast definitions and caster instances
5. Pivot Support: Full casting support on Pivot and MorphPivot models

The system extends Hyperf's base casting while adding Laravel-compatible date handling and improved caching.