artabro/wire/core/Module.php

<?php namespace ProcessWire;

/**
 * ProcessWire Module Interface
 *
 * Provides the base interfaces required by modules.
 * 
 * ProcessWire 3.x, Copyright 2018 by Ryan Cramer
 * https://processwire.com
 * 
 * #pw-summary Module is the primary PHP interface for module types in ProcessWire. 
 * #pw-body = 
 * The Module interface doesn't actually require any specific methods,
 * (other than the `className()` method) but is required as an interface 
 * to state your intention to ProcessWire that your class is to be used 
 * as a Module. As a result, all methods are optional, but including the 
 * Module interface is not. You must also provide a means by which ProcessWire
 * can query information about your module. More on that below. 
 * 
 * ### Implementing the Module interface
 * 
 * Below is how you indicate a PHP class is a ProcessWire Module:
 * 
 * ~~~~~
 * <?php namespace ProcessWire;
 * class HelloWorld extends WireData implements Module { 
 *   // your class implementation
 * }
 * ~~~~~
 * 
 * Modules should either extend the `WireData` class, or if they are a 
 * predefined type already recognized by ProcessWire, they should extend 
 * the base class of that type (or another module based upon it). Base 
 * module types include:
 *
 * - `AdminTheme`
 * - `Fieldtype`
 * - `FileCompilerModule`
 * - `FileValidatorModule`
 * - `Inputfield`
 * - `ModuleJS`
 * - `PageAction`
 * - `Process`
 * - `Textformatter`
 * - `WireAction`
 * - `WireMail`
 * - `WireSessionHandler`
 * 
 * ### Requirements for Modules
 * 
 * 1. Must provide a means of getting information about the module.
 *    This can be with a static `getModuleInfo()` method, or with
 *    a `ModuleName.info.php` file or a `ModuleName.info.json` file. 
 * 
 * 2. Must provide a `className()` method that returns the module 
 *    class name. All Wire derived objects already do this, so 
 *    you don't have to provide it unless your Module does not
 *    descend from a ProcessWire class. We recommend that your
 *    modules extend the Wire or WireData class. 
 * 
 * 3. If you have a `__construct()` method, it must not require any
 *    particular arguments. 
 * 
 * 4. If your module is configurable, it must also fulfill the
 *    `ConfigurableModule` interface. 
 * 
 * ### Optional methods 
 * 
 * - `__construct()` - Called before module config is populated.
 * 
 * - `init()` - Called after module config is populated.
 * 
 * - `ready()` - Called after init(), after API ready. Note that ready() applies to 'autoload' modules only. 
 * 
 * - `install()` - Called when module is installed. 
 * 
 * - `uninstall()` - Called when module is uninstalled. 
 * 
 * - `upgrade($fromVersion, $toVersion)` - Called on version change.
 * 
 * - `isAutoload()` - Returns a boolean indicating whether the module should be loaded at boot. 
 *   Can also be specified as a property in module information.
 * 
 * - `isSingular()` - Returns a boolean indicating whether the module is limited to one instance or not. 
 *   Can also be specified as a property in module information.
 * 
 * - `getModuleInfo()` - A static method that returns an array of module information. 
 * 
 * These methods are outlined in more detail further down on this page. 
 * 
 * -----------------------------------------------------------------
 * 
 * ## Module Information
 * 
 * Modules must have some way to communicate information about 
 * themselves to ProcessWire. This is done by providing an 
 * associative array containing this module information. One
 * of the following implementations is required: 
 * 
 * 1. `getModuleInfo()` static method in your module class that returns an array.
 * 2. `YourModuleClass.info.php` file that populates an `$info` array.
 * 3. `YourModuleClass.info.json` file that contains an `info` object.
 *   
 * Each of these are demonstrated below:
 *  
 * **1) Static getModuleInfo() method:**
 * ~~~~~
 * public static function getModuleInfo() {
 *   return array(
 *     'title' => 'Your Module Title',
 *     'version' => 1,
 *     'author' => 'Your Name',
 *     'summary' => 'Description of what this module does and who made it.',
 *     'href' => 'http://www.domain.com/info/about/this/module/',
 *     'autoload' => false, // set to true if module should auto-load at boot
 *     'requires' => array(
 *        'HelloWorld>=1.0.1', 
 *        'PHP>=5.4.1', 
 *        'ProcessWire>=2.4.1'
 *     ),
 *     'installs' => array('Module1', 'Module2', 'Module3'),
 *     );
 * }
 * ~~~~~
 *
 * **2) YourModuleClass.info.php file:**  
 * Your file should populate an `$info` variable with an array exactly like 
 * described for #1 above, i.e.
 * 
 * ~~~~~
 * $info = array(
 *   'title' => 'Your Module Title',
 *   'version' => 1,
 *   // and so on, like the static version above
 * );
 * ~~~~~
 *
 * **3) YourModuleClass.info.json file:**  
 * Your JSON file should contain nothing but an object/map of the module info:
 * 
 * ~~~~~
 * {
 *   "title": "Your Module Title",
 *   "version": 1
 * }
 * ~~~~~
 * Note: The example JSON above just shows "title" and "version", but you would
 * likely add more than that as needed, like shown in the static version above. 
 * 
 * -----------------------------------------------------------------
 *
 * ## Module information properties
 * 
 * ### Required info properties
 *
 * - `title` (string): The module's title.
 * 
 * - `version` (int|string): An integer or string that indicates the version number.
 * 
 * - `summary` (string): Summary text of the module (1 sentence recommended).
 * 
 * ### Optional info properties
 * 
 * - `href` (string): URL to more information about the module.
 * 
 * - `requires` (array|string): Array or CSV string of module class names that are required by this 
 *    module in order to install.
 * 
 *    - **Requires Module version:** If a particular version of the module is required, then specify an operator
 *		and version number after the module name, like this: "HelloWorld>=1.0.1". 
 * 
 *    - **Requires PHP version:** If a particular version of PHP is required, then specify "PHP" as the module name
 *		followed by an operator and required version number, like this: "PHP>=5.6.0". 
 * 
 *    - **Requires ProcessWire version:** If a particular version of ProcessWire is required, then specify
 *		ProcessWire followed by an operator and required version number, like this: "ProcessWire>=2.4.1". 
 * 
 * - `installs` (array|string): Array or CSV string of module class names that this module will handle install 
 *    and uninstall for.
 *    This causes ProcessWire's dependency checker to ignore them and it is assumed your module will handle 
 *    them. If your module does not handle them, ProcessWire will automatically install/uninstall them 
 *    immediately after your module.
 * 
 * - `permanent` (boolean): This property is intended for only for core modules. When true, a module cannot be uninstalled.
 * 
 * - `permission` (string): Name of permission required of a user before ProcessWire will load the module (for non-superusers).
 *    Note that ProcessWire will not install this permission if it doesn't yet exist. To have it installed automatically,
 *    see the _permissions_ option below this.
 * 
 * - `permissions` (array): Array of permissions that ProcessWire will install (and uninstall) automatically.
 *    Permissions should be in the format: array('permission-name' => 'Permission description'). 
 * 
 * - `icon` (string): Optional icon name to represent this module.
 *    Currently uses [font-awesome](http://fortawesome.github.io/Font-Awesome/) icon names.
 *    Omit the "fa-" part, leaving just the icon name.
 * 
 * - `singular` (boolean): Is only one instance of this module allowed? (default=auto-detect).
 *    This is good for any module that you want to eliminate the possibility of multiple instances
 *    running at once. For instance, modules that become API variables are typically singular, whereas
 *    something like an Inputfield module would not be singular. When not specified, modules that extend an 
 *    existing base type typically inherit the singular setting from the module they extend. 
 * 
 * - `autoload` (boolean|string|callable|int): Should this module load automatically at boot? (default=false).
 *    This is good for modules that attach hooks or that need to otherwise load on every single
 *    request. Autoload is typically specified as a boolean true or false. Below are the different ways
 *    autoload can be specified: 
 * 
 *    - **Boolean:** Specify true or false to indicate the module should either always autoload (true) 
 *      or never autoload (false). 
 * 
 *    - **Selector string:** The module will be automatically loaded only if the current page matches the
 *      selector string. For example, a selector string of `template=admin` would mean the module will
 *      only autoload in the admin side of ProcessWire. 
 * 
 *    - **Callable function:** The module will automatically load only if the given callable function 
 *      returns true. 
 * 
 *    - **Integer:** If given integer 2 or higher, it will autoload the module before other autoload
 *      modules (in /site/modules/). Higher numbers autoload before lower numbers. 
 * 
 * - `searchable` (string): When present, indicates that module implements a search() method 
 *    consistent with the SearchableModule interface. The value of the 'searchable' property should 
 *    be the name that the search results are referred to, using ascii characters of a-z, 0-9, and
 *    underscore. See the SearchableModule interface in this file for more details. 
 * 
 * -----------------------------------------------------------------------------------------------
 * 
 * ## Module Methods
 * 
 * ### __construct()
 * 
 * This method is called by PHP immediately when the module is instantiated, and before any 
 * configuration data has been populated to the module. This method must not have any required
 * arguments. This method is a good place for populating default configuration values or any
 * other initialization you want to occur before ProcessWire sees it or populates anything to it.
 * Your construct method should not assume that the module will actually be executed, as 
 * ProcessWire may instantiate a module for informational reasons. 
 * 
 * ### init()
 * 
 * This method is called after `__construct()` and after any configuration data has been populated
 * to the module. It is called before the module is handed over to the requester. This is a good
 * place to perform any initialization that requires configuration data and can be a good place to 
 * attach hooks. 
 * 
 * ### ready()
 * 
 * This method is used only by _autoload_ modules. It is called when the entire ProcessWire API
 * is ready to use. This may be preferable to the `init()` method for autoload modules because 
 * they are loaded and init()'d at boot, when everything else is loading too. The ready() method
 * is called once the boot has completed and all API variables are ready to use, but before any
 * page has been rendered. This makes it an excellent place to attach hooks. 
 * 
 * ### isSingular()
 *
 * Indicates whether only one instance of a module is allowed to exist in memory. 
 * If this method is not present, it will be auto-determined based on module type. If it is provided
 * in the module information array (discussed above) that will override this method. 
 * 
 * This method exists primarily so that base module types may specify a singular state and have it 
 * automatically inherit to any modules extending the type. If you are not extending a base module
 * type then you can implement this method, or you can provide it in your module info array. 
 *
 * A module that returns TRUE is referred to as a "singular" module, because there will never be any more
 * than a single instance of the module running.
 *
 * Return TRUE if this module is a single reusable instance, returning the same instance on every 
 * call from Modules. Return FALSE if this module should return a new instance on every call from Modules.
 *
 * - Singular modules will have their instance active for the entire request after instantiated.
 * - Non-singular modules return a new instance on every `$modules->get("YourModule")` call.
 * - Modules that attach hooks are usually singular.
 * - Modules that may have multiple instances (like `Inputfield` modules) should _not_be singular.
 *
 * If you are having trouble deciding whether to make your module singular or not, be sure to read 
 * the documentation below for the `isAutoload()` method, because if your module is 'autoload' then 
 * it's probably also 'singular'.
 * 
 * ### isAutoload()
 * 
 * Should this module be automatically loaded at boot?
 * If this method is not present, it will be auto-determined based on module type. If it is provided
 * in the module information array (discussed above) that will override this method.
 *
 * This method exists primarily so that base module types may specify an autoload state and have it
 * automatically inherit to any modules extending the type. If you are not extending a base module
 * type then you can implement this method, or you can provide it in your module info array. 
 *  
 * A module that returns TRUE is referred to as an "autoload" module, because it automatically loads as
 * part of ProcessWire's boot process. Autoload modules load before PW attempts to handle the web request.
 *  
 * Return TRUE if this module is automatically loaded at runtime.
 * Return FALSE if this module must be requested via `$modules->get('ModuleName')` method before it is loaded.
 *  
 * Modules that are intended to attach hooks in the application typically should be autoload because
 * they listen in to classes rather than have classes call upon them. If they weren't autoloaded, then
 * they might never get to attach their hooks.
 *  
 * Modules that shouldn't be autoload are those that may or may not be needed at runtime, for example
 * `Fieldtype` and `Inputfield` modules.
 *  
 * _As a side note, I can't think of any reason why a non-singular module would ever be autoload. The fact that
 * an autoload module is automatically loaded as part of PW's boot process implies it's probably going to be the
 * only instance running. So if you've decided to make your module 'autoload', then is safe to assume you've
 * also decided your module will also be singular (if that helps anyone reading this)._
 * 
 * ### install()
 * 
 * This method is called when the module is first installed. If implemented, install() methods typically are
 * defined hookable as `public function ___install()`. 
 * 
 * The method should prepare the environment with anything else needed by the module, such as newly created 
 * fields, pages, templates, etc. or installation of other modules. 
 * 
 * If the install() method determines that the module cannot be installed for some reason, it should 
 * throw a `WireException.` 
 * 
 * ### uninstall()
 * 
 * This method is called when the module is uninstalled. If implemented, uninstall() methods typically are
 * defined hookable as `public function ___uninstall()`. 
 * 
 * This method should undo everything done by the install() method, or undo anything created by the module,
 * restoring the system back to the state that it was in before the module was installed. 
 * 
 * If the uninstall() method determines that it cannot proceed for some reason, it should throw 
 * a `WireException`. 
 * 
 * ### upgrade($fromVersion, $toVersion)
 * 
 * This method is called when a version change is detected. This method should make any adjustments needed
 * to support the module from one version to another. The previous known version ($fromVersion) and new
 * version ($toVersion) are provided as arguments.
 * 
 * If implemented, upgrade() methods typically are defined hookable as `public function ___upgrade(...)`. 
 * If the upgrade cannot proceed for some reason, this method should throw a `WireException`. 
 * 
 * 
 * 
 *
 * #pw-body
 * 
 * The following methods may or may not be implemented, all are optional:
 * 
 * #pw-method void install() Called when module is installed. 
 * #pw-method void uninstall() Called when module is uninstalled. 
 * #pw-method void upgrade($fromVersion, $toVersion) Called when a version change is detected for the module. 
 * #pw-method array getModuleInfo() Static method that returns array of module info (not required if module implements an info file instead). 
 * #pw-method void init() Called when the module is loaded, immediately after any configuration data has been populated to it. 
 * #pw-method void ready() For autoload modules only, called when the ProcessWire API is ready to use. 
 * #pw-method void setConfigData(array $data) Modules may optionally provide this method to receive config data from ProcessWire.
 * #pw-method bool isSingular() #pw-internal
 * #pw-method bool isAutoload() #pw-internal
 * 
 *
 */

