diff options
31 files changed, 640 insertions, 527 deletions
diff --git a/core/API/Request.php b/core/API/Request.php index 76ee0791be..4edc821465 100644 --- a/core/API/Request.php +++ b/core/API/Request.php @@ -25,14 +25,24 @@ use Piwik\UrlHelper; * * The Request class is used throughout Piwik to call API methods. The difference * between using Request and calling API methods directly is that Request - * will do more after calling the API including: apply generic filters, apply queued filters, - * and handle the **flat** and **label** query parameters. + * will do more after calling the API including: applying generic filters, applying queued filters, + * and handling the **flat** and **label** query parameters. * * Additionally, the Request class will **forward current query parameters** to the request * which is more convenient than calling {@link Piwik\Common::getRequestVar()} many times over. * - * In most cases, using a Request object to query the API is the right way to go. + * In most cases, using a Request object to query the API is the correct approach. * + * ### Post-processing + * + * The return value of API methods undergo some extra processing before being returned by Request. + * To learn more about what happens to API results, read [this](/guides/piwiks-web-api#extra-report-processing). + * + * ### Output Formats + * + * The value returned by Request will be serialized to a certain format before being returned. + * To see the list of supported output formats, read [this](/guides/piwiks-web-api#output-formats). + * * ### Examples * * **Basic Usage** @@ -44,14 +54,15 @@ use Piwik\UrlHelper; * * **Getting a unrendered DataTable** * - * // use convenience the convenience method 'processRequest' + * // use the convenience method 'processRequest' * $dataTable = Request::processRequest('UserSettings.getWideScreen', array( * 'idSite' => 1, * 'date' => 'yesterday', * 'period' => 'week', - * 'format' => 'original', // this is the important bit * 'filter_limit' => 5, * 'filter_offset' => 0 + * + * 'format' => 'original', // this is the important bit * )); * echo "This DataTable has " . $dataTable->getRowsCount() . " rows."; * @@ -112,10 +123,10 @@ class Request /** * Constructor. * - * @param string $request GET request that defines the API call (must at least contain a **method** parameter), - * eg, `'method=UserSettings.getWideScreen&idSite=1&date=yesterday&period=week&format=xml'` - * If a request is not provided, then we use the $_GET and $_POST superglobal and fetch - * the values directly from the HTTP GET query. + * @param string|array $request Query string that defines the API call (must at least contain a **method** parameter), + * eg, `'method=UserSettings.getWideScreen&idSite=1&date=yesterday&period=week&format=xml'` + * If a request is not provided, then we use the values in the `$_GET` and `$_POST` + * superglobals. */ public function __construct($request = null) { @@ -169,8 +180,12 @@ class Request * - running generic filters unless **disable_generic_filters** is set to 1 * - URL decoding label column values * - running queued filters unless **disable_queued_filters** is set to 1 - * - removes columns based on the values of the **hideColumns** and **showColumns** query parameters - * - filters rows if the **label** query parameter is set + * - removing columns based on the values of the **hideColumns** and **showColumns** query parameters + * - filtering rows if the **label** query parameter is set + * - converting the result to the appropriate format (ie, XML, JSON, etc.) + * + * If `'original'` is supplied for the output format, the result is returned as a PHP + * object. * * @throws PluginDeactivatedException if the module plugin is not activated. * @throws Exception if the requested API method cannot be called, if required parameters for the @@ -212,10 +227,10 @@ class Request } /** - * Returns the class name of a plugin's API given the plugin name. + * Returns the name of a plugin's API class by plugin name. * - * @param string $plugin The plugin name. - * @return string + * @param string $plugin The plugin name, eg, `'Referrers'`. + * @return string The fully qualified API class name, eg, `'\Piwik\Plugins\Referrers\API'`. */ static public function getClassNameAPI($plugin) { @@ -254,7 +269,7 @@ class Request } /** - * Returns array( $class, $method) from the given string $class.$method + * Returns array($class, $method) from the given string $class.$method * * @param string $parameter * @throws Exception @@ -273,10 +288,10 @@ class Request * Helper method that processes an API request in one line using the variables in `$_GET` * and `$_POST`. * - * @param string $method The API method to call, ie, Actions.getPageTitles + * @param string $method The API method to call, ie, `'Actions.getPageTitles'`. * @param array $paramOverride The parameter name-value pairs to use instead of what's - * in $_GET & $_POST. - * @return mixed The result of the API request. + * in `$_GET` & `$_POST`. + * @return mixed The result of the API request. See {@link process()}. */ public static function processRequest($method, $paramOverride = array()) { @@ -293,7 +308,7 @@ class Request /** * Returns the original request parameters in the current query string as an array mapping - * query parameter names with values. This result of this function will not be affected + * query parameter names with values. The result of this function will not be affected * by any modifications to `$_GET` and will not include parameters in `$_POST`. * * @return array @@ -308,7 +323,7 @@ class Request } /** - * Returns URL for the current requested report w/o any filter parameters. + * Returns the URL for the current requested report w/o any filter parameters. * * @param string $module The API module. * @param string $action The API action. @@ -360,7 +375,7 @@ class Request } /** - * Returns the unmodified segment from the original request. + * Returns the segment query parameter from the original request, without modifications. * * @return array|bool */ diff --git a/core/ArchiveProcessor.php b/core/ArchiveProcessor.php index 435fb69ad9..6aa62cdc9d 100644 --- a/core/ArchiveProcessor.php +++ b/core/ArchiveProcessor.php @@ -22,24 +22,7 @@ use Piwik\Db; use Piwik\Period; /** - * Used to insert numeric and blob archive data, and to aggregate archive data. - * - * During the Archiving process an instance of this class is used by plugins - * to cache aggregated analytics statistics. - * - * When the {@link Archive} class is used to query for archive data and that archive - * data is found to be absent, the archiving process is launched. Instances of the - * {@link Piwik\Plugin\Archiver} classes for every plugin that supplies one are - * then used to execute archiving logic. - * - * Plugins access ArchiveProcessor instances through the {@link Piwik\Plugin\Archiver} class. - * Read the docs for {@link Piwik\Plugin\Archiver} to learn more about the process. - * - * ### Limitations - * - * - It is currently only possible to aggregate statistics for one site and period - * at a time. The archive.php cron script does, however, issue asynchronous HTTP - * requests that initiate archiving, so statistics can be calculated in parallel. + * Used by {@link Piwik\Plugin\Archiver} instances to insert and aggregate archive data. * * ### See also * @@ -52,7 +35,7 @@ use Piwik\Period; * * **Inserting numeric data** * - * // function in an Archiver descendent + * // function in an Archiver descendant * public function aggregateDayReport() * { * $archiveProcessor = $this->getProcessor(); @@ -63,7 +46,7 @@ use Piwik\Period; * * **Inserting serialized DataTables** * - * // function in an Archiver descendent + * // function in an Archiver descendant * public function aggregateDayReport() * { * $archiveProcessor = $this->getProcessor(); @@ -79,7 +62,7 @@ use Piwik\Period; * * **Aggregating archive data** * - * // function in Archiver descendent + * // function in Archiver descendant * public function aggregateMultipleReports() * { * $archiveProcessor = $this->getProcessor(); @@ -147,7 +130,8 @@ class ArchiveProcessor } /** - * Returns the Parameters object containing the site, period and segment used with this archive. + * Returns the {@link Parameters} object containing the site, period and segment we're archiving + * data for. * * @return Parameters * @api @@ -188,20 +172,19 @@ class ArchiveProcessor * @param int $maximumRowsInDataTableLevelZero Maximum number of rows allowed in the top level DataTable. * @param int $maximumRowsInSubDataTable Maximum number of rows allowed in each subtable. * @param string $columnToSortByBeforeTruncation The name of the column to sort by before truncating a DataTable. - * @param array $columnsAggregationOperation Operations for aggregating columns, @see Row::sumRow(). - * @param array $columnsToRenameAfterAggregation For columns that must change names when summed because they - * cannot be summed, eg, - * `array('nb_uniq_visitors' => 'sum_daily_nb_uniq_visitors')`. + * @param array $columnsAggregationOperation Operations for aggregating columns, see {@link Row::sumRow()}. + * @param array $columnsToRenameAfterAggregation Columns mapped to new names for columns that must change names + * when summed because they cannot be summed, eg, + * `array('nb_uniq_visitors' => 'sum_daily_nb_uniq_visitors')`. * @return array Returns the row counts of each aggregated report before truncation, eg, - * ``` - * array( - * 'report1' => array('level0' => $report1->getRowsCount, - * 'recursive' => $report1->getRowsCountRecursive()), - * 'report2' => array('level0' => $report2->getRowsCount, - * 'recursive' => $report2->getRowsCountRecursive()), - * ... - * ) - * ``` + * + * array( + * 'report1' => array('level0' => $report1->getRowsCount, + * 'recursive' => $report1->getRowsCountRecursive()), + * 'report2' => array('level0' => $report2->getRowsCount, + * 'recursive' => $report2->getRowsCountRecursive()), + * ... + * ) * @api */ public function aggregateDataTableRecords($recordNames, @@ -241,12 +224,12 @@ class ArchiveProcessor * @return array|int Returns the array of aggregate values. If only one metric was aggregated, * the aggregate value will be returned as is, not in an array. * For example, if `array('nb_visits', 'nb_hits')` is supplied for `$columns`, - * ``` - * array( - * 'nb_visits' => 3040, - * 'nb_hits' => 405 - * ) - * ``` + * + * array( + * 'nb_visits' => 3040, + * 'nb_hits' => 405 + * ) + * * could be returned. If `array('nb_visits')` or `'nb_visits'` is used for `$columns`, * then `3040` would be returned. * @api @@ -286,9 +269,8 @@ class ArchiveProcessor * * @param array $numericRecords A name-value mapping of numeric values that should be * archived, eg, - * ``` - * array('Referrers_distinctKeywords' => 23, 'Referrers_distinctCampaigns' => 234) - * ``` + * + * array('Referrers_distinctKeywords' => 23, 'Referrers_distinctCampaigns' => 234) * @api */ public function insertNumericRecords($numericRecords) @@ -302,7 +284,7 @@ class ArchiveProcessor * Caches a single numeric record in the archive for this processor's site, period and * segment. * - * Numeric values are not inserted if they equal 0. + * Numeric values are not inserted if they equal `0`. * * @param string $name The name of the numeric value, eg, `'Referrers_distinctKeywords'`. * @param float $value The numeric value. diff --git a/core/ArchiveProcessor/Parameters.php b/core/ArchiveProcessor/Parameters.php index 7ac9129b3b..25db149f2f 100644 --- a/core/ArchiveProcessor/Parameters.php +++ b/core/ArchiveProcessor/Parameters.php @@ -19,9 +19,9 @@ use Piwik\Segment; use Piwik\Site; /** - * An ArchiveProcessor processes data for an Archive determined by these Parameters: website, period and segment. - * - * @api + * Contains the analytics parameters for the reports that are currently being archived. The analytics + * parameters include the **website** the reports describe, the **period** of time the reports describe + * and the **segment** used to limit the visit set. */ class Parameters { @@ -45,6 +45,11 @@ class Parameters */ private $requestedPlugin = false; + /** + * Constructor. + * + * @ignore + */ public function __construct(Site $site, Period $period, Segment $segment) { $this->site = $site; @@ -69,7 +74,7 @@ class Parameters } /** - * Returns the period we computing statistics for. + * Returns the period we are computing statistics for. * * @return Period * @api @@ -83,6 +88,7 @@ class Parameters * Returns the array of Period which make up this archive. * * @return \Piwik\Period[] + * @ignore */ public function getSubPeriods() { @@ -94,6 +100,7 @@ class Parameters /** * @return array + * @ignore */ public function getIdSites() { @@ -129,7 +136,7 @@ class Parameters } /** - * Returns the Date end of this period. + * Returns the end day of the period in the site's timezone. * * @return Date */ @@ -139,7 +146,7 @@ class Parameters } /** - * Returns the Date start of this period. + * Returns the start day of the period in the site's timezone. * * @return Date */ @@ -180,5 +187,4 @@ class Parameters $this->getDateEnd()->getDateEndUTC() ); } - }
\ No newline at end of file diff --git a/core/Common.php b/core/Common.php index a655599434..26dec8e25e 100644 --- a/core/Common.php +++ b/core/Common.php @@ -18,7 +18,7 @@ use Piwik\Tracker\Cache; /** * Contains helper methods used by both Piwik Core and the Piwik Tracking engine. * - * This is the only external class loaded by the /piwik.php file. + * This is the only non-Tracker class loaded by the **\/piwik.php** file. * * @package Piwik */ @@ -201,24 +201,24 @@ class Common * This function is automatically called when {@link getRequestVar()} is called, * so you should not normally have to use it. * - * You should used it when outputting data that isn't escaped and was + * This function should be used when outputting data that isn't escaped and was * obtained from the user (for example when using the `|raw` twig filter on goal names). * - * NOTE: Sanitized input should not be used directly in an SQL query; SQL placeholders - * should still be used. + * _NOTE: Sanitized input should not be used directly in an SQL query; SQL placeholders + * should still be used._ * * **Implementation Details** * - * - `htmlspecialchars` is used to escape text. - * - Single quotes are not escaped so "Piwik's amazing community" will still be - * "Piwik's amazing community". + * - [htmlspecialchars](http://php.net/manual/en/function.htmlspecialchars.php) is used to escape text. + * - Single quotes are not escaped so **Piwik's amazing community** will still be + * **Piwik's amazing community**. * - Use of the `magic_quotes` setting will not break this method. - * - Boolean, numeric and null values are simply returned. + * - Boolean, numeric and null values are not modified. * - * @param mixed $value The variable to be cleaned. If an array is supplied, the contents + * @param mixed $value The variable to be sanitized. If an array is supplied, the contents * of the array will be sanitized recursively. The keys of the array * will also be sanitized. - * @param bool $alreadyStripslashed + * @param bool $alreadyStripslashed Implementation detail, ignore. * @throws Exception If `$value` is of an incorrect type. * @return mixed The sanitized value. * @api @@ -299,10 +299,10 @@ class Common * the user. * * Some data in Piwik is stored sanitized (such as site name). In this case you may - * have to use this method to unsanitize it after it is retrieved. + * have to use this method to unsanitize it in order to, for example, output it in JSON. * - * @param string|array $value The data to unsanitize. If an array is passed the - * array is sanitized recursively. Keys are not unsanitized. + * @param string|array $value The data to unsanitize. If an array is passed, the + * array is sanitized recursively. Key values are not unsanitized. * @return string|array The unsanitized data. * @api */ @@ -349,18 +349,19 @@ class Common * * Use this function to get request parameter values. **_NEVER use `$_GET` and `$_POST` directly._** * - * If the variable doesn't have neither a value nor a default value provided, an exception is raised. + * If the variable cannot be found, and a default value was not provided, an exception is raised. * - * @see sanitizeInputValues() for the applied sanitization + * _See {@link sanitizeInputValues()} to learn more about sanitization._ * - * @param string $varName Name of the request parameter to get. We look in `$_GET[$varName]` and `$_POST[$varName]` - * for the value. - * @param string|null $varDefault The value to return if the request parameter doesn't exist or has an empty value. - * @param string|null $varType Expected type, the value must be one of the following: `'array'`, `'int'`, `'integer'`, - * `'string'`, `'json'`. If `'json'`, the string value will be `json_decode`-d and all of - * entries sanitized. - * @param array|null $requestArrayToUse The array to use instead of $_GET and $_POST. - * @throws Exception If the request parameter doesn't exist and there is no default value or if the request parameter + * @param string $varName Name of the request parameter to get. By default, we look in `$_GET[$varName]` + * and `$_POST[$varName]` for the value. + * @param string|null $varDefault The value to return if the request parameter cannot be found or has an empty value. + * @param string|null $varType Expected type of the request variable. This parameters value must be one of the following: + * `'array'`, `'int'`, `'integer'`, `'string'`, `'json'`. + * + * If `'json'`, the string value will be `json_decode`-d and then sanitized. + * @param array|null $requestArrayToUse The array to use instead of `$_GET` and `$_POST`. + * @throws Exception If the request parameter doesn't exist and there is no default value, or if the request parameter * exists but has an incorrect type. * @return mixed The sanitized request parameter. * @api @@ -687,10 +688,10 @@ class Common /** * Returns the list of valid language codes. * - * @see core/DataFiles/Languages.php + * See [core/DataFiles/Languages.php](https://github.com/piwik/piwik/blob/master/core/DataFiles/Languages.php). * - * @return array Array of two letter ISO codes mapped with language name (in English). E.g. - * `array('en' => 'English')`. + * @return array Array of two letter ISO codes mapped with their associated language names (in English). E.g. + * `array('en' => 'English', 'ja' => 'Japanese')`. * @api */ public static function getLanguagesList() @@ -702,12 +703,12 @@ class Common } /** - * Returns list of language to country mappings. + * Returns a list of language to country mappings. * - * @see core/DataFiles/LanguageToCountry.php + * See [core/DataFiles/LanguageToCountry.php](https://github.com/piwik/piwik/blob/master/core/DataFiles/LanguageToCountry.php). * * @return array Array of two letter ISO language codes mapped with two letter ISO country codes: - * `array('fr' => 'fr'), // French => France` + * `array('fr' => 'fr') // French => France` * @api */ public static function getLanguageToCountryList() @@ -947,11 +948,13 @@ class Common */ /** - * Returns a string with a comma separated list of placeholders for use in an SQL query based - * on the list of fields we're referencing. Used mainly to fill the `IN (...)` part of a query. + * Returns a string with a comma separated list of placeholders for use in an SQL query. Used mainly + * to fill the `IN (...)` part of a query. * * @param array|string $fields The names of the mysql table fields to bind, e.g. * `array(fieldName1, fieldName2, fieldName3)`. + * + * _Note: The content of the array isn't important, just its length._ * @return string The placeholder string, e.g. `"?, ?, ?"`. * @api */ @@ -995,10 +998,10 @@ class Common } /** - * Mark orphaned object for garbage collection. + * Marks an orphaned object for garbage collection. * - * For more information: @link http://dev.piwik.org/trac/ticket/374 - * @param $var + * For more information: {@link http://dev.piwik.org/trac/ticket/374} + * @param $var The object to destroy. * @api */ static public function destroy(&$var) diff --git a/core/DataAccess/LogAggregator.php b/core/DataAccess/LogAggregator.php index 43fdb295d5..3f065193b0 100644 --- a/core/DataAccess/LogAggregator.php +++ b/core/DataAccess/LogAggregator.php @@ -20,22 +20,20 @@ use Piwik\Metrics; use Piwik\Tracker\GoalManager; /** - * Contains methods that aggregates log data (visits, actions, conversions, ecommerce). + * Contains methods that calculate metrics by aggregating log data (visits, actions, conversions, + * ecommerce items). * - * Plugin {@link Piwik\Plugin\Archiver} descendants can use the methods in this class to aggregate data - * in the log tables without creating their own SQL queries. + * You can use the methods in this class within {@link Piwik\Plugin\Archiver Archiver} descendants + * to aggregate log data without having to write SQL queries. * - * ### Aggregation Principles + * ### Aggregation Dimension * - * **Dimensions** + * All aggregation methods accept a **dimension** parameter. These parameters are important as + * they control how rows in a table are aggregated together. * - * Every aggregation method aggregates rows in a specific table. The rows that are - * aggregated together are chosen by **_dimensions_** that you specify. - * - * A **_dimension_** is a table column. In aggregation methods, rows that have the same - * values for the specified dimensions are aggregated together. Using dimensions you - * can calculate metrics for an entity (visits, actions, etc.) based on the values of one - * or more of the entity's properties. + * A **_dimension_** is just a table column. Rows that have the same values for these columns are + * aggregated together. The result of these aggregations is a set of metrics for every recorded value + * of a **dimension**. * * _Note: A dimension is essentially the same as a **GROUP BY** field._ * @@ -52,7 +50,7 @@ use Piwik\Tracker\GoalManager; * $where = 'log_visit.visitor_returning = 1', * * // also count visits for each browser language that are not located in the US - * $additionalSelects = array('sum(case when log_visit.location_country = 'us' then 1 else 0 end) as nonus'), + * $additionalSelects = array('sum(case when log_visit.location_country <> 'us' then 1 else 0 end) as nonus'), * * // we're only interested in visits, unique visitors & actions, so don't waste time calculating anything else * $metrics = array(Metrics::INDEX_NB_UNIQ_VISITORS, Metrics::INDEX_NB_VISITS, Metrics::INDEX_NB_ACTIONS), @@ -142,7 +140,8 @@ class LogAggregator protected $segment; /** - * Constructor + * Constructor. + * * @param \Piwik\ArchiveProcessor\Parameters $params */ public function __construct(Parameters $params) @@ -237,7 +236,8 @@ class LogAggregator } /** - * Aggregates visit logs, optionally grouping by some dimension, and returns the aggregated data. + * Executes and returns a query aggregating visit logs, optionally grouping by some dimension. Returns + * a DB statement that can be used to iterate over the result * * **Result Set** * @@ -261,25 +261,26 @@ class LogAggregator * * _Note: The metrics returned by this query can be customized by the `$metrics` parameter._ * - * @param array|string $dimensions SELECT fields (or just one field) that will be grouped by, + * @param array|string $dimensions `SELECT` fields (or just one field) that will be grouped by, * eg, `'referrer_name'` or `array('referrer_name', 'referrer_keyword')`. * The metrics retrieved from the query will be specific to combinations * of these fields. So if `array('referrer_name', 'referrer_keyword')` - * is supplied, the query will select the visits for each referrer/keyword + * is supplied, the query will aggregate visits for each referrer/keyword * combination. - * @param bool|string $where Additional condition for the WHERE clause. Can be used to filter + * @param bool|string $where Additional condition for the `WHERE` clause. Can be used to filter * the set of visits that are considered for aggregation. - * @param array $additionalSelects Additional SELECT fields that are not included in the group by + * @param array $additionalSelects Additional `SELECT` fields that are not included in the group by * clause. These can be aggregate expressions, eg, `SUM(somecol)`. * @param bool|array $metrics The set of metrics to calculate and return. If false, the query will select * all of them. The following values can be used: - * - {@link Piwik\Metrics::INDEX_NB_UNIQ_VISITORS} - * - {@link Piwik\Metrics::INDEX_NB_VISITS} - * - {@link Piwik\Metrics::INDEX_NB_ACTIONS} - * - {@link Piwik\Metrics::INDEX_MAX_ACTIONS} - * - {@link Piwik\Metrics::INDEX_SUM_VISIT_LENGTH} - * - {@link Piwik\Metrics::INDEX_BOUNCE_COUNT} - * - {@link Piwik\Metrics::INDEX_NB_VISITS_CONVERTED} + * + * - {@link Piwik\Metrics::INDEX_NB_UNIQ_VISITORS} + * - {@link Piwik\Metrics::INDEX_NB_VISITS} + * - {@link Piwik\Metrics::INDEX_NB_ACTIONS} + * - {@link Piwik\Metrics::INDEX_MAX_ACTIONS} + * - {@link Piwik\Metrics::INDEX_SUM_VISIT_LENGTH} + * - {@link Piwik\Metrics::INDEX_BOUNCE_COUNT} + * - {@link Piwik\Metrics::INDEX_NB_VISITS_CONVERTED} * @param bool|\Piwik\RankingQuery $rankingQuery * A pre-configured ranking query instance that will be used to limit the result. * If set, the return value is the array returned by {@link Piwik\RankingQuery::execute()}. @@ -462,34 +463,31 @@ class LogAggregator } /** - * Aggregates ecommerce item data (everything stored in the **log\_conversion\_item** table) - * and returns a DB statement that can be used to iterate over the aggregated data. + * Executes and returns a query aggregating ecommerce item data (everything stored in the + * **log\_conversion\_item** table) and returns a DB statement that can be used to iterate over the result * * <a name="queryEcommerceItems-result-set"></a> * **Result Set** * - * The following columns are in each row of the result set: + * Each row of the result set represents an aggregated group of ecommerce items. The following + * columns are in each row of the result set: * - * - **{@link Piwik\Metrics::INDEX_ECOMMERCE_ITEM_REVENUE}**: The total revenue for the group of items - * this row aggregated. - * - **{@link Piwik\Metrics::INDEX_ECOMMERCE_ITEM_QUANTITY}**: The total number of items of the group - * this row aggregated. - * - **{@link Piwik\Metrics::INDEX_ECOMMERCE_ITEM_PRICE}**: The total price for the group of items this - * row aggregated. + * - **{@link Piwik\Metrics::INDEX_ECOMMERCE_ITEM_REVENUE}**: The total revenue for the group of items. + * - **{@link Piwik\Metrics::INDEX_ECOMMERCE_ITEM_QUANTITY}**: The total number of items in this group. + * - **{@link Piwik\Metrics::INDEX_ECOMMERCE_ITEM_PRICE}**: The total price for the group of items. * - **{@link Piwik\Metrics::INDEX_ECOMMERCE_ORDERS}**: The total number of orders this group of items * belongs to. This will be <= to the total number * of items in this group. - * - **{@link Piwik\Metrics::INDEX_NB_VISITS}**: The total number of visits during which each item in - * this group of items was logged. + * - **{@link Piwik\Metrics::INDEX_NB_VISITS}**: The total number of visits that caused these items to be logged. * - **ecommerceType**: Either {@link Piwik\Tracker\GoalManager::IDGOAL_CART} if the items in this group were * abandoned by a visitor, or {@link Piwik\Tracker\GoalManager::IDGOAL_ORDER} if they * were ordered by a visitor. * * **Limitations** * - * Segmentation is not yet supported in this aggregation method. + * Segmentation is not yet supported for this aggregation method. * - * @param string $dimension One or more **log_conversion_item** column to group aggregated data by. + * @param string $dimension One or more **log\_conversion\_item** columns to group aggregated data by. * Eg, `'idaction_sku'` or `'idaction_sku, idaction_category'`. * @return Zend_Db_Statement A statement object that can be used to iterate through the query's * result set. See [above](#queryEcommerceItems-result-set) to learn more @@ -523,8 +521,8 @@ class LogAggregator } /** - * Aggregates action data (everything in the log_action table) and returns a DB - * statement that can be used to iterate over the aggregated data. + * Executes and returns a query aggregating action data (everything in the log_action table) and returns + * a DB statement that can be used to iterate over the result * * <a name="queryActionsByDimension-result-set"></a> * **Result Set** @@ -539,7 +537,7 @@ class LogAggregator * * Additional data can be selected through the `$additionalSelects` parameter. * - * _Note: The metrics returned by this query can be customized by the `$metrics` parameter._ + * _Note: The metrics calculated by this query can be customized by the `$metrics` parameter._ * * @param array|string $dimensions One or more SELECT fields that will be used to group the log_action * rows by. This parameter determines which log_action rows will be @@ -548,8 +546,9 @@ class LogAggregator * the set of visits that are considered for aggregation. * @param array $additionalSelects Additional SELECT fields that are not included in the group by * clause. These can be aggregate expressions, eg, `SUM(somecol)`. - * @param bool|array $metrics The set of metrics to calculate and return. If false, the query will select + * @param bool|array $metrics The set of metrics to calculate and return. If `false`, the query will select * all of them. The following values can be used: + * * - {@link Piwik\Metrics::INDEX_NB_UNIQ_VISITORS} * - {@link Piwik\Metrics::INDEX_NB_VISITS} * - {@link Piwik\Metrics::INDEX_NB_ACTIONS} @@ -559,8 +558,10 @@ class LogAggregator * @param bool|string $joinLogActionOnColumn One or more columns from the **log_link_visit_action** table that * log_action should be joined on. The table alias used for each join * is `"log_action$i"` where `$i` is the index of the column in this - * array. If a string is used for this parameter, the table alias is not - * suffixed. + * array. + * + * If a string is used for this parameter, the table alias is not + * suffixed (since there is only one column). * @return mixed A Zend_Db_Statement if `$rankingQuery` isn't supplied, otherwise the result of * {@link Piwik\RankingQuery::execute()}. Read [this](#queryEcommerceItems-result-set) * to see what aggregate data is calculated by the query. @@ -627,8 +628,8 @@ class LogAggregator } /** - * Aggregates conversion data (everything in the **log_conversion** table) and returns - * a DB statement that can be used to iterate over the aggregated data. + * Executes a query aggregating conversion data (everything in the **log_conversion** table) and returns + * a DB statement that can be used to iterate over the result. * * <a name="queryConversionsByDimension-result-set"></a> * **Result Set** @@ -645,30 +646,37 @@ class LogAggregator * - **{@link Piwik\Metrics::INDEX_GOAL_ECOMMERCE_REVENUE_SUBTOTAL}**: The total cost of all ecommerce items sold * within these conversions. This value does not * include tax, shipping or any applied discount. - * _This metric will only be applicable to the special + * + * _This metric is only applicable to the special * **ecommerce** goal (where `idGoal == 'ecommerceOrder'`)._ * - **{@link Piwik\Metrics::INDEX_GOAL_ECOMMERCE_REVENUE_TAX}**: The total tax applied to every transaction in these - * conversions. This metric is only applicable to the special - * **ecommerce** goal (where `idGoal == 'ecommerceOrder'`). + * conversions. + * + * _This metric is only applicable to the special + * **ecommerce** goal (where `idGoal == 'ecommerceOrder'`)._ * - **{@link Piwik\Metrics::INDEX_GOAL_ECOMMERCE_REVENUE_SHIPPING}**: The total shipping cost for every transaction - * in these conversions. _This metric is only applicable - * to the special **ecommerce** goal (where - * `idGoal == 'ecommerceOrder'`)._ + * in these conversions. + * + * _This metric is only applicable to the special + * **ecommerce** goal (where `idGoal == 'ecommerceOrder'`)._ * - **{@link Piwik\Metrics::INDEX_GOAL_ECOMMERCE_REVENUE_DISCOUNT}**: The total discount applied to every transaction - * in these conversions. _This metric is only applicable - * to the special **ecommerce** goal (where - * `idGoal == 'ecommerceOrder'`)._ + * in these conversions. + * + * _This metric is only applicable to the special + * **ecommerce** goal (where `idGoal == 'ecommerceOrder'`)._ * - **{@link Piwik\Metrics::INDEX_GOAL_ECOMMERCE_ITEMS}**: The total number of ecommerce items sold in each transaction - * in these conversions. _This metric is only applicable to the - * special **ecommerce** goal (where `idGoal =='ecommerceOrder'`). + * in these conversions. + * + * _This metric is only applicable to the special + * **ecommerce** goal (where `idGoal == 'ecommerceOrder'`)._ * * Additional data can be selected through the `$additionalSelects` parameter. * * _Note: This method will only query the **log_conversion** table. Other tables cannot be joined * using this method._ * - * @param array|string $dimensions One or more SELECT fields that will be used to group the log_conversion - * rows by. This parameter determines which log_conversion rows will be + * @param array|string $dimensions One or more **SELECT** fields that will be used to group the log_conversion + * rows by. This parameter determines which **log_conversion** rows will be * aggregated together. * @param bool|string $where An optional SQL expression used in the SQL's **WHERE** clause. * @param array $additionalSelects Additional SELECT fields that are not included in the group by @@ -692,11 +700,8 @@ class LogAggregator } /** - * Creates and returns an array of SQL SELECT expressions that will count the number - * of rows for which a specific column falls within specific ranges. - * - * The SELECT expressions will count the number of column values that are - * within each range. + * Creates and returns an array of SQL `SELECT` expressions that will each count how + * many rows have a column whose value is within a certain range. * * **Note:** The result of this function is meant for use in the `$additionalSelects` parameter * in one of the query... methods (for example {@link queryVisitsByDimension()}). @@ -722,23 +727,25 @@ class LogAggregator * LogAggregator::getSelectsFromRangedColumn('visitor_count_visits', $visitCountVisitsRanges, 'log_visit', 'vcv') * ); * - * // perform query + * // perform the query * $logAggregator = // get the LogAggregator somehow * $query = $logAggregator->queryVisitsByDimension($dimensions = array(), $where = false, $selects); * $tableSummary = $query->fetch(); * * $numberOfVisitsWithOneAction = $tableSummary['vta0']; + * $numberOfVisitsBetweenTwoAnd10 = $tableSummary['vta1']; + * + * $numberOfVisitsWithVisitCountOfOne = $tableSummary['vcv0']; * * @param string $column The name of a column in `$table` that will be summarized. - * @param array $ranges An array of arrays describing the ranges over which the data in the table + * @param array $ranges The array of ranges over which the data in the table * will be summarized. For example, * ``` * array( * array(1, 1), * array(2, 2), - * array(3, 5), - * array(6, 10), - * array(10) // everything over 10 + * array(3, 8), + * array(8) // everything over 8 * ) * ``` * @param string $table The unprefixed name of the table whose rows will be summarized. diff --git a/core/DataTable.php b/core/DataTable.php index ef1d325504..f232af65e1 100644 --- a/core/DataTable.php +++ b/core/DataTable.php @@ -45,7 +45,7 @@ require_once PIWIK_INCLUDE_PATH . '/core/Common.php'; * regarding all the data, such as the site or period that the data is for. _Row metadata_ * is information regarding that row, such as a browser logo or website URL. * - * Finally, DataTables all contain a special _summary_ row. This row, if it exists, is + * Finally, all DataTables contain a special _summary_ row. This row, if it exists, is * always at the end of the DataTable. * * ### Populating DataTables @@ -68,9 +68,9 @@ require_once PIWIK_INCLUDE_PATH . '/core/Common.php'; * There are two ways to manipulate a DataTable. You can either: * * 1. manually iterate through each row and manipulate the data, - * 2. or you can use predefined Filters. + * 2. or you can use predefined filters. * - * A Filter is a class that has a 'filter' method which will manipulate a DataTable in + * A filter is a class that has a 'filter' method which will manipulate a DataTable in * some way. There are several predefined Filters that allow you to do common things, * such as, * @@ -80,12 +80,15 @@ require_once PIWIK_INCLUDE_PATH . '/core/Common.php'; * - sort an entire DataTable, * - and more. * - * Using these Filters instead of writing your own code will increase code clarity and - * reduce code redundancy. Additionally, Filters have the advantage that they can be - * applied to DataTable\Map instances. So you can visit every DataTable in a DataTable\Map + * Using these filters instead of writing your own code will increase code clarity and + * reduce code redundancy. Additionally, filters have the advantage that they can be + * applied to DataTable\Map instances. So you can visit every DataTable in a {@link DataTable\Map} * without having to write a recursive visiting function. * - * Note: Anonymous functions can be used as DataTable Filters. + * All predefined filters exist in the **Piwik\DataTable\Filter** namespace. + * + * _Note: For convenience, [anonymous functions](http://www.php.net/manual/en/functions.anonymous.php) + * can be used as DataTable filters._ * * ### Applying Filters * @@ -97,9 +100,7 @@ require_once PIWIK_INCLUDE_PATH . '/core/Common.php'; * * ### Learn more * - * - **{@link ArchiveProcessor}** — to learn how DataTables are persisted. - * - **{@link DataTable\Renderer}** — to learn how DataTable data is exported to XML, JSON, etc. - * - **{@link DataTable\Filter}** — to see all core Filters. + * - See **{@link ArchiveProcessor}** to learn how DataTables are persisted. * * ### Examples * @@ -340,9 +341,9 @@ class DataTable implements DataTableInterface /** * Sorts the DataTable rows using the supplied callback function. * - * @param string $functionCallback A comparison callback compatible with `usort`. + * @param string $functionCallback A comparison callback compatible with {@link usort}. * @param string $columnSortedBy The column name `$functionCallback` sorts by. This is stored - * so we can determine how the DataTable is sorted in the future. + * so we can determine how the DataTable was sorted in the future. */ public function sort($functionCallback, $columnSortedBy) { @@ -392,15 +393,15 @@ class DataTable implements DataTableInterface } /** - * Applies filter to this datatable. + * Applies a filter to this datatable. * * If {@link enableRecursiveFilters()} was called, the filter will be applied * to all subtables as well. * - * @param string|Closure $className Class name, eg. "Sort" or "Sort". If no namespace is supplied, - * `Piwik\DataTable\Filter` is assumed. This parameter can also be - * a closure that takes a DataTable as its first parameter. - * @param array $parameters Array of parameters pass to the filter in addition to the table. + * @param string|Closure $className Class name, eg. `"Sort"` or "Piwik\DataTable\Filters\Sort"`. If no + * namespace is supplied, `Piwik\DataTable\Filter` is assumed. This parameter + * can also be a closure that takes a DataTable as its first parameter. + * @param array $parameters Array of extra parameters to pass to the filter. */ public function filter($className, $parameters = array()) { @@ -430,11 +431,11 @@ class DataTable implements DataTableInterface * Adds a filter and a list of parameters to the list of queued filters. These filters will be * executed when {@link applyQueuedFilters()} is called. * - * Filters that prettify the output or don't need the full set of rows should be queued. This + * Filters that prettify the column values or don't need the full set of rows should be queued. This * way they will be run after the table is truncated which will result in better performance. * - * @param string|Closure $className The class name of the filter, eg. Limit - * @param array $parameters The parameters to give to the filter, eg. array( $offset, $limit) for the filter Limit + * @param string|Closure $className The class name of the filter, eg. `'Limit'`. + * @param array $parameters The parameters to give to the filter, eg. `array($offset, $limit)` for the Limit filter. */ public function queueFilter($className, $parameters = array()) { @@ -460,7 +461,7 @@ class DataTable implements DataTableInterface * Sums a DataTable to this one. * * This method will sum rows that have the same label. If a row is found in `$tableToSum` whose - * label is not found in `$this`, the row will be added to `$this` DataTable. + * label is not found in `$this`, the row will be added to `$this`. * * If the subtables for this table are loaded, they will be summed as well. * @@ -493,7 +494,7 @@ class DataTable implements DataTableInterface * label => row ID mappings. * * @param string $label `'label'` column value to look for. - * @return Row|false The row if found, false if otherwise. + * @return Row|false The row if found, `false` if otherwise. */ public function getRowFromLabel($label) { @@ -650,7 +651,7 @@ class DataTable implements DataTableInterface /** * Sets the summary row. * - * Note: A dataTable can have only one summary row. + * _Note: A DataTable can have only one summary row._ * * @param Row $row * @return Row Returns `$row`. @@ -685,10 +686,10 @@ class DataTable implements DataTableInterface /** * Adds a new row from an array. * - * You can add Row metadata with this method. + * You can add row metadata with this method. * - * @param array $row eg. array(Row::COLUMNS => array('visits' => 13, 'test' => 'toto'), - * Row::METADATA => array('mymetadata' => 'myvalue')) + * @param array $row eg. `array(Row::COLUMNS => array('visits' => 13, 'test' => 'toto'), + * Row::METADATA => array('mymetadata' => 'myvalue'))` */ public function addRowFromArray($row) { @@ -700,7 +701,7 @@ class DataTable implements DataTableInterface * * Row metadata cannot be added with this method. * - * @param array $row eg. array('name' => 'google analytics', 'license' => 'commercial') + * @param array $row eg. `array('name' => 'google analytics', 'license' => 'commercial')` */ public function addRowFromSimpleArray($row) { @@ -757,11 +758,11 @@ class DataTable implements DataTableInterface } /** - * Returns the list of columns the rows in this datatable contain. This will return the - * columns of the first row with data and assume they occur in every other row as well. + * Returns the names of every column this DataTable contains. This method will return the + * columns of the first row with data and will assume they occur in every other row as well. * - * Note: If column names still use their in-database INDEX values (@see Metrics), they - * will be converted to their string name in the array result. + *_ Note: If column names still use their in-database INDEX values (@see Metrics), they + * will be converted to their string name in the array result._ * * @return array Array of string column names. */ @@ -851,8 +852,8 @@ class DataTable implements DataTableInterface } /** - * Returns the number of rows in this DataTable summed with the row count of each subtable - * in the DataTable hierarchy. This includes the subtables of subtables and further descendants. + * Returns the number of rows in the entire DataTable hierarchy. This is the number of rows in this DataTable + * summed with the row count of each descendant subtable. * * @return int */ @@ -998,7 +999,7 @@ class DataTable implements DataTableInterface /** * Returns a string representation of this DataTable for convenient viewing. * - * Note: This uses the Html DataTable renderer. + * _Note: This uses the **html** DataTable renderer._ * * @return string */ @@ -1062,6 +1063,7 @@ class DataTable implements DataTableInterface * @param int $maximumRowsInSubDataTable If not null, defines the maximum number of rows allowed in serialized subtables. * @param string $columnToSortByBeforeTruncation The column to sort by before truncating, eg, `Metrics::INDEX_NB_VISITS`. * @return array The array of serialized DataTables: + * * array( * // this DataTable (the root) * 0 => 'eghuighahgaueytae78yaet7yaetae', @@ -1130,9 +1132,10 @@ class DataTable implements DataTableInterface * * See {@link serialize()}. * - * @param string $stringSerialized A serialized DataTable string in the format of a string in the - * array returned by {@link serialize()}. This function will - * successfully load DataTables serialized by Piwik 1.X. + * _Note: This function will successfully load DataTables serialized by Piwik 1.X._ + * + * @param string $stringSerialized A string with the format of a string in the array returned by + * {@link serialize()}. * @throws Exception if `$stringSerialized` is invalid. */ public function addRowsFromSerializedArray($stringSerialized) @@ -1147,11 +1150,12 @@ class DataTable implements DataTableInterface } /** - * Adds many rows from an array. + * Adds multiple rows from an array. * - * You can add Row metadata with this method. + * You can add row metadata with this method. * * @param array $array Array with the following structure + * * array( * // row1 * array( @@ -1177,16 +1181,17 @@ class DataTable implements DataTableInterface } /** - * Adds many rows from an array containing arrays of column values. + * Adds multiple rows from an array containing arrays of column values. * * Row metadata cannot be added with this method. * - * @param array $array Array with the simple structure: + * @param array $array Array with the following structure: + * * array( * array( col1_name => valueA, col2_name => valueC, ...), * array( col1_name => valueB, col2_name => valueD, ...), * ) - * @throws Exception + * @throws Exception if `$array` is in an incorrect format. */ public function addRowsFromSimpleArray($array) { @@ -1257,30 +1262,36 @@ class DataTable implements DataTableInterface } /** - * Rewrites the input $array - * array ( - * LABEL => array(col1 => X, col2 => Y), - * LABEL2 => array(col1 => X, col2 => Y), - * ) - * to a DataTable, ie. with the internal structure - * array ( - * array( Row::COLUMNS => array('label' => LABEL, col1 => X, col2 => Y)), - * array( Row::COLUMNS => array('label' => LABEL2, col1 => X, col2 => Y)), - * ) + * Rewrites the input `$array` + * + * array ( + * LABEL => array(col1 => X, col2 => Y), + * LABEL2 => array(col1 => X, col2 => Y), + * ) + * + * to a DataTable with rows that look like: + * + * array ( + * array( Row::COLUMNS => array('label' => LABEL, col1 => X, col2 => Y)), + * array( Row::COLUMNS => array('label' => LABEL2, col1 => X, col2 => Y)), + * ) * - * It also works with array having only one value per row, eg. - * array ( - * LABEL => X, - * LABEL2 => Y, - * ) - * would be converted to: - * array ( - * array( Row::COLUMNS => array('label' => LABEL, 'value' => X)), - * array( Row::COLUMNS => array('label' => LABEL2, 'value' => Y)), - * ) + * Will also convert arrays like: + * + * array ( + * LABEL => X, + * LABEL2 => Y, + * ) + * + * to: + * + * array ( + * array( Row::COLUMNS => array('label' => LABEL, 'value' => X)), + * array( Row::COLUMNS => array('label' => LABEL2, 'value' => Y)), + * ) * - * @param array $array Indexed array, two formats are supported - * @param array|null $subtablePerLabel An indexed array of up to one DataTable to associate as a sub table + * @param array $array Indexed array, two formats supported, see above. + * @param array|null $subtablePerLabel An array mapping label values with DataTable instances to associate as a subtable. * @return \Piwik\DataTable */ public static function makeFromIndexedArray($array, $subtablePerLabel = null) @@ -1305,7 +1316,7 @@ class DataTable implements DataTableInterface /** * Sets the maximum depth level to at least a certain value. If the current value is - * greater than the supplied level, the maximum nesting level is not changed. + * greater than `$atLeastLevel`, the maximum nesting level is not changed. * * The maximum depth level determines the maximum number of subtable levels in the * DataTable tree. For example, if it is set to `2`, this DataTable is allowed to @@ -1325,7 +1336,7 @@ class DataTable implements DataTableInterface * Returns metadata by name. * * @param string $name The metadata name. - * @return mixed|false The metadata value or false if it cannot be found. + * @return mixed|false The metadata value or `false` if it cannot be found. */ public function getMetadata($name) { @@ -1369,7 +1380,7 @@ class DataTable implements DataTableInterface } /** - * Sets metadata erasing existing values. + * Sets metadata, erasing existing values. * * @param array $values Array mapping metadata names with metadata values. */ @@ -1392,12 +1403,12 @@ class DataTable implements DataTableInterface /** * Traverses a DataTable tree using an array of labels and returns the row - * it finds or false if it cannot find one. The number of path segments that + * it finds or `false` if it cannot find one. The number of path segments that * were successfully walked is also returned. * - * If $missingRowColumns is supplied, the specified path is created. When - * a subtable is encountered w/o the queried label, a new row is created - * with the label, and a subtable is added to the row. + * If `$missingRowColumns` is supplied, the specified path is created. When + * a subtable is encountered w/o the required label, a new row is created + * with the label, and a new subtable is added to the row. * * Read [http://en.wikipedia.org/wiki/Tree_(data_structure)#Traversal_methods](http://en.wikipedia.org/wiki/Tree_(data_structure)#Traversal_methods) * for more information about tree walking. @@ -1410,9 +1421,9 @@ class DataTable implements DataTableInterface * created for path labels that cannot be found. * @param int $maxSubtableRows The maximum number of allowed rows in new subtables. New * subtables are only created if `$missingRowColumns` is provided. - * @return array First element is the found row or false. Second element is + * @return array First element is the found row or `false`. Second element is * the number of path segments walked. If a row is found, this - * will be == to count($path). Otherwise, it will be the index + * will be == to `count($path)`. Otherwise, it will be the index * of the path segment that we could not find. */ public function walkPath($path, $missingRowColumns = false, $maxSubtableRows = 0) @@ -1468,15 +1479,15 @@ class DataTable implements DataTableInterface } /** - * Returns a new DataTable in which the rows of this table are replaced with the aggregatated rows of all its subtable's. + * Returns a new DataTable in which the rows of this table are replaced with the aggregatated rows of all its subtables. * * @param string|bool $labelColumn If supplied the label of the parent row will be added to * a new column in each subtable row. * - * If set to, 'label' each subtable row's label will be prepended + * If set to, `'label'` each subtable row's label will be prepended * w/ the parent row's label. So `'child_label'` becomes * `'parent_label - child_label'`. - * @param bool $useMetadataColumn If true and if $labelColumn is supplied, the parent row's + * @param bool $useMetadataColumn If true and if `$labelColumn` is supplied, the parent row's * label will be added as metadata and not a new column. * @return \Piwik\DataTable */ diff --git a/core/Db.php b/core/Db.php index a1ae66916d..bfd88878d6 100644 --- a/core/Db.php +++ b/core/Db.php @@ -15,20 +15,19 @@ use Piwik\Db\Adapter; use Piwik\Tracker; /** - * Helper class that contains SQL related helper functions. + * Contains SQL related helper functions for Piwik's MySQL database. * - * Plugins should use this class to execute SQL against the database. + * Plugins should always use this class to execute SQL against the database. * * ### Examples * - * **Basic Usage** - * * $rows = Db::fetchAll("SELECT col1, col2 FROM mytable WHERE thing = ?", array('thingvalue')); * foreach ($rows as $row) { * doSomething($row['col1'], $row['col2']); * } * * $value = Db::fetchOne("SELECT MAX(col1) FROM mytable"); + * doSomethingElse($value); * * Db::query("DELETE FROM mytable WHERE id < ?", array(23)); * @@ -58,9 +57,9 @@ class Db } /** - * Create the database object and connects to the database. + * Connects to the database. * - * Shouldn't be called directly, use {@link get()}. + * Shouldn't be called directly, use {@link get()} instead. * * @param array|null $dbInfos Connection parameters in an array. Defaults to the `[database]` * INI config section. @@ -101,9 +100,10 @@ class Db } /** - * Executes an unprepared SQL query. Recommended for DDL statements like CREATE, - * DROP and ALTER. The return value is DBMS-specific. For MySQLI, it returns the - * number of rows affected. For PDO, it returns the `Zend_Db_Statement` object. + * Executes an unprepared SQL query. Recommended for DDL statements like `CREATE`, + * `DROP` and `ALTER`. The return value is DBMS-specific. For MySQLI, it returns the + * number of rows affected. For PDO, it returns a + * [Zend_Db_Statement](http://framework.zend.com/manual/1.12/en/zend.db.statement.html) object. * * @param string $sql The SQL query. * @throws \Exception If there is an error in the SQL. @@ -128,10 +128,11 @@ class Db } /** - * Executes an SQL query and returns the Zend_Db_Statement object. - * If you want to fetch data from the DB you should use one of the fetch... functions. - * - * See also [http://framework.zend.com/manual/en/zend.db.statement.html](http://framework.zend.com/manual/en/zend.db.statement.html). + * Executes an SQL query and returns the [Zend_Db_Statement](http://framework.zend.com/manual/1.12/en/zend.db.statement.html) + * for the query. + * + * This method is meant for non-query SQL statements like `INSERT` and `UPDATE. If you want to fetch + * data from the DB you should use one of the fetch... functions. * * @param string $sql The SQL query. * @param array $parameters Parameters to bind in the query, eg, `array(param1 => value1, param2 => value2)`. @@ -149,12 +150,13 @@ class Db } /** - * Executes the SQL query and fetches all the rows from the result set. + * Executes an SQL `SELECT` statement and returns all fetched rows from the result set. * * @param string $sql The SQL query. * @param array $parameters Parameters to bind in the query, eg, `array(param1 => value1, param2 => value2)`. * @throws \Exception If there is a problem with the SQL or bind parameters. - * @return array (one row in the array per row fetched in the DB) + * @return array The fetched rows, each element is an associative array mapping column names + * with column values. */ static public function fetchAll($sql, $parameters = array()) { @@ -167,12 +169,13 @@ class Db } /** - * Executes an SQL query and fetches the first row of the result. + * Executes an SQL `SELECT` statement and returns the first row of the result set. * * @param string $sql The SQL query. * @param array $parameters Parameters to bind in the query, eg, `array(param1 => value1, param2 => value2)`. * @throws \Exception If there is a problem with the SQL or bind parameters. - * @return array + * @return array The fetched row, each element is an associative array mapping column names + * with column values. */ static public function fetchRow($sql, $parameters = array()) { @@ -185,7 +188,8 @@ class Db } /** - * Executes an SQL query and fetches the first column of the first row of result set. + * Executes an SQL `SELECT` statement and returns the first column value of the first + * row in the result set. * * @param string $sql The SQL query. * @param array $parameters Parameters to bind in the query, eg, `array(param1 => value1, param2 => value2)`. @@ -203,7 +207,7 @@ class Db } /** - * Executes an SQL query and returns the entire result set indexed by the first + * Executes an SQL `SELECT` statement and returns the entire result set indexed by the first * selected field. * * @param string $sql The SQL query. @@ -234,14 +238,15 @@ class Db * * **Example** * + * // delete all visit rows whose ID is less than a certain value, 100000 rows at a time * $idVisit = // ... * Db::deleteAllRows(Common::prefixTable('log_visit'), "WHERE idvisit <= ?", "idvisit ASC", 100000, array($idVisit)); * * @param string $table The name of the table to delete from. Must be prefixed (see {@link Piwik\Common::prefixTable()}). * @param string $where The where clause of the query. Must include the WHERE keyword. * @param $orderBy The column to order by and the order by direction, eg, `idvisit ASC`. - * @param int $maxRowsPerQuery The maximum number of rows to delete per DELETE query. - * @param array $parameters Parameters to bind in the query. + * @param int $maxRowsPerQuery The maximum number of rows to delete per `DELETE` query. + * @param array $parameters Parameters to bind for each query. * @return int The total number of rows deleted. */ static public function deleteAllRows($table, $where, $orderBy, $maxRowsPerQuery = 100000, $parameters = array()) @@ -264,13 +269,13 @@ class Db } /** - * Runs an OPTIMIZE TABLE query on the supplied table or tables. The table names must be prefixed - * (see {@link Piwik\Common::prefixTable()}). + * Runs an `OPTIMIZE TABLE` query on the supplied table or tables. * - * Tables will only be optimized if the `[General] enable_sql_optimize_queries` config option is + * Tables will only be optimized if the `[General] enable_sql_optimize_queries` INI config option is * set to **1**. * * @param string|array $tables The name of the table to optimize or an array of tables to optimize. + * Table names must be prefixed (see {@link Piwik\Common::prefixTable()}). * @return \Zend_Db_Statement */ static public function optimizeTables($tables) @@ -306,9 +311,10 @@ class Db } /** - * Drops the supplied table or tables. The table names must be prefixed (see {@link Piwik\Common::prefixTable()}). + * Drops the supplied table or tables. * * @param string|array $tables The name of the table to drop or an array of table names to drop. + * Table names must be prefixed (see {@link Piwik\Common::prefixTable()}). * @return \Zend_Db_Statement */ static public function dropTables($tables) @@ -321,13 +327,15 @@ class Db } /** - * Locks the supplied table or tables. The table names must be prefixed (see {@link Piwik\Common::prefixTable()}). + * Locks the supplied table or tables. * - * **NOTE:** Piwik does not require the LOCK TABLES privilege to be available. Piwik - * should still work in case it is not granted. + * **NOTE:** Piwik does not require the `LOCK TABLES` privilege to be available. Piwik + * should still work if it has not been granted. * - * @param string|array $tablesToRead The table or tables to obtain 'read' locks on. - * @param string|array $tablesToWrite The table or tables to obtain 'write' locks on. + * @param string|array $tablesToRead The table or tables to obtain 'read' locks on. Table names must + * be prefixed (see {@link Piwik\Common::prefixTable()}). + * @param string|array $tablesToWrite The table or tables to obtain 'write' locks on. Table names must + * be prefixed (see {@link Piwik\Common::prefixTable()}). * @return \Zend_Db_Statement */ static public function lockTables($tablesToRead, $tablesToWrite = array()) @@ -353,8 +361,8 @@ class Db /** * Releases all table locks. * - * **NOTE:** Piwik does not require the LOCK TABLES privilege to be available. Piwik - * should still work in case it is not granted. + * **NOTE:** Piwik does not require the `LOCK TABLES` privilege to be available. Piwik + * should still work if it has not been granted. * * @return \Zend_Db_Statement */ @@ -364,16 +372,16 @@ class Db } /** - * Performs a SELECT on a table one chunk at a time and returns the first + * Performs a `SELECT` statement on a table one chunk at a time and returns the first * successfully fetched value. * - * In other words, if running a SELECT on one chunk of the table doesn't - * return a value, we move on to the next chunk and we keep moving until - * the SELECT returns a value. + * This function will execute a query on one set of rows in a table. If nothing + * is fetched, it will execute the query on the next set of rows and so on until + * the query returns a value. * - * This function will break up a SELECT into several smaller SELECTs and - * should be used when performing a SELECT that can take a long time to finish. - * Using several smaller SELECTs will ensure that the table will not be locked + * This function will break up a `SELECT into several smaller `SELECT`s and + * should be used when performing a `SELECT` that can take a long time to finish. + * Using several smaller `SELECT`s will ensure that the table will not be locked * for too long. * * **Example** @@ -391,13 +399,13 @@ class Db * // since visits * return Db::segmentedFetchFirst($sql, $maxIdVisit, 0, -self::$selectSegmentSize); * - * @param string $sql The SQL to perform. The last two conditions of the WHERE - * expression must be as follows: 'id >= ? AND id < ?' where - * 'id' is the int id of the table. + * @param string $sql The SQL to perform. The last two conditions of the `WHERE` + * expression must be as follows: `'id >= ? AND id < ?'` where + * **id** is the int id of the table. * @param int $first The minimum ID to loop from. * @param int $last The maximum ID to loop to. - * @param int $step The maximum number of rows to scan in each smaller SELECT. - * @param array $params Parameters to bind in the query, `array(param1 => value1, param2 => value2)` + * @param int $step The maximum number of rows to scan in one query. + * @param array $params Parameters to bind in the query, eg, `array(param1 => value1, param2 => value2)` * * @return string */ @@ -417,20 +425,23 @@ class Db } /** - * Performs a SELECT on a table one chunk at a time and returns an array + * Performs a `SELECT` on a table one chunk at a time and returns an array * of every fetched value. * - * This function will break up a SELECT into several smaller SELECTs and - * accumulate the result. It should be used when performing a SELECT that can - * take a long time to finish. Using several smaller SELECTs will ensure that + * This function will break up a `SELECT` query into several smaller queries by + * using only a limited number of rows at a time. It will accumulate the results + * of each smaller query and return the result. + * + * This function should be used when performing a `SELECT` that can + * take a long time to finish. Using several smaller queries will ensure that * the table will not be locked for too long. * - * @param string $sql The SQL to perform. The last two conditions of the WHERE - * expression must be as follows: 'id >= ? AND id < ?' where - * 'id' is the int id of the table. + * @param string $sql The SQL to perform. The last two conditions of the `WHERE` + * expression must be as follows: `'id >= ? AND id < ?'` where + * **id** is the int id of the table. * @param int $first The minimum ID to loop from. * @param int $last The maximum ID to loop to. - * @param int $step The maximum number of rows to scan in each smaller SELECT. + * @param int $step The maximum number of rows to scan in one query. * @param array $params Parameters to bind in the query, `array(param1 => value1, param2 => value2)` * @return array An array of primitive values. */ @@ -453,19 +464,22 @@ class Db * Performs a SELECT on a table one chunk at a time and returns an array * of every fetched row. * - * This function will break up a SELECT into several smaller SELECTs and - * accumulate the result. It should be used when performing a SELECT that can - * take a long time to finish. Using several smaller SELECTs will ensure that + * This function will break up a `SELECT` query into several smaller queries by + * using only a limited number of rows at a time. It will accumulate the results + * of each smaller query and return the result. + * + * This function should be used when performing a `SELECT` that can + * take a long time to finish. Using several smaller queries will ensure that * the table will not be locked for too long. * - * @param string $sql The SQL to perform. The last two conditions of the WHERE - * expression must be as follows: 'id >= ? AND id < ?' where - * 'id' is the int id of the table. + * @param string $sql The SQL to perform. The last two conditions of the `WHERE` + * expression must be as follows: `'id >= ? AND id < ?'` where + * **id** is the int id of the table. * @param int $first The minimum ID to loop from. * @param int $last The maximum ID to loop to. - * @param int $step The maximum number of rows to scan in each smaller SELECT. + * @param int $step The maximum number of rows to scan in one query. * @param array $params Parameters to bind in the query, array( param1 => value1, param2 => value2) - * @return array An array of rows that includes the result set of every executed + * @return array An array of rows that includes the result set of every smaller * query. */ static public function segmentedFetchAll($sql, $first, $last, $step, $params = array()) @@ -486,14 +500,21 @@ class Db } /** - * Performs a non-SELECT query on a table one chunk at a time. + * Performs a `UPDATE` or `DELETE` statement on a table one chunk at a time. + * + * This function will break up a query into several smaller queries by + * using only a limited number of rows at a time. + * + * This function should be used when executing a non-query statement will + * take a long time to finish. Using several smaller queries will ensure that + * the table will not be locked for too long. * - * @param string $sql The SQL to perform. The last two conditions of the WHERE - * expression must be as follows: 'id >= ? AND id < ?' where - * 'id' is the int id of the table. + * @param string $sql The SQL to perform. The last two conditions of the `WHERE` + * expression must be as follows: `'id >= ? AND id < ?'` where + * **id** is the int id of the table. * @param int $first The minimum ID to loop from. * @param int $last The maximum ID to loop to. - * @param int $step The maximum number of rows to scan in each smaller query. + * @param int $step The maximum number of rows to scan in one query. * @param array $params Parameters to bind in the query, `array(param1 => value1, param2 => value2)` */ static public function segmentedQuery($sql, $first, $last, $step, $params = array()) @@ -513,7 +534,7 @@ class Db /** * Attempts to get a named lock. This function uses a timeout of 1s, but will - * retry a set number of time. + * retry a set number of times. * * @param string $lockName The lock name. * @param int $maxRetries The max number of times to retry. diff --git a/core/Filesystem.php b/core/Filesystem.php index 2eb8ff7a78..aea8f5e1c8 100644 --- a/core/Filesystem.php +++ b/core/Filesystem.php @@ -14,7 +14,7 @@ use Exception; use Piwik\Tracker\Cache; /** - * Contains helper functions that involve the filesystem. + * Contains helper functions that deal with the filesystem. * * @package Piwik */ @@ -92,11 +92,11 @@ class Filesystem /** * Attempts to create a new directory. All errors are silenced. * - * Note: This function does not create directories recursively. + * _Note: This function does **not** create directories recursively._ * * @param string $path The path of the directory to create. * @param bool $denyAccess Whether to deny browser access to this new folder by - * creating a .htaccess file. + * creating an **.htaccess** file. * @api */ public static function mkdir($path, $denyAccess = true) @@ -170,11 +170,12 @@ class Filesystem /** * Recursively find pathnames that match a pattern. + * * See {@link http://php.net/manual/en/function.glob.php glob} for more info. * * @param string $sDir directory The directory to glob in. * @param string $sPattern pattern The pattern to match paths against. - * @param int $nFlags `glob()` flags. See {@link http://php.net/manual/en/function.glob.php}. + * @param int $nFlags `glob()` . See {@link http://php.net/manual/en/function.glob.php glob()}. * @return array The list of paths that match the pattern. * @api */ @@ -200,7 +201,7 @@ class Filesystem * Recursively deletes a directory. * * @param string $dir Path of the directory to delete. - * @param boolean $deleteRootToo Whether to delete `$dir` or just its contents. + * @param boolean $deleteRootToo If true, `$dir` is deleted, otherwise just its contents. * @param \Closure|false $beforeUnlink An optional closure to execute on a file path before unlinking. * @api */ @@ -238,7 +239,7 @@ class Filesystem * @param bool $excludePhp Whether to avoid copying files if the file is related to PHP * (includes .php, .tpl, .twig files). * @throws Exception If the file cannot be copied. - * @return bool + * @return true * @api */ public static function copy($source, $dest, $excludePhp = false) diff --git a/core/FrontController.php b/core/FrontController.php index e9fb8f6093..f45028272a 100644 --- a/core/FrontController.php +++ b/core/FrontController.php @@ -152,7 +152,7 @@ class FrontController extends Singleton * This event can be used to customize the error that occurs when a user is denied access * (for example, displaying an error message, redirecting to a page other than login, etc.). * - * @param NoAccessException $exception The exception that was caught. + * @param \Piwik\NoAccessException $exception The exception that was caught. */ Piwik::postEvent('User.isNotAuthorized', array($exception), $pending = true); } catch (Exception $e) { diff --git a/core/IP.php b/core/IP.php index 6e3140fdae..b13c6264b3 100644 --- a/core/IP.php +++ b/core/IP.php @@ -16,11 +16,11 @@ namespace Piwik; * * As of Piwik 1.3, IP addresses are stored in the DB has VARBINARY(16), * and passed around in network address format which has the advantage of - * being in big-endian byte order, allowing for binary-safe string + * being in big-endian byte order. This allows for binary-safe string * comparison of addresses (of the same length), even on Intel x86. * - * As a matter of naming convention, we use $ip for the network address format - * and $ipString for the presentation format (i.e., human-readable form). + * As a matter of naming convention, we use `$ip` for the network address format + * and `$ipString` for the presentation format (i.e., human-readable form). * * We're not using the network address format (in_addr) for socket functions, * so we don't have to worry about incompatibility with Windows UNICODE @@ -126,7 +126,7 @@ class IP } /** - * Convert presentation format IP address to network address format. + * Converts an IP address in presentation format to network address format. * * @param string $ipString IP address, either IPv4 or IPv6, e.g., `"127.0.0.1"`. * @return string Binary-safe string, e.g., `"\x7F\x00\x00\x01"`. @@ -195,7 +195,7 @@ class IP } /** - * Convert IP address (in network address format) to presentation format. + * Converts an IP address (in network address format) to presentation format. * This is a backward compatibility function for code that only expects * IPv4 addresses (i.e., doesn't support IPv6). * @@ -419,7 +419,7 @@ class IP } /** - * Get hostname for a given IP address. + * Retirms the hostname for a given IP address. * * @param string $ipStr Human-readable IP address. * @return string The hostname or unmodified $ipStr on failure. diff --git a/core/Nonce.php b/core/Nonce.php index c877228a91..e90c5af374 100644 --- a/core/Nonce.php +++ b/core/Nonce.php @@ -19,7 +19,7 @@ use Piwik\Session\SessionNamespace; * part of a robust defense against cross-site request forgery (CSRF/XSRF). This * class provides static methods that create and manage nonce values. * - * Nonces in Piwik are stored as a session variable and have a configurable expiration: + * Nonces in Piwik are stored as a session variable and have a configurable expiration. * * Learn more about nonces [here](http://en.wikipedia.org/wiki/Cryptographic_nonce). * @@ -29,7 +29,7 @@ use Piwik\Session\SessionNamespace; class Nonce { /** - * Returns the existing nonce. If none exists, a new nonce will be generated. + * Returns an existing nonce by ID. If none exists, a new nonce will be generated. * * @param string $id Unique id to avoid namespace conflicts, e.g., `'ModuleName.ActionName'`. * @param int $ttl Optional time-to-live in seconds; default is 5 minutes. (ie, in 5 minutes, @@ -66,9 +66,9 @@ class Nonce * The request is valid if the referrer is a local URL (see {@link Url::isLocalUrl()}) * and if the HTTP origin is valid (see {@link getAcceptableOrigins()}). * - * @param string $id Unique id - * @param string $cnonce Nonce sent to client - * @return bool true if valid; false otherwise + * @param string $id The nonce's unique ID. See {@link getNonce()}. + * @param string $cnonce Nonce sent from client. + * @return bool `true` if valid; `false` otherwise. */ static public function verifyNonce($id, $cnonce) { @@ -110,7 +110,7 @@ class Nonce } /** - * Returns Origin HTTP header or false if not found. + * Returns the **Origin** HTTP header or `false` if not found. * * @return string|bool */ @@ -123,7 +123,7 @@ class Nonce } /** - * Returns a list acceptable values for the HTTP Origin header. + * Returns a list acceptable values for the HTTP **Origin** header. * * @return array */ diff --git a/core/Notification.php b/core/Notification.php index 208ee11c66..7c9289d609 100644 --- a/core/Notification.php +++ b/core/Notification.php @@ -17,10 +17,11 @@ namespace Piwik; * Notifications consist of a message, a context (the message type), a priority * and a display type. * - * A notification's context will affect the way the message looks, but not how it - * is displayed. A notification's display type will determine how the message is - * displayed. The priority determines where it is shown in the list of - * all displayed notifications. + * **The context** affects the way the message looks, but not how it is displayed. + * + * **The display type** determines how the message is displayed. + * + * **The priority** determines where it is shown in the list of all displayed notifications. * * ### Examples * @@ -76,7 +77,7 @@ class Notification const PRIORITY_MAX = 100; /** - * If this flag applied, no close icon will be displayed. _Note: persistent notifications always have a close + * If this flag is applied, no close icon will be displayed. _Note: persistent notifications always have a close * icon._ * * See {@link $flags}. @@ -149,7 +150,7 @@ class Notification /** * If true, the message will not be escaped before being outputted as HTML. If you set this to - * true, make sure you escape text yourself in order to avoid any possible XSS vulnerabilities. + * `true`, make sure you escape text yourself in order to avoid XSS vulnerabilities. * * @var bool */ diff --git a/core/Option.php b/core/Option.php index 8c90022f99..c7908598c1 100644 --- a/core/Option.php +++ b/core/Option.php @@ -42,7 +42,7 @@ class Option * Returns the option value for the requested option `$name`. * * @param string $name The option name. - * @return string|bool The value or false, if not found. + * @return string|false The value or `false`, if not found. */ public static function get($name) { @@ -78,7 +78,7 @@ class Option * * @param string $namePattern Pattern of key to match. `'%'` characters should be used as wildcards, and literal * `'_'` characters should be escaped. - * @param string $value If supplied options will be deleted only if their value matches this value. + * @param string $value If supplied, options will be deleted only if their value matches this value. */ public static function deleteLike($namePattern, $value = null) { diff --git a/core/Period.php b/core/Period.php index 91a6856c54..73b647599d 100644 --- a/core/Period.php +++ b/core/Period.php @@ -20,16 +20,15 @@ use Piwik\Period\Year; /** * Date range representation. * - * Piwik allows users to view aggregated statistics for each day and for date - * ranges consisting of several days. When requesting data, a _date_ string and - * a _period_ string must be used to specify the date range to view statistics - * for. This is the class that Piwik uses to represent and manipulate those - * date ranges. + * Piwik allows users to view aggregated statistics for single days and for date + * ranges consisting of several days. When requesting data, a **date** string and + * a **period** string must be used to specify the date range that the data regards. + * This is the class Piwik uses to represent and manipulate those date ranges. * * There are five types of periods in Piwik: day, week, month, year and range, * where **range** is any date range. The reason the other periods exist instead - * of just **range** is that Piwik will archive for days, weeks, months and years - * periodically, while every other date range is archived on-demand. + * of just **range** is that Piwik will pre-archive reports for days, weeks, months + * and years, while every other date range is archived on-demand. * * ### Examples * @@ -74,9 +73,9 @@ abstract class Period } /** - * Creates a new Period instance with a period ID and Date instance. + * Creates a new Period instance with a period ID and {@link Date} instance. * - * Note: This method cannot create Range periods. + * _Note: This method cannot create {@link Period\Range} periods._ * * @param string $strPeriod `"day"`, `"week"`, `"month"`, `"year"`, `"range"`. * @param Date|string $date A date within the period or the range of dates. @@ -119,11 +118,20 @@ abstract class Period } /** - * Returns true $dateString and $period correspond to multiple periods. - * + * Returns true if `$dateString` and `$period` represent multiple periods. + * + * Will return true for date/period combinations where date references multiple + * dates and period is not `'range'`. For example, will return true for: + * + * - **date** = `2012-01-01,2012-02-01` and **period** = `'day'` + * - **date** = `2012-01-01,2012-02-01` and **period** = `'week'` + * - **date** = `last7` and **period** = `'month'` + * + * etc. + * * @static - * @param $dateString The `'date'` query parameter value. - * @param $period The `'period'` query parameter value. + * @param $dateString The **date** query parameter value. + * @param $period The **period** query parameter value. * @return boolean */ public static function isMultiplePeriod($dateString, $period) @@ -135,11 +143,11 @@ abstract class Period } /** - * Creates a period instance using a Site instance and two strings describing - * the period & date. + * Creates a Period instance using a period, date and timezone. * - * @param string $timezone - * @param string $period The period string: day, week, month, year, range + * @param string $timezone The timezone of the date. Only used if `$date` is `'now'`, `'today'`, + * `'yesterday'` or `'yesterdaySameTime'`. + * @param string $period The period string: `"day"`, `"week"`, `"month"`, `"year"`, `"range"`. * @param string $date The date or date range string. Can be a special value including * `'now'`, `'today'`, `'yesterday'`, `'yesterdaySameTime'`. * @return \Piwik\Period @@ -211,7 +219,7 @@ abstract class Period /** * Returns the period ID. * - * @return int A integer unique to this type of period. + * @return int A unique integer for this type of period. */ public function getId() { @@ -267,9 +275,10 @@ abstract class Period /** * Add a date to the period. * - * Protected because it not yet supported to add periods after the initialization + * Protected because adding periods after initialization is not supported. * * @param \Piwik\Period $period Valid Period object + * @ignore */ protected function addSubperiod($period) { diff --git a/core/Plugin/API.php b/core/Plugin/API.php index 474b73fa29..732f55ac70 100644 --- a/core/Plugin/API.php +++ b/core/Plugin/API.php @@ -16,9 +16,11 @@ use Piwik\Singleton; /** * The base class of all API singletons. * - * Plugins that want to expose functionality through an API should create a class - * that derives from this one. Every public method in that class will be callable - * through Piwik's API. + * Plugins that want to expose functionality through the Reporting API should create a class + * that extends this one. Every public method in that class that is not annotated with **@ignore** + * will be callable through Piwik's Web API. + * + * _Note: If your plugin calculates and stores reports, they should be made available through the API._ * * ### Examples * diff --git a/core/Plugin/Archiver.php b/core/Plugin/Archiver.php index e87e709383..84c9b5526d 100644 --- a/core/Plugin/Archiver.php +++ b/core/Plugin/Archiver.php @@ -15,8 +15,16 @@ use Piwik\ArchiveProcessor; use Piwik\Config as PiwikConfig; /** - * The base class that should be extended by plugins that archive their own - * metrics. + * The base class that should be extended by plugins that compute their own + * analytics data. + * + * Descendants should implement the {@link aggregateDayReport()} and {@link aggregateMultipleReports()} + * methods. + * + * Both of these methods should persist analytics data using the {@link \Piwik\ArchiveProcessor} + * instance returned by {@link getProcessor()}. The {@link aggregateDayReport()} method should + * compute analytics data using the {@link \Piwik\DataAccess\LogAggregator} instance + * returned by {@link getLogAggregator()}. * * ### Examples * @@ -56,13 +64,13 @@ abstract class Archiver /** * Constructor. * - * @param ArchiveProcessor $aggregator The ArchiveProcessor instance sent to the archiving - * event observer. + * @param ArchiveProcessor $processor The ArchiveProcessor instance to use when persisting archive + * data. */ - public function __construct(ArchiveProcessor $aggregator) + public function __construct(ArchiveProcessor $processor) { $this->maximumRows = PiwikConfig::getInstance()->General['datatable_archiving_maximum_rows_standard']; - $this->processor = $aggregator; + $this->processor = $processor; } /** @@ -71,10 +79,10 @@ abstract class Archiver * Implementations of this method should do more computation intensive activities such * as aggregating data across log tables. Since this method only deals w/ data logged for a day, * aggregating individual log table rows isn't a problem. Doing this for any larger period, - * however, would cause performance issues. + * however, would cause performance degradation. * - * Aggregate log table rows using a {@link Piwik\DataAccess\LogAggregator} instance. Get a {@link Piwik\DataAccess\LogAggregator} instance - * using the {@link getLogAggregator()} method. + * Aggregate log table rows using a {@link Piwik\DataAccess\LogAggregator} instance. Get a + * {@link Piwik\DataAccess\LogAggregator} instance using the {@link getLogAggregator()} method. */ abstract public function aggregateDayReport(); @@ -86,15 +94,17 @@ abstract class Archiver * week than to aggregate each log entry of the week. * * Use {@link Piwik\ArchiveProcessor::aggregateNumericMetrics()} and {@link Piwik\ArchiveProcessor::aggregateDataTableRecords()} - * to aggregate archived reports. Get the {@link Piwik\ArchiveProcessor} instance using the {@link getProcessor()}. + * to aggregate archived reports. Get the {@link Piwik\ArchiveProcessor} instance using the {@link getProcessor()} + * method. */ abstract public function aggregateMultipleReports(); /** - * Returns an {@link Piwik\ArchiveProcessor} instance that can be used to insert archive data for - * this period, segment and site. + * Returns a {@link Piwik\ArchiveProcessor} instance that can be used to insert archive data for + * the period, segment and site we are archiving data for. * * @return \Piwik\ArchiveProcessor + * @api */ protected function getProcessor() { @@ -106,6 +116,7 @@ abstract class Archiver * for this period, segment and site. * * @return \Piwik\DataAccess\LogAggregator + * @api */ protected function getLogAggregator() { diff --git a/core/Plugin/ConsoleCommand.php b/core/Plugin/ConsoleCommand.php index 4c0169ae33..54405256a5 100644 --- a/core/Plugin/ConsoleCommand.php +++ b/core/Plugin/ConsoleCommand.php @@ -23,6 +23,11 @@ use Symfony\Component\Console\Input\InputInterface; */ class ConsoleCommand extends SymfonyCommand { + /** + * Constructor. + * + * @param string|null $name The name of the command, eg, `'generate:api'`. + */ public function __construct($name = null) { if (!Common::isPhpCliMode()) { diff --git a/core/Plugin/Controller.php b/core/Plugin/Controller.php index da5c8a8def..27fb10fa9e 100644 --- a/core/Plugin/Controller.php +++ b/core/Plugin/Controller.php @@ -42,9 +42,10 @@ use Piwik\API\Proxy; * * Plugins that wish to add display HTML should create a Controller that either * extends from this class or from {@link ControllerAdmin}. Every public method in - * the controller will be exposed as a controller action. + * the controller will be exposed as a controller method and can be invoked via + * an HTTP request. * - * Learn more about Piwik's MVC system [here](#). + * Learn more about Piwik's MVC system [here](/guides/mvc-in-piwik). * * ### Examples * @@ -77,7 +78,7 @@ abstract class Controller protected $pluginName; /** - * The value of the `'date'` query parameter. + * The value of the **date** query parameter. * * @var string * @api @@ -93,7 +94,7 @@ abstract class Controller protected $date; /** - * The value of the `'idSite'` query parameter. + * The value of the **idSite** query parameter. * * @var int * @api @@ -101,7 +102,7 @@ abstract class Controller protected $idSite; /** - * The Site object created with ($idSite)[#idSite]. + * The Site object created with {@link $idSite}. * * @var Site * @api @@ -110,6 +111,7 @@ abstract class Controller /** * Constructor. + * * @api */ public function __construct() @@ -135,11 +137,11 @@ abstract class Controller } /** - * Helper method that converts "today" or "yesterday" to the specified timezone. + * Helper method that converts `"today"` or `"yesterday"` to the specified timezone. * If the date is absolute, ie. YYYY-MM-DD, it will not be converted to the timezone. * - * @param string $date today, yesterday, YYYY-MM-DD - * @param string $timezone default timezone to use + * @param string $date `'today'`, `'yesterday'`, `'YYYY-MM-DD'` + * @param string $timezone The timezone to use. * @return Date * @api */ @@ -194,7 +196,6 @@ abstract class Controller * * @param ViewInterface $view The view to render. * @return string|void - * @api */ protected function renderView(ViewInterface $view) { @@ -210,6 +211,7 @@ abstract class Controller * @throws \Exception if `$pluginName` is not an existing plugin or if `$apiAction` is not an * existing method of the plugin's API. * @return string|void See `$fetch`. + * @api */ protected function renderReport($apiAction) { @@ -375,12 +377,10 @@ abstract class Controller /** * Returns a URL to a sparkline image for a report served by the current plugin. * - * The result of this URL should be used with the [sparkline()](#) twig function. + * The result of this URL should be used with the [sparkline()](/api-reference/Piwik/View#twig) twig function. * * The current site ID and period will be used. * - * See {@link Piwik\Visualization\Sparkline} for more information about the Sparkline visualization. - * * @param string $action Method name of the controller that serves the report. * @param array $customParameters The array of query parameter name/value pairs that * should be set in result URL. @@ -406,7 +406,7 @@ abstract class Controller } /** - * Sets the first date available in the calendar. + * Sets the first date available in the period selector's calendar. * * @param Date $minDate The min date. * @param View $view The view that contains the period selector. @@ -420,8 +420,8 @@ abstract class Controller } /** - * Sets the last date available in the calendar. Usually this just the "today" date - * for a site (which can depend on the timezone of a site). + * Sets the last date available in the period selector's calendar. Usually this is just the "today" date + * for a site (which varies based on the timezone of a site). * * @param Date $maxDate The max date. * @param View $view The view that contains the period selector. @@ -684,8 +684,7 @@ abstract class Controller } /** - * Helper method used to redirect the current http request to another module/action. - * If specified, will also change the idSite, date and/or period query parameters. + * Helper method used to redirect the current HTTP request to another module/action. * * This function will exit immediately after executing. * @@ -745,6 +744,8 @@ abstract class Controller /** * Returns default site ID that Piwik should load. + * + * _Note: This value is a Piwik setting set by each user._ * * @return bool|int * @api @@ -775,6 +776,8 @@ abstract class Controller /** * Returns default date for Piwik reports. * + * _Note: This value is a Piwik setting set by each user._ + * * @return string `'today'`, `'2010-01-01'`, etc. * @api */ @@ -818,12 +821,10 @@ abstract class Controller } /** - * Checks that the token_auth in the URl matches the current logged in user's token_auth. + * Checks that the token_auth in the URL matches the currently logged-in user's token_auth. * - * This is a protection against CSRF should be used in controller - * actions that are either invoked via AJAX or redirect to a page - * within the site. It should be used in all controller actions that modify - * Piwik or user settings. + * This is a protection against CSRF and should be used in all controller + * methods that modify Piwik or any user settings. * * **The token_auth should never appear in the browser's address bar.** * @@ -877,7 +878,7 @@ abstract class Controller * @param int $currentValue The value to calculate evolution to. * @param string $pastDate The date of past value. * @param int $pastValue The value in the past to calculate evolution from. - * @return string|bool The HTML or false if the evolution is 0 and the current value is 0. + * @return string|false The HTML or `false` if the evolution is 0 and the current value is 0. * @api */ protected function getEvolutionHtml($date, $currentValue, $pastDate, $pastValue) diff --git a/core/Plugin/ControllerAdmin.php b/core/Plugin/ControllerAdmin.php index ae9ff0d9bb..f20ceb1111 100644 --- a/core/Plugin/ControllerAdmin.php +++ b/core/Plugin/ControllerAdmin.php @@ -26,8 +26,6 @@ use Piwik\View; * See {@link Controller} to learn more about Piwik controllers. * * @package Piwik - * - * @api */ abstract class ControllerAdmin extends Controller { @@ -45,6 +43,9 @@ abstract class ControllerAdmin extends Controller self::setBasicVariablesAdminView($view); } + /** + * @ignore + */ static public function displayWarningIfConfigFileNotWritable() { $isConfigFileWritable = PiwikConfig::getInstance()->isFileWritable(); @@ -61,7 +62,7 @@ abstract class ControllerAdmin extends Controller } /** - * Assigns a set of variables to a view that would be useful to an Admin controller. + * Assigns view properties that would be useful to views that render admin pages. * * Assigns the following variables: * diff --git a/core/Plugin/Manager.php b/core/Plugin/Manager.php index 47a012a38a..502f5b0f83 100644 --- a/core/Plugin/Manager.php +++ b/core/Plugin/Manager.php @@ -144,7 +144,7 @@ class Manager extends Singleton } /** - * Returns true if a plugin has been activated. + * Returns `true` if a plugin has been activated. * * @param string $name Name of plugin, eg, `'Actions'`. * @return bool @@ -157,7 +157,7 @@ class Manager extends Singleton } /** - * Returns true if plugin is loaded (in memory). + * Returns `true` if plugin is loaded (in memory). * * @param string $name Name of plugin, eg, `'Acions'`. * @return bool @@ -343,8 +343,9 @@ class Manager extends Singleton } /** - * Returns the theme currently enabled. - * If no theme is enabled, Zeitgeist is returned (default theme) + * Returns the currently enabled theme. + * + * If no theme is enabled, the **Zeitgeist** plugin is returned (this is the base and default theme). * * @return Plugin * @api @@ -385,8 +386,9 @@ class Manager extends Singleton /** * Returns info regarding all plugins. Loads plugins that can be loaded. * - * @return array An array that maps plugin names with arrays of plugin info. Plugin - * info arrays will contain the following entries: + * @return array An array that maps plugin names with arrays of plugin information. Plugin + * information consists of the following entries: + * * - **activated**: Whether the plugin is activated. * - **alwaysActivated**: Whether the plugin should always be activated, * or not. @@ -443,7 +445,7 @@ class Manager extends Singleton } /** - * Returns true if the plugin is bundled with core or false if it is third party. + * Returns `true` if the plugin is bundled with core or `false` if it is third party. * * @param string $name The name of the plugin, eg, `'Actions'`. * @return bool @@ -481,9 +483,9 @@ class Manager extends Singleton /** - * Load the specified plugins + * Load the specified plugins. * - * @param array $pluginsToLoad Array of plugins to load + * @param array $pluginsToLoad Array of plugins to load. */ public function loadPlugins(array $pluginsToLoad) { @@ -497,7 +499,7 @@ class Manager extends Singleton } /** - * Disable plugin loading + * Disable plugin loading. */ public function doNotLoadPlugins() { @@ -505,7 +507,7 @@ class Manager extends Singleton } /** - * Disable loading of "always activated" plugins + * Disable loading of "always activated" plugins. */ public function doNotLoadAlwaysActivatedPlugins() { @@ -824,7 +826,7 @@ class Manager extends Singleton } /** - * Return list of names of installed plugins. + * Return names of all installed plugins. * * @return array * @api diff --git a/core/Plugin/Settings.php b/core/Plugin/Settings.php index 2966ae7075..c8521b9acf 100644 --- a/core/Plugin/Settings.php +++ b/core/Plugin/Settings.php @@ -16,8 +16,8 @@ use Piwik\Settings\Setting; use Piwik\Settings\StorageInterface; /** - * Base class of all Settings providers. Plugins that define their own settings can extend - * this class to easily make their settings available to Piwik users. + * Base class of all plugin settings providers. Plugins that define their own configuration settings + * can extend this class to easily make their settings available to Piwik users. * * Descendants of this class should implement the {@link init()} method and call the * {@link addSetting()} method for each of the plugin's settings. diff --git a/core/Plugin/ViewDataTable.php b/core/Plugin/ViewDataTable.php index 2cd67bbd9e..65c5ab86fc 100644 --- a/core/Plugin/ViewDataTable.php +++ b/core/Plugin/ViewDataTable.php @@ -25,7 +25,7 @@ use Piwik\ViewDataTable\RequestConfig as VizRequest; /** * The base class of all report visualizations. * - * ViewDataTable instances load analytics data via Piwik's API and then output some + * ViewDataTable instances load analytics data via Piwik's Reporting API and then output some * type of visualization of that data. * * Visualizations can be in any format. HTML-based visualizations should extend @@ -38,7 +38,7 @@ use Piwik\ViewDataTable\RequestConfig as VizRequest; * class is used. * * The specific subclass to create is determined, first, by the **viewDataTable** query paramater. - * If this parameter is not set, then the default visualization type for the report that is being + * If this parameter is not set, then the default visualization type for the report being * displayed is used. * * ### Configuring ViewDataTables @@ -51,13 +51,13 @@ use Piwik\ViewDataTable\RequestConfig as VizRequest; * * Display properties can be set at any time before rendering. * - * **Request parameters** + * **Request properties** * - * Request parameters are similar to display properties in the way they are set. They are, + * Request properties are similar to display properties in the way they are set. They are, * however, not used to customize ViewDataTable instances, but in the request to Piwik's * API when loading analytics data. * - * Request parameters are set by setting the fields of a {@link Piwik\ViewDataTable\RequestConfig} object stored in + * Request properties are set by setting the fields of a {@link Piwik\ViewDataTable\RequestConfig} object stored in * the {@link $requestConfig} field. They can be set at any time before rendering. * Setting them after data is loaded will have no effect. * @@ -71,7 +71,7 @@ use Piwik\ViewDataTable\RequestConfig as VizRequest; * in the {@hook ViewDataTable.configure} event. * * ViewDataTable instances are configured by setting and modifying display properties and request - * parameters. + * properties. * * ### Creating new visualizations * @@ -156,11 +156,15 @@ abstract class ViewDataTable implements ViewInterface protected $dataTable = null; /** + * Contains display properties for this visualization. + * * @var \Piwik\ViewDataTable\Config */ public $config; /** + * Contains request properties for this visualization. + * * @var \Piwik\ViewDataTable\RequestConfig */ public $requestConfig; @@ -171,8 +175,9 @@ abstract class ViewDataTable implements ViewInterface protected $request; /** - * Constructor. Initializes the default config, requestConfig and the request itself. After configuring some - * mandatory properties reports can modify the view by listening to the hook 'ViewDataTable.configure'. + * Constructor. Initializes display and request properties to their default values. + * Posts the {@hook ViewDataTable.configure} event which plugins can use to configure the + * way reports are displayed. */ public function __construct($controllerAction, $apiMethodToRequestDataTable) { @@ -230,9 +235,13 @@ abstract class ViewDataTable implements ViewInterface } /** - * Returns the default config. Custom viewDataTables can change the default config to their needs by either - * modifying this config or creating an own Config class that extends the default Config. + * Returns the default config instance. + * + * Visualizations that define their own display properties should override this method and + * return an instance of their new {@link Piwik\ViewDataTable\Config} descendant. * + * See the last example {@link ViewDataTable here} for more information. + * * @return \Piwik\ViewDataTable\Config */ public static function getDefaultConfig() @@ -241,9 +250,13 @@ abstract class ViewDataTable implements ViewInterface } /** - * Returns the default request config. Custom viewDataTables can change the default config to their needs by either - * modifying this config or creating an own RequestConfig class that extends the default RequestConfig. + * Returns the default request config instance. + * + * Visualizations that define their own request properties should override this method and + * return an instance of their new {@link Piwik\ViewDataTable\RequestConfig} descendant. * + * See the last example {@link ViewDataTable here} for more information. + * * @return \Piwik\ViewDataTable\RequestConfig */ public static function getDefaultRequestConfig() @@ -265,7 +278,9 @@ abstract class ViewDataTable implements ViewInterface } /** - * Returns the viewDataTable ID for this DataTable visualization. Derived classes should declare a const ID field + * Returns the viewDataTable ID for this DataTable visualization. + * + * Derived classes should not override this method. They should instead declare a const ID field * with the viewDataTable ID. * * @throws \Exception @@ -284,10 +299,13 @@ abstract class ViewDataTable implements ViewInterface } /** - * Detects whether the viewDataTable or one of its ancestors has the given id. - * - * @param string $viewDataTableId + * Returns `true` if this instance's or any of its ancestors' viewDataTable IDs equals the supplied ID, + * `false` if otherwise. + * + * Can be used to test whether a ViewDataTable object is an instance of a certain visualization or not, + * without having to know where that visualization is. * + * @param string $viewDataTableId The viewDataTable ID to check for, eg, `'table'`. * @return bool */ public function isViewDataTableId($viewDataTableId) @@ -298,10 +316,10 @@ abstract class ViewDataTable implements ViewInterface } /** - * Returns the DataTable loaded from the API + * Returns the DataTable loaded from the API. * * @return DataTable - * @throws \Exception if not yet defined + * @throws \Exception if not yet loaded. */ public function getDataTable() { @@ -314,10 +332,10 @@ abstract class ViewDataTable implements ViewInterface /** * To prevent calling an API multiple times, the DataTable can be set directly. - * It won't be loaded again from the API in this case + * It won't be loaded from the API in this case. * - * @param $dataTable - * @return void $dataTable DataTable + * @param DataTable $dataTable The DataTable to use. + * @return void */ public function setDataTable($dataTable) { @@ -390,7 +408,8 @@ abstract class ViewDataTable implements ViewInterface } /** - * Determine if the view data table requests a single data table or not. + * Returns `true` if this instance will request a single DataTable, `false` if requesting + * more than one. * * @return bool */ @@ -412,11 +431,14 @@ abstract class ViewDataTable implements ViewInterface } /** - * Here you can define whether your visualization can display a specific data table or not. For instance you may - * only display your visualization in case a single data table is requested. If the method returns true, the footer - * icon will be displayed. + * Returns `true` if this visualization can display some type of data or not. + * + * New visualization classes should override this method if they can only visualize certain + * types of data. The evolution graph visualization, for example, can only visualize + * sets of DataTables. If the API method used results in a single DataTable, the evolution + * graph footer icon should not be displayed. * - * @param ViewDataTable $view + * @param ViewDataTable $view Contains the API request being checked. * @return bool */ public static function canDisplayViewDataTable(ViewDataTable $view) diff --git a/core/Plugin/Visualization.php b/core/Plugin/Visualization.php index 73982f7c59..a9df227bd3 100644 --- a/core/Plugin/Visualization.php +++ b/core/Plugin/Visualization.php @@ -47,9 +47,11 @@ use Piwik\ViewDataTable\Manager as ViewDataTableManager; * - The report is loaded through Piwik's Reporting API. * - The display and request properties that require report data in order to determine a default * value are defaulted. These properties are: + * * - {@link Piwik\ViewDataTable\Config::$columns_to_display} * - {@link Piwik\ViewDataTable\RequestConfig::$filter_sort_column} * - {@link Piwik\ViewDataTable\RequestConfig::$filter_sort_order} + * * - Priority filters are applied to the report (see {@link Piwik\ViewDataTable\Config::$filters}). * - The filters that are applied to every report in the Reporting API (called **generic filters**) * are applied. (see {@link Piwik\API\Request}) @@ -122,17 +124,22 @@ use Piwik\ViewDataTable\Manager as ViewDataTableManager; * public function beforeRender() * { * $this->config->max_graph_elements = false; - * $this->config->datatable_js_type = 'TreemapDataTable'; + * $this->config->datatable_js_type = 'MyVisualization'; * $this->config->show_flatten_table = false; * $this->config->show_pagination_control = false; * $this->config->show_offset_information = false; * } * } - * - * @api */ class Visualization extends ViewDataTable { + /** + * The Twig template file to use when rendering, eg, `"@MyPlugin/_myVisualization.twig"`. + * + * Must be defined by classes that extend Visualization. + * + * @api + */ const TEMPLATE_FILE = ''; private $templateVars = array(); @@ -223,11 +230,12 @@ class Visualization extends ViewDataTable } /** - * Assigns a template variable. All assigned variables are available in the twig view template afterwards. You can - * assign either one variable by setting $vars and $value or an array of key/value pairs. + * Assigns a template variable making it available in the Twig template specified by + * {@link TEMPLATE_FILE}. * - * @param array|string $vars - * @param mixed $value + * @param array|string $vars One or more variable names to set. + * @param mixed $value The value to set each variable to. + * @api */ public function assignTemplateVar($vars, $value = null) { @@ -240,6 +248,13 @@ class Visualization extends ViewDataTable } } + /** + * Returns `true` if there is data to display, `false` if otherwise. + * + * Derived classes should override this method if they change the amount of data that is loaded. + * + * @api + */ protected function isThereDataToDisplay() { return true; @@ -483,39 +498,43 @@ class Visualization extends ViewDataTable } /** - * Hook that is intended to change the request config that is sent to the API. + * Hook that is called before loading report data from the API. + * + * Use this method to change the request parameters that is sent to the API when requesting + * data. */ public function beforeLoadDataTable() { } /** - * Hook that is executed before generic filters like "filter_limit" and "filter_offset" are applied + * Hook that is executed before generic filters are applied. + * + * Use this method if you need access to the entire dataset (since generic filters will + * limit and truncate reports). */ public function beforeGenericFiltersAreAppliedToLoadedDataTable() { - } /** - * This hook is executed after generic filters like "filter_limit" and "filter_offset" are applied + * Hook that is executed after generic filters are applied. */ public function afterGenericFiltersAreAppliedToLoadedDataTable() { - } /** - * This hook is executed after the data table is loaded and after all filteres are applied. - * Format the data that you want to pass to the view here. + * Hook that is executed after the report data is loaded and after all filters have been applied. + * Use this method to format the report data before the view is rendered. */ public function afterAllFiltersAreApplied() { } /** - * Hook to make sure config properties have a specific value because the default config can be changed by a - * report or by request ($_GET and $_POST) params. + * Hook that is executed directly before rendering. Use this hook to force display properties to + * be a certain value, despite changes from plugins and query parameters. */ public function beforeRender() { diff --git a/core/ScheduledTask.php b/core/ScheduledTask.php index 705e606c76..7fedcfd747 100644 --- a/core/ScheduledTask.php +++ b/core/ScheduledTask.php @@ -15,7 +15,7 @@ use Exception; use Piwik\ScheduledTime; /** - * Contains metadata describing a chunk of PHP code that should be executed at regular + * Contains metadata referencing PHP code that should be executed at regular * intervals. * * See the {@link TaskScheduler} docs to learn more about scheduled tasks. @@ -72,10 +72,9 @@ class ScheduledTask /** * Constructor. * - * @param mixed $objectInstance The object or class name for the class that contains the method to - * regularly execute. Usually this will be a {@link Plugin} instance. - * @param string $methodName The name of the method of `$objectInstance` that will be regularly - * executed. + * @param mixed $objectInstance The object or class that contains the method to execute regularly. + * Usually this will be a {@link Plugin} instance. + * @param string $methodName The name of the method that will be regularly executed. * @param mixed|null $methodParameter An optional parameter to pass to the method when executed. * Must be convertible to string. * @param ScheduledTime|null $scheduledTime A {@link ScheduledTime} instance that describes when the method @@ -111,7 +110,7 @@ class ScheduledTask } /** - * Returns the object instance on which the method should be executed. Returns a class + * Returns the object instance that contains the method to execute. Returns a class * name if the method is static. * * @return mixed @@ -122,7 +121,7 @@ class ScheduledTask } /** - * Returns the class name that contains the method to execute regularly. + * Returns the name of the class that contains the method to execute. * * @return string */ @@ -132,7 +131,7 @@ class ScheduledTask } /** - * Returns the method name that will be regularly executed. + * Returns the name of the method that will be executed. * * @return string */ @@ -142,7 +141,7 @@ class ScheduledTask } /** - * Returns the a value that will be passed to the method when executed, or `null` if + * Returns the value that will be passed to the method when executed, or `null` if * no value will be supplied. * * @return string|null @@ -186,9 +185,9 @@ class ScheduledTask /** * Returns a unique name for this scheduled task. The name is stored in the DB and is used - * to store when tasks were last executed. The name is created using: + * to store a task's previous execution time. The name is created using: * - * - the class name that contains the method to execute, + * - the name of the class that contains the method to execute, * - the name of the method to regularly execute, * - and the value that is passed to the executed task. * diff --git a/core/Settings/Setting.php b/core/Settings/Setting.php index ba58abbc34..670ba37c88 100644 --- a/core/Settings/Setting.php +++ b/core/Settings/Setting.php @@ -31,9 +31,9 @@ abstract class Setting public $type = null; /** - * Describes how the setting should be manipulated through Piwik's UI. + * Describes what HTML element should be used to manipulate the setting through Piwik's UI. * - * See {@link Piwik\Plugin\Settings} for a list of supportted control types. + * See {@link Piwik\Plugin\Settings} for a list of supported control types. * * @var string */ @@ -73,7 +73,7 @@ abstract class Setting public $introduction = null; /** - * Text that will be appear directly underneath the setting title in the _Plugin Settings_ admin + * Text that will appear directly underneath the setting title in the _Plugin Settings_ admin * page. If set, should be a short description of the setting. * * @var null|string @@ -98,13 +98,11 @@ abstract class Setting * * **Example** * - * ``` - * $setting->validate = function ($value, Setting $setting) { - * if ($value > 60) { - * throw new \Exception('The time limit is not allowed to be greater than 60 minutes.'); + * $setting->validate = function ($value, Setting $setting) { + * if ($value > 60) { + * throw new \Exception('The time limit is not allowed to be greater than 60 minutes.'); + * } * } - * } - * ``` * * @var null|\Closure */ @@ -120,15 +118,13 @@ abstract class Setting * * **Example** * - * ``` - * $setting->transform = function ($value, Setting $setting) { - * if ($value > 30) { - * $value = 30; - * } + * $setting->transform = function ($value, Setting $setting) { + * if ($value > 30) { + * $value = 30; + * } * - * return (int) $value; - * } - * ``` + * return (int) $value; + * } * * @var null|\Closure */ @@ -185,7 +181,7 @@ abstract class Setting } /** - * Returns true if this setting can be displayed for the current user, false if otherwise. + * Returns `true` if this setting can be displayed for the current user, `false` if otherwise. * * @return bool */ diff --git a/core/Settings/SystemSetting.php b/core/Settings/SystemSetting.php index e96f1a1fb0..50e79e11c6 100644 --- a/core/Settings/SystemSetting.php +++ b/core/Settings/SystemSetting.php @@ -16,6 +16,8 @@ use Piwik\Piwik; /** * Describes a system wide setting. Only the super user can change this type of setting and * the value of this setting will affect all users. + * + * See {@link \Piwik\Plugin\Settings}. * * @package Piwik * @subpackage Settings @@ -38,7 +40,7 @@ class SystemSetting extends Setting } /** - * Returns the display order. User settings are displayed after system settings. + * Returns the display order. System settings are displayed before user settings. * * @return int */ diff --git a/core/Settings/UserSetting.php b/core/Settings/UserSetting.php index 7512f693c4..696d940b42 100644 --- a/core/Settings/UserSetting.php +++ b/core/Settings/UserSetting.php @@ -14,8 +14,8 @@ use Piwik\Common; use Piwik\Piwik; /** - * Describes a per user setting. Each user will be able to change this setting but each user - * can set a different value. Changes from one user will not affect other users. + * Describes a per user setting. Each user will be able to change this setting for themselves, + * but not for other users. * * @package Piwik * @subpackage Settings @@ -39,7 +39,7 @@ class UserSetting extends Setting $this->setUserLogin($userLogin); - $this->displayedForCurrentUser = !Piwik::isUserIsAnonymous() && Piwik::isUserHasSomeViewAccess(); + $this->displayedForCurrentUser = Piwik::isUserHasSomeViewAccess(); } /** diff --git a/core/SettingsPiwik.php b/core/SettingsPiwik.php index 58ac848a9a..353256e7d7 100644 --- a/core/SettingsPiwik.php +++ b/core/SettingsPiwik.php @@ -51,10 +51,9 @@ class SettingsPiwik public static $cachedKnownSegmentsToArchive = null; /** - * Returns the list of stored segments to pre-process for all sites when executing cron archiving. + * Returns every stored segment to pre-process for each site during cron archiving. * * @return array The list of stored segments that apply to all sites. - * @api */ public static function getKnownSegmentsToArchive() { @@ -159,7 +158,7 @@ class SettingsPiwik static public $piwikUrlCache = null; /** - * Returns the URL to this Piwik instance, eg. http://demo.piwik.org/ or http://example.org/piwik/. + * Returns the URL to this Piwik instance, eg. **http://demo.piwik.org/** or **http://example.org/piwik/**. * * @return string * @api @@ -196,7 +195,7 @@ class SettingsPiwik } /** - * Returns true if segmentation is allowed for this user, false if otherwise. + * Returns `true` if segmentation is allowed for this user, `false` if otherwise. * * @return bool * @api @@ -210,9 +209,8 @@ class SettingsPiwik /** * Returns true if unique visitors should be processed for the given period type. * - * Unique visitor processing is controlled by the **[General] enable_processing_unique_visitors_...** - * INI config options. By default, day/week/month periods always process unique visitors and - * year/range are not. + * Unique visitor processing is controlled by the `[General] enable_processing_unique_visitors_...` + * INI config options. By default, unique visitors are processed only for day/week/month periods. * * @param string $periodLabel `"day"`, `"week"`, `"month"`, `"year"` or `"range"` * @return bool diff --git a/core/SettingsServer.php b/core/SettingsServer.php index c43b1f9502..0e6baf131d 100644 --- a/core/SettingsServer.php +++ b/core/SettingsServer.php @@ -12,14 +12,15 @@ namespace Piwik; /** * Contains helper methods that can be used to get information regarding the - * server, its settings and PHP settings. + * server, its settings and currently used PHP settings. * * @package Piwik */ class SettingsServer { /** - * Returns true if the current script execution was triggered misc/cron/archive.php. + * Returns true if the current script execution was triggered by the cron archiving + * script (**misc/cron/archive.php**). * * Helpful for error handling: directly throw error without HTML (eg. when DB is down). * @@ -33,7 +34,7 @@ class SettingsServer } /** - * Returns true if running on Microsoft IIS 7 (or above), false if otherwise. + * Returns `true` if running on Microsoft IIS 7 (or above), `false` if otherwise. * * @return bool * @api @@ -48,7 +49,7 @@ class SettingsServer } /** - * Returns true if running on an Apache web server, false if otherwise. + * Returns `true` if running on an Apache web server, `false` if otherwise. * * @return bool * @api @@ -62,7 +63,7 @@ class SettingsServer } /** - * Returns true if running on a Windows operating system, false if otherwise. + * Returns `true` if running on a Windows operating system, `false` if otherwise. * * @since 0.6.5 * @return bool @@ -74,8 +75,8 @@ class SettingsServer } /** - * Returns true if this php version/build supports timezone manipulation - * (e.g., php >= 5.2, or compiled with EXPERIMENTAL_DATE_SUPPORT=1 for + * Returns `true` if this PHP version/build supports timezone manipulation + * (e.g., php >= 5.2, or compiled with **EXPERIMENTAL_DATE_SUPPORT=1** for * php < 5.2). * * @return bool @@ -92,9 +93,9 @@ class SettingsServer } /** - * Returns true if the GD PHP extension is available, false if otherwise. + * Returns `true` if the GD PHP extension is available, `false` if otherwise. * - * ImageGraph and sparklines depend on the GD extension. + * _Note: ImageGraph and the sparkline report visualization depend on the GD extension._ * * @return bool * @api diff --git a/core/UrlHelper.php b/core/UrlHelper.php index f6daa0734d..7092906aa7 100644 --- a/core/UrlHelper.php +++ b/core/UrlHelper.php @@ -19,8 +19,7 @@ class UrlHelper { /** * Converts an array of query parameter name/value mappings into a query string. - * Parameters that are in `$parametersToExclude` will not appear in the result - * query string. + * Parameters that are in `$parametersToExclude` will not appear in the result. * * @static * @param $queryParameters Array of query parameters, eg, `array('site' => '0', 'date' => '2012-01-01')`. @@ -113,7 +112,7 @@ class UrlHelper * Returns a URL created from the result of the [parse_url](http://php.net/manual/en/function.parse-url.php) * function. * - * Copied from the PHP comments at http://php.net/parse_url + * Copied from the PHP comments at [http://php.net/parse_url](http://php.net/parse_url). * * @param array $parsed Result of [parse_url](http://php.net/manual/en/function.parse-url.php). * @return false|string The URL or `false` if `$parsed` isn't an array. @@ -144,7 +143,7 @@ class UrlHelper /** * Returns a URL query string as an array. * - * @param string $urlQuery The query string. + * @param string $urlQuery The query string, eg, `'?param1=value1¶m2=value2'`. * @return array eg, `array('param1' => 'value1', 'param2' => 'value2')` * @api */ @@ -221,7 +220,7 @@ class UrlHelper /** * Returns the path and query string of a URL. * - * @param string $url + * @param string $url The URL. * @return string eg, `/test/index.php?module=CoreHome` if `$url` is `http://piwik.org/test/index.php?module=CoreHome`. * @api */ diff --git a/core/WidgetsList.php b/core/WidgetsList.php index a3b1098940..d2c2c63cc7 100644 --- a/core/WidgetsList.php +++ b/core/WidgetsList.php @@ -14,7 +14,7 @@ namespace Piwik; * Manages the global list of reports that can be displayed as dashboard widgets. * * Reports are added as dashboard widgets through the {@hook WidgetsList.addWidgets} - * event. Plugins should call {@link add()} in event observers for this event. + * event. Observers for this event should call the {@link add()} method to add reports. * * @package PluginsFunctions * @api @@ -38,12 +38,12 @@ class WidgetsList /** * Returns all available widgets. * - * @return array Maps widget categories with an array of widget information, eg, + * @return array Array Mapping widget categories with an array of widget information, eg, * ``` * array( * 'Visitors' => array( - * array(...), - * array(...) + * array(...), // info about first widget in this category + * array(...) // info about second widget in this category, etc. * ), * 'Visits' => array( * array(...), @@ -157,11 +157,11 @@ class WidgetsList } /** - * Removes one more widgets from the widget list. + * Removes one or more widgets from the widget list. * * @param string $widgetCategory The widget category. Can be a translation token. * @param string|false $widgetName The name of the widget to remove. Cannot be a - * translation token. If not supplied, entire category + * translation token. If not supplied, the entire category * will be removed. */ static public function remove($widgetCategory, $widgetName = false) @@ -179,11 +179,10 @@ class WidgetsList } /** - * Returns true if the widget with the given parameters exists in the widget list, - * false if otherwise. + * Returns `true` if a report exists in the widget list, `false` if otherwise. * - * @param string $controllerName The controller name of the widget's report. - * @param string $controllerAction The controller action of the widget's report. + * @param string $controllerName The controller name of the report. + * @param string $controllerAction The controller action of the report. * @return bool */ static public function isDefined($controllerName, $controllerAction) |