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;
13
14use FreeDSx\Asn1\Type\AbstractType;
15use FreeDSx\Ldap\Control\Ad\DirSyncRequestControl;
16use FreeDSx\Ldap\Control\Ad\ExpectedEntryCountControl;
17use FreeDSx\Ldap\Control\Ad\ExtendedDnControl;
18use FreeDSx\Ldap\Control\Ad\PolicyHintsControl;
19use FreeDSx\Ldap\Control\Ad\SdFlagsControl;
20use FreeDSx\Ldap\Control\Ad\SetOwnerControl;
21use FreeDSx\Ldap\Control\Control;
22use FreeDSx\Ldap\Control\PagingControl;
23use FreeDSx\Ldap\Control\Sorting\SortingControl;
24use FreeDSx\Ldap\Control\Sorting\SortKey;
25use FreeDSx\Ldap\Control\Vlv\VlvControl;
26use FreeDSx\Ldap\Protocol\ProtocolElementInterface;
27use FreeDSx\Ldap\Search\Filter\GreaterThanOrEqualFilter;
28
29/**
30 * Provides some simple factory methods for building controls.
31 *
32 * @author Chad Sikorra <Chad.Sikorra@gmail.com>
33 */
34class Controls
35{
36    /**
37     * Create a generic control by OID.
38     *
39     * @param string $oid
40     * @param bool $criticality
41     * @param AbstractType|ProtocolElementInterface|null $value
42     * @return Control
43     */
44    public static function create(string $oid, bool $criticality = false, $value = null): Control
45    {
46        return new Control($oid, $criticality, $value);
47    }
48
49    /**
50     * Creates an AD DirSync request control.
51     *
52     * @param int $flags
53     * @param string $cookie
54     * @param int $maxBytes
55     * @return DirSyncRequestControl
56     */
57    public static function dirSync(int $flags = DirSyncRequestControl::FLAG_INCREMENTAL_VALUES, string $cookie = '', int $maxBytes = 2147483647)
58    {
59        return new DirSyncRequestControl($flags, $cookie, $maxBytes);
60    }
61
62    /**
63     * Create an AD ExpectedEntryCount control to help restrict / validate the amount of entries returned from a search.
64     *
65     * @param int $min
66     * @param int $max
67     * @return ExpectedEntryCountControl
68     */
69    public static function expectedEntryCount(int $min, int $max): ExpectedEntryCountControl
70    {
71        return new ExpectedEntryCountControl($min, $max);
72    }
73
74    /**
75     * Create an AD ExtendedDn control.
76     *
77     * @param bool $useHexFormat
78     * @return ExtendedDnControl
79     */
80    public static function extendedDn(bool $useHexFormat = false): ExtendedDnControl
81    {
82        return new ExtendedDnControl($useHexFormat);
83    }
84
85    /**
86     * Create a paging control with a specific size.
87     *
88     * @param int $size
89     * @param string $cookie
90     * @return PagingControl
91     */
92    public static function paging(int $size, string $cookie = ''): PagingControl
93    {
94        return new PagingControl($size, $cookie);
95    }
96
97    /**
98     * Create an AD Policy Hints control. This enforces password constraints when modifying an AD password.
99     *
100     * @param bool $isEnabled
101     * @return PolicyHintsControl
102     */
103    public static function policyHints(bool $isEnabled = true): PolicyHintsControl
104    {
105        return new PolicyHintsControl($isEnabled);
106    }
107
108    /**
109     * Create a password policy control.
110     *
111     * @param bool $criticality
112     * @return Control
113     */
114    public static function pwdPolicy(bool $criticality = true): Control
115    {
116        return new Control(Control::OID_PWD_POLICY, $criticality);
117    }
118
119    /**
120     * Create an AD Set Owner control. Pass it a string SID and use when adding objects to set the owner.
121     *
122     * @param string $sid
123     * @return SetOwnerControl
124     */
125    public static function setOwner(string $sid): SetOwnerControl
126    {
127        return new SetOwnerControl($sid);
128    }
129
130    /**
131     * Create an AD Show Deleted control. This will return deleted AD entries in a search.
132     *
133     * @return Control
134     */
135    public static function showDeleted(): Control
136    {
137        return self::create(Control::OID_SHOW_DELETED, true);
138    }
139
140    /**
141     * Create an AD Show Recycled control. This will return recycled AD entries in a search.
142     *
143     * @return Control
144     */
145    public static function showRecycled(): Control
146    {
147        return self::create(Control::OID_SHOW_RECYCLED, true);
148    }
149
150    /**
151     * Create a server side sort with a set of SortKey objects, or simple set of attribute names.
152     *
153     * @param SortKey|string ...$sortKeys
154     * @return SortingControl
155     */
156    public static function sort(...$sortKeys): SortingControl
157    {
158        $keys = [];
159        foreach ($sortKeys as $sort) {
160            $keys[] = $sort instanceof SortKey ? $sort : new SortKey($sort);
161        }
162
163        return new SortingControl(...$keys);
164    }
165
166    /**
167     * Create a control for a subtree delete. On a delete request this will do a recursive delete from the DN and all
168     * of its children.
169     *
170     * @param bool $criticality
171     * @return Control
172     */
173    public static function subtreeDelete(bool $criticality = false): Control
174    {
175        return new Control(Control::OID_SUBTREE_DELETE, $criticality);
176    }
177
178    /**
179     * Create a VLV offset based control.
180     *
181     * @param int $before
182     * @param int $after
183     * @param int $offset
184     * @param int $count
185     * @param null|string $contextId
186     * @return VlvControl
187     */
188    public static function vlv(int $before, int $after, int $offset = 1, int $count = 0, ?string $contextId = null): VlvControl
189    {
190        return new VlvControl($before, $after, $offset, $count, null, $contextId);
191    }
192
193    /**
194     * Create a VLV filter based control.
195     *
196     * @param int $before
197     * @param int $after
198     * @param GreaterThanOrEqualFilter $filter
199     * @param null|string $contextId
200     * @return VlvControl
201     */
202    public static function vlvFilter(int $before, int $after, GreaterThanOrEqualFilter $filter, ?string $contextId = null): VlvControl
203    {
204        return new VlvControl($before, $after, null, null, $filter, $contextId);
205    }
206
207    /**
208     * Create an AD SD Flags Control.
209     *
210     * @param int $flags
211     * @return SdFlagsControl
212     */
213    public static function sdFlags(int $flags): SdFlagsControl
214    {
215        return new SdFlagsControl($flags);
216    }
217}
218