$sub_filters */ class Filter { /* ************************************************************************************************* * Leaf mode ************************************************************************************************* */ /** * The attribute name * @var string|null */ private $attr_name; /** * The operator * @var string|null */ private $op; /** * The attribute value pattern * @var string|null */ private $pattern; /* ************************************************************************************************* * Combine mode ************************************************************************************************* */ /** * The logical operator * @var string|null */ private $log_op; /** * The LDAP sub-filters objects * @var array|null */ private $sub_filters; /* ************************************************************************************************* * Some constants ************************************************************************************************* */ /** * List of possible logical operators * @var array */ private static $log_ops = array('&', '|', '!'); /** * List of logical operators aliases * @var array */ private static $log_op_aliases = array('and' => '&', 'or' => '|', 'not' => '!'); /** * The NOT logical operator * @var string */ private static $not_op = '!'; /** * List of possible operators * @var array */ private static $ops = array('=', '<', '>', '<=', '>=', '~='); /** * List of operators aliases * @var array */ private static $op_aliases = array( 'equals' => '=', '==' => '=', 'lower' => '<', 'greater' => '>', 'lower_or_equals' => '<=', 'greater_or_equals' => '>=', 'approx' => '~=', ); /** * Characters to escape in a LDAP filter string * @var array */ private static $espace_chars = array ( '\\' => '\5c', // \ '(' => '\28', // ( ')' => '\29', // ) '*' => '\2a', // * "\u{0000}" => '\00', // NUL ); /** * Regex to match on OID * @var string */ private static $oid_regex = '/^[0-9]+(\.[0-9]+)+$/'; /** * Regex to match attribute name * @var string */ private static $attr_name_regex = '/^(?P[a-zA-Z][a-zA-Z0-9\-]*)(;(?P[a-zA-Z0-9\-]+))*$/'; /** * Regex to match extensible attribute name * @throws FilterException * @var string */ private static $ext_attr_name_regex = '/^(?P[a-zA-Z0-9\-]+)?\:((?Pdn|DN)\:)?((?P[a-zA-Z]+|[0-9]+(\.[0-9]+)*)\:)?$/'; /** * Constructor * @param array|bool> $args * @return void */ public function __construct(...$args) { // Handle espace optional argument $escape = true; if ($args && is_bool(end($args))) $escape = array_pop($args); if (!$args) throw new FilterException('Invalid constructor arguments: no argument provided!'); // One logical operator followed by some filters if (self :: is_log_op($args[0])) { // @phpstan-ignore-next-line $this -> log_op = self :: unalias_log_op(array_shift($args)); // Convert args as filters $this -> sub_filters = array(); foreach ($args as $arg) { if (!is_array($arg)) $arg = array($arg); foreach ($arg as $a) { if (is_string($a)) $a = self :: parse($a); if (!$a instanceof Filter) throw new FilterException( 'Invalid constructor arguments: logical operator must be followed by Filter object, '. 'filter string or array of Filter or filter string.' ); $this -> sub_filters[] = $a; } } // Check number of filters against logical operator if (self :: is_not_op($this -> log_op) && count($this -> sub_filters) != 1) throw new FilterException( 'Invalid constructor arguments: NOT operator must be followed by exactly one filter'); return; } // array('attribute', 'operator', 'pattern') if (count($args) == 3) { if ( self :: is_attr_name($args[0]) && (self :: is_op($args[1]) || in_array($args[1], array('begins', 'contains', 'ends'))) && is_string($args[2]) ) { $this -> attr_name = $args[0]; $this -> pattern = $escape?self :: escape($args[2]):$args[2]; switch ($args[1]) { case 'begins': $this -> op = '='; $this -> pattern = sprintf('%s*', $this -> pattern); break; case 'contains': $this -> op = '='; $this -> pattern = sprintf('*%s*', $this -> pattern); break; case 'ends': $this -> op = '='; $this -> pattern = sprintf('*%s', $this -> pattern); break; default: // @phpstan-ignore-next-line $this -> op = self :: unalias_op($args[1]); } return; } } // array('attribute', 'present|any') if (count($args) == 2) { if ( self :: is_attr_name($args[0]) && in_array($args[1], array('present', 'any')) ) { $this -> attr_name = $args[0]; $this -> op = '='; $this -> pattern = '*'; return; } } throw new FilterException( 'Invalid constructor arguments provided to construct a Filter object'); } /** * Get filter property * @param string $key * @return mixed */ public function __get($key) { switch ($key) { case 'attr_name': case 'attribute': return isset($this -> attr_name)?$this -> attr_name:null; case 'op': case 'operator': return isset($this -> op)?$this -> op:null; case 'pattern': return isset($this -> pattern)?$this -> pattern:null; case 'log_op': case 'logical_operator': return isset($this -> log_op)?$this -> log_op:null; case 'sub_filters': return isset($this -> sub_filters)?$this -> sub_filters:array(); } throw new FilterException("Invalid property '$key' requested"); } /** * Get operators * @return array */ public static function operators() { return self :: $ops; } /** * Get operator aliases * @return array */ public static function operator_aliases() { return self :: $op_aliases; } /** * Get logical operators * @return array */ public static function logical_operators() { return self :: $log_ops; } /** * Get logical operator aliases * @return array */ public static function logical_operator_aliases() { return self :: $log_op_aliases; } /** * Check filter is a leaf one * @phpstan-assert-if-true string $this->attr_name * @phpstan-assert-if-true string $this->op * @phpstan-assert-if-true string $this->pattern * @return bool */ public function is_leaf() { return isset($this -> attr_name) && isset($this -> op) && isset($this -> pattern); } /** * Check filter is a combine one * @phpstan-assert-if-true string $this->log_op * @phpstan-assert-if-true non-empty-array $this->sub_filters * @return bool */ public function is_combine() { return ( isset($this -> log_op) && isset($this -> sub_filters) && is_array($this -> sub_filters) && $this -> sub_filters ); } /** * Return LDAP filter as a string * @param bool $pretty Enable pretty format: as line return and tabulations to easily distinguate * logical groups. * @param int $level Level of iteration (internally use in pretty format mode) * @return string */ public function as_string($pretty=false, $level=0) { // Leaf filter if ($this -> is_leaf()) { if ($pretty) return ( str_repeat("\t", $level). sprintf("(%s%s%s)", $this -> attr_name, $this -> op, $this -> pattern). ($level?"\n":"") ); return sprintf("(%s%s%s)", $this -> attr_name, $this -> op, $this -> pattern); } // Combine filter if ($this -> is_combine()) { $return = ''; foreach ($this->sub_filters as $filter) $return .= $filter -> as_string($pretty, $level+1); if ($pretty) return ( str_repeat("\t", $level). "(".$this -> log_op."\n". $return. str_repeat("\t", $level).")". ($level?"\n":"") ); return sprintf("(%s%s)", $this -> log_op, $return); } // May never occured throw new FilterException('Filter is not leaf nor combine one?!'); } /** * Combine LDAP filter objects or strings using a logical operator * * @param string $log_op The locical operator. May be "and", "or", "not" or the subsequent logical * equivalents "&", "|", "!" * @param array> $args LDAP filters to combine: could be * LDAP objects, LDAP strings or array of * LDAP objects or LDAP strings. * @throws CombineException * @return Filter * @static */ public static function combine($log_op, ...$args) { // Unalias & check logical operator $log_op = self :: unalias_log_op($log_op); if (!$log_op) throw new CombineException('Invalid logical operator provided!'); // Convert args as filters $filters = array(); foreach ($args as $arg) { if (!is_array($arg)) $arg = array($arg); foreach ($arg as $a) { if (is_string($a)) $a = self :: parse($a); if (!$a instanceof Filter) throw new CombineException( 'Invalid filter provided: must be a Filter object or a LDAP filter string!' ); $filters[] = $a; } } // Check number of filters against logical operator if (self :: is_not_op($log_op)) { if (count($filters) != 1) throw new CombineException('NOT operator accept only one filter!'); } return new Filter($log_op, ...$filters); } /** * Parse an LDAP filter string * @param string $value The LDAP filter string to parse * @throws ParserException * @static * @return Filter */ public static function parse($value) { // Only handle filter enclosed with brackets if (!preg_match('/^\((.+?)\)$/', $value, $matches)) return self :: parse("($value)"); // Check for right bracket syntax: count of unescaped opening // brackets must match count of unescaped closing brackets. // At this stage we may have: // 1. one filter component with already removed outer brackets // 2. one or more subfilter components $c_openbracks = preg_match_all('/(?1 is too deep, 1 is ok, 0 is outside any // subcomponent for ($curpos = 0; $curpos < strlen($remaining_component); $curpos++) { $cur_char = substr($remaining_component, $curpos, 1); // rise/lower bracket level if ($cur_char == '(' && $prev_char != '\\') { $level++; } elseif ($cur_char == ')' && $prev_char != '\\') { $level--; } if ($cur_char == '(' && $prev_char == ')' && $level == 1) { array_push($sub_index_pos, $curpos); // mark the position for splitting } $prev_char = $cur_char; } // now perform the splits. To get also the last part, we // need to add the "END" index to the split array array_push($sub_index_pos, strlen($remaining_component)); $subfilters = array(); $oldpos = 0; foreach ($sub_index_pos as $s_pos) { $str_part = substr($remaining_component, $oldpos, $s_pos - $oldpos); array_push($subfilters, $str_part); $oldpos = $s_pos; } // some error checking... if (count($subfilters) > 1) { // several subfilters found if ($log_op == "!") { throw new ParserException( "Filter parsing error: invalid filter syntax - NOT operator detected but ". "several arguments given!" ); } } // Now parse the subfilters into objects and combine them using the operator $subfilters_o = array(); foreach ($subfilters as $subfilter) { array_push($subfilters_o, self :: parse($subfilter)); } return self :: combine($log_op, $subfilters_o); } // This is one leaf filter component, do some syntax checks, then escape and build filter_o // $matches[1] should be now something like "foo=bar" // detect multiple leaf components // [TODO] Maybe this will make problems with filters containing brackets inside the value if (stristr($matches[1], ')') || stristr($matches[1], '(')) { throw new ParserException( "Filter parsing error: invalid filter syntax - multiple leaf components ". "detected!" ); } $filter_parts = self :: split_attr_string($matches[1]); if (!is_array($filter_parts) || count($filter_parts) != 3) { throw new ParserException( "Filter parsing error: invalid filter syntax - unknown matching rule used"); } $filter_parts[] = false; // Disable escaping return new Filter(...$filter_parts); } /** * Splits an attribute=value syntax into an array * @param string $value * @static * @return array|false */ public static function split_attr_string($value) { $splited_value = preg_split( '/(?