public class Datasource

class.datasource.php #21

The Datasource class provides functionality to mainly process any parameters that the fields will use in filters find the relevant Entries and return these Entries data as XML so that XSLT can be applied on it to create your website. In Symphony, there are four Datasource types provided, Section, Author, Navigation and Dynamic XML. Section is the mostly commonly used Datasource, which allows the filtering and searching for Entries in a Section to be returned as XML. Navigation datasources expose the Symphony Navigation structure of the Pages in the installation. Authors expose the Symphony Authors that are registered as users of the backend. Finally, the Dynamic XML datasource allows XML pages to be retrieved. This is especially helpful for working with Restful XML API's. Datasources are saved through the Symphony backend, which uses a Datasource template defined in TEMPLATE . /datasource.tpl.

Constants

static integer FILTER_AND = 1

A constant that represents if this filter is an AND filter in which an Entry must match all these filters. This filter is triggered when the filter string contains a +.

static integer FILTER_OR = 2

A constant that represents if this filter is an OR filter in which an entry can match any or all of these filters

Methods

void __construct(array $env, boolean $process_params)

Constructor for the datasource sets the parent, if $process_params is set, the $env variable will be run through Datasource::processParameters.

Parameters
  • $env arrayThe environment variables from the Frontend class which includes any params set by Symphony or Events or by other Datasources

  • $process_params booleanIf set to true, Datasource::processParameters will be called. By default this is true

See Also
integer __determineFilterType(string $value)

By default, all Symphony filters are considering to be AND filters, that is they are all used and Entries must match each filter to be included. It is possible to use OR filtering in a field by using an + to separate the values. eg. If the filter is test1 + test2, this will match any entries where this field is test1 OR test2. This function is run on each filter (ie. each field) in a datasource

Parameters
  • $value stringThe filter string for a field.

Returns

Datasource::FILTEROR or Datasource::FILTERAND

Deprecated

Since Symphony 2.6.0 it is recommended to use the static version, Datasource::determineFilterType

XMLElement __negateResult()

Returns an error XMLElement with 'Result Negated' text

XMLElement __noRecordsFound()

Returns an error XMLElement with 'No records found' text

string __processParametersInString(string $value, array $env, boolean $includeParenthesis, boolean $escape)

This function will replace any parameters in a string with their value. Parameters are defined by being prefixed by a $ character. In certain situations, the parameter will be surrounded by {}, which Symphony takes to mean, evaluate this parameter to a value, other times it will be omitted which is usually used to indicate that this parameter exists

Parameters
  • $value stringThe string with the parameters that need to be evaluated

  • $env arrayThe environment variables from the Frontend class which includes any params set by Symphony or Events or by other Datasources

  • $includeParenthesis booleanParameters will sometimes not be surrounded by {}. If this is the case setting this parameter to false will make this function automatically add them to the parameter. By default this is true, which means all parameters in the string already are surrounded by {}

  • $escape booleanIf set to true, the resulting value will passed through urlencode before being returned. By default this is false

Returns

The string with all parameters evaluated. If a parameter is not found, it will not be replaced and remain in the $value.

array about()

Returns an associative array of information about a datasource.

boolean allowEditorToParse()

This function is required in order to edit it in the datasource editor page. Do not overload this function if you are creating a custom datasource. It is only used by the datasource editor. If this is set to false, which is default, the Datasource's about() information will be displayed.

Returns

True if the Datasource can be edited, false otherwise. Defaults to false

static integer determineFilterType(string $value)

By default, all Symphony filters are considering to be AND filters, that is they are all used and Entries must match each filter to be included. It is possible to use OR filtering in a field by using an + to separate the values. eg. If the filter is test1 + test2, this will match any entries where this field is test1 OR test2. This function is run on each filter (ie. each field) in a datasource

Parameters
  • $value stringThe filter string for a field.

Returns

Datasource::FILTEROR or Datasource::FILTERAND

XMLElement emptyXMLSet(XMLElement $xml)

If there is no results to return this function calls Datasource::__noRecordsFound which appends an XMLElement to the current root element.

Parameters
  • $xml XMLElementThe root element XMLElement for this datasource. By default, this will the handle of the datasource, as defined by $this->dsParamROOTELEMENT

static string escapeCommas(string $string)

Using regexp, this escapes any commas in the given string

Parameters
  • $string stringThe string to escape the commas in

XMLElement execute(array $param_pool)

The meat of the Datasource, this function includes the datasource type's file that will preform the logic to return the data for this datasource It is passed the current parameters.

Parameters
  • $param_pool arrayThe current parameter pool that this Datasource can use when filtering and finding Entries or data.

Returns

The XMLElement to add into the XML for a page.

static mixed findParameterInEnv(string $needle, array $env)

Parameters can exist in three different facets of Symphony; in the URL, in the parameter pool or as an Symphony param. This function will attempt to find a parameter in those three areas and return the value. If it is not found null is returned

Parameters
  • $needle stringThe parameter name

  • $env arrayThe environment variables from the Frontend class which includes any params set by Symphony or Events or by other Datasources

Returns

If the value is not found, null, otherwise a string or an array is returned

array getDependencies()

Accessor function to return this Datasource's dependencies

mixed getSource()

This function is required in order to identify what section this Datasource is for. It is used in the datasource editor. It must remain intact. Do not overload this function in custom events. Other datasources may return a string here defining their datasource type when they do not query a section.

void grab(mixed $param_pool)
See Also
Deprecated

This function has been renamed to execute as of Symphony 2.3.1, please use execute() instead. This function will be removed in Symphony 3.0

XMLElement negateXMLSet(XMLElement $xml)

If the datasource has been negated this function calls Datasource::__negateResult which appends an XMLElement to the current root element.

Parameters
  • $xml XMLElementThe root element XMLElement for this datasource. By default, this will the handle of the datasource, as defined by $this->dsParamROOTELEMENT

string parseParamURL(string $url)

This function will parse a string (usually a URL) and fully evaluate any parameters (defined by {$param}) to return the absolute string value.

Parameters
  • $url stringThe string (usually a URL) that contains the parameters (or doesn't)

Returns

The parsed URL

void processParameters(array $env)

This function will iterates over the filters and replace any parameters with their actual values. All other Datasource variables such as sorting, ordering and pagination variables are also set by this function

Parameters
  • $env arrayThe environment variables from the Frontend class which includes any params set by Symphony or Events or by other Datasources

static string removeEscapedCommas(string $string)

Used in conjunction with escapeCommas, this function will remove the escaping pattern applied to the string (and commas)

Parameters
  • $string stringThe string with the escaped commas in it to remove

Symphony • Open Source XSLT CMS

Server Requirements

  • PHP 5.3-5.6 or 7.0-7.3
  • PHP's LibXML module, with the XSLT extension enabled (--with-xsl)
  • MySQL 5.5 or above
  • An Apache or Litespeed webserver
  • Apache's mod_rewrite module or equivalent

Compatible Hosts

Sign in

Login details