<?php
namespace Code_Snippets\Model;
use WP_Exception;
/**
* Base class for representing an item of data without needing to use direct access or individual getter and setter functions.
*
* @package Code_Snippets
*/
abstract class Model {
/**
* List of data fields keyed to their current values. Will be initialized with default values.
*
* @var array<string, mixed>
*/
protected array $fields;
/**
* List of default values provided for fields.
*
* @var array<string, mixed>
*/
protected static array $default_values = [];
/**
* Optional list of field name aliases to map when resolving a field name.
*
* @var array<string, string> Field alias names keyed to actual field names.
*/
protected static array $field_aliases = [];
/**
* Class constructor.
*
* @param array<string, mixed>|Model $initial_data Optional initial data to populate fields.
*/
public function __construct( $initial_data = null ) {
assert( static::$default_values, get_class( $this ) . '::$default_values not set' );
$this->fields = static::$default_values;
$this->set_fields( $initial_data );
}
/**
* Set all data fields from an array or object. Invalid fields will be ignored.
*
* @param array<string, mixed>|Model|mixed $data List of data.
*/
public function set_fields( $data ) {
// Only accept arrays or objects.
if ( ! is_array( $data ) && ! is_object( $data ) ) {
return;
}
// Convert objects into arrays.
if ( is_object( $data ) ) {
$data = method_exists( $data, 'get_fields' )
? $data->get_fields()
: get_object_vars( $data );
}
// Loop through the provided fields and set their values.
foreach ( $data as $field => $value ) {
$this->set_field( $field, $value );
}
}
/**
* Retrieve list of current data fields.
*
* @return array<string, mixed> Field names keyed to current values.
*/
public function get_fields(): array {
$fields = [];
foreach ( $this->get_allowed_fields() as $field_name ) {
$fields[ $field_name ] = $this->$field_name;
}
return $fields;
}
/**
* Retrieve a list of current data fields, excluding values that are unchanged from the default.
*
* @return array<string, mixed>
*/
public function get_modified_fields(): array {
return array_filter(
$this->get_fields(),
function ( $value, $field ) {
// The field list includes aliases, which have no entry of their own
// in the defaults. Compare against the field an alias resolves to,
// so reading a snippet built from alias keys does not warn.
$default = static::$default_values[ static::resolve_field_name( $field ) ] ?? null;
return $value && $value !== $default;
},
ARRAY_FILTER_USE_BOTH
);
}
/**
* Internal function for resolving the actual name of a field.
*
* @param string $field A field name, potentially a field alias.
*
* @return string The resolved field name.
*/
protected static function resolve_field_name( string $field ): string {
return static::$field_aliases[ $field ] ?? $field;
}
/**
* Check if a field is set.
*
* @param string $field The field name.
*
* @return bool Whether the field is set.
*/
public function __isset( string $field ) {
$field = self::resolve_field_name( $field );
return isset( $this->fields[ $field ] ) || method_exists( $this, 'get_' . $field );
}
/**
* Retrieve a field's value.
*
* @param string $field The field name.
*
* @return mixed The field value
*
* @throws WP_Exception If the field name is not allowed.
*/
public function __get( string $field ) {
$field = self::resolve_field_name( $field );
if ( method_exists( $this, 'get_' . $field ) ) {
return call_user_func( array( $this, 'get_' . $field ) );
}
if ( ! $this->is_allowed_field( $field ) ) {
if ( function_exists( 'wp_trigger_error' ) ) {
// translators: 1: class name, 2: field name.
$message = sprintf( 'Trying to access invalid property on "%1$s" class: %2$s', get_class( $this ), $field );
wp_trigger_error( __FUNCTION__, $message, E_USER_WARNING );
}
return null;
}
return $this->fields[ $field ];
}
/**
* Set the value of a field without any validation.
*
* @param string $resolved_field The resolved field name.
* @param mixed $value The field value.
*/
private function set_value_internal( string $resolved_field, $value ) {
$value = method_exists( $this, 'prepare_' . $resolved_field ) ?
call_user_func( array( $this, 'prepare_' . $resolved_field ), $value ) :
$this->prepare_field( $value, $resolved_field );
$this->fields[ $resolved_field ] = $value;
}
/**
* Set the value of a field.
*
* @param string $field The field name.
* @param mixed $value The field value.
*
* @throws WP_Exception If the field name is not allowed.
*/
public function __set( string $field, $value ) {
$resolved_field = $this->resolve_field_name( $field );
if ( $this->is_allowed_field( $resolved_field ) ) {
$this->set_value_internal( $resolved_field, $value );
} elseif ( function_exists( 'wp_trigger_error' ) ) {
// translators: 1: class name, 2: field name.
$message = sprintf( 'Trying to set invalid property on "%s" class: %s', get_class( $this ), $field );
wp_trigger_error( __FUNCTION__, $message, E_USER_ERROR );
}
}
/**
* Prepare a value before it is stored.
*
* @param mixed $value Value to prepare.
* @param string $field Field name.
*
* @return mixed Value in the correct format.
*/
abstract protected function prepare_field( $value, string $field );
/**
* Retrieve the list of fields that can be written to.
*
* @return array<string> List of field names.
*/
public function get_allowed_fields(): array {
return array_merge( array_keys( $this->fields ), array_keys( static::$field_aliases ) );
}
/**
* Determine whether a field is allowed to be written to
*
* @param string $field The field name.
*
* @return bool true if the is allowed, false if invalid.
*/
public function is_allowed_field( string $field ): bool {
return ( $this->fields && array_key_exists( $field, $this->fields ) ) ||
( static::$field_aliases && array_key_exists( $field, static::$field_aliases ) );
}
/**
* Safely set the value for a field.
* If the field name is invalid, false will be returned instead of an error thrown.
*
* @param string $field The field name.
* @param mixed $value The field value.
*
* @return bool true if the field was set successfully, false if the field name is invalid.
*/
public function set_field( string $field, $value ): bool {
$resolved_field = $this->resolve_field_name( $field );
if ( ! $this->is_allowed_field( $resolved_field ) ) {
return false;
}
$this->set_value_internal( $resolved_field, $value );
return true;
}
}