1 <?php
2 /* === AUTO-GENERATED - DO NOT EDIT === */
3
4 /*
5 Copyright (c) 2012, University of Cambridge Computing Service
6
7 This file is part of the Lookup/Ibis client library.
8
9 This library is free software: you can redistribute it and/or modify
10 it under the terms of the GNU Lesser General Public License as published
11 by the Free Software Foundation, either version 3 of the License, or
12 (at your option) any later version.
13
14 This library is distributed in the hope that it will be useful, but
15 WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
16 or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public
17 License for more details.
18
19 You should have received a copy of the GNU Lesser General Public License
20 along with this library. If not, see <http://www.gnu.org/licenses/>.
21 */
22
23 require_once dirname(__FILE__) . "/../client/IbisException.php";
24
25 /**
26 * Methods for querying and manipulating groups.
27 *
28 * **The fetch parameter for groups**
29 *
30 * All methods that return groups also accept an optional ``fetch``
31 * parameter that may be used to request additional information about the
32 * groups returned. For more details about the general rules that apply to
33 * the ``fetch`` parameter, refer to the {@link PersonMethods}
34 * documentation.
35 *
36 * For groups the ``fetch`` parameter may be used to fetch references
37 * to people, institutions or other groups. In each case, only non-cancelled
38 * people, institutions and groups will be included when fetching references.
39 * The following references are supported:
40 *
41 * * ``"all_members"`` - fetches all the people who are members of the
42 * group, including members of groups included by the group, and groups
43 * included by those groups, and so on.
44 *
45 * * ``"direct_members"`` - fetches all the people who are direct
46 * members of the group, not taking into account any included groups.
47 *
48 * * ``"members_of_inst"`` - if the group is a membership group for an
49 * institution, this fetches that institution.
50 *
51 * * ``"owning_insts"`` - fetches all the institutions to which the
52 * group belongs.
53 *
54 * * ``"manages_insts"`` - fetches all the institutions that the group
55 * manages. Typically this only applies to "Editor" groups.
56 *
57 * * ``"manages_groups"`` - fetches all the groups that this group
58 * manages. Note that some groups are self-managed, so this may be a
59 * self-reference.
60 *
61 * * ``"managed_by_groups"`` - fetches all the groups that manage this
62 * group.
63 *
64 * * ``"reads_groups"`` - fetches all the groups that this group has
65 * privileged access to. This means that members of this group can see the
66 * members of the referenced groups regardless of the membership visibility
67 * settings.
68 *
69 * * ``"read_by_groups"`` - fetches all the groups that have privileged
70 * access to this group.
71 *
72 * * ``"includes_groups"`` - fetches all the groups included by this
73 * group.
74 *
75 * * ``"included_by_groups"`` - fetches all the groups that include
76 * this group.
77 *
78 * As with person ``fetch`` parameters, the references may be used
79 * in a chain by using the "dot" notation to fetch additional information
80 * about referenced people, institutions or groups. For example
81 * ``"all_members.email"`` will fetch the email addresses of all members
82 * of the group. For more information about what can be fetched from
83 * referenced people and institutions, refer to the documentation for
84 * {@link PersonMethods} and {@link InstitutionMethods}.
85 *
86 * @author Dean Rasheed (dev-group@ucs.cam.ac.uk)
87 */
88 class GroupMethods
89 {
90 // The connection to the server
91 private $conn;
92
93 /**
94 * Create a new GroupMethods object.
95 *
96 * @param ClientConnection $conn The ClientConnection object to use to
97 * invoke methods on the server.
98 */
99 public function __construct($conn)
100 {
101 $this->conn = $conn;
102 }
103
104 /**
105 * Return a list of all groups.
106 *
107 * By default, only a few basic details about each group are returned,
108 * but the optional ``fetch`` parameter may be used to fetch
109 * additional attributes or references.
110 *
111 * ``[ HTTP: GET /api/v1/group/all-groups ]``
112 *
113 * @param boolean $includeCancelled [optional] Whether or not to include cancelled
114 * groups. By default, only live groups are returned.
115 * @param string $fetch [optional] A comma-separated list of any additional
116 * attributes or references to fetch.
117 *
118 * @return IbisGroup[] The requested groups (in groupid order).
119 */
120 public function allGroups($includeCancelled,
121 $fetch=null)
122 {
123 $pathParams = array();
124 $queryParams = array("includeCancelled" => $includeCancelled,
125 "fetch" => $fetch);
126 $formParams = array();
127 $result = $this->conn->invokeMethod("GET",
128 'api/v1/group/all-groups',
129 $pathParams,
130 $queryParams,
131 $formParams);
132 if (isset($result->error))
133 throw new IbisException($result->error);
134 return $result->groups;
135 }
136
137 /**
138 * Get the groups with the specified IDs or names.
139 *
140 * By default, only a few basic details about each group are returned,
141 * but the optional ``fetch`` parameter may be used to fetch
142 * additional attributes or references.
143 *
144 * The results are sorted by groupid.
145 *
146 * NOTE: The URL path length is limited to around 8000 characters,
147 * which limits the number of groups that this method can fetch. Group
148 * IDs are currently 6 characters long, and must be comma separated and
149 * URL encoded, which limits this method to around 800 groups by ID,
150 * but probably fewer by name, depending on the group name lengths.
151 *
152 * NOTE: The groups returned may include cancelled groups. It is the
153 * caller's responsibility to check their cancelled flags.
154 *
155 * ``[ HTTP: GET /api/v1/group/list?groupids=... ]``
156 *
157 * @param string $groupids [required] A comma-separated list of group IDs or
158 * group names (may be a mix of both).
159 * @param string $fetch [optional] A comma-separated list of any additional
160 * attributes or references to fetch.
161 *
162 * @return IbisGroup[] The requested groups (in groupid order).
163 */
164 public function listGroups($groupids,
165 $fetch=null)
166 {
167 $pathParams = array();
168 $queryParams = array("groupids" => $groupids,
169 "fetch" => $fetch);
170 $formParams = array();
171 $result = $this->conn->invokeMethod("GET",
172 'api/v1/group/list',
173 $pathParams,
174 $queryParams,
175 $formParams);
176 if (isset($result->error))
177 throw new IbisException($result->error);
178 return $result->groups;
179 }
180
181 /**
182 * Find all groups modified between the specified pair of transactions.
183 *
184 * The transaction IDs specified should be the IDs from two different
185 * requests for the last (most recent) transaction ID, made at different
186 * times, that returned different values, indicating that some Lookup
187 * data was modified in the period between the two requests. This method
188 * then determines which (if any) groups were affected.
189 *
190 * By default, only a few basic details about each group are returned,
191 * but the optional ``fetch`` parameter may be used to fetch
192 * additional attributes or references.
193 *
194 * NOTE: All data returned reflects the latest available data about each
195 * group. It is not possible to query for old data, or more detailed
196 * information about the specific changes made.
197 *
198 * ``[ HTTP: GET /api/v1/group/modified-groups?minTxId=...&maxTxId=... ]``
199 *
200 * @param long $minTxId [required] Include modifications made in transactions
201 * after (but not including) this one.
202 * @param long $maxTxId [required] Include modifications made in transactions
203 * up to and including this one.
204 * @param string $groupids [optional] Only include groups with IDs or names in
205 * this list. By default, all modified groups will be included.
206 * @param boolean $includeCancelled [optional] Include cancelled groups. By
207 * default, cancelled groups are excluded.
208 * @param boolean $membershipChanges [optional] Include groups whose members have
209 * changed. By default, changes to group memberships are not taken into
210 * consideration.
211 * @param string $fetch [optional] A comma-separated list of any additional
212 * attributes or references to fetch.
213 *
214 * @return IbisGroup[] The modified groups (in groupid order).
215 */
216 public function modifiedGroups($minTxId,
217 $maxTxId,
218 $groupids=null,
219 $includeCancelled=null,
220 $membershipChanges=null,
221 $fetch=null)
222 {
223 $pathParams = array();
224 $queryParams = array("minTxId" => $minTxId,
225 "maxTxId" => $maxTxId,
226 "groupids" => $groupids,
227 "includeCancelled" => $includeCancelled,
228 "membershipChanges" => $membershipChanges,
229 "fetch" => $fetch);
230 $formParams = array();
231 $result = $this->conn->invokeMethod("GET",
232 'api/v1/group/modified-groups',
233 $pathParams,
234 $queryParams,
235 $formParams);
236 if (isset($result->error))
237 throw new IbisException($result->error);
238 return $result->groups;
239 }
240
241 /**
242 * Search for groups using a free text query string. This is the same
243 * search function that is used in the Lookup web application.
244 *
245 * By default, only a few basic details about each group are returned,
246 * but the optional ``fetch`` parameter may be used to fetch
247 * additional attributes or references.
248 *
249 * NOTE: If the query string starts with the prefix ``"group:"``, it
250 * is treated as an <a href="/lql" target="_top">LQL query</a>, allowing
251 * more advanced searches. An LQL query will ignore the
252 * ``approxMatches`` parameter, but it will respect the value of
253 * ``includeCancelled``. In addition, an LQL query will ignore
254 * the ``orderBy`` parameter, since LQL queries always return
255 * results in ID order.
256 *
257 * ``[ HTTP: GET /api/v1/group/search?query=... ]``
258 *
259 * @param string $query [required] The search string.
260 * @param boolean $approxMatches [optional] Flag to enable more approximate
261 * matching in the search, causing more results to be returned. Defaults
262 * to ``false``. This is ignored for LQL queries.
263 * @param boolean $includeCancelled [optional] Flag to allow cancelled groups to
264 * be included. Defaults to ``false``.
265 * @param int $offset [optional] The number of results to skip at the start
266 * of the search. Defaults to 0.
267 * @param int $limit [optional] The maximum number of results to return.
268 * Defaults to 100.
269 * @param string $orderBy [optional] The order in which to list the results.
270 * This may be ``"groupid"``, ``"name"`` (the default for non-LQL
271 * queries) or ``"title"``. This is ignored for LQL queries, which
272 * always return results in groupid order.
273 * @param string $fetch [optional] A comma-separated list of any additional
274 * attributes or references to fetch.
275 *
276 * @return IbisGroup[] The matching groups.
277 */
278 public function search($query,
279 $approxMatches=null,
280 $includeCancelled=null,
281 $offset=null,
282 $limit=null,
283 $orderBy=null,
284 $fetch=null)
285 {
286 $pathParams = array();
287 $queryParams = array("query" => $query,
288 "approxMatches" => $approxMatches,
289 "includeCancelled" => $includeCancelled,
290 "offset" => $offset,
291 "limit" => $limit,
292 "orderBy" => $orderBy,
293 "fetch" => $fetch);
294 $formParams = array();
295 $result = $this->conn->invokeMethod("GET",
296 'api/v1/group/search',
297 $pathParams,
298 $queryParams,
299 $formParams);
300 if (isset($result->error))
301 throw new IbisException($result->error);
302 return $result->groups;
303 }
304
305 /**
306 * Count the number of groups that would be returned by a search using
307 * a free text query string.
308 *
309 * NOTE: If the query string starts with the prefix ``"group:"``, it
310 * is treated as an <a href="/lql" target="_top">LQL query</a>, allowing
311 * more advanced searches. An LQL query will ignore the
312 * ``approxMatches`` parameter, but it will respect the value of
313 * ``includeCancelled``.
314 *
315 * ``[ HTTP: GET /api/v1/group/search-count?query=... ]``
316 *
317 * @param string $query [required] The search string.
318 * @param boolean $approxMatches [optional] Flag to enable more approximate
319 * matching in the search, causing more results to be returned. Defaults
320 * to ``false``. This is ignored for LQL queries.
321 * @param boolean $includeCancelled [optional] Flag to allow cancelled groups to
322 * be included. Defaults to ``false``.
323 *
324 * @return int The number of matching groups.
325 */
326 public function searchCount($query,
327 $approxMatches=null,
328 $includeCancelled=null)
329 {
330 $pathParams = array();
331 $queryParams = array("query" => $query,
332 "approxMatches" => $approxMatches,
333 "includeCancelled" => $includeCancelled);
334 $formParams = array();
335 $result = $this->conn->invokeMethod("GET",
336 'api/v1/group/search-count',
337 $pathParams,
338 $queryParams,
339 $formParams);
340 if (isset($result->error))
341 throw new IbisException($result->error);
342 return intval($result->value);
343 }
344
345 /**
346 * Get the group with the specified ID or name.
347 *
348 * By default, only a few basic details about the group are returned,
349 * but the optional ``fetch`` parameter may be used to fetch
350 * additional attributes or references of the group.
351 *
352 * NOTE: The group returned may be a cancelled group. It is the caller's
353 * responsibility to check its cancelled flag.
354 *
355 * ``[ HTTP: GET /api/v1/group/{groupid} ]``
356 *
357 * @param string $groupid [required] The ID or name of the group to fetch. This
358 * may be either the numeric ID or the short hyphenated group name (for
359 * example ``"100656"`` or ``"cs-editors"``).
360 * @param string $fetch [optional] A comma-separated list of any additional
361 * attributes or references to fetch.
362 *
363 * @return IbisGroup The requested group or ``null`` if it was not found.
364 */
365 public function getGroup($groupid,
366 $fetch=null)
367 {
368 $pathParams = array("groupid" => $groupid);
369 $queryParams = array("fetch" => $fetch);
370 $formParams = array();
371 $result = $this->conn->invokeMethod("GET",
372 'api/v1/group/%1$s',
373 $pathParams,
374 $queryParams,
375 $formParams);
376 if (isset($result->error))
377 throw new IbisException($result->error);
378 return $result->group;
379 }
380
381 /**
382 * Get all the cancelled members of the specified group, including
383 * cancelled members of groups included by the group, and groups included
384 * by those groups, and so on.
385 *
386 * By default, only a few basic details about each member are returned,
387 * but the optional ``fetch`` parameter may be used to fetch
388 * additional attributes or references of each person.
389 *
390 * NOTE: This method returns only cancelled people. It does not include
391 * people who were removed from the group. Cancelled people are no longer
392 * considered to be current staff, students or accredited visitors, and
393 * are no longer regarded as belonging to any groups or institutions. The
394 * list returned here reflects their group memberships just before they
395 * were cancelled, and so is out-of-date data that should be used with
396 * caution.
397 *
398 * ``[ HTTP: GET /api/v1/group/{groupid}/cancelled-members ]``
399 *
400 * @param string $groupid [required] The ID or name of the group.
401 * @param string $fetch [optional] A comma-separated list of any additional
402 * attributes or references to fetch for each person.
403 *
404 * @return IbisPerson[] The group's cancelled members (in identifier order).
405 */
406 public function getCancelledMembers($groupid,
407 $fetch=null)
408 {
409 $pathParams = array("groupid" => $groupid);
410 $queryParams = array("fetch" => $fetch);
411 $formParams = array();
412 $result = $this->conn->invokeMethod("GET",
413 'api/v1/group/%1$s/cancelled-members',
414 $pathParams,
415 $queryParams,
416 $formParams);
417 if (isset($result->error))
418 throw new IbisException($result->error);
419 return $result->people;
420 }
421
422 /**
423 * Get the direct members of the specified group, not including members
424 * included via groups included by the group.
425 *
426 * By default, only a few basic details about each member are returned,
427 * but the optional ``fetch`` parameter may be used to fetch
428 * additional attributes or references of each person.
429 *
430 * NOTE: This method will not include cancelled people.
431 *
432 * ``[ HTTP: GET /api/v1/group/{groupid}/direct-members ]``
433 *
434 * @param string $groupid [required] The ID or name of the group.
435 * @param string $fetch [optional] A comma-separated list of any additional
436 * attributes or references to fetch for each person.
437 *
438 * @return IbisPerson[] The group's direct members (in identifier order).
439 */
440 public function getDirectMembers($groupid,
441 $fetch=null)
442 {
443 $pathParams = array("groupid" => $groupid);
444 $queryParams = array("fetch" => $fetch);
445 $formParams = array();
446 $result = $this->conn->invokeMethod("GET",
447 'api/v1/group/%1$s/direct-members',
448 $pathParams,
449 $queryParams,
450 $formParams);
451 if (isset($result->error))
452 throw new IbisException($result->error);
453 return $result->people;
454 }
455
456 /**
457 * Update the list of people who are direct members of the group. This
458 * will not affect people who are included in the group due to the
459 * inclusion of other groups.
460 *
461 * Any non-cancelled people in the list of identifiers specified by
462 * ``addIds`` will be added to the group. This list should be a
463 * comma-separated list of identifiers, each of which may be either a
464 * CRSid or an identifier from another identifier scheme, prefixed with
465 * that scheme's name and a slash. For example ``"mug99"`` or
466 * ``"usn/123456789"``.
467 *
468 * Any people in the list of identifiers specified by ``removeIds``
469 * will be removed from the group, except if they are also in the list
470 * ``addIds``. The special identifier ``"all-members"`` may be
471 * used to remove all existing group members, replacing them with the
472 * list specified by ``newIds``.
473 *
474 * **Examples:**
475 * <pre>
476 * updateDirectMembers("test-group",
477 * "mug99,crsid/yyy99,usn/123456789",
478 * "xxx99",
479 * "Remove xxx99 and add mug99, yyy99 and usn/123456789 to test-group");
480 * </pre>
481 * <pre>
482 * updateDirectMembers("test-group",
483 * "xxx99,yyy99",
484 * "all-members",
485 * "Set the membership of test-group to include only xxx99 and yyy99");
486 * </pre>
487 *
488 * ``[ HTTP: PUT /api/v1/group/{groupid}/direct-members ]``
489 *
490 * @param string $groupid [required] The ID or name of the group.
491 * @param string $addIds [optional] The identifiers of people to add to the group.
492 * @param string $removeIds [optional] The identifiers of people to remove from
493 * the group.
494 * @param string $commitComment [recommended] A short textual description of
495 * the change made (will be visible on the history tab of the group and
496 * all the affected people in the web application).
497 *
498 * @return IbisPerson[] The updated list of direct members of the group (in identifier
499 * order).
500 */
501 public function updateDirectMembers($groupid,
502 $addIds=null,
503 $removeIds=null,
504 $commitComment=null)
505 {
506 $pathParams = array("groupid" => $groupid);
507 $queryParams = array();
508 $formParams = array("addIds" => $addIds,
509 "removeIds" => $removeIds,
510 "commitComment" => $commitComment);
511 $result = $this->conn->invokeMethod("PUT",
512 'api/v1/group/%1$s/direct-members',
513 $pathParams,
514 $queryParams,
515 $formParams);
516 if (isset($result->error))
517 throw new IbisException($result->error);
518 return $result->people;
519 }
520
521 /**
522 * Get all the members of the specified group, including members of
523 * groups included by the group, and groups included by those groups,
524 * and so on.
525 *
526 * By default, only a few basic details about each member are returned,
527 * but the optional ``fetch`` parameter may be used to fetch
528 * additional attributes or references of each person.
529 *
530 * NOTE: This method will not include cancelled people.
531 *
532 * ``[ HTTP: GET /api/v1/group/{groupid}/members ]``
533 *
534 * @param string $groupid [required] The ID or name of the group.
535 * @param string $fetch [optional] A comma-separated list of any additional
536 * attributes or references to fetch for each person.
537 *
538 * @return IbisPerson[] The group's members (in identifier order).
539 */
540 public function getMembers($groupid,
541 $fetch=null)
542 {
543 $pathParams = array("groupid" => $groupid);
544 $queryParams = array("fetch" => $fetch);
545 $formParams = array();
546 $result = $this->conn->invokeMethod("GET",
547 'api/v1/group/%1$s/members',
548 $pathParams,
549 $queryParams,
550 $formParams);
551 if (isset($result->error))
552 throw new IbisException($result->error);
553 return $result->people;
554 }
555
556 /**
557 * Get a signed JSON Web Token (JWT) with the group as subject and
558 * specified audience, only if authorized user/group has permission to edit
559 * the group.
560 *
561 * ``[ HTTP: GET /api/v1/group/{groupid}/token?aud=... ]``
562 *
563 * @param string $groupid [required] The ID of the group.
564 * @param string $aud [required] Audience for the signed JWT.
565 *
566 * @return String The serialized JWT
567 */
568 public function getToken($groupid,
569 $aud)
570 {
571 $pathParams = array("groupid" => $groupid);
572 $queryParams = array("aud" => $aud);
573 $formParams = array();
574 $result = $this->conn->invokeMethod("GET",
575 'api/v1/group/%1$s/token',
576 $pathParams,
577 $queryParams,
578 $formParams);
579 if (isset($result->error))
580 throw new IbisException($result->error);
581 return $result->value;
582 }
583 }
584