Filter
in package
implements
XmlSerializable
Represents XML urn:ietf:params:xml:ns:carddav:filter elements as PHP objects (RFC 6352).
From RFC 6352: The "filter" element specifies the search filter used to match address objects that should be returned by a report. The "test" attribute specifies whether any (logical OR) or all (logical AND) of the prop-filter tests need to match in order for the overall filter to match.
Tags
Interfaces, Classes and Traits
- XmlSerializable
Table of Contents
- $propFilters : array<int, PropFilter>
- The PropFilter child elements of this filter.
- $testType : string
- Semantics of match for multiple conditions (AND or OR).
- __construct() : mixed
- Constructs a Filter consisting of zero or more PropFilter elements.
- xmlAttributes() : array<string, string>
- Produces a list of attributes for this filter suitable to pass to a Sabre XML Writer.
- xmlSerialize() : void
- This function encodes the element's value (not the element itself!) to the given XML writer.
Properties
$propFilters
The PropFilter child elements of this filter.
public
array<int, PropFilter>
$propFilters
= []
Tags
$testType
Semantics of match for multiple conditions (AND or OR).
public
string
$testType
Tags
Methods
__construct()
Constructs a Filter consisting of zero or more PropFilter elements.
public
__construct(array<string|int, mixed> $conditions, bool $matchAll) : mixed
For ease of use, the $conditions parameter can take a simple form, which allows exactly one match criterion per VCard property. Or it can take a more elaborate form where for each property, several lists of match criteria can be defined.
Note that property names can be prefixed with a group name like "GROUP.EMAIL" to only match properties that belong to the given group. If no group prefix is given, the match applies to all properties of the type, independent of whether they belong to a group or not.
Simple form
The simple form is an associative array mapping property names to null or a filter condition.
A filter condition can either be a string with a text match specification (see TextMatch constructor for format) or a two-element array{string,?string} where the first element is the name of a parameter and the second is a string for TextMatch or null with a meaning as for a property filter.
Examples for the simple form:
-
['EMAIL' => null]: Matches all VCards that do NOT have an EMAIL property -
['EMAIL' => "//"]: Matches all VCards that DO have an EMAIL property (with any value) -
['EMAIL' => '/@example.com/$']: Matches all VCards that have an EMAIL property with an email address of the example.com domain -
['EMAIL' => '/@example.com/$', 'N' => '/Mustermann;/^']: Like before, but additionally/alternatively the surname must be Mustermann (depending on $matchAll) -
['EMAIL' => ['TYPE' => '/home/=']]: Matches all VCards with an EMAIL property that has a TYPE parameter with value home
Elaborate form
The more elaborate form is an array of two-element arrays where the first element is a property name and the second element is any of the values possible in the simple form, or an array object with a list of conditions of which all/any need to apply, plus an optional key "matchAll" that can be set to true to indicate that all conditions need to match (AND semantics).
Examples for the elaborate form:
-
[['EMAIL', ['/@example.com/$', ['TYPE', '/home/='], 'matchAll' => true]], ['N', '/Mustermann;/^']]: Matches all VCards, that have an EMAIL property with an address in the domain example.com and at the same time a TYPE parameter with value home, and/or an N property with a surname of Mustermann.
It is also possible to mix both forms, where string keys are used for the simple form and numeric indexes are used for the elaborate form filters.
Parameters
- $conditions : array<string|int, mixed>
-
The match conditions for the query, or for one property filter. An empty array will cause all VCards to match.
- $matchAll : bool
-
Whether all or any of the conditions needs to match.
Tags
Return values
mixed —xmlAttributes()
Produces a list of attributes for this filter suitable to pass to a Sabre XML Writer.
public
xmlAttributes() : array<string, string>
The attributes produced are:
-
test="allof/anyof"
Return values
array<string, string> —A list of attributes (attrname => attrvalue)
xmlSerialize()
This function encodes the element's value (not the element itself!) to the given XML writer.
public
xmlSerialize(Writer $writer) : void
Parameters
- $writer : Writer