Piwik\

Common

Contains helper methods used by both Matomo (formerly Piwik) Core and the Matomo Tracking engine.

This is the only non-Tracker class loaded by the \/piwik.php file.

Methods

The class defines the following methods:

• prefixTable() — Returns a prefixed table name.
• unprefixTable() — Removes the prefix from a table name and returns the result.
• sanitizeInputValues() — Sanitizes a string to help avoid XSS vulnerabilities.
• unsanitizeInputValue() — Unsanitizes a single input value and returns the result.
• unsanitizeInputValues() — Unsanitizes one or more values and returns the result.
• getRequestVar() — Gets a sanitized request parameter by name from the $_GET and $_POST superglobals.
• getSqlStringFieldsArray() — Returns a string with a comma separated list of placeholders for use in an SQL query.
• destroy() — Marks an orphaned object for garbage collection.

prefixTable()

Returns a prefixed table name.

The table prefix is determined by the [database] tables_prefix INI config option.

Signature

• It accepts the following parameter(s):

  • $table (string) — The table name to prefix, ie "log_visit"

• Returns: string — The prefixed name, ie "piwik-production_log_visit".

unprefixTable()

Removes the prefix from a table name and returns the result.

The table prefix is determined by the [database] tables_prefix INI config option.

Signature

• It accepts the following parameter(s):

  • $table (string) — The prefixed table name, eg "piwik-production_log_visit".

• Returns: string — The unprefixed table name, eg "log_visit".

sanitizeInputValues()

Sanitizes a string to help avoid XSS vulnerabilities.

This function is automatically called when getRequestVar() is called, so you should not normally have to use it.

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.

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.
• Use of the magic_quotes setting will not break this method.
• Boolean, numeric and null values are not modified.

Signature

• It accepts the following parameter(s):

  • $value (mixed) — 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.
  • $alreadyStripslashed (bool) — Implementation detail, ignore.

• Returns: mixed — The sanitized value.

• It throws one of the following exceptions:
  • Exception — If $value is of an incorrect type.

unsanitizeInputValue()

Unsanitizes a single input value and returns the result.

Signature

• It accepts the following parameter(s):

  • $value (string) —

• Returns: string — unsanitized input

unsanitizeInputValues()

Unsanitizes one or more values and returns the result.

This method should be used when you need to unescape data that was obtained from the user.

Some data in Matomo is stored sanitized (such as site name). In this case you may have to use this method to unsanitize it in order to, for example, output it in JSON.

Signature

• It accepts the following parameter(s):

  • $value (string|array) — The data to unsanitize. If an array is passed, the array is sanitized recursively. Key values are not unsanitized.

• Returns: string|array — The unsanitized data.

getRequestVar()

Gets a sanitized request parameter by name from the $_GET and $_POST superglobals.

Use this function to get request parameter values. NEVER use $_GET and $_POST directly.

If the variable cannot be found, and a default value was not provided, an exception is raised.

See sanitizeInputValues() to learn more about sanitization.

Signature

• It accepts the following parameter(s):

  • $varName (string) — Name of the request parameter to get. By default, we look in $_GET[$varName] and $_POST[$varName] for the value.
  • $varDefault (string|null) — The value to return if the request parameter cannot be found or has an empty value.
  • $varType (string|null) — 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.
  • $requestArrayToUse (array|null) — The array to use instead of $_GET and $_POST.

• Returns: mixed — The sanitized request parameter.

• It throws one of the following exceptions:
  • 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.

getSqlStringFieldsArray()

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.

Signature

• It accepts the following parameter(s):

  • $fields (array|string) — 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.

• Returns: string — The placeholder string, e.g. "?, ?, ?".

destroy()

Marks an orphaned object for garbage collection.

For more information: https://github.com/piwik/piwik/issues/374

Signature

• It accepts the following parameter(s):
  • $var (mixed) — The object to destroy.
• It does not return anything or a mixed result.