/wire/core/Module.php
PHP | 247 lines | 10 code | 20 blank | 217 comment | 0 complexity | 35e32601b4d26da5e02d37c1f1372101 MD5 | raw file
- <?php
- /**
- * ProcessWire Module Interface
- *
- * Provides the base interfaces required by modules.
- *
- * ProcessWire 2.x
- * Copyright (C) 2011 by Ryan Cramer
- * Licensed under GNU/GPL v2, see LICENSE.TXT
- *
- * http://www.processwire.com
- * http://www.ryancramer.com
- *
- */
- /**
- * ConfigurableModule is an interface that indicates the module is configurable by providing
- * a getModuleConfigInputfields method and config properties may be get/set directly like:
- *
- * $val = $obj->property, and $obj->property = $val
- *
- * 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().
- * See commented function reference in the interface below.
- *
- */
- interface ConfigurableModule {
- /**
- * Return an InputfieldsWrapper of Inputfields used to configure the class
- *
- * @param array $data Array of config values indexed by field name
- * @return InputfieldsWrapper
- *
- */
- public static function getModuleConfigInputfields(array $data);
- public function __get($key);
- 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);
- *
- */
-
- }
- /**
- * Base interface for all ProcessWire Modules
- *
- */
- interface Module {
- /**
- * Return an array of module information
- *
- * Example:
- *
- * public static function getModuleInfo() {
- * return array(
- * 'title' => 'Your Module's Title',
- * 'version' => 100,
- * 'author' => 'Ryan Cramer',
- * 'summary' => 'Description of what this module does and who made it.',
- * 'href' => 'http://www.domain.com/info/about/this/module/',
- * 'singular' => false,
- * 'autoload' => false,
- * 'requires' => array('HelloWorld', 'LazyCron'),
- * 'installs' => array('Module1', 'Module2', 'Module3'),
- * );
- * }
- *
- *
- * The retured array is associative with the following fields. Fields bulleted with a "+" are required and
- * fields bulleted with a "-" are optional, and fields bulleted with a "*" may be optional (see details):
- *
- * + title: The module's title.
- * + version: an integer that indicates the version number, 101 = 1.0.1
- * + summary: a summary of the module (1 sentence to 1 paragraph reommended)
- * - href: URL to more information about the module.
- * - requires: array of module class names that are required by this module in order to install.
- * If just one module is required, then it can also be a string with just the module name.
- * - installs: array of module class names that this module will handle install/uninstall.
- * This causes PW's dependency checker to ignore them and it is assumed your module will handle them (optional).
- * If your module does not handle them, PW will automatically install/uninstall them immediately after your module.
- * Like requires, this may be a string if there's only one and must be an array if multiple.
- * * singular: is only one instance of this module allowed? return boolean true or false.
- * If specified, this overrides the isSingular() method, if that method exists in your class.
- * See the information for the isSingular() method for more about the 'singular' property.
- * If you don't provide an isSingular() method, then you should provide this property here.
- * * autoload: should this module load automatically at application start? return boolean true or false.
- * If specified, this overrides the isAutoload() method, if that method exists in your class.
- * See the information for the isAutoload() method for more about the 'autoload' property.
- * If you don't provide an isAutoload() method, then you should provide this property here.
- * - permanent: boolean, for core only. True only if the module is permanent and uninstallable.
- * This is true only of PW core modules, so leave this out elsewhere.
- *
- * @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();
- */
- /**
- * Returns the class name of this Module instance
- *
- * 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.
- *
- * If you do want to implement this, then it can be just: "return get_class($this);"
- *
- * ProcessWire may sometimes substitute placeholders for a module that need to respond with the
- * non-placeholder classname. PHP's get_class won't work, which is why this method is used instead.
- * This method is only required for PW internal classes. As a result, implementation is optional for others.
- *
- public function className();
- */
- /**
- * 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();
- */
- /**
- * Is this module intended to be only a single instance?
- *
- * This method is OPTIONAL and therefore commented out in this interface. If ommitted, it is assumed that
- * you are providing this inforamtion in the getModuleInfo() method, documented above.
- *
- * 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.
- *
- * Why you'd use this method over the property in the getModuleInfo() method:
- * Using this method is useful if you have multiple descending classes that you want to provide a default
- * value for, rather than having each descending class specify it individually in the getModuleInfo().
- * For example, Fieldtype or Inputfield modules.
- *
- *
- * 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 Inputfields) 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'.
- *
- * @return bool
- *
- * This method may be optional, which is why it's commented out below.
- *
- public function isSingular();
- */
- /**
- * Is this module automatically loaded at runtime?
- *
- * This method is OPTIONAL and therefore commented out in this interface. If ommitted, it is assumed that
- * you are providing this information in the getModuleInfo() method.
- *
- * 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 [and it's init() method called] at runtime.
- * Return FALSE if this module must be requested [via the $modules->get('ModuleName') method] before it is loaded.
- *
- * Modules that are intended to attach hooks in the application typically should be autoloaded 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 autoloaded are those that may or may not be needed at runtime, for example
- * Fieldtypes and Inputfields.
- *
- * 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).
- *
- * Why you'd use this method over the property in the getModuleInfo() method:
- * Using this method is useful if you have multiple descending classes that you want to provide a default
- * value for, rather than having each descending class specify it individually in the getModuleInfo().
- * For example, Fieldtype or Inputfield modules.
- *
- *
- * @return bool
- *
- * This method may be optional, which is why it's commented out below.
- *
- public function isAutoload();
- */
- }