artabro/wire/core/Wire.php

<?php namespace ProcessWire;

/**
 * ProcessWire Base Class "Wire"
 * 
 * #pw-summary Wire is the base class for most ProcessWire classes and modules. 
 * #pw-body = 
 * Wire derived classes have a `$this->wire()` method that provides access to ProcessWire’s API variables.
 * API variables can also be accessed as local properties in most cases. Wire also provides basic methods 
 * for tracking changes and managing runtime notices specific to the instance. 
 * 
 * Wire derived classes can specify which methods are “hookable” by precending the method name with 
 * 3 underscores like this: `___myMethod()`. Other classes can then hook either before or after that method, 
 * modifying arguments or return values. Several other hook methods are also provided for Wire derived 
 * classes that are hooking into others. 
 * #pw-body
 * #pw-order-groups common,identification,hooks,notices,changes,hooker,api-helpers
 * #pw-summary-api-helpers Shortcuts to ProcessWire API variables. Access without any arguments returns the API variable. Some support arguments as shortcuts to methods in the API variable.
 * #pw-summary-changes Methods to support tracking and retrieval of changes made to the object.
 * #pw-summary-hooks Methods for managing hooks for an object instance or class. 
 * 
 * ProcessWire 3.x, Copyright 2022 by Ryan Cramer
 * https://processwire.com
 * 
 * #pw-use-constants
 * 
 * @property string $className #pw-internal
 * 
 * API variables accessible as properties (unless $useFuel has been set to false):
 * 
 * @property AdminTheme|AdminThemeFramework|null $adminTheme #pw-internal
 * @property WireCache $cache #pw-internal
 * @property Config $config #pw-internal
 * @property WireDatabasePDO $database #pw-internal
 * @property Database $db #pw-internal deprecated
 * @property WireDateTime $datetime #pw-internal
 * @property Fieldgroups|Fieldgroup[] $fieldgroups #pw-internal
 * @property Fields|Field[] $fields #pw-internal
 * @property Fieldtypes|Fieldtype[] $fieldtypes #pw-internal
 * @property WireFileTools $files #pw-internal
 * @property Fuel $fuel #pw-internal
 * @property WireHooks $hooks #pw-internal
 * @property WireInput $input #pw-internal
 * @property Languages|Language[] $languages (present only if LanguageSupport installed) #pw-internal
 * @property WireLog $log #pw-internal
 * @property WireMailTools $mail #pw-internal
 * @property Modules $modules #pw-internal
 * @property Notices|Notice[] $notices #pw-internal
 * @property Page $page #pw-internal
 * @property Pages $pages #pw-internal
 * @property Permissions|Permission[] $permissions #pw-internal
 * @property Process|ProcessPageView $process #pw-internal
 * @property WireProfilerInterface $profiler #pw-internal
 * @property Roles|Role[] $roles #pw-internal
 * @property Sanitizer $sanitizer #pw-internal
 * @property Session $session #pw-internal
 * @property Templates|Template[] $templates #pw-internal
 * @property Paths $urls #pw-internal
 * @property User $user #pw-internal
 * @property Users $users #pw-internal
 * @property ProcessWire $wire #pw-internal
 * 
 * The following map API variables to function names and apply only if another function in the class does not 
 * already have the same name, which would override. All defined API variables can be accessed as functions 
 * that return the API variable, whether documented below or not. 
 *
 * @method WireCache|string|array|PageArray|null cache($name = '', $expire = null, $func = null) Access the $cache API variable as a function.  #pw-group-api-helpers
 * @method Config|mixed config($key = '', $value = null) Access the $config API variable as a function. #pw-group-api-helpers
 * @method WireDatabasePDO database() Access the $database API variable as a function.  #pw-group-api-helpers
 * @method WireDateTime|string|int datetime($format = '', $value = '') Access the $datetime API variable as a function.  #pw-group-api-helpers
 * @method Field|Fields|null fields($name = '') Access the $fields API variable as a function.  #pw-group-api-helpers
 * @method WireFileTools files() Access the $files API variable as a function.  #pw-group-api-helpers
 * @method WireInput|WireInputData|WireInputDataCookie|array|string|int|null input($type = '', $key = '', $sanitizer = '') Access the $input API variable as a function.  #pw-group-api-helpers
 * @method WireInputDataCookie|string|int|array|null inputCookie($key = '', $sanitizer = '') Access the $input->cookie() API variable as a function.  #pw-group-api-helpers
 * @method WireInputData|string|int|array|null inputGet($key = '', $sanitizer = '') Access the $input->get() API variable as a function.  #pw-group-api-helpers
 * @method WireInputData|string|int|array|null inputPost($key = '', $sanitizer = '') Access the $input->post() API variable as a function.  #pw-group-api-helpers
 * @method Languages|Language|NullPage|null languages($name = '') Access the $languages API variable as a function.  #pw-group-api-helpers
 * @method Modules|Module|ConfigurableModule|null modules($name = '') Access the $modules API variable as a function. #pw-group-api-helpers
 * @method Page|Mixed page($key = '', $value = null) Access the $page API variable as a function. #pw-group-api-helpers
 * @method Pages|PageArray|Page|NullPage pages($selector = '') Access the $pages API variable as a function. #pw-group-api-helpers
 * @method Permissions|Permission|PageArray|null|NullPage permissions($selector = '') Access the $permissions API variable as a function.  #pw-group-api-helpers
 * @method Roles|Role|PageArray|null|NullPage roles($selector = '') Access the $roles API variable as a function.  #pw-group-api-helpers
 * @method Sanitizer|string|int|array|null|mixed sanitizer($name = '', $value = '') Access the $sanitizer API variable as a function.  #pw-group-api-helpers
 * @method Session|mixed session($key = '', $value = null) Access the $session API variable as a function.  #pw-group-api-helpers
 * @method Templates|Template|null templates($name = '') Access the $templates API variable as a function. #pw-group-api-helpers
 * @method User|mixed user($key = '', $value = null) Access the $user API variable as a function. #pw-group-api-helpers
 * @method Users|PageArray|User|mixed users($selector = '') Access the $users API variable as a function. #pw-group-api-helpers
 * 
 * Other standard hookable methods
 * 
 * @method changed(string $what, $old = null, $new = null) See Wire::___changed()
 * @method log($str = '', array $options = array()) See Wire::___log()
 * @method callUnknown($method, $arguments) See Wire::___callUnknown()
 * @method Wire trackException(\Exception $e, $severe = true, $text = null)
 * 
 * 
 */

abstract class Wire implements WireTranslatable, WireFuelable, WireTrackable {

	/*******************************************************************************************************
	 * API VARIABLE/FUEL INJECTION AND ACCESS
	 * 
	 * PLEASE NOTE: All the following fuel related variables/methods will be going away in PW 3.0.
	 * You should use the $this->wire() method instead for compatibility with PW 3.0. The only methods
	 * and variables sticking around for PW 3.0 are:
	 * 
	 * $this->wire(...);
	 * $this->useFuel(bool);
	 * $this->useFuel
	 * 
	 */

	/**
	 * Whether this class may use fuel variables in local scope, like $this->item
	 * 
	 * @var bool
	 *
	 */
	protected $useFuel = true;
	
	/**
	 * Total number of Wire class instances
	 *
	 * @var int
	 *
	 */
	static private $_instanceTotal = 0;

	/**
	 * ID of this Wire class instance
	 *
	 * @var int
	 *
	 */
	private $_instanceNum = 0;
	
	/**
	 * Construct
	 * 
	 */
	public function __construct() {}

	/**
	 * Clone this Wire instance
	 * 
	 */
	public function __clone() {
		$this->_instanceNum = 0;
		$this->getInstanceNum();
	}
	
	/**
	 * Get this Wire object’s instance number
	 * 
	 * - This is a unique number among all other Wire (or derived) instances in the system.
	 * - If this instance ID has not yet been set, this will set it. 
	 * - Note that this is different from the ProcessWire instance ID.
	 * 
	 * #pw-group-identification
	 *
	 * @param bool $getTotal Specify true to get the total quantity of Wire instances rather than this instance number. 
	 * @return int Instance number
	 *
	 */
	public function getInstanceNum($getTotal = false) {
		if(!$this->_instanceNum) {
			self::$_instanceTotal++;
			$this->_instanceNum = self::$_instanceTotal;
		}
		if($getTotal) return self::$_instanceTotal;
		return $this->_instanceNum;
	}

	/**
	 * Add fuel to all classes descending from Wire
	 * 
	 * #pw-internal
	 *
	 * @param string $name 
	 * @param mixed $value 
	 * @param bool $lock Whether the API value should be locked (non-overwritable)
	 * @internal Fuel is an internal-only keyword.
	 * 	Unless static needed, use $this->wire($name, $value) instead.
	 * @deprecated Use $this->wire($name, $value, $lock) instead.
	 *
	 */
	public static function setFuel($name, $value, $lock = false) {
		$wire = ProcessWire::getCurrentInstance();
		$log = $wire->wire()->log;
		if($log) $log->deprecatedCall();
		$wire->fuel()->set($name, $value, $lock);
	}

