<?php namespace ProcessWire;

/**
 * ProcessWire ConfigurableModule and ConfigModule Interfaces
 *
 * Provides the base interfaces required by modules.
 * 
 * This file is licensed under the MIT license
 * https://processwire.com/about/license/mit/
 *
 * ProcessWire 3.x, Copyright 2021 by Ryan Cramer
 * https://processwire.com
 *
 * 
 * About the ConfigurableModule interface
 * ======================================
 * ConfigurableModule is an interface that indicates the module is configurable by providing
 * `__get()` and `__set()` methods for getting and setting config values. Modules implementing 
 * this interface are assumed to also implement the `Module` interface.
 * 
 * The module must also provide one (1) of the following:
 *
 * 1. A `getModuleConfigInputfields([$data])` method (static or non-static); OR
 * 2. A separate `ModuleName.config.php` file that just populates $config array; OR
 * 3. A separate `ModuleNameConfig.php` file that contains a ModuleConfig class.
 *
 * For more details about the above options, see the commented methods within
 * the interface.
 *
 * When you use this as an interface, you MUST also use `Module` as an interface,
 * i.e. `class Something implements Module, ConfigurableModule`
 *
 * Hint: Make your ConfigurableModule classes inherit from `WireData`, which already has
 * the get/set required methods.
 *
 * You may optionally specify a handler method for configuration data: `setConfigData()`.
 * If present, it will be used. See commented function reference in the interface below.
 * 
 * 
 * About the ConfigModule interface (3.0.179+)
 * ===========================================
 * This interface indicates the module can receive config settings, but is not
 * interactively configurable. Use this for modules where configuration will
 * only be managed from the API/code side. Config settings must be saved using
 * `$modules->saveConfig()`. Settings will be automatically populated to the module
 * when it is loaded, or may be retrieved with `$modules->getConfig()`.
 *
 * Beyond the difference mentioned above, this interface is identical to the
 * ConfigurableModule interface except that it needs no getModuleConfigInputfields()
 * method nor will it use a configuration php or json file. 
 * 
 * A module *must not* contain both the ConfigModule and ConfigurableModule interfaces 
 * in their implements definition at the same time, so choose just one. 
 * 
 *
 */
interface ConfigurableModule {

	/**********************************************************************************
	 * getModuleConfigInputfields method (static or non-static)
	 *
	 * Return an InputfieldWrapper of Inputfields used to configure the class. This may
	 * be specified either as a static method or a non-static method.
	 *
	 * Benefits of static version
	 * ===========================
	 * 1. The module does not need to be instantiated in order to configure it, which
	 *    means that unnecessary hooks won't get attached and unnecessary assets won't
	 *    be triggered to load.
	 * 2. It is supported by all versions of ProcessWire.
	 *
	 * Drawbacks of static version
	 * ===========================
	 * 1. You cannot pull config values directly from the module since it isn't
	 *    instantiated, and thus you must use the provided $data array. This $data array
	 *    only contains values if the module has been configured before.
	 * 2. You can't access $this or anything you'd typically pull from it, like API vars
	 *    or translation methods.
	 *
	 * Benefits of non-static version
	 * ==============================
	 * 1. You are working with the module in the same context that it is when running,
	 *    thus you can pull config values and API vars directly from $this->something.
	 * 2. It can be extended in descending classes.
	 * 3. The $data argument can be omitted, as you don't need it since all config
	 *    properties can be accessed directly from $this->[any property]. 
	 * 4. You can specify an optional $inputfields argument in your function definition
	 *    and if present, ProcessWire will prepare an InputfieldWrapper for you, saving
	 *    a step. When present, you can optionally omit the return statement at the 
	 *    bottom of the method as well. 
	 *
	 * Drawbacks of non-static version
	 * ================================
	 * 1. It is supported only in ProcessWire versions 2.5.27 or newer.
	 * 2. The module must be instantiated in order to configure it, so it may trigger
	 *    load of any used assets or attachment of any hooks unnecessarily.
	 *
	 * @param array $data Array of config values indexed by field name (static version only)
	 * 	Note that this array will be empty if the module has not been configured before.
	 * @return InputfieldWrapper
	 *
	 *  
	 * // static version
	 * public static function getModuleConfigInputfields(array $data); 
	 * 
	 * // non-static version
	 * public function getModuleConfigInputfields(); 
	 *  
	 * // non-static version with optional $data array, if you want it for some reason
	 * public function getModuleConfigInputfields(array $data); 
	 *  
	 * // non-static version with optional InputfieldWrapper as a convenience
	 * // note that the "return" statement may be omitted when using the $inputfields param.
	 * public function getModuleConfigInputfields($inputfields); 
	 * 
	 */

	/*********************************************************************************
	 * Return an array defining Inputfields (static or non-static)
	 * 
	 * You should use either getModuleConfigArray() or getModuleConfigInputfields(),
	 * do not use both, as ProcessWire will only recognize one or the other. Likewise,
	 * you should either use the static version of non-static version, not both. 
	 *
	 * See notes for getModuleConfigInputfields() above for benefits and drawbacks
	 * of static vs. non-static versions. The primary difference between this method
	 * and that method is that this one returns an array. The format of the array should
	 * be as shown in InputfieldWrapper::importArray (see InputfieldWrapper.php).
	 * 
	 * Whether static or non-static, your 'value' attributes in the array need only 
	 * represent the default values. ProcessWire will populate the actual values 
	 * to the resulting Inputfields after the method has been called. This is a benefit
	 * over the getModuleConfigInputfields() methods. 
	 *
	 * @return array
	 *
	 * public static function getModuleConfigArray(); // static version
	 * public function getModuleConfigArray(); // non-static version
	 */

	/**
	 * Get a module config property
	 *
	 * @param string $key
	 * @return mixed
	 *
	 */
	public function __get($key);

	/**
	 * Set a module config property
	 *
	 * @param $key
	 * @param $value
	 * @return mixed
	 *
	 */
	public function __set($key, $value);

	/**
	 * An optional method you may include in your ConfigurableModule to have ProcessWire
	 * send the configuration data to it rather than populating the properties individually.
	 *
	 * @param array $data Array of data in $key => $value format.
	 *
	 * public function setConfigData(array $data);
	 *
	 */

}

/**
 * ProcessWire ConfigModule interface
 * 
 * See notes about this interface and its differences in the ConfigurableModule documentation.
 * 
 * @since 3.0.179
 *
 */
interface ConfigModule {
	public function __get($key);
	public function __set($key, $value);
}