Subversion Repositories web.active

<?php namespace ProcessWire;

/**
 * ProcessWire Interfaces
 *
 * Interfaces used throughout ProcessWire's core.
 * 
 * This file is licensed under the MIT license
 * https://processwire.com/about/license/mit/
 * 
 * ProcessWire 3.x, Copyright 2016 by Ryan Cramer
 * https://processwire.com
 *
 */

/** 
 * For classes that are saved to a database or disk.
 *
 * Item must have a gettable/settable 'id' property for this interface as well
 * 
 * @property int $id
 * @property string $name
 *
 */
interface Saveable {

    /**
     * Save the object's current state to database.
     *
     */
    public function save(); 

    /**
     * Get an array of this item's saveable data, should match exact with the table it saves in
     * 
     * @return array
     *
     */
    public function getTableData();

}

/**
 * For classes that may have their data exported to an array 
 * 
 * Classes implementing this interface are also assumed to be able to accept the same 
 * 
 * 
 */ 
interface Exportable {
    
    /**
     * Return export data (may be the same as getTableData from Saveable interface)
     *
     * @return array
     *
     */
    public function getExportData();

    /**
     * Given an export data array, import it back to the class and return what happened
     * 
     * @param array $data
     * @return array Returns array(
     *  [property_name] => array(
     *      'old' => 'old value',   // old value, always a string
     *      'new' => 'new value',   // new value, always a string
     *      'error' => 'error message or blank if no error'
     *  )
     * 
     */
    public function setImportData(array $data);

}


/**
 * Class HasRoles
 * 
 * @deprecated
 * 
 */
interface HasRoles {
    // To be deleted
}


/**
 * For classes that contain lookup items, as used by WireSaveableItemsLookup
 *
 */
interface HasLookupItems {

    /**
     * Get all lookup items, usually in a WireArray derived type, but specified by class
     *
     */
    public function getLookupItems(); 

    /**
     * Add a lookup item to this instance
     *
     * @param int $item The ID of the item to add 
     * @param array $row The row from which it was retrieved (in case you want to retrieve or modify other details)
     *
     */
    public function addLookupItem($item, array &$row); 
    
}


/**
 * For classes that need to track changes made by other objects. 
 *
 */
interface WireTrackable {

    /**
     * Turn change tracking ON or OFF
     *
     * @param bool|int $trackChanges True to turn on, false to turn off. Integer to specify bitmask.
     * @return $this
     *
     */
    public function setTrackChanges($trackChanges = true);

    /**
     * Track a change to a property in this object
     *
     * The change will only be recorded if self::$trackChanges is true.
     *
     * @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);

    /**
     * Has the given property changed?
     *
     * Applicable only for properties you are tracking while $trackChanges is true.
     *
     * @param string $what Name of property, or if left blank, check if any properties have changed.
     * @return bool
     *
     */ 
    public function isChanged($what = ''); 

    /**
     * Return an array of properties that have changed while change tracking was on.
     *
     * @param bool $getValues If true, then an associative array will be retuned with field names and previous values.
     * @return array
     *
     */
    public function getChanges($getValues = false);

}


/**
 * Indicates that a given Fieldtype may be used for page titles
 *
 */
interface FieldtypePageTitleCompatible { }

/**
 * Indicates Fieldtype manages files
 *
 */
interface FieldtypeHasFiles {
    /**
     * Whether or not given Page/Field has any files connected with it
     * 
     * @param Page $page
     * @param Field $field
     * @return bool
     * 
     */
    public function hasFiles(Page $page, Field $field);
    
    /**
     * Get array of full path/file for all files managed by given page and field
     * 
     * @param Page $page
     * @param Field $field
     * @return array
     * 
     */
    public function getFiles(Page $page, Field $field);

    /**
     * Get path where files are (or would be) stored
     * 
     * @param Page $page
     * @param Field $field
     * @return string
     * 
     */
    public function getFilesPath(Page $page, Field $field); 
}


/**
 * Indicates that an Inputfield provides tree selection capabilities
 *
 * In such Inputfields a parent_id refers to the root of the tree rather than an immediate parent.
 *
 */
interface InputfieldPageListSelection { }

/**
 * Indicates that an Inputfield renders a list of items
 *
 */