	/**
	 * Get the Fuel specified by $name or NULL if it doesn't exist
	 * 
	 * #pw-internal
	 *
	 * @param string $name
	 * @return mixed|null
	 * @internal Fuel is an internal-only keyword.  
	 * 	Use $this->wire(name) or $this->wire()->name instead, unless static is required.
	 * @deprecated
	 *
	 */
	public static function getFuel($name = '') {
		$wire = ProcessWire::getCurrentInstance();
		$log = $wire->wire()->log;
		if($log) $log->deprecatedCall();
		if(empty($name)) return $wire->fuel();	
		return $wire->fuel()->$name;
	}

	/**
	 * Returns an iterable Fuel object of all Fuel currently loaded
	 * 
	 * #pw-internal
	 *
	 * @return Fuel
	 * @deprecated This method will be going away. 
	 * 	Use $this->wire() instead, or if static required use: Wire::getFuel() with no arguments
	 *
	 */
	public static function getAllFuel() {
		$wire = ProcessWire::getCurrentInstance();
		$log = $wire->wire()->log;
		if($log) $log->deprecatedCall();
		return $wire->fuel();	
	}

	/**
	 * Get the Fuel specified by $name or NULL if it doesn't exist (DEPRECATED)
	 * 
	 * #pw-internal
	 * 
	 * DO NOT USE THIS METHOD: It is deprecated and only used by the ProcessWire class. 
	 * It is here in the Wire class for legacy support only. Use the wire() method instead.
	 *
	 * @param string $name
	 * @return mixed|null
	 *
	 */
	public function fuel($name = '') {
		$wire = $this->wire();
		$log = $wire->wire()->log;
		if($log) $log->deprecatedCall();
		return $wire->fuel($name);
	}
	
	/**
	 * Should fuel vars be scoped locally to this class instance? (internal use only)
	 *
	 * If so, you can do things like $this->apivar.
	 * If not, then you'd have to do $this->wire('apivar').
	 *
	 * If you specify a value, it will set the value of useFuel to true or false.
	 * If you don't specify a value, the current value will be returned.
	 *
	 * Local fuel scope should be disabled in classes where it might cause any conflict with class vars.
	 * 
	 * #pw-internal
	 *
	 * @param bool $useFuel Optional boolean to turn it on or off.
	 * @return bool Current value of $useFuel
	 *
	 */
	public function useFuel($useFuel = null) {
		if($useFuel !== null) $this->useFuel = $useFuel ? true : false;
		return $this->useFuel;
	}


	/*******************************************************************************************************
	 * IDENTIFICATION
	 *
	 */
	
	/**
	 * Return this object’s class name
	 * 
	 * By default, this method returns the class name without namespace. To include the namespace, call it
	 * with boolean true as the first argument. 
	 * 
	 * ~~~~~
	 * echo $page->className(); // outputs: Page
	 * echo $page->className(true); // outputs: ProcessWire\Page
	 * ~~~~~
	 * 
	 * #pw-group-identification
	 *
	 * @param array|bool|null $options Specify boolean `true` to return class name with namespace, or specify an array of
	 *  one or more options:
	 * 	- `lowercase` (bool): Specify true to make it return hyphenated lowercase version of class name (default=false).
	 * 	- `namespace` (bool): Specify true to include namespace from returned class name (default=false). 
	 * 	- *Note: The lowercase and namespace options may not both be true at the same time.*
	 * @return string String with class name
	 *
	 */
	public function className($options = null) {
		
		if(is_bool($options)) {
			$options = array('namespace' => $options);
		} else if(is_array($options)) {
			if(!empty($options['lowercase'])) $options['namespace'] = false;
		} else {
			$options = array();
		}

		if(isset($options['namespace']) && $options['namespace'] === true) {
			$className = get_class($this);
			if(strpos($className, '\\') === false) $className = "\\$className";
		} else {
			$className = wireClassName($this, false);
		}

		if(!empty($options['lowercase'])) {
			static $cache = array();
			if(isset($cache[$className])) {
				$className = $cache[$className];
			} else {
				$_className = $className;
				$part = substr($className, 1);
				if(strtolower($part) != $part) {
					// contains more than 1 uppercase character, convert to hyphenated lowercase
					$className = substr($className, 0, 1) . preg_replace('/([A-Z])/', '-$1', $part);
				}
				$className = strtolower($className);
				$cache[$_className] = $className;
			}
		}
		
		return $className;
	}


	/**
	 * Unless overridden, classes descending from Wire return their class name when typecast as a string
	 * 
	 * @return string
	 *
	 */
	public function __toString() {
		return $this->className();
	}


	/*******************************************************************************************************
	 * HOOKS
	 *
	 */
	
	/**
	 * Hooks that are local to this instance of the class only.
	 *
	 */
	protected $localHooks = array();

	/**
	 * @var WireHooks|null
	 * 
	 */
	private $_wireHooks = null;

	/**
	 * @return WireHooks|null
	 * @since 3.0.171
	 * 
	 */
	protected function _wireHooks() {
		if($this->_wireHooks === null) $this->_wireHooks = $this->wire()->hooks;
		return $this->_wireHooks;
	}

	/**
	 * Return all local hooks for this instance
	 * 
	 * #pw-internal
	 * 
	 * @return array
	 * 
	 */
	public function getLocalHooks() {
		return $this->localHooks;
	}

	/**
	 * Set local hooks for this instance
	 * 
	 * #pw-internal
	 * 
	 * @param array $hooks
	 * 
	 */
	public function setLocalHooks(array $hooks) {
		$this->localHooks = $hooks;
	}

	/**
	 * Call a method in this object, for use by WireHooks
	 * 
	 * #pw-internal
	 * 
	 * @param string $method
	 * @param array $arguments
	 * @return mixed
	 * 
	 */
	public function _callMethod($method, $arguments) {
		$qty = $arguments ? count($arguments) : 0;
		switch($qty) {
			case 0:
				$result = $this->$method();
				break;
			case 1:
				$result = $this->$method($arguments[0]);
				break;
			case 2:
				$result = $this->$method($arguments[0], $arguments[1]);
				break;
			case 3:
				$result = $this->$method($arguments[0], $arguments[1], $arguments[2]);
				break;
			default:
				$result = call_user_func_array(array($this, $method), $arguments);
		}
		return $result;
	}

	/**
	 * Call a hook method (optimization when it's known for certain the method exists)
	 * 
	 * #pw-internal
	 * 
	 * @param string $method Method name, without leading "___"
	 * @param array $arguments
	 * @return mixed
	 * 
	 */
	public function _callHookMethod($method, array $arguments = array()) {
		if(method_exists($this, $method)) {
			return $this->_callMethod($method, $arguments);
		}
		/** @var WireHooks $hooks */
		$hooks = $this->_wireHooks();
		if($hooks && $hooks->isMethodHooked($this, $method)) {
			$result = $hooks->runHooks($this, $method, $arguments);
			return $result['return'];
		} else {
			return $this->_callMethod("___$method", $arguments);
		}
	}

	/**
	 * Provides the gateway for calling hooks in ProcessWire
	 * 
	 * When a non-existant method is called, this checks to see if any hooks have been defined and sends the call to them. 
	 * 
	 * Hooks are defined by preceding the "hookable" method in a descending class with 3 underscores, like __myMethod().
	 * When the API calls $myObject->myMethod(), it gets sent to $myObject->___myMethod() after any 'before' hooks have been called. 
	 * Then after the ___myMethod() call, any "after" hooks are then called. "after" hooks have the opportunity to change the return value.
	 *
	 * Hooks can also be added for methods that don't actually exist in the class, allowing another class to add methods to this class. 
	 *
	 * See the Wire::runHooks() method for the full implementation of hook calls.
	 *
	 * @param string $method
	 * @param array $arguments
	 * @return mixed
	 * @throws WireException
	 *
	 */ 
	public function __call($method, $arguments) {
		if(empty($arguments) && Fuel::isCommon($method)) { 
			// faster version of _callWireAPI for when conditions allow
			if($this->_wire && !method_exists($this, "___$method")) {
				// get a common API var with no arguments as method call more quickly 
				$val = $this->_wire->fuel($method);
				if($val !== null) return $val;
			}
		}
		$hooks = $this->_wireHooks();
		if($hooks) {
			$result = $hooks->runHooks($this, $method, $arguments);
			if(!$result['methodExists'] && !$result['numHooksRun']) {
				$result = $this->_callWireAPI($method, $arguments);
				if(!$result) return $this->callUnknown($method, $arguments);
			}
		} else {
			$result = $this->_callWireAPI($method, $arguments);
			if(!$result) return $this->___callUnknown($method, $arguments);
		}
		return $result['return'];
	}

