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