Column.php

<?php
/**
 * Base Custom Database Table Column Class.
 *
 * @package     Database
 * @subpackage  Column
 * @copyright   Copyright (c) 2020
 * @license     https://opensource.org/licenses/gpl-2.0.php GNU Public License
 * @since       1.0.0
 */
namespace BerlinDB\Database;

// Exit if accessed directly
defined( 'ABSPATH' ) || exit;

/**
 * Base class used for each column for a custom table.
 *
 * @since 1.0.0
 *
 * @see Column::__construct() for accepted arguments.
 */
class Column extends Base {

	/** Table Attributes ******************************************************/

	/**
	 * Name for the database column.
	 *
	 * Required. Must contain lowercase alphabetical characters only. Use of any
	 * other character (number, ascii, unicode, emoji, etc...) will result in
	 * fatal application errors.
	 *
	 * @since 1.0.0
	 * @var   string
	 */
	public $name = '';

	/**
	 * Type of database column.
	 *
	 * See: https://dev.mysql.com/doc/en/data-types.html
	 *
	 * @since 1.0.0
	 * @var   string
	 */
	public $type = '';

	/**
	 * Length of database column.
	 *
	 * See: https://dev.mysql.com/doc/en/storage-requirements.html
	 *
	 * @since 1.0.0
	 * @var   string
	 */
	public $length = false;

	/**
	 * Is integer unsigned?
	 *
	 * See: https://dev.mysql.com/doc/en/numeric-type-overview.html
	 *
	 * @since 1.0.0
	 * @var   bool
	 */
	public $unsigned = true;

	/**
	 * Is integer filled with zeroes?
	 *
	 * See: https://dev.mysql.com/doc/en/numeric-type-overview.html
	 *
	 * @since 1.0.0
	 * @var   bool
	 */
	public $zerofill = false;

	/**
	 * Is data in a binary format?
	 *
	 * See: https://dev.mysql.com/doc/en/binary-varbinary.html
	 *
	 * @since 1.0.0
	 * @var   bool
	 */
	public $binary = false;

	/**
	 * Is null an allowed value?
	 *
	 * See: https://dev.mysql.com/doc/en/data-type-defaults.html
	 *
	 * @since 1.0.0
	 * @var   bool
	 */
	public $allow_null = false;

	/**
	 * Typically empty/null, or date value.
	 *
	 * See: https://dev.mysql.com/doc/en/data-type-defaults.html
	 *
	 * @since 1.0.0
	 * @var   string
	 */
	public $default = '';

	/**
	 * auto_increment, etc...
	 *
	 * See: https://dev.mysql.com/doc/en/data-type-defaults.html
	 *
	 * @since 1.0.0
	 * @var   string
	 */
	public $extra = '';

	/**
	 * Typically inherited from the database interface (wpdb).
	 *
	 * By default, this will use the globally available database encoding. You
	 * most likely do not want to change this; if you do, you already know what
	 * to do.
	 *
	 * See: https://dev.mysql.com/doc/mysql/en/charset-column.html
	 *
	 * @since 1.0.0
	 * @var   string
	 */
	public $encoding = '';

	/**
	 * Typically inherited from the database interface (wpdb).
	 *
	 * By default, this will use the globally available database collation. You
	 * most likely do not want to change this; if you do, you already know what
	 * to do.
	 *
	 * See: https://dev.mysql.com/doc/mysql/en/charset-column.html
	 *
	 * @since 1.0.0
	 * @var   string
	 */
	public $collation = '';

	/**
	 * Typically empty; probably ignore.
	 *
	 * By default, columns do not have comments. This is unused by any other
	 * relative code, but you can include less than 1024 characters here.
	 *
	 * @since 1.0.0
	 * @var   string
	 */
	public $comment = '';

	/** Special Attributes ****************************************************/

	/**
	 * Is this the primary column?
	 *
	 * By default, columns are not the primary column. This is used by the Query
	 * class for several critical functions, including (but not limited to) the
	 * cache key, meta-key relationships, auto-incrementing, etc...
	 *
	 * @since 1.0.0
	 * @var   bool
	 */
	public $primary = false;

