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

Class: Net_LDAP2_Filter

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

Class Overview

PEAR
   |
   --Net_LDAP2_Filter

Object representation of a part of a LDAP filter.


Author(s):

Variables

Methods


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 http://www.ietf.org/rfc/rfc2254.txt

Here a quick copy&paste example:

  1.  $filter0 Net_LDAP2_Filter::create('stars''equals''***');
  2.  $filter_not0 Net_LDAP2_Filter::combine('not'$filter0);
  3.  
  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));
  7.  
  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.


Parameters:

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

Parameters:

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()!

Examples:

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

  • Access: public

Parameters:

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

Parameters:

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

Parameters:

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

Parameters:

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

Parameters:

resource   $FH     (optional) A filehandle resource

[ Top ]


Documentation generated on Mon, 09 Dec 2013 10:30:05 +0000 by phpDocumentor 1.4.3. PEAR Logo Copyright © PHP Group 2004.