1<?php
2
3/**
4 * This file is part of the FreeDSx LDAP package.
5 *
6 * (c) Chad Sikorra <Chad.Sikorra@gmail.com>
7 *
8 * For the full copyright and license information, please view the LICENSE
9 * file that was distributed with this source code.
10 */
11
12namespace FreeDSx\Ldap\Search;
13
14use FreeDSx\Ldap\Exception\FilterParseException;
15use FreeDSx\Ldap\Search\Filter\AndFilter;
16use FreeDSx\Ldap\Search\Filter\ApproximateFilter;
17use FreeDSx\Ldap\Search\Filter\EqualityFilter;
18use FreeDSx\Ldap\Search\Filter\FilterInterface;
19use FreeDSx\Ldap\Search\Filter\GreaterThanOrEqualFilter;
20use FreeDSx\Ldap\Search\Filter\LessThanOrEqualFilter;
21use FreeDSx\Ldap\Search\Filter\MatchingRuleFilter;
22use FreeDSx\Ldap\Search\Filter\NotFilter;
23use FreeDSx\Ldap\Search\Filter\OrFilter;
24use FreeDSx\Ldap\Search\Filter\PresentFilter;
25use FreeDSx\Ldap\Search\Filter\SubstringFilter;
26
27/**
28 * Provides some simple factory methods for building filters.
29 *
30 * @author Chad Sikorra <Chad.Sikorra@gmail.com>
31 */
32class Filters
33{
34    /**
35     * Create a logical 'and' filter, containing other filters.
36     *
37     * @param FilterInterface ...$filters
38     * @return AndFilter
39     */
40    public static function and(FilterInterface ...$filters): AndFilter
41    {
42        return new AndFilter(...$filters);
43    }
44
45    /**
46     * Create a logical 'or' filter, containing other filters.
47     *
48     * @param FilterInterface ...$filters
49     * @return OrFilter
50     */
51    public static function or(FilterInterface ...$filters): OrFilter
52    {
53        return new OrFilter(...$filters);
54    }
55
56    /**
57     * Create a simple equality value check filter.
58     *
59     * @param string $attribute
60     * @param string $value
61     * @return EqualityFilter
62     */
63    public static function equal(string $attribute, string $value): EqualityFilter
64    {
65        return new EqualityFilter($attribute, $value);
66    }
67
68    /**
69     * Create a filter to check for the negation of another filter.
70     *
71     * @param FilterInterface $filter
72     * @return NotFilter
73     */
74    public static function not(FilterInterface $filter): NotFilter
75    {
76        return new NotFilter($filter);
77    }
78
79    /**
80     * A greater-than-or-equal-to check filter.
81     *
82     * @param string $attribute
83     * @param string $value
84     * @return GreaterThanOrEqualFilter
85     */
86    public static function greaterThanOrEqual(string $attribute, string $value): GreaterThanOrEqualFilter
87    {
88        return new GreaterThanOrEqualFilter($attribute, $value);
89    }
90
91    /**
92     * An alias of greaterThanOrEqual.
93     *
94     * @param string $attribute
95     * @param string $value
96     * @return GreaterThanOrEqualFilter
97     */
98    public static function gte(string $attribute, string $value): GreaterThanOrEqualFilter
99    {
100        return self::greaterThanOrEqual($attribute, $value);
101    }
102
103    /**
104     * A less-than-or-equal-to check filter.
105     *
106     * @param string $attribute
107     * @param string $value
108     * @return LessThanOrEqualFilter
109     */
110    public static function lessThanOrEqual(string $attribute, string $value): LessThanOrEqualFilter
111    {
112        return new LessThanOrEqualFilter($attribute, $value);
113    }
114
115    /**
116     * An alias of lessThanOrEqual.
117     *
118     * @param string $attribute
119     * @param string $value
120     * @return LessThanOrEqualFilter
121     */
122    public static function lte(string $attribute, string $value): LessThanOrEqualFilter
123    {
124        return self::lessThanOrEqual($attribute, $value);
125    }
126
127    /**
128     * Check if any attribute value is present.
129     *
130     * @param string $attribute
131     * @return PresentFilter
132     */
133    public static function present(string $attribute): PresentFilter
134    {
135        return new PresentFilter($attribute);
136    }
137
138    /**
139     * Create a substring filter (starts with, ends with, contains).
140     *
141     * @param string $attribute
142     * @param null|string $startsWith
143     * @param null|string $endsWith
144     * @param string ...$contains
145     * @return SubstringFilter
146     */
147    public static function substring(string $attribute, ?string $startsWith, ?string $endsWith, string ...$contains): SubstringFilter
148    {
149        return new SubstringFilter($attribute, $startsWith, $endsWith, ...$contains);
150    }
151
152    /**
153     * Creates a substring filter to specifically check if an attribute value contains a value.
154     *
155     * @param string $attribute
156     * @param string ...$values
157     * @return SubstringFilter
158     */
159    public static function contains(string $attribute, string ...$values): SubstringFilter
160    {
161        return new SubstringFilter($attribute, null, null, ...$values);
162    }
163
164    /**
165     * Check if an attribute value ends with a specific value.
166     *
167     * @param string $attribute
168     * @param string $value
169     * @return SubstringFilter
170     */
171    public static function endsWith(string $attribute, string $value): SubstringFilter
172    {
173        return new SubstringFilter($attribute, null, $value);
174    }
175
176    /**
177     * Check if an attribute value starts with a specific value.
178     *
179     * @param string $attribute
180     * @param string $value
181     * @return SubstringFilter
182     */
183    public static function startsWith(string $attribute, string $value): SubstringFilter
184    {
185        return new SubstringFilter($attribute, $value);
186    }
187
188    /**
189     * Create an extensible matching rule.
190     *
191     * @param null|string $attribute
192     * @param string $value
193     * @param null|string $rule
194     * @param bool $matchDn
195     * @return MatchingRuleFilter
196     */
197    public static function extensible(?string $attribute, string $value, ?string $rule, bool $matchDn = false): MatchingRuleFilter
198    {
199        return new MatchingRuleFilter($rule, $attribute, $value, $matchDn);
200    }
201
202    /**
203     * Create an approximate equality check (directory specific implementation).
204     *
205     * @param string $attribute
206     * @param string $value
207     * @return ApproximateFilter
208     */
209    public static function approximate(string $attribute, string $value): ApproximateFilter
210    {
211        return new ApproximateFilter($attribute, $value);
212    }
213
214    /**
215     * Create a filter object based off a string LDAP filter. For example, the filter "(cn=foo)" would return an
216     * equality filter object.
217     *
218     * @param string $filter
219     * @return FilterInterface
220     * @throws FilterParseException
221     */
222    public static function raw(string $filter): FilterInterface
223    {
224        return FilterParser::parse($filter);
225    }
226}
227