	/**
	 * Is this the column used as a created date?
	 *
	 * By default, columns do not represent the date a value was first entered.
	 * This is used by the Query class to set its value automatically to the
	 * current datetime value immediately before insert.
	 *
	 * @since 1.0.0
	 * @var   bool
	 */
	public $created = false;

	/**
	 * Is this the column used as a modified date?
	 *
	 * By default, columns do not represent the date a value was last changed.
	 * This is used by the Query class to update its value automatically to the
	 * current datetime value immediately before insert|update.
	 *
	 * @since 1.0.0
	 * @var   bool
	 */
	public $modified = false;

	/**
	 * Is this the column used as a unique universal identifier?
	 *
	 * By default, columns are not UUIDs. This is used by the Query class to
	 * generate a unique string that can be used to identify a row in a database
	 * table, typically in such a way that is unrelated to the row data itself.
	 *
	 * @since 1.0.0
	 * @var   bool
	 */
	public $uuid = false;

	/** Query Attributes ******************************************************/

	/**
	 * What is the string-replace pattern?
	 *
	 * By default, column patterns will be guessed based on their type. Set this
	 * manually to `%s|%d|%f` only if you are doing something weird, or are
	 * explicitly storing numeric values in text-based column types.
	 *
	 * @since 1.0.0
	 * @var   string
	 */
	public $pattern = '';

	/**
	 * Is this column searchable?
	 *
	 * By default, columns are not searchable. When `true`, the Query class will
	 * add this column to the results of search queries.
	 *
	 * Avoid setting to `true` on large blobs of text, unless you've optimized
	 * your database server to accommodate these kinds of queries.
	 *
	 * @since 1.0.0
	 * @var   bool
	 */
	public $searchable = false;

	/**
	 * Is this column a date?
	 *
	 * By default, columns do not support date queries. When `true`, the Query
	 * class will accept complex statements to help narrow results down to
	 * specific periods of time for values in this column.
	 *
	 * @since 1.0.0
	 * @var   bool
	 */
	public $date_query = false;

	/**
	 * Is this column used in orderby?
	 *
	 * By default, columns are not sortable. This ensures that the database
	 * table does not perform costly operations on unindexed columns or columns
	 * of an inefficient type.
	 *
	 * You can safely turn this on for most numeric columns, indexed columns,
	 * and text columns with intentionally limited lengths.
	 *
	 * @since 1.0.0
	 * @var   bool
	 */
	public $sortable = false;

	/**
	 * Is __in supported?
	 *
	 * By default, columns support being queried using an `IN` statement. This
	 * allows the Query class to retrieve rows that match your array of values.
	 *
	 * Consider setting this to `false` for longer text columns.
	 *
	 * @since 1.0.0
	 * @var   bool
	 */
	public $in = true;

	/**
	 * Is __not_in supported?
	 *
	 * By default, columns support being queried using a `NOT IN` statement.
	 * This allows the Query class to retrieve rows that do not match your array
	 * of values.
	 *
	 * Consider setting this to `false` for longer text columns.
	 *
	 * @since 1.0.0
	 * @var   bool
	 */
	public $not_in = true;

	/** Cache Attributes ******************************************************/

	/**
	 * Does this column have its own cache key?
	 *
	 * By default, only primary columns are used as cache keys. If this column
	 * is unique, or is frequently used to get database results, you may want to
	 * consider setting this to true.
	 *
	 * Use in conjunction with a database index for speedy queries.
	 *
	 * @since 1.0.0
	 * @var   string
	 */
	public $cache_key = false;

	/** Action Attributes *****************************************************/

	/**
	 * Does this column fire a transition action when it's value changes?
	 *
	 * By default, columns do not fire transition actions. In some cases, it may
	 * be desirable to know when a database value changes, and what the old and
	 * new values are when that happens.
	 *
	 * The Query class is responsible for triggering the event action.
	 *
	 * @since 1.0.0
	 * @var   bool
	 */
	public $transition = false;

	/** Callback Attributes ***************************************************/

	/**
	 * Maybe validate this data before it is written to the database.
	 *
	 * By default, column data is validated based on the type of column that it
	 * is. You can set this to a callback function of your choice to override
	 * the default validation behavior.
	 *
	 * @since 1.0.0
	 * @var   string
	 */
	public $validate = '';