	/**
	 * Helper to __call() method that maps a call to an API variable when appropriate
	 * 
	 * @param string $method
	 * @param array $arguments
	 * @return array|bool
	 * @internal
	 * 
	 */
	protected function _callWireAPI($method, $arguments) {
		$var = $this->_wire ? $this->_wire->fuel()->$method : null;
		if(!$var) return false;
		// requested method maps to an API variable
		$result = array('return' => null);
		if(count($arguments)) {
			$funcName = 'wire' . ucfirst($method);
			if(__NAMESPACE__) $funcName = __NAMESPACE__ . "\\$funcName";
			if(function_exists($funcName)) {
				// a function exists with this API var name
				$wire = ProcessWire::getCurrentInstance();
				// ensure function call maps to this PW instance
				if($wire !== $this->_wire) ProcessWire::setCurrentInstance($this->_wire);
				$result['return'] = call_user_func_array($funcName, $arguments);
				if($wire !== $this->_wire) ProcessWire::setCurrentInstance($wire);
			}
		} else {
			// if no arguments provided, just return API var
			$result['return'] = $var;
		}
		return $result;
	}

	/**
	 * If method call resulted in no handler, this hookable method is called. 
	 * 
	 * This standard implementation just throws an exception. This is a template method, so the reason it
	 * exists is so that other classes can override and provide their own handler. Classes that provide
	 * their own handler should not do a `parent::__callUnknown()` unless they also fail, as that will 
	 * cause an exception to be thrown. 
	 * 
	 * If you want to override this method with a hook, see the example below. 
	 * ~~~~~
	 * $wire->addHookBefore('Wire::callUnknown', function(HookEvent $event) {
	 *   // Get information about unknown method that was called
	 *   $methodObject = $event->object; 
	 *   $methodName = $event->arguments(0); // string
	 *   $methodArgs = $event->arguments(1); // array
	 *   // The replace option replaces the method and blocks the exception
	 *   $event->replace = true; 
	 *   // Now do something with the information you have, for example
	 *   // you might want to populate a value to $event->return if 
	 *   // you want the unknown method to return a value. 
	 * }); 
	 * ~~~~~
	 * 
	 * #pw-hooker
	 * 
	 * @param string $method Requested method name
	 * @param array $arguments Arguments provided
	 * @return null|mixed Return value of method (if applicable)
	 * @throws WireException
	 * 
	 */
	protected function ___callUnknown($method, $arguments) {
		if($arguments) {} // intentional to avoid unused argument notice
		$config = $this->wire()->config;
		if($config && $config->disableUnknownMethodException) return null;
		throw new WireException("Method " . $this->className() . "::$method does not exist or is not callable in this context"); 
	}

	/**
	 * Provides the implementation for calling hooks in ProcessWire
	 *
	 * Unlike __call, this method won't trigger an Exception if the hook and method don't exist. 
	 * Instead it returns a result array containing information about the call. 
	 * 
	 * #pw-internal
	 *
	 * @param string $method Method or property to run hooks for.
	 * @param array $arguments Arguments passed to the method and hook. 
	 * @param string|array $type May be either 'method', 'property' or array of hooks (from getHooks) to run. Default is 'method'.
	 * @return array Returns an array with the following information: 
	 * 	[return] => The value returned from the hook or NULL if no value returned or hook didn't exist. 
	 *	[numHooksRun] => The number of hooks that were actually run. 
	 *	[methodExists] => Did the hook method exist as a real method in the class? (i.e. with 3 underscores ___method).
	 *	[replace] => Set by the hook at runtime if it wants to prevent execution of the original hooked method.
	 *
	 */
	public function runHooks($method, $arguments, $type = 'method') {
		return $this->_wireHooks()->runHooks($this, $method, $arguments, $type);
	}

	/**
	 * Return all hooks associated with this class instance or method (if specified)
	 * 
	 * #pw-group-hooks
	 *
	 * @param string $method Optional method that hooks will be limited to. Or specify '*' to return all hooks everywhere.
	 * @param int $type Type of hooks to return, specify one of the following constants (from the WireHooks class):
	 * 	- `WireHooks::getHooksAll` returns all hooks (default).
	 * 	- `WireHooks::getHooksLocal` returns local hooks only.
	 * 	- `WireHooks::getHooksStatic` returns static hooks only.
	 * @return array
	 *
	 */
	public function getHooks($method = '', $type = 0) {
		return $this->_wireHooks()->getHooks($this, $method, $type); 
	}
	
	/**
	 * Returns true if the method/property is hooked, false if it isn’t.
	 * 
	 * This is for optimization use. It does not distinguish about class instance. 
	 * It only distinguishes about class if you provide a class with the `$method` argument (i.e. `Class::`).
	 * As a result, a true return value indicates something "might" be hooked, as opposed to be 
	 * being definitely hooked. 
	 *
	 * If checking for a hooked method, it should be in the form "Class::method()" or "method()". 
	 * If checking for a hooked property, it should be in the form "Class::property" or "property". 
	 * 
	 * #pw-internal
	 * 
	 * @param string $method Method or property name in one of the following formats:
	 * 	Class::method()
	 * 	Class::property
	 * 	method()
	 * 	property
	 * @param Wire|null $instance Optional instance to check against (see hasHook method for details)
	 * 	Note that if specifying an $instance, you may not use the Class::method() or Class::property options for $method argument.
	 * @return bool
	 * @deprecated 
	 *
	 */
	static public function isHooked($method, Wire $instance = null) {
		/** @var ProcessWire $wire */
		$wire = $instance ? $instance->wire() : ProcessWire::getCurrentInstance();
		if($instance) return $instance->wire()->hooks->hasHook($instance, $method);
		return $wire->hooks->isHooked($method);
	}

	/**
	 * Returns true if the method or property is hooked, false if it isn’t.
	 *
	 * - This method checks for both static hooks and local hooks.
	 * - Accepts a `method()` or `property` name as an argument. 
	 * - Class context is assumed to be the current class this method is called on. 
	 * - Also considers the class parents for hooks. 
	 * 
	 * ~~~~~
	 * if($pages->hasHook('find()')) {
	 *   // the Pages::find() method is hooked
	 * }
	 * ~~~~~
	 *
	 * #pw-group-hooks
	 *
	 * @param string $name Method() name or property name:
	 *   - If checking for a hooked method, it should be in the form `method()`.
	 *   - If checking for a hooked property, it should be in the form `property`.
	 * @return bool True if this class instance has the hook, false if not. 
	 * @throws WireException When you try to call it with a Class::something() type method, which is not supported. 
	 *
	 */
	public function hasHook($name) {
		return $this->_wireHooks()->hasHook($this, $name);
	}

	/**
	 * Hook a function/method to a hookable method call in this object
	 *
	 * - This method provides the implementation for addHookBefore(), addHookAfter(), addHookProperty(), addHookMethod()
	 * - Hookable method calls are methods preceded by three underscores. 
	 * - You may also specify a method that doesn't exist already in the class.
	 * - The hook method that you define may be part of a class or a globally scoped function. 
	 * 
	 * #pw-internal
	 *
	 * @param string|array $method Method name to hook into, NOT including the three preceding underscores. 
	 * 	May also be Class::Method for same result as using the fromClass option.
	 *  May also be array or CSV string of hook definitions to attach multiple to the same $toMethod (since 3.0.137). 
	 * @param object|null|callable $toObject Object to call $toMethod from,
	 * 	Or null if $toMethod is a function outside of an object,
	 * 	Or function|callable if $toObject is not applicable or function is provided as a closure.
	 * @param string|array $toMethod Method from $toObject, or function name to call on a hook event, or $options array. Optional.
	 * @param array $options Options that can modify default behaviors: 
	 *  - `type` (string): May be 'method', 'property' or 'either'. If property, then it will respond to $obj->property
	 *     rather than $obj->method(). If 'either' it will respond to both. The default type is 'method'.
	 *  - `before` (bool): Execute the hook before the method call? (allows modification of arguments).
	 *     Not applicable if 'type' is 'property'.
	 *  - `after` (bool): Execute the hook after the method call? (allows modification of return value).
	 *     Not applicable if 'type' is 'property'.
	 *  - `priority` (int): A number determining the priority of a hook, where lower numbers are executed before
	 *     higher numbers. The default priority is 100.
	 *  - `allInstances` (bool): attach the hook to all instances of this object? Set automatically, but you may
	 *     still use in some instances.
	 *  - `fromClass` (string): The name of the class containing the hooked method, if not the object where addHook
	 *     was called. Set automatically, but you may still use in some instances.
	 *  - `argMatch` (array|null): An array of Selectors objects where the indexed argument (n) to the hooked method
	 *     must match, in order to execute hook. Default is null.
	 *  - `objMatch` (array|null): Selectors object that the current object must match in order to execute hook.
	 *     Default is null. 
	 * @return string A special Hook ID that should be retained if you need to remove the hook later.
	 *  If multiple methods were hooked then it is a CSV string of hook IDs, accepted removeHook method (since 3.0.137). 
	 * @throws WireException
	 * @see https://processwire.com/docs/modules/hooks/
	 *
	 */
	public function addHook($method, $toObject, $toMethod = null, $options = array()) {
		return $this->_wireHooks()->addHook($this, $method, $toObject, $toMethod, $options);
	}

