1<?php
2
3/* vim: set expandtab tabstop=4 shiftwidth=4 softtabstop=4: */
4
5/**
6 * Contains a data class representing a GPG user id
7 *
8 * LICENSE:
9 *
10 * This library is free software; you can redistribute it and/or modify
11 * it under the terms of the GNU Lesser General Public License as
12 * published by the Free Software Foundation; either version 2.1 of the
13 * License, or (at your option) any later version.
14 *
15 * This library is distributed in the hope that it will be useful,
16 * but WITHOUT ANY WARRANTY; without even the implied warranty of
17 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
18 * Lesser General Public License for more details.
19 *
20 * You should have received a copy of the GNU Lesser General Public
21 * License along with this library; if not, see
22 * <http://www.gnu.org/licenses/>
23 *
24 * @category  Encryption
25 * @package   Crypt_GPG
26 * @author    Michael Gauthier <mike@silverorange.com>
27 * @copyright 2008-2010 silverorange
28 * @license   http://www.gnu.org/copyleft/lesser.html LGPL License 2.1
29 * @link      http://pear.php.net/package/Crypt_GPG
30 */
31
32/**
33 * A class for GPG user id information
34 *
35 * This class is used to store the results of the {@link Crypt_GPG::getKeys()}
36 * method. User id objects are members of a {@link Crypt_GPG_Key} object.
37 *
38 * @category  Encryption
39 * @package   Crypt_GPG
40 * @author    Michael Gauthier <mike@silverorange.com>
41 * @copyright 2008-2010 silverorange
42 * @license   http://www.gnu.org/copyleft/lesser.html LGPL License 2.1
43 * @link      http://pear.php.net/package/Crypt_GPG
44 * @see       Crypt_GPG::getKeys()
45 * @see       Crypt_GPG_Key::getUserIds()
46 */
47class Crypt_GPG_UserId
48{
49    /**
50     * The name field of this user id
51     *
52     * @var string
53     */
54    private $_name = '';
55
56    /**
57     * The comment field of this user id
58     *
59     * @var string
60     */
61    private $_comment = '';
62
63    /**
64     * The email field of this user id
65     *
66     * @var string
67     */
68    private $_email = '';
69
70    /**
71     * Whether or not this user id is revoked
72     *
73     * @var boolean
74     */
75    private $_isRevoked = false;
76
77    /**
78     * Whether or not this user id is valid
79     *
80     * @var boolean
81     */
82    private $_isValid = true;
83
84    /**
85     * Creates a new user id
86     *
87     * User ids can be initialized from an array of named values. Available
88     * names are:
89     *
90     * - <kbd>string  name</kbd>    - the name field of the user id.
91     * - <kbd>string  comment</kbd> - the comment field of the user id.
92     * - <kbd>string  email</kbd>   - the email field of the user id.
93     * - <kbd>boolean valid</kbd>   - whether or not the user id is valid.
94     * - <kbd>boolean revoked</kbd> - whether or not the user id is revoked.
95     *
96     * @param Crypt_GPG_UserId|string|array|null $userId Either an existing user id object,
97     *                                                   which is copied; a user id string,
98     *                                                   which is parsed; or an array of
99     *                                                   initial values.
100     */
101    public function __construct($userId = null)
102    {
103        // parse from string
104        if (is_string($userId)) {
105            $userId = self::parse($userId);
106        }
107
108        // copy from object
109        if ($userId instanceof Crypt_GPG_UserId) {
110            $this->_name      = $userId->_name;
111            $this->_comment   = $userId->_comment;
112            $this->_email     = $userId->_email;
113            $this->_isRevoked = $userId->_isRevoked;
114            $this->_isValid   = $userId->_isValid;
115        }
116
117        // initialize from array
118        if (is_array($userId)) {
119            if (array_key_exists('name', $userId)) {
120                $this->setName($userId['name']);
121            }
122
123            if (array_key_exists('comment', $userId)) {
124                $this->setComment($userId['comment']);
125            }
126
127            if (array_key_exists('email', $userId)) {
128                $this->setEmail($userId['email']);
129            }
130
131            if (array_key_exists('revoked', $userId)) {
132                $this->setRevoked($userId['revoked']);
133            }
134
135            if (array_key_exists('valid', $userId)) {
136                $this->setValid($userId['valid']);
137            }
138        }
139    }
140
141    /**
142     * Gets the name field of this user id
143     *
144     * @return string the name field of this user id.
145     */
146    public function getName()
147    {
148        return $this->_name;
149    }
150
151    /**
152     * Gets the comments field of this user id
153     *
154     * @return string the comments field of this user id.
155     */
156    public function getComment()
157    {
158        return $this->_comment;
159    }
160
161    /**
162     * Gets the email field of this user id
163     *
164     * @return string the email field of this user id.
165     */
166    public function getEmail()
167    {
168        return $this->_email;
169    }
170
171    /**
172     * Gets whether or not this user id is revoked
173     *
174     * @return boolean true if this user id is revoked and false if it is not.
175     */
176    public function isRevoked()
177    {
178        return $this->_isRevoked;
179    }
180
181    /**
182     * Gets whether or not this user id is valid
183     *
184     * @return boolean true if this user id is valid and false if it is not.
185     */
186    public function isValid()
187    {
188        return $this->_isValid;
189    }
190
191    /**
192     * Gets a string representation of this user id
193     *
194     * The string is formatted as:
195     * <b><kbd>name (comment) <email-address></kbd></b>.
196     *
197     * @return string a string representation of this user id.
198     */
199    public function __toString()
200    {
201        $components = array();
202
203        if (mb_strlen($this->_name, '8bit') > 0) {
204            $components[] = $this->_name;
205        }
206
207        if (mb_strlen($this->_comment, '8bit') > 0) {
208            $components[] = '(' . $this->_comment . ')';
209        }
210
211        if (mb_strlen($this->_email, '8bit') > 0) {
212            $components[] = '<' . $this->_email. '>';
213        }
214
215        return implode(' ', $components);
216    }
217
218    /**
219     * Sets the name field of this user id
220     *
221     * @param string $name the name field of this user id.
222     *
223     * @return Crypt_GPG_UserId the current object, for fluent interface.
224     */
225    public function setName($name)
226    {
227        $this->_name = strval($name);
228        return $this;
229    }
230
231    /**
232     * Sets the comment field of this user id
233     *
234     * @param string $comment the comment field of this user id.
235     *
236     * @return Crypt_GPG_UserId the current object, for fluent interface.
237     */
238    public function setComment($comment)
239    {
240        $this->_comment = strval($comment);
241        return $this;
242    }
243
244    /**
245     * Sets the email field of this user id
246     *
247     * @param string $email the email field of this user id.
248     *
249     * @return Crypt_GPG_UserId the current object, for fluent interface.
250     */
251    public function setEmail($email)
252    {
253        $this->_email = strval($email);
254        return $this;
255    }
256
257    /**
258     * Sets whether or not this user id is revoked
259     *
260     * @param boolean $isRevoked whether or not this user id is revoked.
261     *
262     * @return Crypt_GPG_UserId the current object, for fluent interface.
263     */
264    public function setRevoked($isRevoked)
265    {
266        $this->_isRevoked = ($isRevoked) ? true : false;
267        return $this;
268    }
269
270    /**
271     * Sets whether or not this user id is valid
272     *
273     * @param boolean $isValid whether or not this user id is valid.
274     *
275     * @return Crypt_GPG_UserId the current object, for fluent interface.
276     */
277    public function setValid($isValid)
278    {
279        $this->_isValid = ($isValid) ? true : false;
280        return $this;
281    }
282
283    /**
284     * Parses a user id object from a user id string
285     *
286     * A user id string is of the form:
287     * <b><kbd>name (comment) <email-address></kbd></b> with the <i>comment</i>
288     * and <i>email-address</i> fields being optional.
289     *
290     * @param string $string the user id string to parse.
291     *
292     * @return Crypt_GPG_UserId the user id object parsed from the string.
293     */
294    public static function parse($string)
295    {
296        $userId  = new Crypt_GPG_UserId();
297        $name    = '';
298        $email   = '';
299        $comment = '';
300
301        // get email address from end of string if it exists
302        $matches = array();
303        if (preg_match('/^(.*?)<([^>]+)>$/', $string, $matches) === 1) {
304            $string = trim($matches[1]);
305            $email  = $matches[2];
306        }
307
308        // get comment from end of string if it exists
309        $matches = array();
310        if (preg_match('/^(.+?) \(([^\)]+)\)$/', $string, $matches) === 1) {
311            $string  = $matches[1];
312            $comment = $matches[2];
313        }
314
315        // there can be an email without a name
316        if (!$email && preg_match('/^[\S]+@[\S]+$/', $string, $matches) === 1) {
317            $email = $string;
318        } else {
319            $name = $string;
320        }
321
322        $userId->setName($name);
323        $userId->setComment($comment);
324        $userId->setEmail($email);
325
326        return $userId;
327    }
328}
329