	/**
	 * Array of capabilities used to interface with this column.
	 *
	 * These are used by the Query class to allow and disallow CRUD access to
	 * column data, typically based on roles or capabilities.
	 *
	 * @since 1.0.0
	 * @var   array
	 */
	public $caps = array();

	/**
	 * Array of possible aliases this column can be referred to as.
	 *
	 * These are used by the Query class to allow for columns to be renamed
	 * without requiring complex architectural backwards compatibility support.
	 *
	 * @since 1.0.0
	 * @var   array
	 */
	public $aliases = array();

	/**
	 * Array of possible relationships this column has with columns in other
	 * database tables.
	 *
	 * These are typically unenforced foreign keys, and are used by the Query
	 * class to help prime related items.
	 *
	 * @since 1.0.0
	 * @var   array
	 */
	public $relationships = array();

	/** Methods ***************************************************************/

	/**
	 * Sets up the order query, based on the query vars passed.
	 *
	 * @since 1.0.0
	 *
	 * @param string|array $args {
	 *     Optional. Array or query string of order query parameters. Default empty.
	 *
	 *     @type string   $name           Name of database column
	 *     @type string   $type           Type of database column
	 *     @type int      $length         Length of database column
	 *     @type bool     $unsigned       Is integer unsigned?
	 *     @type bool     $zerofill       Is integer filled with zeroes?
	 *     @type bool     $binary         Is data in a binary format?
	 *     @type bool     $allow_null     Is null an allowed value?
	 *     @type mixed    $default        Typically empty/null, or date value
	 *     @type string   $extra          auto_increment, etc...
	 *     @type string   $encoding       Typically inherited from wpdb
	 *     @type string   $collation      Typically inherited from wpdb
	 *     @type string   $comment        Typically empty
	 *     @type bool     $pattern        What is the string-replace pattern?
	 *     @type bool     $primary        Is this the primary column?
	 *     @type bool     $created        Is this the column used as a created date?
	 *     @type bool     $modified       Is this the column used as a modified date?
	 *     @type bool     $uuid           Is this the column used as a universally unique identifier?
	 *     @type bool     $searchable     Is this column searchable?
	 *     @type bool     $sortable       Is this column used in orderby?
	 *     @type bool     $date_query     Is this column a datetime?
	 *     @type bool     $in             Is __in supported?
	 *     @type bool     $not_in         Is __not_in supported?
	 *     @type bool     $cache_key      Is this column queried independently?
	 *     @type bool     $transition     Does this column transition between changes?
	 *     @type string   $validate       A callback function used to validate on save.
	 *     @type array    $caps           Array of capabilities to check.
	 *     @type array    $aliases        Array of possible column name aliases.
	 *     @type array    $relationships  Array of columns in other tables this column relates to.
	 * }
	 */
	public function __construct( $args = array() ) {

		// Parse arguments
		$r = $this->parse_args( $args );

		// Maybe set variables from arguments
		if ( ! empty( $r ) ) {
			$this->set_vars( $r );
		}
	}

	/** Argument Handlers *****************************************************/

	/**
	 * Parse column arguments
	 *
	 * @since 1.0.0
	 * @param array $args Default empty array.
	 * @return array
	 */
	private function parse_args( $args = array() ) {

		// Parse arguments
		$r = wp_parse_args( $args, array(

			// Table
			'name'       => '',
			'type'       => '',
			'length'     => '',
			'unsigned'   => false,
			'zerofill'   => false,
			'binary'     => false,
			'allow_null' => false,
			'default'    => '',
			'extra'      => '',
			'encoding'   => $this->get_db()->charset,
			'collation'  => $this->get_db()->collate,
			'comment'    => '',

			// Query
			'pattern'    => false,
			'searchable' => false,
			'sortable'   => false,
			'date_query' => false,
			'transition' => false,
			'in'         => true,
			'not_in'     => true,

			// Special
			'primary'    => false,
			'created'    => false,
			'modified'   => false,
			'uuid'       => false,

			// Cache
			'cache_key'  => false,

			// Validation
			'validate'   => '',

			// Capabilities
			'caps'          => array(),

			// Backwards Compatibility
			'aliases'       => array(),

			// Column Relationships
			'relationships' => array()
		) );

		// Force some arguments for special column types
		$r = $this->special_args( $r );

		// Set the args before they are sanitized
		$this->set_vars( $r );

		// Return array
		return $this->validate_args( $r );
	}