	/**
	 * Add a hook to be executed before the hooked method 
	 * 
	 * - Use a "before" hook when you have code that should execute before a hookable method executes. 
	 * - One benefit of using a "before" hook is that you can have it modify the arguments that are sent to the hookable method. 
	 * - This type of hook can also completely replace a hookable method if hook populates an `$event->replace` property.
	 *   See the HookEvent class for details. 
	 * 
	 * ~~~~~
	 * // Attach hook to a method in current object
	 * $this->addHookBefore('Page::path', $this, 'yourHookMethodName'); 
	 *   
	 * // Attach hook to an inline function
	 * $this->addHookBefore('Page::path', function($event) { ... }); 
	 *   
	 * // Attach hook to a procedural function
	 * $this->addHookBefore('Page::path', 'your_function_name'); 
	 *   
	 * // Attach hook from single object instance ($page) to inline function
	 * $page->addHookBefore('path', function($event) { ... }); 
	 * ~~~~~
	 * 
	 * #pw-group-hooks
	 *
	 * @param string|array $method Method to hook in one of the following formats (please omit 3 leading underscores): 
	 *  - `Class::method` - If hooking to *all* object instances of the class. 
	 *  - `method` - If hooking to a single object instance. 
	 *  - Since 3.0.137 it may also be multiple methods to hook in CSV string or array. 
	 * @param object|null|callable $toObject Specify one of the following: 
	 *  - Object instance to call `$toMethod` from (like `$this`).
	 *  - Inline function (closure) if providing implemention inline. 
	 *  - Procedural function name, if hook is implemented by a procedural function. 
	 *  - Null if you want to use the 3rd argument and don't need this argument. 
	 * @param string|array $toMethod Method from $toObject, or function name to call on a hook event. 
	 *   This argument can be sustituted as the 2nd argument when the 2nd argument isn’t needed,
	 *   or it can be the $options argument. 
	 * @param array $options Array of options that can modify behavior: 
	 *  - `type` (string): May be either 'method' or 'property'. If property, then it will respond to $obj->property 
	 *     rather than $obj->method(). The default type is 'method'.
	 *  - `priority` (int): A number determining the priority of a hook, where lower numbers are executed before 
	 *     higher numbers. The default priority is 100. 
	 * @return string A special Hook ID (or CSV string of hook IDs) that should be retained if you need to remove the hook later.
	 * @see https://processwire.com/docs/modules/hooks/
	 *
	 */
	public function addHookBefore($method, $toObject, $toMethod = null, $options = array()) {
		// This is the same as calling addHook with the 'before' option set the $options array.
		$options['before'] = true; 
		if(!isset($options['after'])) $options['after'] = false; 
		return $this->_wireHooks()->addHook($this, $method, $toObject, $toMethod, $options); 
	}

	/**
	 * Add a hook to be executed after the hooked method
	 * 
	 * - Use an "after" hook when you have code that should execute after a hookable method executes.
	 * - One benefit of using an "after" hook is that you can have it modify the return value. 
	 *
	 * ~~~~~
	 * // Attach hook to a method in current object
	 * $this->addHookAfter('Page::path', $this, 'yourHookMethodName');
	 *  
	 * // Attach hook to an inline function
	 * $this->addHookAfter('Page::path', function($event) { ... });
	 *  
	 * // Attach hook to a procedural function
	 * $this->addHookAfter('Page::path', 'your_function_name');
	 *  
	 * // Attach hook from single object instance ($page) to inline function
	 * $page->addHookAfter('path', function($event) { ... });
	 * ~~~~~
	 * 
	 * #pw-group-hooks
	 *
	 * @param string|array $method Method to hook in one of the following formats (please omit 3 leading underscores):
	 *  - `Class::method` - If hooking to *all* object instances of the class.
	 *  - `method` - If hooking to a single object instance.
	 *  - Since 3.0.137 it may also be multiple methods to hook in CSV string or array. 
	 * @param object|null|callable $toObject Specify one of the following:
	 *  - Object instance to call `$toMethod` from (like `$this`).
	 *  - Inline function (closure) if providing implemention inline.
	 *  - Procedural function name, if hook is implemented by a procedural function.
	 *  - Null if you want to use the 3rd argument and don't need this argument.
	 * @param string|array $toMethod Method from $toObject, or function name to call on a hook event.
	 *   This argument can be sustituted as the 2nd argument when the 2nd argument isn't needed,
	 *   or it can be the $options argument. 
	 * @param array $options Array of options that can modify behavior:
	 *  - `type` (string): May be either 'method' or 'property'. If property, then it will respond to $obj->property
	 *     rather than $obj->method(). The default type is 'method'.
	 *  - `priority` (int): A number determining the priority of a hook, where lower numbers are executed before
	 *     higher numbers. The default priority is 100.
	 * @return string A special Hook ID (or CSV string of hook IDs) that should be retained if you need to remove the hook later.
	 * @see https://processwire.com/docs/modules/hooks/
	 *
	 */
	public function addHookAfter($method, $toObject, $toMethod = null, $options = array()) {
		$options['after'] = true; 
		if(!isset($options['before'])) $options['before'] = false; 
		return $this->_wireHooks()->addHook($this, $method, $toObject, $toMethod, $options); 
	}

	/**
	 * Add a hook that will be accessible as a new object property. 
	 * 
	 * This enables you to add a new accessible property to an existing object, which will execute
	 * your hook implementation method when called upon. 
	 * 
	 * Note that adding a hook with this just makes it possible to call the hook as a property. 
	 * Any hook property you add can also be called as a method, i.e. `$obj->foo` and `$obj->foo()`
	 * are the same.
	 * 
	 * ~~~~~
	 * // Adding a hook property
	 * $wire->addHookProperty('Page::lastModifiedStr', function($event) {
	 *   $page = $event->object; 
	 *   $event->return = wireDate('relative', $page->modified); 
	 * });
	 * 
	 * // Accessing the property (from any instance)
	 * echo $page->lastModifiedStr; // outputs: "10 days ago"
	 * ~~~~~
	 * 
	 * #pw-group-hooks
	 *
	 * @param string|array $property Name of property you want to add, must not collide with existing property or method names:
	 *  - `Class::property` to add the property to all instances of Class. 
	 *  - `property` if just adding to a single object instance.
	 *  - Since 3.0.137 it may also be multiple properties to hook in CSV string or array. 
	 * @param object|null|callable $toObject Specify one of the following:
	 *  - Object instance to call `$toMethod` from (like `$this`).
	 *  - Inline function (closure) if providing implemention inline.
	 *  - Procedural function name, if hook is implemented by a procedural function.
	 *  - Null if you want to use the 3rd argument and don't need this argument.
	 * @param string|array $toMethod Method from $toObject, or function name to call on a hook event.
	 *   This argument can be sustituted as the 2nd argument when the 2nd argument isn’t needed,
	 *   or it can be the $options argument. 
	 * @param array $options Options typically aren't used in this context, but see Wire::addHookBefore() $options if you'd like.
	 * @return string A special Hook ID (or CSV string of hook IDs) that should be retained if you need to remove the hook later.
	 * @see https://processwire.com/docs/modules/hooks/
	 *
	 */
	public function addHookProperty($property, $toObject, $toMethod = null, $options = array()) {
		// This is the same as calling addHook with the 'type' option set to 'property' in the $options array. 
	    // Note that descending classes that override __get must call getHook($property) and/or runHook($property).
		$options['type'] = 'property'; 
		return $this->_wireHooks()->addHook($this, $property, $toObject, $toMethod, $options); 
	}
	