interface InputfieldItemList { }

/**
 * Interface that indicates a class contains gettext() like translation methods 
 *
 */
interface WireTranslatable {
    /**
     * 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.
     *
     * @param string $text Text string to translate
     * @return string
     *
     */
    public function _($text);

    /**
     * Perform a language translation in a specific context
     *
     * Used when to text strings might be the same in English, but different in other languages.
     *
     * @param string $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);

    /**
     * Perform a language translation with singular and plural versions
     *
     * @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);
}


/**
 * Interface that indicates the required methods for a class to be hookable.
 * 
 * @deprecated
 * 
 */
interface WireHookable { }

/**
 * Interface that indicates a class supports API variable dependency injection and retrieval
 * 
 */
interface WireFuelable {
    
    /**
     * Get or inject a ProcessWire API variable or fuel a new object instance
     *
     * See Wire::wire() for explanation of all options. 
     *
     * @param string|WireFuelable $name Name of API variable to retrieve, set, or omit to retrieve entire Fuel 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 mixed|Fuel
     * @throws WireException
     *
     */
    public function wire($name = '', $value = null, $lock = false);

    /**
     * Set the ProcessWire instance
     * 
     * @param ProcessWire $wire
     * 
     */
    public function setWire(ProcessWire $wire);

    /**
     * Get the ProcessWire instance
     * 
     * @return ProcessWire
     * 
     */
    public function getWire(); 
    
}

/**
 * Interface that indicates the class supports Notice messaging
 * 
 */
interface WireNoticeable {
    /**
     * Record an informational or 'success' message in the system-wide notices.
     *
     * This method automatically identifies the message as coming from this class.
     *
     * @param string $text
     * @param int $flags See Notices::flags
     * @return $this
     *
     */
    public function message($text, $flags = 0);

    /**
     * Record an non-fatal error message in the system-wide notices.
     *
     * This method automatically identifies the error as coming from this class.
     *
     * Fatal errors should still throw a WireException (or class derived from it)
     *
     * @param string $text
     * @param int $flags See Notices::flags
     * @return $this
     *
     */
    public function error($text, $flags = 0);
}

/**
 * Interface for ProcessWire database layer
 * 
 */

interface WireDatabase {
    /**
     * Is the given string a database comparison operator?
     *
     * @param string $str 1-2 character opreator to test
     * @return bool
     *
     */
    public function isOperator($str);
}

/**
 * Interface for Process modules that can edit pages (ProcessPageEdit being the most obvious)
 *
 */
interface WirePageEditor {
    /**
     * @return Page The current page being edited
     */
    public function getPage();  
}

/**
 * Interface shared by all ProcessWire Null objects
 *
 */
interface WireNull { }

/**
 * Interface that indicates the object supports its items being paginated
 * 
 */
interface WirePaginatable {
    
    /**
     * Set the total number of items, if more than are in the WireArray.
     *
     * @param int $total
     * @return $this
     *
     */
    public function setTotal($total);

    /**
     * Get the total number of items in all paginations of the WireArray.
     * 
     * If no limit used, this returns total number of items currently in the WireArray.
     *
     * @return int
     *
     */
    public function getTotal();
    
    /**
     * Set the limit that was used in pagination.
     *
     * @param int $numLimit
     * @return $this
     *
     */
    public function setLimit($numLimit);

    /**
     * Get the limit that was used in pagination.
     *
     * If no limit set, then return number of items currently in this WireArray.
     *
     * @return int
     *
     */
    public function getLimit();

    /**
     * Set the starting offset that was used for pagination.
     *
     * @param int $numStart;
     * @return $this
     *
     */
    public function setStart($numStart);
    
    /**
     * Get the starting offset that was used for pagination.
     *
     * @return int
     *
     */
    public function getStart();

}

/**
 * Interface WireMatchable
 * 
 * Interface for objects that provide their own matches() method for matching selector strings
 * 
 */
interface WireMatchable {
    
    /**
     * Does this object match the given Selectors object or string?
     * 
     * @param Selectors|string $s
     * @return bool
     * 
     */
    public function matches($s); 
}

/**
 * Interface LanguagesValueInterface
 * 
 * Interface for multi-language fields
 * 
 */
interface LanguagesValueInterface {