	/**
	 * Validate arguments after they are parsed.
	 *
	 * @since 1.0.0
	 * @param array $args Default empty array.
	 * @return array
	 */
	private function validate_args( $args = array() ) {

		// Sanitization callbacks
		$callbacks = array(
			'name'          => 'sanitize_key',
			'type'          => 'strtoupper',
			'length'        => 'intval',
			'unsigned'      => 'wp_validate_boolean',
			'zerofill'      => 'wp_validate_boolean',
			'binary'        => 'wp_validate_boolean',
			'allow_null'    => 'wp_validate_boolean',
			'default'       => array( $this, 'sanitize_default' ),
			'extra'         => 'wp_kses_data',
			'encoding'      => 'wp_kses_data',
			'collation'     => 'wp_kses_data',
			'comment'       => 'wp_kses_data',

			'primary'       => 'wp_validate_boolean',
			'created'       => 'wp_validate_boolean',
			'modified'      => 'wp_validate_boolean',
			'uuid'          => 'wp_validate_boolean',

			'searchable'    => 'wp_validate_boolean',
			'sortable'      => 'wp_validate_boolean',
			'date_query'    => 'wp_validate_boolean',
			'transition'    => 'wp_validate_boolean',
			'in'            => 'wp_validate_boolean',
			'not_in'        => 'wp_validate_boolean',
			'cache_key'     => 'wp_validate_boolean',

			'pattern'       => array( $this, 'sanitize_pattern'       ),
			'validate'      => array( $this, 'sanitize_validation'    ),
			'caps'          => array( $this, 'sanitize_capabilities'  ),
			'aliases'       => array( $this, 'sanitize_aliases'       ),
			'relationships' => array( $this, 'sanitize_relationships' )
		);

		// Default args array
		$r = array();

		// Loop through and try to execute callbacks
		foreach ( $args as $key => $value ) {

			// Callback is callable
			if ( isset( $callbacks[ $key ] ) && is_callable( $callbacks[ $key ] ) ) {
				$r[ $key ] = call_user_func( $callbacks[ $key ], $value );

			// Callback is malformed so just let it through to avoid breakage
			} else {
				$r[ $key ] = $value;
			}
		}

		// Return sanitized arguments
		return $r;
	}

	/**
	 * Force column arguments for special column types
	 *
	 * @since 1.0.0
	 * @param array $args Default empty array.
	 * @return array
	 */
	private function special_args( $args = array() ) {

		// Primary key columns are always used as cache keys
		if ( ! empty( $args['primary'] ) ) {
			$args['cache_key'] = true;

		// All UUID columns need to follow a very specific pattern
		} elseif ( ! empty( $args['uuid'] ) ) {
			$args['name']       = 'uuid';
			$args['type']       = 'varchar';
			$args['length']     = '100';
			$args['in']         = false;
			$args['not_in']     = false;
			$args['searchable'] = false;
			$args['sortable']   = false;
		}

		// Return args
		return (array) $args;
	}

	/** Public Helpers ********************************************************/

	/**
	 * Return if a column type is numeric or not.
	 *
	 * @since 1.0.0
	 * @return bool
	 */
	public function is_numeric() {
		return $this->is_type( array(
			'tinyint',
			'int',
			'mediumint',
			'bigint'
		) );
	}

	/** Private Helpers *******************************************************/

	/**
	 * Return if this column is of a certain type.
	 *
	 * @since 1.0.0
	 * @param mixed $type Default empty string. The type to check. Also accepts an array.
	 * @return bool True if of type, False if not
	 */
	private function is_type( $type = '' ) {

		// If string, cast to array
		if ( is_string( $type ) ) {
			$type = (array) $type;
		}

		// Make them lowercase
		$types = array_map( 'strtolower', $type );

		// Return if match or not
		return (bool) in_array( strtolower( $this->type ), $types, true );
	}

	/** Private Sanitizers ****************************************************/

	/**
	 * Sanitize capabilities array
	 *
	 * @since 1.0.0
	 * @param array $caps Default empty array.
	 * @return array
	 */
	private function sanitize_capabilities( $caps = array() ) {
		return wp_parse_args( $caps, array(
			'select' => 'exist',
			'insert' => 'exist',
			'update' => 'exist',
			'delete' => 'exist'
		) );
	}