	/**
	 * Add a hook accessible as a new public method in a class (or object) 
	 * 
	 * - This enables you to add a new accessible public method to an existing object, which will execute
	 *   your hook implementation method when called upon. 
	 *   
	 * - Hook method can accept arguments and/or populate return values, just like any other regular method 
	 *   in the class. However, methods such as this do not have access to private or protected 
	 *   properties/methods in the class. 
	 *   
	 * - Methods added like this themselves become hookable as well. 
	 * 
	 * #pw-group-hooks
	 *
	 * ~~~~~
	 * // Adds a myHasParent($parent) method to all Page objects
	 * $wire->addHookMethod('Page::myHasParent', function($event) {
	 *   $page = $event->object;
	 *   $parent = $event->arguments(0); 
	 *   if(!$parent instanceof Page) {
	 *     throw new WireException("Page::myHasParent() requires a Page argument"); 
	 *   }
	 *   if($page->parents()->has($parent)) {
	 *     // this page has the given parent
	 *     $event->return = true; 
	 *   } else {
	 *     // does not have the given parent
	 *     $event->return = false; 
	 *   }
	 * });
	 *
	 * // Calling the new method (from any instance)
	 * $parent = $pages->get('/products/'); 
	 * if($page->myHasParent($parent)) {
	 *   // $page has the given $parent
	 * } 
	 * ~~~~~
	 *
	 * @param string $method Name of method you want to add, must not collide with existing property or method names:
	 *  - `Class::method` to add the method to all instances of Class.
	 *  - `method` to just add to a single object instance.
	 *  - Since 3.0.137 it may also be multiple methods to hook in CSV string or array. 
	 * @param object|null|callable $toObject Specify one of the following:
	 *  - Object instance to call `$toMethod` from (like `$this`).
	 *  - Inline function (closure) if providing implemention inline.
	 *  - Procedural function name, if hook is implemented by a procedural function.
	 *  - Null if you want to use the 3rd argument and don't need this argument.
	 * @param string|array $toMethod Method from $toObject, or function name to call on a hook event.
	 *   This argument can be sustituted as the 2nd argument when the 2nd argument isn’t needed, 
	 *   or it can be the $options argument. 
	 * @param array $options Options typically aren't used in this context, but see Wire::addHookBefore() $options if you'd like.
	 * @return string A special Hook ID (or CSV string of hook IDs) that should be retained if you need to remove the hook later.
	 * @since 3.0.16 Added as an alias to addHook() for syntactic clarity, previous versions can use addHook() method with same arguments. 
	 * @see https://processwire.com/docs/modules/hooks/
	 *
	 */
	public function addHookMethod($method, $toObject, $toMethod = null, $options = array()) {
		return $this->_wireHooks()->addHook($this, $method, $toObject, $toMethod, $options);
	}

	/**
	 * Given a Hook ID, remove the hook
	 * 
	 * Once a hook is removed, it will no longer execute. 
	 * 
	 * ~~~~~
	 * // Add a hook
	 * $hookID = $pages->addHookAfter('find', function($event) {
	 *   // do something
	 * });
	 * 
	 * // Remove the hook
	 * $pages->removeHook($hookID); 
	 * ~~~~~
	 * ~~~~~
	 * // Hook function that removes itself
	 * $hookID = $pages->addHookAfter('find', function($event) {
	 *   // do something
	 *   $event->removeHook(null); // note: calling removeHook on $event
	 * });
	 * ~~~~~
	 * 
	 * #pw-group-hooks
	 *
	 * @param string|array|null $hookId ID of hook to remove (ID is returned by the addHook() methods)
	 *  Since 3.0.137 it may also be an array or CSV string of hook IDs to remove.
	 * @return $this
	 *
	 */
	public function removeHook($hookId) {
		return $this->_wireHooks()->removeHook($this, $hookId);
	}

	
	/*******************************************************************************************************
	 * CHANGE TRACKING
	 *
	 */

	/**
	 * For setTrackChanges() method flags: track names only (default).
	 * 
	 * #pw-group-changes
	 *
	 */
	const trackChangesOn = 2;
	
	/**
	 * For setTrackChanges() method flags: track names and values.
	 * 
	 * #pw-group-changes
	 *
	 */
	const trackChangesValues = 4;
	
	/**
	 * Track changes mode
	 * 
	 * @var int Bitmask
	 *
	 */
	protected $trackChanges = 0;

	/**
	 * Array containing the names of properties (as array keys) that were changed while change tracking was ON.
	 * 
	 * Array values are insignificant unless trackChangeMode is trackChangesValues (1), in which case the values are the previous values.
	 * 
	 * @var array
	 *
	 */
	private $changes = array();
	
	/**
	 * Does the object have changes, or has the given property changed? 
	 *
	 * Applicable only when object has change tracking enabled. 
	 * 
	 * ~~~~~
	 * // Check if page has changed
	 * if($page->isChanged()) {
	 *   // Page has changes
	 * }
	 * 
	 * // Check if the page title field has changed
	 * if($page->isChanged('title')) {
	 *   // The title has changed
	 * }
	 * ~~~~~
	 * 
	 * #pw-group-changes
	 *
	 * @param string $what Name of property, or if left blank, checks if any properties have changed. 
	 * @return bool True if property has changed, false if not. 
	 *
	 */
	public function isChanged($what = '') {
		if(!$what) return count($this->changes) > 0; 
		return array_key_exists($what, $this->changes); 
	}

	/**
	 * Hookable method that is called whenever a property has changed while change tracking is enabled. 
	 *
	 * - Enables hooks to monitor changes to the object. 
	 * - Do not call this method directly, as the `Wire::trackChange()` method already does so. 
	 * - Descending classes should call `$this->trackChange('name', $oldValue, $newValue);` when a property they are tracking has changed.
	 *
	 * #pw-group-hooker
	 * 
	 * @param string $what Name of property that changed
	 * @param mixed $old Previous value before change 
	 * @param mixed $new New value
	 * @see Wire::trackChange()
	 *
	 */
	public function ___changed($what, $old = null, $new = null) {
		// for hooks to listen to 
	}

	/**
	 * Track a change to a property in this object
	 *
	 * The change will only be recorded if change tracking is enabled for this object instance. 
	 * 
	 * #pw-group-changes
	 *
	 * @param string $what Name of property that changed
	 * @param mixed $old Previous value before change
	 * @param mixed $new New value
	 * @return $this
	 * 
	 */
	public function trackChange($what, $old = null, $new = null) {
		
		if($this->trackChanges & self::trackChangesOn) {
			
			// establish it as changed
			if(array_key_exists($what, $this->changes)) {
				// remember last value so we can avoid duplication in hooks or storage
				$lastValue = end($this->changes[$what]); 
			} else {
				$lastValue = null;
				$this->changes[$what] = array();
			}
		
			if(is_null($old) || is_null($new) || $lastValue !== $new) {
				/** @var WireHooks $hooks */
				$hooks = $this->_wireHooks();
				if(($hooks && $hooks->isHooked('changed()')) || !$hooks) {
					$this->changed($what, $old, $new); // triggers ___changed hook
				} else {
					$this->___changed($what, $old, $new); 
				}
			}
			
			if($this->trackChanges & self::trackChangesValues) {
				// track changed values, but avoid successive duplication of same value
				if(is_object($old) && $old === $new) $old = clone $old; // keep separate copy of objects for old value
				if($lastValue !== $old || !count($this->changes[$what])) $this->changes[$what][] = $old; 
				
			} else {
				// don't track changed values, just names of fields
				$this->changes[$what][] = null;
			}
			
		}
		
		return $this; 
	}

	/**
	 * Untrack a change to a property in this object
	 * 
	 * #pw-group-changes
	 *
	 * @param string $what Name of property that you want to remove its change being tracked
	 * @return $this
	 * 
	 */
	public function untrackChange($what) {
		unset($this->changes[$what]); 
		return $this; 
	}

	/**
	 * Turn change tracking ON or OFF
	 * 
	 * ~~~~~
	 * // Enable change tracking
	 * $page->setTrackChanges(true);
	 * 
	 * // Disable change tracking
	 * $page->setTrackChanges(false);
	 * 
	 * // Enable change tracking and remember values
	 * $page->setTrackChanges(Wire::trackChangesValues); 
	 * $page->setTrackChanges(true);
	 * ~~~~~
	 * 
	 * #pw-group-changes
	 *
	 * @param bool|int $trackChanges Specify one of the following: 
	 *   - `true` (bool): Enables change tracking. 
	 *   - `false` (bool): Disables change tracking
	 *   - `Wire::trackChangesOn` (constant): Enables change tracking (same as specifying boolean true).
	 *   - `Wire::trackChangesValues` (constant): Enables tracking of changed values when change tracking is already on. 
	 *     This uses more memory since it keeps previous values, so it is not enabled by default. Once enabled, the 
	 *     setting will persist through boolean true|false arguments. 
	 * @return $this
	 *
	 */
	public function setTrackChanges($trackChanges = true) {
		if(is_bool($trackChanges) || !$trackChanges) {
			// turn change track on or off
			if($trackChanges) {
				$this->trackChanges = $this->trackChanges | self::trackChangesOn; // add bit
			} else {
				$this->trackChanges = $this->trackChanges & ~self::trackChangesOn; // remove bit
			}
		} else if(is_int($trackChanges)) {
			// set bitmask
			$allowed = array(
				self::trackChangesOn, 
				self::trackChangesValues, 
				self::trackChangesOn | self::trackChangesValues
			); 
			if(in_array($trackChanges, $allowed)) $this->trackChanges = $trackChanges; 
		}
		return $this; 
	}

	/**
	 * Returns true or 1 if change tracking is on, or false or 0 if it is not, or mode bitmask (int) if requested. 
	 * 
	 * #pw-group-changes
	 *
	 * @param bool $getMode When true, the track changes mode bitmask will be returned 
	 * @return int 0/false if off, 1/true if On, or mode bitmask if requested 
	 * 
	 */
	public function trackChanges($getMode = false) {
		if($getMode) return $this->trackChanges; 
		return $this->trackChanges & self::trackChangesOn;	
	}