interface Module {

	/**
	 * Return an array of module information
	 * 
	 * @return array
	 *
	 * public static function getModuleInfo(); 
	 * 
	 */

	/**
	 * Method to initialize the module. 
	 *
	 * While the method is required, if you don't need it, then just leave the implementation blank.
	 *
	 * This is called after ProcessWire's API is fully ready for use and hooks. It is called at the end of the 
	 * bootstrap process. This is before PW has started retrieving or rendering a page. If you need to have the
	 * API ready with the $page ready as well, then see the ready() method below this one. 
	 *
	 * public function init();
	 * 
	 */

	/**
	 * Method called when API is fully ready and the $page is determined and set, but before a page is rendered.
	 *
	 * Optional and only called if it exists in the module. 
	 *
	 * public function ready();
	 * 
	 */

	/**
	 * Return this object’s class name
	 * 
	 * If your Module descends from Wire, or any of it's derivatives (as would usually be the case),
	 * then you don't need to implement this method as it's already present. 
	 *
	 * @param array|bool|null $options Optionally an option or boolean for 'namespace' option:
	 * - `lowercase` (bool): Specify true to make it return hyphenated lowercase version of class name
	 * - `namespace` (bool): Specify false to omit namespace from returned class name. Default=true.
	 * - Note: when lowercase=true option is specified, the namespace=false option is required.
	 * @return string
	 * @see Wire::className()
	 *
	 */
	public function className($options = null);