	/**
	 * Sanitize aliases array using `sanitize_key()`
	 *
	 * @since 1.0.0
	 * @param array $aliases Default empty array.
	 * @return array
	 */
	private function sanitize_aliases( $aliases = array() ) {
		return array_map( 'sanitize_key', $aliases );
	}

	/**
	 * Sanitize relationships array
	 *
	 * @todo
	 * @since 1.0.0
	 * @param array $relationships Default empty array.
	 * @return array
	 */
	private function sanitize_relationships( $relationships = array() ) {
		return array_filter( $relationships );
	}

	/**
	 * Sanitize the default value
	 *
	 * @since 1.0.0
	 * @param string $default
	 * @return string|null
	 */
	private function sanitize_default( $default = '' ) {

		// Null
		if ( ( true === $this->allow_null ) && is_null( $default ) ) {
			return null;

		// String
		} elseif ( is_string( $default ) ) {
			return wp_kses_data( $default );

		// Integer
		} elseif ( $this->is_numeric() ) {
			return (int) $default;
		}

		// @todo datetime, decimal, and other column types

		// Unknown, so return the default's default
		return '';
	}

	/**
	 * Sanitize the pattern
	 *
	 * @since 1.0.0
	 * @param mixed $pattern
	 * @return string
	 */
	private function sanitize_pattern( $pattern = false ) {

		// Allowed patterns
		$allowed_patterns = array( '%s', '%d', '%f' );

		// Return pattern if allowed
		if ( in_array( $pattern, $allowed_patterns, true ) ) {
			return $pattern;
		}

		// Fallback to digit or string
		return $this->is_numeric()
			? '%d'
			: '%s';
	}

	/**
	 * Sanitize the validation callback
	 *
	 * @since 1.0.0
	 * @param string $callback Default empty string. A callable PHP function name or method
	 * @return string The most appropriate callback function for the value
	 */
	private function sanitize_validation( $callback = '' ) {

		// Return callback if it's callable
		if ( is_callable( $callback ) ) {
			return $callback;
		}

		// UUID special column
		if ( true === $this->uuid ) {
			$callback = array( $this, 'validate_uuid' );

		// Datetime fallback
		} elseif ( $this->is_type( 'datetime' ) ) {
			$callback = array( $this, 'validate_datetime' );

		// Decimal fallback
		} elseif ( $this->is_type( 'decimal' ) ) {
			$callback = array( $this, 'validate_decimal' );

		// Intval fallback
		} elseif ( $this->is_numeric() ) {
			$callback = 'intval';
		}

		// Return the callback
		return $callback;
	}

	/** Public Validators *****************************************************/

	/**
	 * Fallback to validate a datetime value if no other is set.
	 *
	 * This assumes NO_ZERO_DATES is off or overridden.
	 *
	 * If MySQL drops support for zero dates, this method will need to be
	 * updated to support different default values based on the environment.
	 *
	 * @since 1.0.0
	 * @param string $value Default ''. A datetime value that needs validating
	 * @return string A valid datetime value
	 */
	public function validate_datetime( $value = '' ) {

		// Handle "empty" values
		if ( empty( $value ) || ( '0000-00-00 00:00:00' === $value ) ) {
			$value = ! empty( $this->default )
				? $this->default
				: '';

		// Convert to MySQL datetime format via gmdate() && strtotime
		} elseif ( function_exists( 'gmdate' ) ) {
			$value = gmdate( 'Y-m-d H:i:s', strtotime( $value ) );
		}

		// Return the validated value
		return $value;
	}

