[ class tree: Net_LDAP2 ] [ index: Net_LDAP2 ] [ all elements ]

Class: Net_LDAP2_Filter

Source Location: /Net_LDAP2-2.2.0/Net/LDAP2/Filter.php

Class Overview


Object representation of a part of a LDAP filter.




Inherited Variables

Inherited Methods

Class Details

[line 60]
Object representation of a part of a LDAP filter.

This Class is not completely compatible to the PERL interface!

The purpose of this class is, that users can easily build LDAP filters without having to worry about right escaping etc. A Filter is built using several independent filter objects which are combined afterwards. This object works in two modes, depending how the object is created. If the object is created using the create() method, then this is a leaf-object. If the object is created using the combine() method, then this is a container object.

LDAP filters are defined in RFC-2254 and can be found under

Here a quick copy&paste example:

  1.  $filter0 Net_LDAP2_Filter::create('stars''equals''***');
  2.  $filter_not0 Net_LDAP2_Filter::combine('not'$filter0);
  4.  $filter1 Net_LDAP2_Filter::create('gn''begins''bar');
  5.  $filter2 Net_LDAP2_Filter::create('gn''ends''baz');
  6.  $filter_comp Net_LDAP2_Filter::combine('or',array($filter_not0$filter1$filter2));
  8.  echo $filter_comp->asString();
  9.  // This will output: (|(!(stars=\0x5c0x2a\0x5c0x2a\0x5c0x2a))(gn=bar*)(gn=*baz))
  10.  // The stars in $filter0 are treaten as real stars unless you disable escaping.

[ Top ]

Class Variables

$_filter =

[line 94]

Single filter

If we operate in leaf filter mode, then the constructing method stores the filter representation here

  • Access: protected

Type:   string

[ Top ]

$_match =

[line 82]

Match of this filter

If this is a leaf filter, then a matching rule is stored, if it is a container, then it is a logical operator

  • Access: protected

Type:   string

[ Top ]

$_subfilters = array()

[line 71]

Storage for combination of filters

This variable holds a array of filter objects that should be combined by this filter object.

  • Access: protected

Type:   array

[ Top ]

Method Detail

__construct (Constructor)   [line 108]

Net_LDAP2_Filter __construct( [string $filter = false])

Create a new Net_LDAP2_Filter object and parse $filter.

This is for PERL Net::LDAP interface. Construction of Net_LDAP2_Filter objects should happen through either create() or combine() which give you more control. However, you may use the perl iterface if you already have generated filters.


string   $filter   —  LDAP filter string

[ Top ]

asString   [line 457]

string|Net_LDAP2_Error asString( )

Get the string representation of this filter

This method runs through all filter objects and creates the string representation of the filter. If this filter object is a leaf filter, then it will return the string representation of this filter.

  • Access: public

[ Top ]

as_string   [line 477]

string|Net_LDAP2_Error as_string( )

Alias for perl interface as_string()

[ Top ]

combine   [line 248]

Net_LDAP2_Filter|Net_LDAP2_Error &combine( string $log_op, array|Net_LDAP2_Filter $filters)

Combine two or more filter objects using a logical operator

This static method combines two or more filter objects and returns one single filter object that contains all the others. Call this method statically: $filter = Net_LDAP2_Filter::combine('or', array($filter1, $filter2)) If the array contains filter strings instead of filter objects, we will try to parse them.

  • Access: public


string   $log_op   —  The locical operator. May be "and", "or", "not" or the subsequent logical equivalents "&", "|", "!"
array|Net_LDAP2_Filter   $filters   —  array with Net_LDAP2_Filter objects

[ Top ]

create   [line 164]

Net_LDAP2_Filter|Net_LDAP2_Error create( string $attr_name, string $match, [string $value = ''], [boolean $escape = true])

Constructor of a new part of a LDAP filter.

The following matching rules exists:

  • equals: One of the attributes values is exactly $value Please note that case sensitiviness is depends on the attributes syntax configured in the server.
  • begins: One of the attributes values must begin with $value
  • ends: One of the attributes values must end with $value
  • contains: One of the attributes values must contain $value
  • present | any: The attribute can contain any value but must be existent
  • greater: The attributes value is greater than $value
  • less: The attributes value is less than $value
  • greaterOrEqual: The attributes value is greater or equal than $value
  • lessOrEqual: The attributes value is less or equal than $value
  • approx: One of the attributes values is similar to $value
