1 <?php
2 /*
3 Copyright (c) 2012, University of Cambridge Computing Service
4
5 This file is part of the Lookup/Ibis client library.
6
7 This library is free software: you can redistribute it and/or modify
8 it under the terms of the GNU Lesser General Public License as published
9 by the Free Software Foundation, either version 3 of the License, or
10 (at your option) any later version.
11
12 This library is distributed in the hope that it will be useful, but
13 WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
14 or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public
15 License for more details.
16
17 You should have received a copy of the GNU Lesser General Public License
18 along with this library. If not, see <http://www.gnu.org/licenses/>.
19 */
20
21 require_once "IbisDto.php";
22 require_once "IbisGroup.php";
23 require_once "IbisInstitution.php";
24
25 /**
26 * Class representing a person returned by the web service API. Note that
27 * the identifier is the person's primary identifier (typically their CRSid),
28 * regardless of which identifier was used to query for the person.
29 *
30 * @author Dean Rasheed (dev-group@ucs.cam.ac.uk)
31 */
32 class IbisPerson extends IbisDto
33 {
34 /* Properties marked as @XmlAttribte in the JAXB class */
35 protected static $xmlAttrs = array("cancelled", "id", "ref");
36
37 /* Properties marked as @XmlElement in the JAXB class */
38 protected static $xmlElems = array("identifier", "displayName",
39 "registeredName", "surname",
40 "visibleName", "misAffiliation");
41
42 /* Properties marked as @XmlElementWrapper in the JAXB class */
43 protected static $xmlArrays = array("identifiers", "attributes",
44 "institutions", "groups",
45 "directGroups");
46
47 /** @var boolean Flag indicating if the person is cancelled. */
48 public $cancelled;
49
50 /**
51 * @var IbisIdentifier The person's primary identifier (typically their
52 * CRSid).
53 */
54 public $identifier;
55
56 /** @var string The person's display name (if visible). */
57 public $displayName;
58
59 /** @var string The person's registered name (if visible). */
60 public $registeredName;
61
62 /** @var string The person's surname (if visible). */
63 public $surname;
64
65 /**
66 * @var string The person's display name if that is visible, otherwise
67 * their registered name if that is visible, otherwise their surname if
68 * that is visible, otherwise the value of their primary identifier
69 * (typically their CRSid) which is always visible.
70 */
71 public $visibleName;
72
73 /**
74 * @var string The person's MIS status (``"staff"``, ``"student"``,
75 * ``"staff,student"`` or ``""``).
76 */
77 public $misAffiliation;
78
79 /**
80 * @var IbisIdentifier[] A list of the person's identifiers. This will
81 * only be populated if the ``fetch`` parameter includes the
82 * ``"all_identifiers"`` option.
83 */
84 public $identifiers;
85
86 /**
87 * @var IbisAttribute[] A list of the person's attributes. This will only
88 * be populated if the ``fetch`` parameter includes the ``"all_attrs"``
89 * option, or any specific attribute schemes such as ``"email"`` or
90 * ``"title"``, or the special pseudo-attribute scheme
91 * ``"phone_numbers"``.
92 */
93 public $attributes;
94
95 /**
96 * @var IbisInstitution[] A list of all the institution's to which the
97 * person belongs. This will only be populated if the ``fetch`` parameter
98 * includes the ``"all_insts"`` option.
99 */
100 public $institutions;
101
102 /**
103 * @var IbisGroup[] A list of all the groups to which the person belongs,
104 * including indirect group memberships, via groups that include other
105 * groups. This will only be populated if the ``fetch`` parameter
106 * includes the ``"all_groups"`` option.
107 */
108 public $groups;
109
110 /**
111 * @var IbisGroup[] A list of all the groups that the person directly
112 * belongs to. This does not include indirect group memberships - i.e.,
113 * groups that include these groups. This will only be populated if the
114 * ``fetch`` parameter includes the ``"direct_groups"`` option.
115 */
116 public $directGroups;
117
118 /**
119 * @ignore
120 * @var string An ID that can uniquely identify this person within the
121 * returned XML/JSON document. This is only used in the flattened
122 * XML/JSON representation (if the "flatten" parameter is specified).
123 */
124 public $id;
125
126 /**
127 * @ignore
128 * @var string A reference (by id) to a person element in the XML/JSON
129 * document. This is only used in the flattened XML/JSON representation
130 * (if the "flatten" parameter is specified).
131 */
132 public $ref;
133
134 /* Flag to prevent infinite recursion due to circular references. */
135 private $unflattened;
136
137 /**
138 * @ignore
139 * Create an IbisPerson from the attributes of an XML node.
140 *
141 * @param array $attrs The attributes on the XML node.
142 */
143 public function __construct($attrs=array())
144 {
145 parent::__construct($attrs);
146 if (isset($this->cancelled))
147 $this->cancelled = strcasecmp($this->cancelled, "true") == 0;
148 $this->unflattened = false;
149 }
150
151 /**
152 * Returns ``true`` if the person is a member of staff.
153 *
154 * Note that this tests for an misAffiliation of ``""``, ``"staff"`` or
155 * ``"staff,student"`` since some members of staff will have a blank
156 * misAffiliation.
157 *
158 * @return boolean ``true`` if the person is a member of staff.
159 */
160 public function isStaff()
161 {
162 return is_null($this->misAffiliation) ||
163 $this->misAffiliation !== "student";
164 }
165
166 /**
167 * Returns ``true`` if the person is a student.
168 *
169 * This tests for an misAffiliation of ``"student"`` or
170 * ``"staff,student"``.
171 *
172 * @return boolean ``true`` if the person is a student.
173 */
174 public function isStudent()
175 {
176 return isset($this->misAffiliation) &&
177 strpos($this->misAffiliation, "student") !== false;
178 }
179
180 /**
181 * @ignore
182 * Unflatten a single IbisPerson.
183 *
184 * @param IbisResultEntityMap $em The mapping from IDs to entities.
185 */
186 public function unflatten($em)
187 {
188 if (isset($this->ref))
189 {
190 $person = $em->getPerson($this->ref);
191 if (!$person->unflattened)
192 {
193 $person->unflattened = true;
194 IbisInstitution::unflattenInsts($em, $person->institutions);
195 IbisGroup::unflattenGroups($em, $person->groups);
196 IbisGroup::unflattenGroups($em, $person->directGroups);
197 }
198 return $person;
199 }
200 return $this;
201 }
202
203 /**
204 * @ignore
205 * Unflatten a list of IbisPerson objects (done in place).
206 *
207 * @param IbisResultEntityMap $em The mapping from IDs to entities.
208 * @param IbisPerson[] $people The people to unflatten.
209 */
210 public static function unflattenPeople($em, &$people)
211 {
212 if (isset($people))
213 foreach ($people as $idx => $person)
214 $people[$idx] = $person->unflatten($em);
215 }
216 }
217