	/**
	 * Perform any installation procedures specific to this module, if needed. 
	 *
	 * The Modules class calls this install method right after performing the install. 
	 * 
	 * If this method throws an exception, PW will catch it, remove it from the installed module list, and
	 * report that the module installation failed. You may specify details about why with the exception, i.e.
	 * throw new WireException("Can't install because of ..."); 
	 *
	 * This method is OPTIONAL, which is why it's commented out below. 
	 *
	 * public function ___install();
	 * 
	 */

	/**
	 * Perform any uninstall procedures specific to this module, if needed. 
	 *
	 * It calls this uninstall method right before completing the uninstall. 
	 *
	 * This method is OPTIONAL, which is why it's commented out below. 
	 *
	 * public function ___uninstall();
	 * 
	 */
	
	/**
	 * Called when a version change is detected on the module
	 * 
	 * public function ___upgrade($fromVersion, $toVersion);
	 * 
	 */ 

	/**
	 * Is this module intended to be only a single instance?
	 *
	 * @return bool
	 * 
	 * public function isSingular();
	 * 
	 */

	/**
	 * Is this module automatically loaded at runtime?
	 * 
	 * @return bool
	 *	
	 * public function isAutoload(); 
	 * 
	 */ 
}

/**
 * Standard module interface with all methods. 
 * 
 * This interface is not intended to be used for anything other than for code hinting purposes. 
 *
 */