    /**
     * Sets the value for a given language
     *
     * @param int|Language $languageID
     * @param mixed $value
     *
     */
    public function setLanguageValue($languageID, $value);

    /**
     * Given a language, returns the value in that language
     *
     * @param Language|int
     * @return int
     *
     */
    public function getLanguageValue($languageID);

    /**
     * Given an Inputfield with multi language values, this grabs and populates the language values from it
     *
     * @param Inputfield $inputfield
     *
     */
    public function setFromInputfield(Inputfield $inputfield);

}

/**
 * Interface used to indicate that the Fieldtype supports multiple languages
 *
 */
interface FieldtypeLanguageInterface {
    /*
     * This interface is symbolic only and doesn't require any additional methods, 
     * however you do need to add an 'implements FieldtypeLanguageInterface' when defining your class. 
     * 
     */
}

/**
 * Interface for objects that carry a Field value for a Page
 * 
 * Optional, but enables Page to do some of the work rather than the Fieldtype
 *
 */
interface PageFieldValueInterface {
    
    /**
     * Get or set formatted state
     * 
     * @param bool|null $set Specify bool to set formatted state or omit to retrieve formatted state
     * @return bool
     * 
     */
    public function formatted($set = null);

    /**
     * Set the Page
     * 
     * @param Page $page
     * 
     */
    public function setPage(Page $page);

    /**
     * Set the Field
     * 
     * @param Field $field
     * 
     */
    public function setField(Field $field);

    /**
     * Get the page or null if not set
     * 
     * @return Page|null
     * 
     */
    public function getPage();

    /**
     * Get the field or null if not set
     * 
     * @return Field|null
     * 
     */
    public function getField();
}

/**
 * Interface for tracking runtime events
 *
 */
interface WireProfilerInterface {
    
    /**
     * Start profiling an event
     * 
     * Return the event array to be used for stop profiling
     * 
     * @param string $name Name of event in format "method" or "method.id" or "something"
     * @param Wire|object|string|null Source of event (may be object instance)
     * @param array $data
     * @return mixed Event to be used for stop call
     * 
     */
    public function start($name, $source = null, $data = array()); 

    /**
     * Stop profiling an event
     * 
     * @param array|object|string $event Event returned by start() 
     * @return void
     * 
     */
    public function stop($event);

    /**
     * End of request maintenance
     * 
     * @return void
     * 
     */
    public function maintenance();
}

/**
 * Inputfields that implement this interface always have a $value attribute that is an array
 *
 */
interface InputfieldHasArrayValue { }

/**
 * Inputfield that doesn’t have an array value by default but can return array value or accept it
 * 
 * @since 3.0.176
 *
 */
interface InputfieldSupportsArrayValue {
    /**
     * @return array
     * 
     */
    public function getArrayValue();

    /**
     * @param array $value
     * 
     */
    public function setArrayValue(array $value);
}

/**
 * Inputfield that supports a Page selector for selectable options
 *
 * @since 3.0.176
 *
 */
interface InputfieldSupportsPageSelector {
    /**
     * Set page selector or test if feature is disabledd
     * 
     * @param string $selector Selector string or blank string when testing if feature is disabled
     * @return bool Return boolean false if feature disabled, otherwise boolean true
     * 
     */
    public function setPageSelector($selector);
}

/**
 * Inputfield that has a text value by default
 * 
 * @since 3.0.176
 * 
 */
interface InputfieldHasTextValue { }

/**
 * Inputfield that has a sortable value (usually in addition to InputfieldHasArrayValue)
 *
 */
interface InputfieldHasSortableValue { }

/**
 * Inputfield that supports selectable options
 * 
 * @since 3.0.176
 *
 */
interface InputfieldHasSelectableOptions {
    /**
     * Add a selectable option
     * 
     * @param string|int $value
     * @param string|null $label
     * @param array|null $attributes
     * @return self|$this
     * 
     */
    public function addOption($value, $label = null, array $attributes = null);
    
    /**
     * Add selectable option with label, optionally for specific language
     *
     * @param string|int $value
     * @param string $label
     * @param Language|null $language
     * @return self|$this
     *
     */
    public function addOptionLabel($value, $label, $language = null);
}