	/**
	 * Clears out any tracked changes and turns change tracking ON or OFF
	 * 
	 * ~~~~
	 * // Clear any changes that have been tracked and start fresh
	 * $page->resetTrackChanges();
	 * ~~~~
	 * 
	 * #pw-group-changes
	 *
	 * @param bool $trackChanges True to turn change tracking ON, or false to turn OFF. Default of true is assumed.
	 * @return $this
	 *
	 */
	public function resetTrackChanges($trackChanges = true) {
		$this->changes = array();
		return $this->setTrackChanges($trackChanges); 
	}

	/**
	 * Return an array of properties that have changed while change tracking was on. 
	 * 
	 * ~~~~~
	 * // Get an array of changed field names
	 * $changes = $page->getChanges();
	 * ~~~~~
	 * 
	 * #pw-group-changes
	 *
	 * @param bool $getValues Specify one of the following, or omit for default setting. 
	 *  - `false` (bool): return array of changed property names (default setting).
	 *  - `true` (bool): return an associative array containing an array of previous values, indexed by 
	 *     property name, oldest to newest. Requires Wire::trackChangesValues mode to be enabled. 
	 *  - `2` (int): Return array where both keys and values are changed property names. 
	 * @return array
	 *
	 */
	public function getChanges($getValues = false) {
		if($getValues === 2) {
			$changes = array();
			foreach($this->changes as $name => $value) {
				if($value) {} // value ignored
				$changes[$name] = $name;
			}
			return $changes;
		} else if($getValues) {
			return $this->changes;
		} else {
			return array_keys($this->changes);
		}
	}

	
	/*******************************************************************************************************
	 * NOTICES AND LOGS
	 *
	 */

	/**
	 * @var Notices[]
	 * 
	 */
	protected $_notices = array(
		'errors' => null, 
		'warnings' => null, 
		'messages' => null
	);

	/**
	 * Record a Notice, internal use (contains the code for message, warning and error methods)
	 * 
	 * @param string|array|Wire $text Title of notice
	 * @param int|string $flags Flags bitmask or space separated string of flag names
	 * @param string $name Name of container
	 * @param string $class Name of Notice class
	 * @return $this
	 * 
	 */
	protected function _notice($text, $flags, $name, $class) {
		if($flags === true) $flags = Notice::log;
		$class = wireClassName($class, true);
		$notice = $this->wire(new $class($text, $flags)); /** @var Notice $notice */
		$notice->class = $this->className();
		if($this->_notices[$name] === null) $this->_notices[$name] = $this->wire(new Notices());
		$notices = $this->wire()->notices;
		if($notices) $notices->add($notice); // system wide
		if(!($notice->flags & Notice::logOnly)) $this->_notices[$name]->add($notice); // local only
		return $this; 
	}

	/**
	 * Record an informational or “success” message in the system-wide notices. 
	 *
	 * This method automatically identifies the message as coming from this class.
	 * 
	 * ~~~~~
	 * $this->message("This is the notice text");
	 * $this->message("This notice is also logged", true);
	 * $this->message("This notice is only shown in debug mode", Notice::debug);
	 * $this->message("This notice allows <em>markup</em>", Notice::allowMarkup);
	 * $this->message("Notice using multiple flags", Notice::debug | Notice::logOnly);
	 * ~~~~~
	 * 
	 * #pw-group-notices
	 *
	 * @param string|array|Wire $text Text to include in the notice
	 * @param int|bool|string $flags Optional flags to alter default behavior:
	 *  - `Notice::admin` (constant): Show notice only if user is in the admin.
	 *  - `Notice::allowMarkdown` (constant): Allow basic markdown and bracket markup (see $sanitizer->entitiesMarkdown()).
	 *  - `Notice::allowMarkup` (constant): Indicates notice should allow the use of HTML markup tags.
	 *  - `Notice::debug` (constant): Indicates notice should only be shown when debug mode is active.
	 *  - `Notice::log` (constant): Indicates notice should also be logged.
	 *  - `Notice::logOnly` (constant): Indicates notice should only be logged.
	 *  - `Notice::login` (constant): Show notice only if it will be seen by a logged-in user.
	 *  - `Notice::noGroup` (constant): Indicates notice should not group with others of the same type (where supported).
	 *  - `Notice::prepend` (constant): Indicates notice should prepend rather than append.
	 *  - `Notice::superuser` (constant): Show notice only if current user is a superuser.
	 *  - `true` (boolean): Shortcut for the `Notice::log` constant.
	 *  - In 3.0.149+ you may also specify a space-separated string of flag names, i.e. "admin log noGroup". 
	 * @return $this
	 * @see Wire::messages(), Wire::warning(), Wire::error()
	 *
	 */
	public function message($text, $flags = 0) {
		return $this->_notice($text, $flags, 'messages', 'NoticeMessage'); 
	}
	
	/**
	 * Record a warning error message in the system-wide notices.
	 *
	 * This method automatically identifies the warning as coming from this class.
	 * 
	 * ~~~~~
	 * $this->warning("This is the notice text");
	 * $this->warning("This notice is also logged", true);
	 * $this->warning("This notice is only shown in debug mode", Notice::debug);
	 * $this->warning("This notice allows <em>markup</em>", Notice::allowMarkup);
	 * $this->warning("Notice using multiple flags", Notice::debug | Notice::logOnly);
	 * ~~~~~
	 * 
	 * #pw-group-notices
	 *
	 * @param string|array|Wire $text Text to include in the notice
	 * @param int|bool|string $flags Optional flags to alter default behavior:
	 *  - `Notice::admin` (constant): Show notice only if user is in the admin.
	 *  - `Notice::allowMarkdown` (constant): Allow basic markdown and bracket markup (see $sanitizer->entitiesMarkdown()).
	 *  - `Notice::allowMarkup` (constant): Indicates notice should allow the use of HTML markup tags.
	 *  - `Notice::debug` (constant): Indicates notice should only be shown when debug mode is active.
	 *  - `Notice::log` (constant): Indicates notice should also be logged.
	 *  - `Notice::logOnly` (constant): Indicates notice should only be logged.
	 *  - `Notice::login` (constant): Show notice only if it will be seen by a logged-in user.
	 *  - `Notice::noGroup` (constant): Indicates notice should not group with others of the same type (where supported).
	 *  - `Notice::prepend` (constant): Indicates notice should prepend rather than append.
	 *  - `Notice::superuser` (constant): Show notice only if current user is a superuser.
	 *  - `true` (boolean): Shortcut for the `Notice::log` constant.
	 *  - In 3.0.149+ you may also specify a space-separated string of flag names, i.e. "admin log noGroup". 
	 * @return $this
	 * @see Wire::warnings(), Wire::message(), Wire::error()
	 *
	 *
	 */
	public function warning($text, $flags = 0) {
		return $this->_notice($text, $flags, 'warnings', 'NoticeWarning'); 
	}

	/**
	 * Record an non-fatal error message in the system-wide notices. 
	 *
	 * - This method automatically identifies the error as coming from this class. 
	 * - You should still make fatal errors throw a `WireException` (or class derived from it).
	 * 
	 * ~~~~~
	 * $this->error("This is the notice text"); 
	 * $this->error("This notice is also logged", true);
	 * $this->error("This notice is only shown in debug mode", Notice::debug);
	 * $this->error("This notice allows <em>markup</em>", Notice::allowMarkup);
	 * $this->error("Notice using multiple flags", Notice::debug | Notice::logOnly);
	 * ~~~~~
	 * 
	 * #pw-group-notices
	 *
	 * @param string|array|Wire $text Text to include in the notice
	 * @param int|bool|string $flags Optional flags to alter default behavior:
	 *  - `Notice::admin` (constant): Show notice only if user is in the admin.
	 *  - `Notice::allowMarkdown` (constant): Allow basic markdown and bracket markup (see $sanitizer->entitiesMarkdown()).
	 *  - `Notice::allowMarkup` (constant): Indicates notice should allow the use of HTML markup tags.
	 *  - `Notice::debug` (constant): Indicates notice should only be shown when debug mode is active.
	 *  - `Notice::log` (constant): Indicates notice should also be logged.
	 *  - `Notice::logOnly` (constant): Indicates notice should only be logged.
	 *  - `Notice::login` (constant): Show notice only if it will be seen by a logged-in user.
	 *  - `Notice::noGroup` (constant): Indicates notice should not group with others of the same type (where supported).
	 *  - `Notice::prepend` (constant): Indicates notice should prepend rather than append.
	 *  - `Notice::superuser` (constant): Show notice only if current user is a superuser.
	 *  - `true` (boolean): Shortcut for the `Notice::log` constant.
	 *  - In 3.0.149+ you may also specify a space-separated string of flag names, i.e. "admin log noGroup". 
	 * @return $this
	 * @see Wire::errors(), Wire::message(), Wire::warning()
	 *
	 */
	public function error($text, $flags = 0) {
		return $this->_notice($text, $flags, 'errors', 'NoticeError'); 
	}