interface _Module {
	
	public function install();
	public function uninstall();
	public function upgrade($fromVersion, $toVersion);
	
	/** @return array */
	public static function getModuleInfo();
	
	public function init();
	
	public function ready();
	
	public function setConfigData(array $data);
	
	/** @return bool */
	public function isSingular();
	
	/** @return bool */
	public function isAutoload();

	/**
	 * @param InputfieldWrapper|array|null $data
	 * @return InputfieldWrapper
	 * 
	 */
	public function getModuleConfigInputfields($data = null);

	/**
	 * @return array
	 * 
	 */
	public function getModuleConfigArray();
}

/**
 * Interface SearchableModule
 *
 * Interface for modules that implement a method and expected array return value
 * for completing basic text searches (primarily for admin search engine).
 * 
 * It is optional to add this interface to "implements" section of the module class definition.
 * However, you must specify a "searchable: name" property in your getModuleInfo() method in 
 * order for ProcessWire to recognize the module is searchable. See below for more info:
 *
 * ~~~~~~
 * public static function getModuleInfo() {
 *   return array(
 *     'searchable' => 'name', 
 * 
 *     // You'll need the above 'searchable' property returned by your getModuleInfo(). 
 *     // The value of 'name' should be the name by which search results should be referred to	
 *     // if the user wants to limit the search to this module. For instance, if your module 
 *     // was called “ProcessWidgets”, you’d probably choose the name “widgets” for this. 
 *     // If the module represents an API variable, the name should be the same as the API variable. 
 *     // ...
 *   );
 * }
 * ~~~~~
 * 
 */
