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