	/**
	 * Hookable method called when an Exception occurs
	 * 
	 * - It will log Exception to `exceptions.txt` log if 'exceptions' is in `$config->logs`. 
	 * - It will re-throw Exception if `$config->allowExceptions` is true. 
	 * - If additional `$text` is provided, it will be sent to notice method call. 
	 * 
	 * #pw-hooker
	 * 
	 * @param \Exception|WireException $e Exception object that was thrown.
	 * @param bool|int $severe Whether or not it should be considered severe (default=true).
	 * @param string|array|object|true $text Additional details (optional):
	 * 	- When provided, it will be sent to `$this->error($text)` if $severe is true, or `$this->warning($text)` if $severe is false.
	 * 	- Specify boolean `true` to just send the `$e->getMessage()` to `$this->error()` or `$this->warning()`. 
	 * @return $this
	 * @throws \Exception If `$severe==true` and `$config->allowExceptions==true`
	 * 
	 */
	public function ___trackException(\Exception $e, $severe = true, $text = null) {
		$config = $this->wire()->config;
		$log = $this->wire()->log;
		$msg = $e->getMessage();
		if($text !== null) {
			if($text === true) $text = $msg;
			$severe ? $this->error($text) : $this->warning($text);
			if(strlen($msg) && strpos($text, $msg) === false) $msg = "$text - $msg";
		}
		if(in_array('exceptions', $config->logs) && $log) {
			$msg .= " (in " . str_replace($config->paths->root, '/', $e->getFile()) . " line " . $e->getLine() . ")";
			$log->save('exceptions', $msg);
		}
		if($severe && $config->allowExceptions) {
			throw $e; // re-throw, if requested
		}
		return $this;
	}

	/**
	 * Return or manage errors recorded by just this object or all Wire objects
	 * 
	 * This method returns and manages errors that were previously set by `Wire::error()`. 
	 * 
	 * ~~~~~
	 * // Get errors for one object
	 * $errors = $obj->errors();
	 * 
	 * // Get first error in object
	 * $error = $obj->errors('first');
	 * 
	 * // Get errors for all Wire objects
	 * $errors = $obj->errors('all'); 
	 * 
	 * // Get and clear all errors for all Wire objects
	 * $errors = $obj->errors('clear all'); 
	 * ~~~~~
	 * 
	 * #pw-group-notices
	 * 
	 * @param string|array $options One or more of array elements or space separated string of:
	 * 	- `first` - only first item will be returned 
	 * 	- `last` - only last item will be returned 
	 * 	- `all` - include all errors, including those beyond the scope of this object
	 * 	- `clear` - clear out all items that are returned from this method
	 * 	- `array` - return an array of strings rather than series of Notice objects.
	 * 	- `string` - return a newline separated string rather than array/Notice objects. 
	 * @return Notices|array|string Array of `NoticeError` errors, or string if last, first or str option was specified.
	 * 
	 */
	public function errors($options = array()) {
		if(!is_array($options)) $options = explode(' ', strtolower($options)); 
		$options[] = 'errors';
		return $this->messages($options); 
	}

	/**
	 * Return or manage warnings recorded by just this object or all Wire objects
	 * 
	 * This method returns and manages warnings that were previously set by `Wire::warning()`. 
	 * 
	 * ~~~~~
	 * // Get warnings for one object
	 * $warnings = $obj->warnings();
	 *
	 * // Get first warning in object
	 * $warning = $obj->warnings('first');
	 *
	 * // Get warnings for all Wire objects
	 * $warnings = $obj->warnings('all');
	 *
	 * // Get and clear all warnings for all Wire objects
	 * $warnings = $obj->warnings('clear all');
	 * ~~~~~
	 * 
	 * #pw-group-notices
	 *
	 * @param string|array $options One or more of array elements or space separated string of:
	 * 	- `first` - only first item will be returned
	 * 	- `last` - only last item will be returned
	 * 	- `all` - include all errors, including those beyond the scope of this object
	 * 	- `clear` - clear out all items that are returned from this method
	 * 	- `array` - return an array of strings rather than series of Notice objects.
	 * 	- `string` - return a newline separated string rather than array/Notice objects.
	 * @return Notices|array|string Array of `NoticeWarning` warnings, or string if last, first or str option was specified.
	 * 
	 *
	 */
	public function warnings($options = array()) {
		if(!is_array($options)) $options = explode(' ', strtolower($options));
		$options[] = 'warnings';
		return $this->messages($options); 
	}

	/**
	 * Return or manage messages recorded by just this object or all Wire objects
	 * 
	 * This method returns and manages messages that were previously set by `Wire::message()`. 
	 *
	 * ~~~~~
	 * // Get messages for one object
	 * $messages = $obj->messages();
	 *
	 * // Get first message in object
	 * $message = $obj->messages('first');
	 *
	 * // Get messages for all Wire objects
	 * $messages = $obj->messages('all');
	 *
	 * // Get and clear all messages for all Wire objects
	 * $messages = $obj->messages('clear all');
	 * ~~~~~
	 * 
	 * #pw-group-notices
	 *
	 * @param string|array $options One or more of array elements or space separated string of:
	 * 	- `first` - only first item will be returned
	 * 	- `last` - only last item will be returned
	 * 	- `all` - include all messages, including those beyond the scope of this object
	 * 	- `clear` - clear out all items that are returned from this method
	 * 	- `array` - return an array of strings rather than series of Notice objects.
	 * 	- `string` - return a newline separated string rather than array/Notice objects.
	 * @return Notices|array|string Array of `NoticeMessage` messages, or string if last, first or str option was specified.
	 *
	 */
	public function messages($options = array()) {
		if(!is_array($options)) $options = explode(' ', strtolower($options)); 
		if(in_array('errors', $options)) {
			$type = 'errors';
		} else if(in_array('warnings', $options)) {
			$type = 'warnings';
		} else {
			$type = 'messages';
		}
		$clear = in_array('clear', $options); 
		if(in_array('all', $options)) {
			// get all of either messages, warnings or errors (either in or out of this object instance)
			$notices = $this->wire()->notices; 
			$value = $this->wire(new Notices()); /** @var Notices $value */
			foreach($notices as $notice) {
				if($notice->getName() != $type) continue;
				$value->add($notice);
				if($clear) $notices->remove($notice); // clear global
			}
			if($clear) $this->_notices[$type] = null; // clear local
		} else {
			// get messages, warnings or errors specific to this object instance
			/** @var Notices $value */
			$value = $this->_notices[$type] === null ? $this->wire(new Notices()) : $this->_notices[$type];
			if(in_array('first', $options)) {
				$value = $clear ? $value->shift() : $value->first();
			} else if(in_array('last', $options)) {
				$value = $clear ? $value->pop() : $value->last();
			} else if($clear) {
				$this->_notices[$type] = null;
			}
			if($clear && $value) {
				$this->wire()->notices->removeItems($value); // clear from global notices
			}
		}
		if(in_array('array', $options) || in_array('string', $options)) {
			if($value instanceof Notice) {
				$value = array($value->text);
			} else {
				$_value = array();
				foreach($value as $notice) {
					/** @var Notice $notice */
					$_value[] = $notice->text;
				}
				$value = $_value; 
			}
			if(in_array('string', $options)) {
				$value = implode("\n", $value); 
			}
		}
		return $value; 
	}

	/**
	 * Log a message for this class
	 * 
	 * Message is saved to a log file in ProcessWire's logs path to a file with 
	 * the same name as the class, converted to hyphenated lowercase. For example, 
	 * a class named `MyWidgetData` would have a log named `my-widget-data.txt`.
	 * 
	 * ~~~~~
	 * $this->log("This message will be logged"); 
	 * ~~~~~
	 * 
	 * #pw-group-notices
	 * 
	 * @param string $str Text to log, or omit to return the `$log` API variable.
	 * @param array $options Optional extras to include: 
	 *  - `url` (string): URL to record the with the log entry (default=auto-detect)
	 *  - `name` (string): Name of log to use (default=auto-detect)
	 *  - `user` (User|string|null): User instance, user name, or null to log for current User. (default=null)
	 * @return WireLog
	 *
	 */
	public function ___log($str = '', array $options = array()) {
		$log = $this->wire()->log;
		if($log && strlen($str)) {
			if(isset($options['name'])) {
				$name = $options['name'];
				unset($options['name']);
			} else {
				$name = $this->className(array('lowercase' => true));
			}
			$log->save($name, $str, $options);
		}
		return $log; 
	}
	
	/*******************************************************************************************************
	 * TRANSLATION 
	 * 
	 */

	/**
	 * Translate the given text string into the current language if available. 
	 *
	 * If not available, or if the current language is the native language, then it returns the text as is. 
	 * 
	 * #pw-group-translation
	 *
	 * @param string|array $text Text string to translate (or array in 3.0.151 also supported)
	 * @return string
	 *
	 */
	public function _($text) {
		return __($text, $this); 
	}

	/**
	 * Perform a language translation in a specific context
	 * 
	 * Used when to text strings might be the same in English, but different in other languages. 
	 * 
	 * #pw-group-translation
	 * 
	 * @param string|array $text Text for translation. 
	 * @param string $context Name of context
	 * @return string Translated text or original text if translation not available.
	 *
	 */
	public function _x($text, $context) {
		return _x($text, $context, $this); 
	}