interface SearchableModule {

	/**
	 * Search for items containing $text and return an array representation of them
	 * 
	 * You may also implement this method as hookable, i.e. ___search(), but note that you’ll
	 * want to skip the "implements SearchableModule" in your class definition. 
	 *
	 * Must return PHP array in the format below. For each item in the 'items' array, Only the 'title' 
	 * and 'url' properties are required for each item (the rest are optional). 
	 *
	 * $result = array(
	 *   'title' => 'Title of these items',
	 *   'total' => 999, // total number of items found, or omit if pagination not supported or active
	 *   'url' => '', // optional URL to view all items, or omit for a PW-generated one
	 *   'properties' => array(), // optional list of supported search properties, only looked for if $options['info'] === true;
	 *   'items' => array(
	 *     [0] => array(
	 *       'id' => 123, // Unique ID of item (optional)
	 *       'name' => 'Name of item', // (optional)
	 *       'title' => 'Title of item', // (*required)
	 *       'subtitle' => 'Secondary/subtitle of item',  // (optional)
	 *       'summary' => 'Summary or description of item', // (optional)
	 *       'url' => 'URL to view or edit the item', // (*required)
	 *       'icon' => 'Optional icon name to represent the item, i.e. "gear" or "fa-gear"', // (optional)
	 *       'group' => 'Optionally group with other items having this group name, overrides $result[title]', // (optional)
	 *       'status' => int, // refers to Page status, omit if not a Page item (optional)
	 *       'modified' => int, // modified date of item as unix timestamp (optional)
	 *     [1] => array(
	 *       ...
	 *     ),
	 *   ),
	 * );
	 *
	 * PLEASE NOTE:  
	 * When ProcessWire calls this method, if the module is not already loaded (autoload), 
	 * it instantiates the module but DOES NOT call the init() or ready() methods. That’s because the 
	 * search method is generally self contained. If you need either of those methods to be called,
	 * and your module is not autoload, you should call the method(s) from your search() method.
	 * 
	 * About the optional “properties” index:
	 * If ProcessWire calls your search() method with $options['info'] == true; then it is likely wanting to see
	 * what properties are available for search. For instance, properties for a Module search might be: 
	 * [ 'name', 'title', 'summary' ]. Implementation of the properties index is optional, and for PW’s informational
	 * purposes only. 
	 * 
	 * @param string $text Text to search for
	 * @param array $options Options array provided to search() calls: 
	 *  - `edit` (bool): True if any 'url' returned should be to edit rather than view items, where access allows. (default=true)
	 *  - `multilang` (bool): If true, search all languages rather than just current (default=true).
	 *  - `start` (int): Start index (0-based), if pagination active (default=0).
	 *  - `limit` (int): Limit to this many items, or 0 for no limit. (default=0).
	 *  - `type` (string): If search should only be of a specific type, i.e. "pages", "modules", etc. then it is 
	 *     specified here. This corresponds with the getModuleInfo()['searchable'] name or item 'group' property. 
	 *     Note that ProcessWire won’t call your search() method if the type cannot match this search. 
	 *  - `operator` (string): Selector operator type requested, if more than one is supported (default is %=).
	 *  - `property` (string): If search should limit to a particular property/field, it is named here. 
	 *  - `verbose` (bool): True if output can optionally be more verbose, false if not. (default=false)
	 *  - `debug` (bool): True if DEBUG option was specified in query. (default=false)
	 *  - `help` (bool): True if we are just querying for help/info and are not using the search results. (default=false)
	 * @return array
	 *
	 */
	public function search($text, array $options = array()); 
}