Negation ("not") can be done by prepending the above operators with the "not" or "!" keyword, see example below.

If $escape is set to true (default) then $value will be escaped properly. If it is set to false then $value will be treaten as raw filter value string. You should escape yourself using Net_LDAP2_Util::escape_filter_value()!


  1.    // This will find entries that contain an attribute "sn" that ends with "foobar":
  2.    $filter Net_LDAP2_Filter::create('sn''ends''foobar');
  4.    // This will find entries that contain an attribute "sn" that has any value set:
  5.    $filter Net_LDAP2_Filter::create('sn''any');
  7.    // This will build a negated equals filter:
  8.    $filter Net_LDAP2_Filter::create('sn''not equals''foobar');

  • Access: public


string   $attr_name   —  Name of the attribute the filter should apply to
string   $match   —  Matching rule (equals, begins, ends, contains, greater, less, greaterOrEqual, lessOrEqual, approx, any)
string   $value   —  (optional) if given, then this is used as a filter
boolean   $escape   —  Should $value be escaped? (default: yes, see Net_LDAP2_Util::escape_filter_value() for detailed information)

[ Top ]

escape   [line 538]

string escape( string $value)

This can be used to escape a string to provide a valid LDAP-Filter.

LDAP will only recognise certain characters as the character istself if they are properly escaped. This is what this method does. The method can be called statically, so you can use it outside for your own purposes (eg for escaping only parts of strings)

In fact, this is just a shorthand to Net_LDAP2_Util::escape_filter_value(). For upward compatibiliy reasons you are strongly encouraged to use the escape methods provided by the Net_LDAP2_Util class.

  • Return: The string $string, but escaped
  • Deprecated: Do not use this method anymore, instead use Net_LDAP2_Util::escape_filter_value() directly
  • Access: public


string   $value   —  Any string who should be escaped

[ Top ]

getComponents   [line 659]

array|Net_LDAP2_Error getComponents( )

Retrieve this leaf-filters attribute, match and value component.

For leaf filters, this returns array(attr, match, value). Match is be the logical operator, not the text representation, eg "=" instead of "equals". Note that some operators are really a combination of operator+value with wildcard, like "begins": That will return "=" with the value "value*"!

For non-leaf filters this will drop an error.

  • Todo: $this->_match is not always available and thus not usable here; it would be great if it would set in the factory methods and constructor.

[ Top ]

isLeaf   [line 550]

boolean isLeaf( )

Is this a container or a leaf filter object?
  • Access: protected

[ Top ]

matches   [line 569]

int|Net_LDAP2_Error matches( array|Net_LDAP2_Entry &$entries, [array &$results = array()])

Filter entries using this filter or see if a filter matches
  • Return: Returns the number of matched entries or error
  • Todo: Currently slow and naive implementation with preg_match, could be optimized (esp. begins, ends filters etc)
  • Todo: Currently only "="-based matches (equals, begins, ends, contains, any) implemented; Implement all the stuff!
  • Todo: Implement expert code with schema checks in case $entry is connected to a directory


array|Net_LDAP2_Entry   &$entries   —  The entry (or array with entries) to check
array   &$results   —  If given, the array will be appended with entries who matched the filter. Return value is true if any entry matched.

[ Top ]

parse   [line 328]

Net_LDAP2_Filter|Net_LDAP2_Error parse( string $FILTER)

Parse FILTER into a Net_LDAP2_Filter object

This parses an filter string into Net_LDAP2_Filter objects.

  • Todo: Leaf-mode: Do we need to escape at all? what about *-chars?check for the need of encoding values, tackle problems (see code comments)
  • Access: public


string   $FILTER   —  The filter string

[ Top ]

printMe   [line 493]

true|Net_LDAP2_Error printMe( [resource $FH = false])

Print the text representation of the filter to FH, or the currently selected output handle if FH is not given

This method is only for compatibility to the perl interface. However, the original method was called "print" but due to PHP language restrictions, we can't have a print() method.

  • Access: public


resource   $FH   —  (optional) A filehandle resource

[ Top ]

Documentation generated on Fri, 30 Oct 2015 21:00:04 +0000 by phpDocumentor 1.4.4. PEAR Logo Copyright © PHP Group 2004.