	/**
	 * Validate a decimal
	 *
	 * (Recommended decimal column length is '18,9'.)
	 *
	 * This is used to validate a mixed value before it is saved into a decimal
	 * column in a database table.
	 *
	 * Uses number_format() which does rounding to the last decimal if your
	 * value is longer than specified.
	 *
	 * @since 1.0.0
	 * @param mixed $value    Default empty string. The decimal value to validate
	 * @param int   $decimals Default 9. The number of decimal points to accept
	 * @return float
	 */
	public function validate_decimal( $value = 0, $decimals = 9 ) {

		// Protect against non-numeric values
		if ( ! is_numeric( $value ) ) {
			$value = 0;
		}

		// Protect against non-numeric decimals
		if ( ! is_numeric( $decimals ) ) {
			$decimals = 9;
		}

		// Is the value negative?
		$negative_exponent = ( $value < 0 )
			? -1
			: 1;

		// Only numbers and period
		$value = preg_replace( '/[^0-9\.]/', '', (string) $value );

		// Format to number of decimals, and cast as float
		$formatted = number_format( $value, $decimals, '.', '' );

		// Adjust for negative values
		$retval = $formatted * $negative_exponent;

		// Return
		return $retval;
	}

	/**
	 * Validate a UUID.
	 *
	 * This uses the v4 algorithm to generate a UUID that is used to uniquely
	 * and universally identify a given database row without any direct
	 * connection or correlation to the data in that row.
	 *
	 * From http://php.net/manual/en/function.uniqid.php#94959
	 *
	 * @since 1.0.0
	 * @param string $value The UUID value (empty on insert, string on update)
	 * @return string Generated UUID.
	 */
	public function validate_uuid( $value = '' ) {

		// Default URN UUID prefix
		$prefix = 'urn:uuid:';

		// Bail if not empty and correctly prefixed
		// (UUIDs should _never_ change once they are set)
		if ( ! empty( $value ) && ( 0 === strpos( $value, $prefix ) ) ) {
			return $value;
		}

		// Put the pieces together
		$value = sprintf( "{$prefix}%04x%04x-%04x-%04x-%04x-%04x%04x%04x",

			// 32 bits for "time_low"
			mt_rand( 0, 0xffff ), mt_rand( 0, 0xffff ),

			// 16 bits for "time_mid"
			mt_rand( 0, 0xffff ),

			// 16 bits for "time_hi_and_version",
			// four most significant bits holds version number 4
			mt_rand( 0, 0x0fff ) | 0x4000,

			// 16 bits, 8 bits for "clk_seq_hi_res",
			// 8 bits for "clk_seq_low",
			// two most significant bits holds zero and one for variant DCE1.1
			mt_rand( 0, 0x3fff ) | 0x8000,

			// 48 bits for "node"
			mt_rand( 0, 0xffff ), mt_rand( 0, 0xffff ), mt_rand( 0, 0xffff )
		);

		// Return the new UUID
		return $value;
	}

	/** Table Helpers *********************************************************/

	/**
	 * Return a string representation of what this column's properties look like
	 * in a MySQL.
	 *
	 * @todo
	 * @since 1.0.0
	 * @return string
	 */
	public function get_create_string() {

		// Default return val
		$retval = '';

		// Bail if no name
		if ( ! empty( $this->name ) ) {
			$retval .= $this->name;
		}

		// Type
		if ( ! empty( $this->type ) ) {
			$retval .= " {$this->type}";
		}

		// Length
		if ( ! empty( $this->length ) ) {
			$retval .= '(' . $this->length . ')';
		}

		// Unsigned
		if ( ! empty( $this->unsigned ) ) {
			$retval .= " unsigned";
		}

		// Zerofill
		if ( ! empty( $this->zerofill ) ) {
			// TBD
		}

		// Binary
		if ( ! empty( $this->binary ) ) {
			// TBD
		}

		// Allow null
		if ( ! empty( $this->allow_null ) ) {
			$retval .= " NOT NULL ";
		}

		// Default
		if ( ! empty( $this->default ) ) {
			$retval .= " default '{$this->default}'";

		// A literal false means no default value
		} elseif ( false !== $this->default ) {

			// Numeric
			if ( $this->is_numeric() ) {
				$retval .= " default '0'";
			} elseif ( $this->is_type( 'datetime' ) ) {
				$retval .= " default '0000-00-00 00:00:00'";
			} else {
				$retval .= " default ''";
			}
		}

		// Extra
		if ( ! empty( $this->extra ) ) {
			$retval .= " {$this->extra}";
		}

		// Encoding
		if ( ! empty( $this->encoding ) ) {

		} else {

		}

		// Collation
		if ( ! empty( $this->collation ) ) {

		} else {

		}

		// Return the create string
		return $retval;
	}
}