Merge remote-tracking branch 'origin/release/2.0.0' into feat/introduce-schema-model

Author: dpanta94

README.md

@@ -8,6 +8,7 @@ A library for a simple model structure.
 * [Configuration](#configuration)
 * [Creating a model](#creating-a-model)
 * [Interacting with a model](#interacting-with-a-model)
+* [Attribute validation](#attribute-validation)
 * [Data transfer objects](#data-transfer-objects)
 * [Classes of note](#classes-of-note)
   * [Model](#model)
@@ -57,7 +58,9 @@ Models are classes that hold data and provide some helper methods for interactin
 
 ### A simple model
 
-This is an example of a model that just holds properties.
+This is an example of a model that just holds properties. Properties can be defined in one or both of the following ways:
+
+#### Using the shorthand syntax:
 
 ```php
 namespace Boomshakalaka\Whatever;
@@ -70,14 +73,43 @@ class Breakfast_Model extends Model {
 	 */
 	protected static $properties = [
 		'id'        => 'int',
-		'name'      => 'string',
+		'name'      => ['string', 'Default Name'], // With default value
 		'price'     => 'float',
 		'num_eggs'  => 'int',
 		'has_bacon' => 'bool',
 	];
 }
 ```
 
+#### Using property definitions for more control:
+
+```php
+namespace Boomshakalaka\Whatever;
+
+use Boomshakalaka\StellarWP\Models\Model;
+use Boomshakalaka\StellarWP\Models\ModelPropertyDefinition;
+
+class Breakfast_Model extends Model {
+	/**
+	 * @inheritDoc
+	 */
+	protected static function properties(): array {
+		return [
+			'id' => ModelPropertyDefinition::create()
+				->type('int')
+				->required(),
+			'name' => ModelPropertyDefinition::create()
+				->type('string')
+				->default('Default Name')
+				->nullable(),
+			'price' => ModelPropertyDefinition::create()
+				->type('float')
+				->requiredOnSave(),
+		];
+	}
+}
+```
+
 ### A ReadOnly model
 
 This is a model whose intent is to only read and store data. The Read operations should - in most cases - be deferred to
@@ -183,6 +215,115 @@ class Breakfast_Model extends Model implements Contracts\ModelCrud {
 }
 ```
 
+## Interacting with a model
+
+### Change tracking
+
+Models track changes to their properties and provide methods to manage those changes:
+
+```php
+$breakfast = new Breakfast_Model([
+	'name' => 'Original Name',
+	'price' => 5.99,
+]);
+
+// Check if a property is dirty (changed)
+$breakfast->setAttribute('name', 'New Name');
+if ($breakfast->isDirty('name')) {
+	echo 'Name has changed!';
+}
+
+// Get all dirty values
+$dirtyValues = $breakfast->getDirty(); // ['name' => 'New Name']
+
+// Commit changes (makes current values the "original")
+$breakfast->commitChanges();
+// or use the alias:
+$breakfast->syncOriginal();
+
+// Revert a specific property change
+$breakfast->setAttribute('price', 7.99);
+$breakfast->revertChange('price'); // price is back to 5.99
+
+// Revert all changes
+$breakfast->setAttribute('name', 'Another Name');
+$breakfast->setAttribute('price', 8.99);
+$breakfast->revertChanges(); // All properties back to original
+
+// Get original value
+$originalName = $breakfast->getOriginal('name');
+$allOriginal = $breakfast->getOriginal(); // Get all original values
+```
+
+### Checking if properties are set
+
+The `isSet()` method checks if a property has been set. This is different from PHP's `isset()` because it considers `null` values and default values as "set":
+
+```php
+$breakfast = new Breakfast_Model();
+
+// Properties with defaults are considered set
+if ($breakfast->isSet('name')) { // true if 'name' has a default value
+    echo 'Name is set';
+}
+
+// Properties without defaults are not set until assigned
+if (!$breakfast->isSet('price')) { // false - no default and not assigned
+    echo 'Price is not set';
+}
+
+// Setting a property to null still counts as set
+$breakfast->setAttribute('price', null);
+if ($breakfast->isSet('price')) { // true - explicitly set to null
+    echo 'Price is set (even though it\'s null)';
+}
+
+// PHP's isset() behaves differently with null
+if (!isset($breakfast->price)) { // false - isset() returns false for null
+    echo 'PHP isset() returns false for null values';
+}
+```
+
+**Key differences from PHP's `isset()`:**
+- `isSet()` returns `true` for properties with default values
+- `isSet()` returns `true` for properties explicitly set to `null`
+- `isSet()` returns `false` only for properties that have no default and haven't been assigned
+
+### Creating models from query data
+
+Models can be created from database query results using the `fromData()` method:
+
+```php
+// From an object or array
+$data = DB::get_row("SELECT * FROM breakfasts WHERE id = 1");
+$breakfast = Breakfast_Model::fromData($data);
+
+// With different build modes
+$breakfast = Breakfast_Model::fromData($data, Breakfast_Model::BUILD_MODE_STRICT);
+$breakfast = Breakfast_Model::fromData($data, Breakfast_Model::BUILD_MODE_IGNORE_MISSING);
+$breakfast = Breakfast_Model::fromData($data, Breakfast_Model::BUILD_MODE_IGNORE_EXTRA);
+```
+
+Build modes:
+- `BUILD_MODE_STRICT`: Throws exceptions for missing or extra properties
+- `BUILD_MODE_IGNORE_MISSING`: Ignores properties missing from the data
+- `BUILD_MODE_IGNORE_EXTRA`: Ignores extra properties in the data (default)
+
+### Extending model construction
+
+Models can perform custom initialization after construction by overriding the `afterConstruct()` method:
+
+```php
+class Breakfast_Model extends Model {
+	protected function afterConstruct() {
+		// Perform custom initialization
+		if ($this->has_bacon && $this->num_eggs > 2) {
+			$this->setAttribute('name', $this->name . ' (Hearty!)');
+		}
+	}
+}
+```
+
 ## Attribute validation
 
 Sometimes it would be helpful to validate attributes that are set in the model. To do that, you can create `validate_*()`
@@ -442,6 +583,13 @@ $breakfast = Breakfast_Model::find( 1 );
 $breakfast->delete();
 ```
 
+### Unsetting properties
+
+```php
+$breakfast = Breakfast_Model::find( 1 );
+unset($breakfast->price); // Unsets the price property
+```
+
 ## Classes of note
 
 ### `Model`
@@ -455,7 +603,7 @@ This is an abstract class to extend for creating model factories.
 ### `ModelQueryBuilder`
 
 This class extends the [`stellarwp/db`](https://github.com/stellarwp/db) `QueryBuilder` class so that it returns
-model instances rather than arrays or `stdClass` instances. Using this requires models that implement the `ModelFromQueryBuilderObject`
+model instances rather than arrays or `stdClass` instances. Using this requires models that implement the `ModelBuildsFromData`
 interface.
 
 ### `DataTransferObject`

src/Models/Contracts/Model.php

@@ -57,7 +57,26 @@ public function getDirty() : array;
 	 *
 	 * @return mixed|array
 	 */
-	public function getOriginal( string $key = null );
+	public function getOriginal( ?string $key = null );
+
+	/**
+	 * Returns the property definition for the given key.
+	 *
+	 * @since 2.0.0
+	 *
+	 * @param string $key Property name.
+	 *
+	 * @return ModelPropertyDefinition
+	 */
+	public static function getPropertyDefinition( string $key ) : ModelPropertyDefinition;
+
+	/**
+	 * Returns the property definitions for the model.
+	 *
+	 * @since 2.0.0
+	 * @return array<string,ModelPropertyDefinition>
+	 */
+	public static function getPropertyDefinitions() : array;
 
 	/**
 	 * Returns the property definition for the given key.

src/Models/Model.php

@@ -86,10 +86,20 @@ abstract class Model implements ModelInterface, Arrayable, JsonSerializable {
 	 *
 	 * @param array<string,mixed> $attributes Attributes.
 	 */
-	public function __construct( array $attributes = [] ) {
+	final public function __construct( array $attributes = [] ) {
 		$this->propertyCollection = ModelPropertyCollection::fromPropertyDefinitions( static::getPropertyDefinitions(), $attributes );
+		$this->afterConstruct();
 	}
 
+	/**
+	 * This method is meant to be overridden by the model to perform actions after the model is constructed.
+	 *
+	 * @since 2.0.0
+	 */
+	protected function afterConstruct() {
+		// This method is meant to be overridden by the model to perform actions after the model is constructed.
+		return;
+	}
 	/**
 	 * Casts the value for the type, used when constructing a model from query data. If the model needs to support
 	 * additional types, especially class types, this method can be overridden.
@@ -101,8 +111,6 @@ public function __construct( array $attributes = [] ) {
 	 * @param string $property The property being casted.
 	 *
 	 * @return mixed
-	 *
-	 * @throws InvalidArgumentException If the value is not valid for the property.
 	 */
 	protected static function castValueForProperty( ModelPropertyDefinition $definition, $value, string $property ) {
 		if ( $definition->isValidValue( $value ) || $value === null ) {
@@ -115,7 +123,7 @@ protected static function castValueForProperty( ModelPropertyDefinition $definit
 
 		$type = $definition->getType();
 		if ( count( $type ) !== 1 ) {
-			throw new InvalidArgumentException( "Property '$property' has multiple types: " . implode( ', ', $type ) . ". To support additional types, implement a custom castValueForProperty() method." );
+			throw new \InvalidArgumentException( "Property '$property' has multiple types: " . implode( ', ', $type ) . ". To support additional types, implement a custom castValueForProperty() method." );
 		}
 
 		switch ( $type[0] ) {
@@ -130,7 +138,7 @@ protected static function castValueForProperty( ModelPropertyDefinition $definit
 			case 'float':
 				return (float) filter_var( $value, FILTER_SANITIZE_NUMBER_FLOAT,FILTER_FLAG_ALLOW_FRACTION );
 			default:
-				Config::throwInvalidArgumentException( "Unexpected type: '$type'. To support additional types, overload this method or use Definition casting." );
+				Config::throwInvalidArgumentException( "Unexpected type: '{$type[0]}'. To support additional types, overload this method or use Definition casting." );
 		}
 	}
 
@@ -235,10 +243,10 @@ public static function getPropertyDefinition( string $key ): ModelPropertyDefini
 	 *
 	 * @throws InvalidArgumentException If the property key is not a string.
 	 */
-	public static function getPropertyDefinitions(): array {
 		if ( isset( static::$cached_definitions[ static::class ] ) ) {
 			return static::$cached_definitions[ static::class ];
 		}
+	public static function getPropertyDefinitions(): array {
 
 		$definitions = array_merge( static::$properties, static::properties() );
 
@@ -448,6 +456,10 @@ public static function fromData($data, $mode = self::BUILD_MODE_IGNORE_EXTRA) {
 
 		foreach (static::$properties as $key => $type) {
 			if ( ! array_key_exists( $key, $data ) ) {
+				// Skip missing properties when BUILD_MODE_IGNORE_MISSING is set
+				if ( $mode & self::BUILD_MODE_IGNORE_MISSING ) {
+					continue;
+				}
 				Config::throwInvalidArgumentException( "Property '$key' does not exist." );
 			}