	/**
	 * Perform a language translation with singular and plural versions
	 * 
	 * #pw-group-translation
	 * 
	 * @param string $textSingular Singular version of text (when there is 1 item).
	 * @param string $textPlural Plural version of text (when there are multiple items or 0 items).
	 * @param int $count Quantity used to determine whether singular or plural.
	 * @return string Translated text or original text if translation not available.
	 *
	 */
	public function _n($textSingular, $textPlural, $count) {
		return _n($textSingular, $textPlural, $count, $this); 
	}
	
	/*******************************************************************************************************
	 * API VARIABLE MANAGEMENT
	 * 
	 * To replace fuel in PW 3.0
	 *
	 */

	/**
	 * ProcessWire instance
	 *
	 * @var ProcessWire|bool|null
	 *
	 */
	protected $_wire = null;

	/**
	 * Set the current ProcessWire instance for this object (PW 3.0)
	 * 
	 * #pw-internal
	 *
	 * @param ProcessWire $wire
	 *
	 */
	public function setWire(ProcessWire $wire) {
		$wired = $this->_wire;
		if($wired === $wire) return;
		$this->_wire = $wire;
		if($this->_wireHooks) $this->_wireHooks = $wire->wire()->hooks;
		if($wired) return;
		$this->getInstanceNum();
		$this->wired();
	}

	/**
	 * Get the current ProcessWire instance (PW 3.0)
	 * 
	 * You can also use the wire() method with no arguments.
	 * 
	 * #pw-internal
	 *
	 * @return null|ProcessWire
	 *
	 */
	public function getWire() {
		return $this->_wire ? $this->_wire : null;
	}

	/**
	 * Is this object wired to a ProcessWire instance?
	 * 
	 * #pw-internal
	 * 
	 * @return bool
	 * 
	 */
	public function isWired() {
		return $this->_wire ? true : false;
	}
	
	/**
	 * Get an API variable, create an API variable, or inject dependencies.
	 * 
	 * This method provides the following:
	 * 
	 * - Access to API variables:   
	 *   `$pages = $this->wire('pages');`
	 *   
	 * - Access to current ProcessWire instance:   
	 *   `$wire = $this->wire();`
	 *   
	 * - Creating new API variables:   
	 *   `$this->wire('widgets', $widgets);`
	 *   
	 * - Injection of dependencies to Wire derived objects:   
	 *   `$this->wire($widgets);`
	 * 
	 * Most Wire derived objects also support access to API variables directly via `$this->apiVar`. 
	 * 
	 * There is also the `wire()` procedural function, which provides the same access to get API 
	 * variables. Note however the procedural version does not support creating API variables or 
	 * injection of dependencies. 
	 * 
	 * ~~~~~
	 * // Get the 'pages' API variable
	 * $pages = $this->wire('pages');
	 *   
	 * // Get the 'pages' API variable using alternate syntax
	 * $pages = $this->wire()->pages; 
	 *  
	 * // Get all API variables (returns a Fuel object)
	 * $all = $this->wire('all');
	 *   
	 * // Get the current ProcessWire instance (no arguments)
	 * $wire = $this->wire(); 
	 *  
	 * // Create a new API variable named 'widgets'
	 * $this->wire('widgets', $widgets);
	 *  
	 * // Create new API variable and lock it so nothing can overwrite 
	 * $this->wire('widgets', $widgets, true); 
	 *   
	 * // Alternate syntax for the two above
	 * $this->wire()->set('widgets', $widgets);
	 * $this->wire()->set('widgets', $widgets, true); // lock 
	 *   
	 * // Inject dependencies into Wire derived object
	 * $this->wire($widgets); 
	 *   
	 * // Inject dependencies during construct
	 * $newPage = $this->wire(new Page());
	 * ~~~~~
	 *
	 * @param string|object $name Name of API variable to retrieve, set, or omit to retrieve the master ProcessWire object.
	 * @param null|mixed $value Value to set if using this as a setter, otherwise omit.
	 * @param bool $lock When using as a setter, specify true if you want to lock the value from future changes (default=false).
	 * @return ProcessWire|Wire|Session|Page|Pages|Modules|User|Users|Roles|Permissions|Templates|Fields|Fieldtypes|Sanitizer|Config|Notices|WireDatabasePDO|WireHooks|WireDateTime|WireFileTools|WireMailTools|WireInput|string|mixed
	 * @throws WireException
	 *
	 *
	 */
	public function wire($name = '', $value = null, $lock = false) {

		if($this->_wire) {
			// this instance is wired
			$wire = $this->_wire;
			// quick exit when _wire already set and not getting/setting API var
			if($name === '') return $wire;
		} else {
			// this object has not yet been wired! use last known current instance as fallback
			// note this condition is unsafe in multi-instance mode
			$wire = ProcessWire::getCurrentInstance();
			if(!$wire) return is_object($name) ? $name : null; // there are no ProcessWire instances
			if($name && $this->_wire === null) {
				$this->_wire = false; // false prevents this from being called another time for this object
				$wire->_objectNotWired($this, $name, $value);
			}
		}

		if(is_object($name)) {
			// make an object wired (inject ProcessWire instance to object)
			if($name instanceof WireFuelable) {
				if($this->_wire) $name->setWire($wire); // inject fuel, PW 3.0 
				if(is_string($value) && $value) {
					// set as new API var if API var name specified in $value
					$wire->fuel()->set($value, $name, $lock);
				}
				$value = $name; // return the provided instance
			} else {
				throw new WireException('Wire::wire($o) expected WireFuelable for $o and was given ' . get_class($name));
			}

		} else if($value !== null) {
			// setting a API variable/fuel value, and make it wired
			if($value instanceof WireFuelable && $this->_wire) $value->setWire($wire);
			$wire->fuel()->set($name, $value, $lock);
			
		} else if(empty($name)) {
			// return ProcessWire instance
			$value = $wire;
			
		} else if($name === '*' || $name === 'all' || $name == 'fuel') {
			// return Fuel instance
			$value = $wire->fuel();
			
		} else {
			// get API variable
			$value = $wire->fuel()->$name;
		}
		
		return $value;
	}

	/**
	 * Initialization called when object injected with ProcessWire instance (aka “wired”)
	 *
	 * - Can be used for any constructor-type initialization that depends on API vars.
	 * - Called automatically when object is “wired”, do not call it on your own.
	 * - Expects to be called only once per object instance.
	 * - Typically called after `__construct()` but before any other method calls.
	 * - Please note: If object is never “wired” then this method will not be called!
	 *
	 * ~~~~~
	 * class Test extends Wire {
	 *   function wired() { 
	 *     echo "Wired to ProcessWire instance: "; 
	 *     echo $this->wire()->getProcessWireInstanceID();
	 *   }
	 * }
	 *
	 * // objects in ProcessWire are “wired” like this:
	 * $o = new Test();
	 * $this->wire($o); // outputs "ProcessWire instance: n"
	 *
	 * // or on one line, like this…
	 * $this->wire(new Test()); // outputs "ProcessWire instance: n"
	 * ~~~~~
	 *
	 * #pw-internal
	 *
	 * @since 3.0.158
	 *
	 */
	public function wired() { }

	/**
	 * Get an object property by direct reference or NULL if it doesn't exist
	 *
	 * If not overridden, this is primarily used as a shortcut for the fuel() method.
	 *
	 * Descending classes may have their own __get() but must pass control to this one when they can't find something.
	 *
	 * @param string $name
	 * @return mixed|null
	 *
	 */
	public function __get($name) {

		if($name === 'wire') return $this->wire();
		if($name === 'fuel') return $this->wire('fuel');
		if($name === 'className') return $this->className();

		if($this->useFuel()) {
			$value = $this->wire($name);
			if($value !== null) return $value; 
		}

		$hooks = $this->_wireHooks(); /** @var WireHooks $hooks */
		if($hooks && $hooks->isHooked($name)) { // potential property hook
			$result = $hooks->runHooks($this, $name, array(), 'property');
			return $result['return'];
		}

		return null;
	}

	/**
	 * debugInfo PHP 5.6+ magic method
	 *
	 * This is used when you print_r() an object instance.
	 *
	 * @return array
	 *
	 */
	public function __debugInfo() {
		/** @var WireDebugInfo $debugInfo */
		require_once(__DIR__ . '/WireDebugInfo.php');
		$debugInfo = $this->wire(new WireDebugInfo());
		return $debugInfo->getDebugInfo($this, true);
	}

	/**
	 * Minimal/small debug info
	 * 
	 * Same as __debugInfo() but with no hooks info, no change tracking info, and less verbose 
	 * 
	 * #pw-internal
	 * 
	 * @return array
	 * @since 3.0.130
	 * 
	 */
	public function debugInfoSmall() {
		/** @var WireDebugInfo $debugInfo */
		$debugInfo = $this->wire(new WireDebugInfo());
		return $debugInfo->getDebugInfo($this, true);
	}


}