Commit | Line | Data |
---|---|---|
7f254ad8 AE |
1 | <?php |
2 | /** | |
3 | * Build (create) and fetch vCard 2.1 and 3.0 text blocks. | |
4 | * | |
5 | * PHP versions 4 and 5 | |
6 | * | |
7 | * LICENSE: This source file is subject to version 3.0 of the PHP license | |
8 | * that is available through the world-wide-web at the following URI: | |
9 | * http://www.php.net/license/3_0.txt. If you did not receive a copy of | |
10 | * the PHP License and are unable to obtain it through the web, please | |
11 | * send a note to license@php.net so we can mail you a copy immediately. | |
12 | * | |
13 | * @category File_Formats | |
14 | * @package Contact_Vcard_Build | |
15 | * @author Paul M. Jones <pjones@ciaweb.net> | |
16 | * @copyright 1997-2007 The PHP Group | |
17 | * @license http://www.php.net/license/3_0.txt PHP License 3.0 | |
18 | * @version CVS: $Id: Build.php,v 1.10 2007/11/19 01:22:27 till Exp $ | |
19 | * @link http://pear.php.net/package/Contact_Vcard_Build | |
20 | */ | |
21 | ||
22 | // Part numbers for N components | |
23 | define('VCARD_N_FAMILY', 0); | |
24 | define('VCARD_N_GIVEN', 1); | |
25 | define('VCARD_N_ADDL', 2); | |
26 | define('VCARD_N_PREFIX', 3); | |
27 | define('VCARD_N_SUFFIX', 4); | |
28 | ||
29 | // Part numbers for ADR components | |
30 | define('VCARD_ADR_POB', 0); | |
31 | define('VCARD_ADR_EXTEND', 1); | |
32 | define('VCARD_ADR_STREET', 2); | |
33 | define('VCARD_ADR_LOCALITY', 3); | |
34 | define('VCARD_ADR_REGION', 4); | |
35 | define('VCARD_ADR_POSTCODE', 5); | |
36 | define('VCARD_ADR_COUNTRY', 6); | |
37 | ||
38 | // Part numbers for GEO components | |
39 | define('VCARD_GEO_LAT', 0); | |
40 | define('VCARD_GEO_LON', 1); | |
41 | ||
42 | /** | |
43 | * @ignore | |
44 | */ | |
45 | require_once 'PEAR.php'; | |
46 | ||
47 | /** | |
48 | * This class builds a single vCard (version 3.0 or 2.1). | |
49 | * | |
50 | * General note: we use the terms "set" "add" and "get" as function | |
51 | * prefixes. | |
52 | * | |
53 | * "Set" means there is only one iteration of a component, and it has | |
54 | * only one value repetition, so you set the whole thing at once. | |
55 | * | |
56 | * "Add" means eith multiple iterations of a component are allowed, or | |
57 | * that there is only one iteration allowed but there can be multiple | |
58 | * value repetitions, so you add iterations or repetitions to the current | |
59 | * stack. | |
60 | * | |
61 | * "Get" returns the full vCard line for a single iteration. | |
62 | * | |
63 | * @category File_Formats | |
64 | * @package Contact_Vcard_Build | |
65 | * @author Paul M. Jones <pjones@ciaweb.net> | |
66 | * @copyright 1997-2007 The PHP Group | |
67 | * @license http://www.php.net/license/3_0.txt PHP License 3.0 | |
68 | * @version Release: 1.1.2 | |
69 | * @link http://pear.php.net/package/Contact_Vcard_Build | |
70 | * | |
71 | */ | |
72 | class Contact_Vcard_Build extends PEAR | |
73 | { | |
74 | /** | |
75 | * Values for vCard components. | |
76 | * | |
77 | * @access public | |
78 | * @var array | |
79 | */ | |
80 | var $value = array(); | |
81 | ||
82 | /** | |
83 | * Parameters for vCard components. | |
84 | * | |
85 | * @access public | |
86 | * @var array | |
87 | */ | |
88 | var $param = array(); | |
89 | ||
90 | /** | |
91 | * Tracks which component (N, ADR, TEL, etc) value was last set or added. | |
92 | * Used when adding parameters automatically to the proper component. | |
93 | * | |
94 | * @access public | |
95 | * @var string | |
96 | */ | |
97 | var $autoparam = null; | |
98 | ||
99 | /** | |
100 | * Constructor. | |
101 | * | |
102 | * @param string $version The vCard version to build; affects which | |
103 | * parameters are allowed and which components | |
104 | * are returned by fetch(). | |
105 | * | |
106 | * @access public | |
107 | * @return void | |
108 | * @see Contact_Vcard_Build::fetch() | |
109 | */ | |
110 | function Contact_Vcard_Build($version = '3.0') | |
111 | { | |
112 | $this->PEAR(); | |
113 | $this->setErrorHandling(PEAR_ERROR_PRINT); | |
114 | $this->setVersion($version); | |
115 | } | |
116 | ||
117 | /** | |
118 | * Prepares a string so it may be safely used as vCard values. DO | |
119 | * NOT use this with binary encodings. Operates on text in-place; | |
120 | * does not return a value. Recursively descends into arrays. | |
121 | * | |
122 | * Escapes a string so that... | |
123 | * : => \; | |
124 | * ; => \; | |
125 | * , => \, | |
126 | * newline => literal \n | |
127 | * | |
128 | * @param mixed &$text The string or array or strings to escape. | |
129 | * | |
130 | * @access public | |
131 | * @return mixed Void on success, or a PEAR_Error object on failure. | |
132 | */ | |
133 | function escape(&$text) | |
134 | { | |
135 | if (is_object($text)) { | |
136 | ||
137 | $msg = 'The escape() method works only with string literals and arrays.'; | |
138 | return $this->raiseError($msg); | |
139 | ||
140 | } | |
141 | if (is_array($text)) { | |
142 | ||
143 | foreach ($text as $key => $val) { | |
144 | $this->escape($val); | |
145 | $text[$key] = $val; | |
146 | } | |
147 | return; | |
148 | } | |
149 | ||
150 | /* | |
151 | // escape colons not led by a backslash | |
152 | $regex = '(?<!\\\\)(\:)'; | |
153 | $text = preg_replace("/$regex/i", "\\:", $text); | |
154 | ||
155 | // escape semicolons not led by a backslash | |
156 | $regex = '(?<!\\\\)(\;)'; | |
157 | $text = preg_replace("/$regex/i", "\\;", $text); | |
158 | ||
159 | // escape commas not led by a backslash | |
160 | $regex = '(?<!\\\\)(\,)'; | |
161 | $text = preg_replace("/$regex/i", "\\,", $text); | |
162 | ||
163 | // escape newlines | |
164 | $regex = '\\n'; | |
165 | $text = preg_replace("/$regex/i", "\\n", $text); | |
166 | */ | |
167 | ||
168 | // combined (per note from Daniel Convissor) | |
169 | $regex = '(?<!\\\\)([\:\;\,\\n])'; | |
170 | // changed as a possible fix for Outlook compatibility [CiviCRM] | |
171 | $regex = '(?<!\\\\)([\;\\n])'; | |
172 | $text = preg_replace("/$regex/", '\\\$1', $text); | |
173 | ||
174 | // fix http(s)\:// to http(s):// | |
175 | $text = str_replace('http\://', 'http://', $text); | |
176 | $text = str_replace('https\://', 'http://', $text); | |
177 | ||
178 | return; | |
179 | } | |
180 | ||
181 | /** | |
182 | * Adds a parameter value for a given component and parameter name. | |
183 | * | |
184 | * Note that although vCard 2.1 allows you to specify a parameter | |
185 | * value without a name (e.g., "HOME" instead of "TYPE=HOME") this | |
186 | * class is not so lenient. ;-) You must specify a parameter name | |
187 | * (TYPE, ENCODING, etc) when adding a parameter. Call multiple | |
188 | * times if you want to add multiple values to the same parameter. | |
189 | * E.g.: | |
190 | * | |
191 | * $vcard = new Contact_Vcard_Build(); | |
192 | * | |
193 | * // set "TYPE=HOME,PREF" for the first TEL component | |
194 | * $vcard->addParam('TYPE', 'HOME', 'TEL', 0); | |
195 | * $vcard->addParam('TYPE', 'PREF', 'TEL', 0); | |
196 | * | |
197 | * @param string $param_name The parameter name, such as TYPE, VALUE, | |
198 | * or ENCODING. | |
199 | * @param string $param_value The parameter value. | |
200 | * @param string $comp The vCard component for which this is a | |
201 | * paramter (ADR, TEL, etc). If null, will be | |
202 | * the component that was last set or added-to. | |
203 | * @param mixed $iter An integer vCard component iteration that this | |
204 | * is a param for. E.g., if you have more than | |
205 | * one ADR component, 0 refers to the first ADR, | |
206 | * 1 to the second ADR, and so on. If null, the | |
207 | * parameter will be added to the last component | |
208 | * iteration available. | |
209 | * | |
210 | * @access public | |
211 | * @return mixed Void on success, or a PEAR_Error object on failure. | |
212 | */ | |
213 | function addParam($param_name, $param_value, $comp = null, $iter = null) | |
214 | { | |
215 | // if component is not specified, default to the last component | |
216 | // that was set or added. | |
217 | if ($comp === null) { | |
218 | $comp = $this->autoparam; | |
219 | } | |
220 | ||
221 | // using a null iteration means the param should be associated | |
222 | // with the latest/most-recent iteration of the selected | |
223 | // component. | |
224 | if ($iter === null) { | |
225 | $iter = $this->countIter($comp) - 1; | |
226 | } | |
227 | ||
228 | // massage the text arguments | |
229 | $comp = strtoupper(trim($comp)); | |
230 | $param_name = strtoupper(trim($param_name)); | |
231 | $param_value = trim($param_value); | |
232 | ||
233 | if (! is_integer($iter) || $iter < 0) { | |
234 | ||
235 | $msg = "$iter is not a valid iteration number for $comp; "; | |
236 | $msg .= "must be a positive integer."; | |
237 | ||
238 | return $this->raiseError($msg); | |
239 | ||
240 | } | |
241 | ||
242 | $result = $this->validateParam($param_name, $param_value, $comp, $iter); | |
243 | ||
244 | if (PEAR::isError($result)) { | |
245 | return $result; | |
246 | } | |
247 | $this->param[$comp][$iter][$param_name][] = $param_value; | |
248 | ||
249 | } | |
250 | ||
251 | /** | |
252 | * Validates parameter names and values based on the vCard version | |
253 | * (2.1 or 3.0). | |
254 | * | |
255 | * @param string $name The parameter name (e.g., TYPE or ENCODING). | |
256 | * @param string $text The parameter value (e.g., HOME or BASE64). | |
257 | * @param string $comp Optional, the component name (e.g., ADR or | |
258 | * PHOTO). Only used for error messaging. | |
259 | * @param string $iter Optional, the iteration of the component. | |
260 | * Only used for error messaging. | |
261 | * | |
262 | * @access public | |
263 | * @return mixed Boolean true if the parameter is valid, or a | |
264 | * PEAR_Error object if not. | |
265 | * | |
266 | */ | |
267 | function validateParam($name, $text, $comp = null, $iter = null) | |
268 | { | |
269 | $name = strtoupper($name); | |
270 | $text = strtoupper($text); | |
271 | ||
272 | switch ($comp) { | |
273 | ||
274 | case 'TEL': | |
275 | case 'TEL;PREF;CELL': | |
276 | case 'TEL;PREF;VOICE': | |
277 | case 'TEL;PREF;FAX': | |
278 | case 'EMAIL': | |
279 | case 'ADR': | |
280 | break; | |
281 | ||
282 | default: | |
283 | // all param values must have only the characters A-Z 0-9 and -. | |
284 | if (preg_match('/[^a-zA-Z0-9\-]/i', $text)) { | |
285 | ||
286 | $msg = "vCard [$comp] [$iter] [$name]: "; | |
287 | $msg .= 'The parameter value may contain only '; | |
288 | $msg .= 'a-z, A-Z, 0-9, and dashes (-).'; | |
289 | ||
290 | return $this->raiseError($msg); | |
291 | ||
292 | } | |
293 | break; | |
294 | } | |
295 | ||
296 | if ($this->value['VERSION'][0][0][0] == '2.1') { | |
297 | ||
298 | // Validate against version 2.1 (pretty strict) | |
299 | ||
300 | $types = array ( | |
301 | 'DOM', 'INTL', 'POSTAL', 'PARCEL','HOME', 'WORK', | |
302 | 'PREF', 'VOICE', 'FAX', 'MSG', 'CELL', 'PAGER', | |
303 | 'BBS', 'MODEM', 'CAR', 'ISDN', 'VIDEO', | |
304 | 'AOL', 'APPLELINK', 'ATTMAIL', 'CIS', 'EWORLD', | |
305 | 'INTERNET', 'IBMMAIL', 'MCIMAIL', | |
306 | 'POWERSHARE', 'PRODIGY', 'TLX', 'X400', | |
307 | 'GIF', 'CGM', 'WMF', 'BMP', 'MET', 'PMB', 'DIB', | |
308 | 'PICT', 'TIFF', 'PDF', 'PS', 'JPEG', 'QTIME', | |
309 | 'MPEG', 'MPEG2', 'AVI', | |
310 | 'WAVE', 'AIFF', 'PCM', | |
311 | 'X509', 'PGP' | |
312 | ); | |
313 | ||
314 | switch ($name) { | |
315 | ||
316 | case 'TYPE': | |
317 | if (! in_array($text, $types)) { | |
318 | $msg = "vCard 2.1 [$comp] [$iter]: "; | |
319 | $msg .= "$text is not a recognized TYPE."; | |
320 | ||
321 | $result = $this->raiseError($msg); | |
322 | } else { | |
323 | $result = true; | |
324 | } | |
325 | break; | |
326 | ||
327 | case 'ENCODING': | |
328 | if ($text != '7BIT' && | |
329 | $text != '8BIT' && | |
330 | $text != 'BASE64' && | |
331 | $text != 'QUOTED-PRINTABLE') { | |
332 | $msg = "vCard 2.1 [$comp] [$iter]: "; | |
333 | $msg .= "$text is not a recognized ENCODING."; | |
334 | ||
335 | $result = $this->raiseError($msg); | |
336 | } else { | |
337 | $result = true; | |
338 | } | |
339 | break; | |
340 | ||
341 | case 'CHARSET': | |
342 | // all charsets are OK | |
343 | $result = true; | |
344 | break; | |
345 | ||
346 | case 'LANGUAGE': | |
347 | // all languages are OK | |
348 | $result = true; | |
349 | break; | |
350 | ||
351 | case 'VALUE': | |
352 | if ($text != 'INLINE' && | |
353 | $text != 'CONTENT-ID' && | |
354 | $text != 'CID' && | |
355 | $text != 'URL' && | |
356 | $text != 'VCARD') { | |
357 | ||
358 | $msg = "vCard 2.1 [$comp] [$iter]: "; | |
359 | $msg .= "$text is not a recognized VALUE."; | |
360 | ||
361 | $result = $this->raiseError($msg); | |
362 | } else { | |
363 | $result = true; | |
364 | } | |
365 | break; | |
366 | ||
367 | default: | |
368 | $msg = "vCard 2.1 [$comp] [$iter]: "; | |
369 | $msg .= "$name is an unknown or invalid parameter name."; | |
370 | ||
371 | return $this->raiseError($msg); | |
372 | break; | |
373 | } | |
374 | ||
375 | } elseif ($this->value['VERSION'][0][0][0] == '3.0') { | |
376 | ||
377 | // Validate against version 3.0 (pretty lenient) | |
378 | ||
379 | switch ($name) { | |
380 | ||
381 | case 'TYPE': | |
382 | // all types are OK | |
383 | $result = true; | |
384 | break; | |
385 | ||
386 | case 'LANGUAGE': | |
387 | // all languages are OK | |
388 | $result = true; | |
389 | break; | |
390 | ||
391 | case 'ENCODING': | |
392 | if ($text != '8BIT' && | |
393 | $text != 'B') { | |
394 | ||
395 | $msg = "vCard 3.0 [$comp] [$iter]: "; | |
396 | $msg .= "The only allowed ENCODING"; | |
397 | $msg .= " parameters are 8BIT and B."; | |
398 | ||
399 | $result = $this->raiseError($msg); | |
400 | } else { | |
401 | $result = true; | |
402 | } | |
403 | break; | |
404 | ||
405 | case 'VALUE': | |
406 | if ($text != 'BINARY' && | |
407 | $text != 'PHONE-NUMBER' && | |
408 | $text != 'TEXT' && | |
409 | $text != 'URI' && | |
410 | $text != 'UTC-OFFSET' && | |
411 | $text != 'VCARD') { | |
412 | ||
413 | $msg = "vCard 3.0 [$comp] [$iter]: The only allowed VALUE "; | |
414 | $msg .= "parameters are "; | |
415 | $msg .= "BINARY, PHONE-NUMBER, TEXT, URI, UTC-OFFSET,"; | |
416 | $msg .= " and VCARD."; | |
417 | ||
418 | return $this->raiseError($msg); | |
419 | } | |
420 | $result = true; | |
421 | break; | |
422 | ||
423 | default: | |
424 | ||
425 | $msg = "vCard 3.0 [$comp] [$iter]: "; | |
426 | $msg .= "Unknown or invalid parameter name ($name)."; | |
427 | ||
428 | return $this->raiseError($msg); | |
429 | break; | |
430 | } | |
431 | ||
432 | } else { | |
433 | ||
434 | $msg = "[$comp] [$iter] Unknown vCard version number or other error."; | |
435 | return $this->raiseError($msg); | |
436 | ||
437 | } | |
438 | ||
439 | return $result; | |
440 | ||
441 | } | |
442 | ||
443 | /** | |
444 | * Gets back the parameter string for a given component. | |
445 | * | |
446 | * @param string $comp The component to get parameters for | |
447 | * (ADR, TEL, etc). | |
448 | * | |
449 | * @param int $iter The vCard component iteration to get the param | |
450 | * list for. E.g., if you have more than one ADR component, | |
451 | * 0 refers to the first ADR, 1 to the second ADR, and so on. | |
452 | * | |
453 | * @access public | |
454 | * @return string | |
455 | */ | |
456 | function getParam($comp, $iter = 0) | |
457 | { | |
458 | $comp = strtoupper($comp); | |
459 | $text = ''; | |
460 | ||
461 | if (isset($this->param[$comp][$iter]) && | |
462 | is_array($this->param[$comp][$iter])) { | |
463 | ||
464 | // loop through the array of parameters for | |
465 | // the component | |
466 | ||
467 | foreach ($this->param[$comp][$iter] as $param_name => $param_val) { | |
468 | ||
469 | // if there were previous parameter names, separate with | |
470 | // a semicolon | |
471 | if ($text != '') { | |
472 | $text .= ';'; | |
473 | } | |
474 | ||
475 | if ($param_val === null) { | |
476 | ||
477 | // no parameter value was specified, which is typical | |
478 | // for vCard version 2.1 -- the name is the value. | |
479 | $this->escape($param_name); | |
480 | $text .= $param_name; | |
481 | ||
482 | } else { | |
483 | // set the parameter name... | |
484 | $text .= strtoupper($param_name) . '='; | |
485 | ||
486 | // ...then escape and comma-separate the parameter | |
487 | // values. | |
488 | $this->escape($param_val); | |
489 | $text .= implode(',', $param_val); | |
490 | } | |
491 | } | |
492 | } | |
493 | ||
494 | // if there were no parameters, this will be blank. | |
495 | return $text; | |
496 | } | |
497 | ||
498 | ||
499 | /** | |
500 | * Resets the vCard values and params to be blank. | |
501 | * | |
502 | * @param string $version The vCard version to reset to ('2.1' or | |
503 | * '3.0' -- default is the same version as | |
504 | * previously set). | |
505 | * | |
506 | * @access public | |
507 | * @return void | |
508 | */ | |
509 | function reset($version = null) | |
510 | { | |
511 | $prev = $this->value['VERSION'][0][0][0]; | |
512 | ||
513 | $this->value = array(); | |
514 | $this->param = array(); | |
515 | $this->autoparam = null; | |
516 | ||
517 | if ($version === null) { | |
518 | $this->setVersion($prev); | |
519 | } else { | |
520 | $this->setVersion($version); | |
521 | } | |
522 | } | |
523 | ||
524 | /** | |
525 | * Generic, all-purpose method to store a string or array in | |
526 | * $this->value, in a way suitable for later output as a vCard | |
527 | * element. This forces the value to be the passed text or array | |
528 | * value, overriding any prior values. | |
529 | * | |
530 | * @param string $comp The component to set the value for ('N', | |
531 | * 'ADR', etc). | |
532 | * @param int $iter The component-iteration to set the value for. | |
533 | * @param int $part The part number of the component-iteration to set | |
534 | * the value for. | |
535 | * @param mixed $text A string or array; the set of repeated values | |
536 | * for this component-iteration part. | |
537 | * | |
538 | * @access public | |
539 | * @return void | |
540 | */ | |
541 | function setValue($comp, $iter, $part, $text) | |
542 | { | |
543 | $comp = strtoupper($comp); | |
544 | settype($text, 'array'); | |
545 | $this->value[$comp][$iter][$part] = $text; | |
546 | //mark this component as having been set. | |
547 | $this->autoparam = $comp; | |
548 | } | |
549 | ||
550 | /** | |
551 | * Generic, all-purpose method to add a repetition of a string or | |
552 | * array in $this->value, in a way suitable for later output as a | |
553 | * vCard element. This appends the value to be the passed text or | |
554 | * array value, leaving any prior values in place. | |
555 | * | |
556 | * @param string $comp The component to set the value for ('N', 'ADR', etc). | |
557 | * @param int $iter The component-iteration to set the value for. | |
558 | * @param int $part The part number of the component-iteration to set | |
559 | * the value for. | |
560 | * @param mixed $text A string or array; the set of repeated values | |
561 | * for this component-iteration part. | |
562 | * | |
563 | * @access public | |
564 | * @return void | |
565 | */ | |
566 | function addValue($comp, $iter, $part, $text) | |
567 | { | |
568 | $comp = strtoupper($comp); | |
569 | ||
570 | settype($text, 'array'); | |
571 | ||
572 | foreach ($text as $val) { | |
573 | $this->value[$comp][$iter][$part][] = $val; | |
574 | } | |
575 | $this->autoparam = $comp; | |
576 | } | |
577 | ||
578 | /** | |
579 | * Generic, all-purpose method to get back the data stored in $this->value. | |
580 | * | |
581 | * @param string $comp The component to set the value for ('N', | |
582 | * 'ADR', etc). | |
583 | * @param int $iter The component-iteration to set the value for. | |
584 | * @param int $part The part number of the component-iteration to get | |
585 | * the value for. | |
586 | * @param mixed $rept The repetition number within the part to get; | |
587 | * if null, get all repetitions of the part within the | |
588 | * iteration. | |
589 | * | |
590 | * @access public | |
591 | * @return string The value, escaped and delimited, of all | |
592 | * repetitions in the component-iteration part (or specific | |
593 | * repetition within the part). | |
594 | */ | |
595 | function getValue($comp, $iter = 0, $part = 0, $rept = null) | |
596 | { | |
597 | if ($rept === null && | |
598 | is_array($this->value[$comp][$iter][$part]) ) { | |
599 | ||
600 | // get all repetitions of a part | |
601 | $list = array(); | |
602 | foreach ($this->value[$comp][$iter][$part] as $key => $val) { | |
603 | $list[] = trim($val); | |
604 | } | |
605 | ||
606 | $this->escape($list); | |
607 | return implode(',', $list); | |
608 | ||
609 | } | |
610 | ||
611 | // get a specific repetition of a part | |
612 | $text = trim($this->value[$comp][$iter][$part][$rept]); | |
613 | $this->escape($text); | |
614 | return $text; | |
615 | } | |
616 | ||
617 | /** | |
618 | * Sets the full N component of the vCard. Will replace all other | |
619 | * values. There can only be one N component per vCard. | |
620 | * | |
621 | * @param mixed $family Single (string) or multiple (array) | |
622 | * family/last name. | |
623 | * @param mixed $given Single (string) or multiple (array) | |
624 | * given/first name. | |
625 | * @param mixed $addl Single (string) or multiple (array) | |
626 | * additional/middle name. | |
627 | * @param mixed $prefix Single (string) or multiple (array) honorific | |
628 | * prefix such as Mr., Miss, etc. | |
629 | * @param mixed $suffix Single (string) or multiple (array) honorific | |
630 | * suffix such as III, Jr., Ph.D., etc. | |
631 | * | |
632 | * @access public | |
633 | * @return void | |
634 | */ | |
635 | function setName($family, $given, $addl, $prefix, $suffix) | |
636 | { | |
637 | $this->autoparam = 'N'; | |
638 | $this->setValue('N', 0, VCARD_N_FAMILY, $family); | |
639 | $this->setValue('N', 0, VCARD_N_GIVEN, $given); | |
640 | $this->setValue('N', 0, VCARD_N_ADDL, $addl); | |
641 | $this->setValue('N', 0, VCARD_N_PREFIX, $prefix); | |
642 | $this->setValue('N', 0, VCARD_N_SUFFIX, $suffix); | |
643 | } | |
644 | ||
645 | ||
646 | /** | |
647 | * Gets back the full N component (first iteration only, since there | |
648 | * can only be one N component per vCard). | |
649 | * | |
650 | * @access public | |
651 | * @return string The first N component-interation of the vCard. | |
652 | */ | |
653 | function getName() | |
654 | { | |
655 | return $this->getMeta('N', 0) . | |
656 | $this->getValue('N', 0, VCARD_N_FAMILY) . ';' . | |
657 | $this->getValue('N', 0, VCARD_N_GIVEN) . ';' . | |
658 | $this->getValue('N', 0, VCARD_N_ADDL) . ';' . | |
659 | $this->getValue('N', 0, VCARD_N_PREFIX) . ';' . | |
660 | $this->getValue('N', 0, VCARD_N_SUFFIX); | |
661 | } | |
662 | ||
663 | /** | |
664 | * Sets the FN component of the card. If no text is passed as the | |
665 | * FN value, constructs an FN automatically from N components. There | |
666 | * is only one FN iteration per vCard. | |
667 | * | |
668 | * @param string $text Override the automatic generation of FN from N | |
669 | * elements with the specified text. | |
670 | * | |
671 | * @access public | |
672 | * @return mixed Void on success, or a PEAR_Error object on failure. | |
673 | */ | |
674 | function setFormattedName($text = null) | |
675 | { | |
676 | $this->autoparam = 'FN'; | |
677 | ||
678 | if ($text !== null) { | |
679 | $this->setValue('FN', 0, 0, $text); | |
680 | return; | |
681 | } | |
682 | ||
683 | // no text was specified for the FN, so build it | |
684 | // from the current N components if an N exists | |
685 | if (is_array($this->value['N'])) { | |
686 | ||
687 | // build from N. | |
688 | // first (given) name, first iteration, first repetition | |
689 | $text .= $this->getValue('N', 0, VCARD_N_GIVEN, 0); | |
690 | ||
691 | // add a space after, if there was text | |
692 | if ($text != '') { | |
693 | $text .= ' '; | |
694 | } | |
695 | ||
696 | // last (family) name, first iteration, first repetition | |
697 | $text .= $this->getValue('N', 0, VCARD_N_FAMILY, 0); | |
698 | ||
699 | // add a space after, if there was text | |
700 | if ($text != '') { | |
701 | $text .= ' '; | |
702 | } | |
703 | ||
704 | // last-name suffix, first iteration, first repetition | |
705 | $text .= $this->getValue('N', 0, VCARD_N_SUFFIX, 0); | |
706 | ||
707 | $this->setValue('FN', 0, 0, $text); | |
708 | return; | |
709 | } | |
710 | ||
711 | // no N exists, and no FN was set, so return. | |
712 | $msg = 'FN not specified and N not set; cannot set FN.'; | |
713 | return $this->raiseError($msg); | |
714 | } | |
715 | ||
716 | /** | |
717 | * Gets back the full FN component value. Only ever returns iteration | |
718 | * zero, because only one FN component is allowed per vCard. | |
719 | * | |
720 | * @access public | |
721 | * @uses self::getMeta() | |
722 | * @return string The FN value of the vCard. | |
723 | * @uses self::getMeta() | |
724 | */ | |
725 | function getFormattedName() | |
726 | { | |
727 | return $this->getMeta('FN', 0) . $this->getValue('FN', 0, 0); | |
728 | } | |
729 | ||
730 | /** | |
731 | * Sets the version of the the vCard. Only one iteration. | |
732 | * | |
733 | * @param string $text The text value of the verson text ('3.0' or '2.1'). | |
734 | * | |
735 | * @access public | |
736 | * @return mixed Void on success, or a PEAR_Error object on failure. | |
737 | */ | |
738 | function setVersion($text = '3.0') | |
739 | { | |
740 | $this->autoparam = 'VERSION'; | |
741 | if ($text != '3.0' && $text != '2.1') { | |
742 | return $this->raiseError('Version must be 3.0 or 2.1 to be valid.'); | |
743 | } | |
744 | $this->setValue('VERSION', 0, 0, $text); | |
745 | } | |
746 | ||
747 | /** | |
748 | * Gets back the version of the the vCard. Only one iteration. | |
749 | * | |
750 | * @access public | |
751 | * @uses self::getMeta() | |
752 | * @return string The data-source of the vCard. | |
753 | */ | |
754 | function getVersion() | |
755 | { | |
756 | return $this->getMeta('VERSION', 0) . $this->getValue('VERSION', 0); | |
757 | } | |
758 | ||
759 | /** | |
760 | * Sets the data-source of the the vCard. Only one iteration. | |
761 | * | |
762 | * @param string $text The text value of the data-source text. | |
763 | * | |
764 | * @access public | |
765 | * @return void | |
766 | */ | |
767 | function setSource($text) | |
768 | { | |
769 | $this->autoparam = 'SOURCE'; | |
770 | $this->setValue('SOURCE', 0, 0, $text); | |
771 | } | |
772 | ||
773 | /** | |
774 | * Gets back the data-source of the the vCard. Only one iteration. | |
775 | * | |
776 | * @access public | |
777 | * @return string The data-source of the vCard. | |
778 | */ | |
779 | function getSource() | |
780 | { | |
781 | return $this->getMeta('SOURCE', 0) . $this->getValue('SOURCE', 0, 0); | |
782 | } | |
783 | ||
784 | /** | |
785 | * Sets the displayed name of the vCard data-source. Only one iteration. | |
786 | * If no name is specified, copies the value of SOURCE. | |
787 | * | |
788 | * @param string $text The text value of the displayed data-source | |
789 | * name. If null, copies the value of SOURCE. | |
790 | * | |
791 | * @access public | |
792 | * @return mixed Void on success, or a PEAR_Error object on failure. | |
793 | */ | |
794 | function setSourceName($text = null) | |
795 | { | |
796 | $this->autoparam = 'NAME'; | |
797 | ||
798 | if ($text === null) { | |
799 | if (is_array($this->value['SOURCE'])) { | |
800 | $text = $this->getValue('SOURCE', 0, 0); | |
801 | } else { | |
802 | $msg = 'NAME not specified and SOURCE not set; cannot set NAME.'; | |
803 | return $this->raiseError($msg); | |
804 | } | |
805 | } | |
806 | ||
807 | $this->setValue('NAME', 0, 0, $text); | |
808 | } | |
809 | ||
810 | /** | |
811 | * Gets back the displayed data-source name of the the vCard. Only | |
812 | * one iteration. | |
813 | * | |
814 | * @access public | |
815 | * @return string The data-source name of the vCard. | |
816 | */ | |
817 | function getSourceName() | |
818 | { | |
819 | return $this->getMeta('NAME', 0) . $this->getValue('NAME', 0, 0); | |
820 | } | |
821 | ||
822 | /** | |
823 | * Sets the value of the PHOTO component. There is only one allowed | |
824 | * per vCard. | |
825 | * | |
826 | * @param string $text The value to set for this component. | |
827 | * @param boolean $url True or false, depending if $text is one. | |
828 | * | |
829 | * @access public | |
830 | * @return void | |
831 | */ | |
832 | function setPhoto($text, $url = false) | |
833 | { | |
834 | if ($url === false) { | |
835 | $this->autoparam = 'PHOTO'; | |
836 | $this->setValue('PHOTO', 0, 0, $text); | |
837 | return; | |
838 | } | |
839 | $this->autoparam = 'PHOTO;VALUE=URI'; | |
840 | $this->setValue('PHOTO;VALUE=URI', 0, 0, $text); | |
841 | } | |
842 | ||
843 | /** | |
844 | * Gets back the value of the PHOTO component. There is only one | |
845 | * allowed per vCard. | |
846 | * | |
847 | * @access public | |
848 | * @return string The value of this component or false if no photo is set. | |
849 | */ | |
850 | function getPhoto() | |
851 | { | |
852 | if (isset($this->value['PHOTO'])) { | |
853 | return $this->getMeta('PHOTO') . $this->getValue('PHOTO', 0, 0); | |
854 | } | |
855 | if (isset($this->value['PHOTO;VALUE=URI'])) { | |
856 | return $this->getMeta('PHOTO;VALUE=URI') . | |
857 | $this->getValue('PHOTO;VALUE=URI', 0, 0); | |
858 | } | |
859 | return false; | |
860 | } | |
861 | ||
862 | /** | |
863 | * Sets the value of the LOGO component. There is only one allowed | |
864 | * per vCard. | |
865 | * | |
866 | * @param string $text The value to set for this component. | |
867 | * | |
868 | * @access public | |
869 | * @return void | |
870 | */ | |
871 | function setLogo($text) | |
872 | { | |
873 | $this->autoparam = 'LOGO'; | |
874 | $this->setValue('LOGO', 0, 0, $text); | |
875 | } | |
876 | ||
877 | /** | |
878 | * Gets back the value of the LOGO component. There is only one | |
879 | * allowed per vCard. | |
880 | * | |
881 | * @access public | |
882 | * @return string The value of this component. | |
883 | */ | |
884 | function getLogo() | |
885 | { | |
886 | return $this->getMeta('LOGO') . $this->getValue('LOGO', 0, 0); | |
887 | } | |
888 | ||
889 | /** | |
890 | * Sets the value of the SOUND component. There is only one allowed | |
891 | * per vCard. | |
892 | * | |
893 | * @param string $text The value to set for this component. | |
894 | * | |
895 | * @access public | |
896 | * @return void | |
897 | */ | |
898 | function setSound($text) | |
899 | { | |
900 | $this->autoparam = 'SOUND'; | |
901 | $this->setValue('SOUND', 0, 0, $text); | |
902 | } | |
903 | ||
904 | /** | |
905 | * Gets back the value of the SOUND component. There is only one | |
906 | * allowed per vCard. | |
907 | * | |
908 | * @access public | |
909 | * @return string The value of this component. | |
910 | */ | |
911 | function getSound() | |
912 | { | |
913 | return $this->getMeta('SOUND') . $this->getValue('SOUND', 0, 0); | |
914 | } | |
915 | ||
916 | /** | |
917 | * Sets the value of the KEY component. There is only one allowed | |
918 | * per vCard. | |
919 | * | |
920 | * @param string $text The value to set for this component. | |
921 | * | |
922 | * @access public | |
923 | * @return void | |
924 | */ | |
925 | function setKey($text) | |
926 | { | |
927 | $this->autoparam = 'KEY'; | |
928 | $this->setValue('KEY', 0, 0, $text); | |
929 | } | |
930 | ||
931 | /** | |
932 | * Gets back the value of the KEY component. There is only one | |
933 | * allowed per vCard. | |
934 | * | |
935 | * @access public | |
936 | * @return string The value of this component. | |
937 | */ | |
938 | function getKey() | |
939 | { | |
940 | return $this->getMeta('KEY') . $this->getValue('KEY', 0, 0); | |
941 | } | |
942 | ||
943 | /** | |
944 | * Sets the value of the BDAY component. There is only one allowed | |
945 | * per vCard. Date format is "yyyy-mm-dd[Thh:ii[:ss[Z|-06:00]]]". | |
946 | * | |
947 | * @param string $text The value to set for this component. | |
948 | * | |
949 | * @access public | |
950 | * @return void | |
951 | */ | |
952 | function setBirthday($text) | |
953 | { | |
954 | $this->autoparam = 'BDAY'; | |
955 | $this->setValue('BDAY', 0, 0, $text); | |
956 | } | |
957 | ||
958 | /** | |
959 | * Gets back the value of the BDAY component. There is only one | |
960 | * allowed per vCard. | |
961 | * | |
962 | * @access public | |
963 | * @return string The value of this component. | |
964 | */ | |
965 | function getBirthday() | |
966 | { | |
967 | return $this->getMeta('BDAY') . $this->getValue('BDAY', 0, 0); | |
968 | } | |
969 | ||
970 | /** | |
971 | * Sets the value of the TZ component. There is only one allowed per | |
972 | * vCard. | |
973 | * | |
974 | * @param string $text The value to set for this component. | |
975 | * | |
976 | * @access public | |
977 | * @return void | |
978 | */ | |
979 | function setTZ($text) | |
980 | { | |
981 | $this->autoparam = 'TZ'; | |
982 | $this->setValue('TZ', 0, 0, $text); | |
983 | } | |
984 | ||
985 | /** | |
986 | * Gets back the value of the TZ component. There is only one | |
987 | * allowed per vCard. | |
988 | * | |
989 | * @access public | |
990 | * @return string The value of this component. | |
991 | */ | |
992 | function getTZ() | |
993 | { | |
994 | return $this->getMeta('TZ') . $this->getValue('TZ', 0, 0); | |
995 | } | |
996 | ||
997 | /** | |
998 | * Sets the value of the MAILER component. There is only one allowed | |
999 | * per vCard. | |
1000 | * | |
1001 | * @param string $text The value to set for this component. | |
1002 | * | |
1003 | * @access public | |
1004 | * @return void | |
1005 | */ | |
1006 | function setMailer($text) | |
1007 | { | |
1008 | $this->autoparam = 'MAILER'; | |
1009 | $this->setValue('MAILER', 0, 0, $text); | |
1010 | } | |
1011 | ||
1012 | /** | |
1013 | * Gets back the value of the MAILER component. There is only one | |
1014 | * allowed per vCard. | |
1015 | * | |
1016 | * @access public | |
1017 | * @return string The value of this component. | |
1018 | */ | |
1019 | function getMailer() | |
1020 | { | |
1021 | return $this->getMeta('MAILER') . $this->getValue('MAILER', 0, 0); | |
1022 | } | |
1023 | ||
1024 | /** | |
1025 | * Sets the value of the NOTE component. There is only one allowed | |
1026 | * per vCard. | |
1027 | * | |
1028 | * @param string $text The value to set for this component. | |
1029 | * | |
1030 | * @access public | |
1031 | * @return void | |
1032 | */ | |
1033 | function setNote($text) | |
1034 | { | |
1035 | $this->autoparam = 'NOTE'; | |
1036 | $this->setValue('NOTE', 0, 0, $text); | |
1037 | } | |
1038 | ||
1039 | /** | |
1040 | * Gets back the value of the NOTE component. There is only one | |
1041 | * allowed per vCard. | |
1042 | * | |
1043 | * @access public | |
1044 | * @return string The value of this component. | |
1045 | */ | |
1046 | function getNote() | |
1047 | { | |
1048 | return $this->getMeta('NOTE') . $this->getValue('NOTE', 0, 0); | |
1049 | } | |
1050 | ||
1051 | /** | |
1052 | * Sets the value of the TITLE component. There is only one allowed | |
1053 | * per vCard. | |
1054 | * | |
1055 | * @param string $text The value to set for this component. | |
1056 | * | |
1057 | * @access public | |
1058 | * @return void | |
1059 | */ | |
1060 | function setTitle($text) | |
1061 | { | |
1062 | $this->autoparam = 'TITLE'; | |
1063 | $this->setValue('TITLE', 0, 0, $text); | |
1064 | } | |
1065 | ||
1066 | /** | |
1067 | * Gets back the value of the TITLE component. There is only one | |
1068 | * allowed per vCard. | |
1069 | * | |
1070 | * @access public | |
1071 | * @return string The value of this component. | |
1072 | */ | |
1073 | function getTitle() | |
1074 | { | |
1075 | return $this->getMeta('TITLE') . $this->getValue('TITLE', 0, 0); | |
1076 | } | |
1077 | ||
1078 | /** | |
1079 | * Sets the value of the ROLE component. There is only one allowed | |
1080 | * per vCard. | |
1081 | * | |
1082 | * @param string $text The value to set for this component. | |
1083 | * | |
1084 | * @access public | |
1085 | * @return void | |
1086 | */ | |
1087 | function setRole($text) | |
1088 | { | |
1089 | $this->autoparam = 'ROLE'; | |
1090 | $this->setValue('ROLE', 0, 0, $text); | |
1091 | } | |
1092 | ||
1093 | /** | |
1094 | * Gets back the value of the ROLE component. There is only one | |
1095 | * allowed per vCard. | |
1096 | * | |
1097 | * @access public | |
1098 | * @return string The value of this component. | |
1099 | */ | |
1100 | function getRole() | |
1101 | { | |
1102 | return $this->getMeta('ROLE') . $this->getValue('ROLE', 0, 0); | |
1103 | } | |
1104 | ||
1105 | /** | |
1106 | * Sets the value of the URL component. There is only one allowed | |
1107 | * per vCard. | |
1108 | * | |
1109 | * @param string $text The value to set for this component. | |
1110 | * | |
1111 | * @access public | |
1112 | * @return void | |
1113 | */ | |
1114 | function setURL($text) | |
1115 | { | |
1116 | $this->autoparam = 'URL'; | |
1117 | $this->setValue('URL', 0, 0, $text); | |
1118 | } | |
1119 | ||
1120 | /** | |
1121 | * Gets back the value of the URL component. There is only one | |
1122 | * allowed per vCard. | |
1123 | * | |
1124 | * @access public | |
1125 | * @return string The value of this component. | |
1126 | */ | |
1127 | function getURL() | |
1128 | { | |
1129 | return $this->getMeta('URL') . $this->getValue('URL', 0, 0); | |
1130 | } | |
1131 | ||
1132 | /** | |
1133 | * Sets the value of the CLASS component. There is only one allowed | |
1134 | * per vCard. | |
1135 | * | |
1136 | * @param string $text The value to set for this component. | |
1137 | * | |
1138 | * @access public | |
1139 | * @return void | |
1140 | */ | |
1141 | function setClass($text) | |
1142 | { | |
1143 | $this->autoparam = 'CLASS'; | |
1144 | $this->setValue('CLASS', 0, 0, $text); | |
1145 | } | |
1146 | ||
1147 | /** | |
1148 | * Gets back the value of the CLASS component. There is only one | |
1149 | * allowed per vCard. | |
1150 | * | |
1151 | * @access public | |
1152 | * @return string The value of this component. | |
1153 | */ | |
1154 | function getClass() | |
1155 | { | |
1156 | return $this->getMeta('CLASS') . $this->getValue('CLASS', 0, 0); | |
1157 | } | |
1158 | ||
1159 | /** | |
1160 | * Sets the value of the SORT-STRING component. There is only one | |
1161 | * allowed per vCard. | |
1162 | * | |
1163 | * @param string $text The value to set for this component. | |
1164 | * | |
1165 | * @access public | |
1166 | * @return void | |
1167 | */ | |
1168 | function setSortString($text) | |
1169 | { | |
1170 | $this->autoparam = 'SORT-STRING'; | |
1171 | $this->setValue('SORT-STRING', 0, 0, $text); | |
1172 | } | |
1173 | ||
1174 | /** | |
1175 | * Gets back the value of the SORT-STRING component. There is only | |
1176 | * one allowed per vCard. | |
1177 | * | |
1178 | * @access public | |
1179 | * @return string The value of this component. | |
1180 | */ | |
1181 | function getSortString() | |
1182 | { | |
1183 | return $this->getMeta('SORT-STRING') . $this->getValue('SORT-STRING', 0, 0); | |
1184 | } | |
1185 | ||
1186 | /** | |
1187 | * Sets the value of the PRODID component. There is only one allowed | |
1188 | * per vCard. | |
1189 | * | |
1190 | * @param string $text The value to set for this component. | |
1191 | * | |
1192 | * @access public | |
1193 | * @return void | |
1194 | */ | |
1195 | function setProductID($text) | |
1196 | { | |
1197 | $this->autoparam = 'PRODID'; | |
1198 | $this->setValue('PRODID', 0, 0, $text); | |
1199 | } | |
1200 | ||
1201 | /** | |
1202 | * Gets back the value of the PRODID component. There is only one | |
1203 | * allowed per vCard. | |
1204 | * | |
1205 | * @access public | |
1206 | * @return string The value of this component. | |
1207 | */ | |
1208 | function getProductID() | |
1209 | { | |
1210 | return $this->getMeta('PRODID') . $this->getValue('PRODID', 0, 0); | |
1211 | } | |
1212 | ||
1213 | /** | |
1214 | * Sets the value of the REV component. There is only one allowed | |
1215 | * per vCard. This value is free and should reflect whatever you use | |
1216 | * for control - e.g. a DATETIME value. | |
1217 | * | |
1218 | * @param string $text The value to set for this component. | |
1219 | * | |
1220 | * @access public | |
1221 | * @return void | |
1222 | */ | |
1223 | function setRevision($text) | |
1224 | { | |
1225 | $this->autoparam = 'REV'; | |
1226 | $this->setValue('REV', 0, 0, $text); | |
1227 | } | |
1228 | ||
1229 | /** | |
1230 | * Gets back the value of the REV component. There is only one | |
1231 | * allowed per vCard. | |
1232 | * | |
1233 | * @access public | |
1234 | * @return string The value of this component. | |
1235 | */ | |
1236 | function getRevision() | |
1237 | { | |
1238 | return $this->getMeta('REV') . $this->getValue('REV', 0, 0); | |
1239 | } | |
1240 | ||
1241 | /** | |
1242 | * Sets the value of the UID component. There is only one allowed | |
1243 | * per vCard. | |
1244 | * | |
1245 | * @param string $text The value to set for this component. | |
1246 | * | |
1247 | * @access public | |
1248 | * @return void | |
1249 | */ | |
1250 | function setUniqueID($text) | |
1251 | { | |
1252 | $this->autoparam = 'UID'; | |
1253 | $this->setValue('UID', 0, 0, $text); | |
1254 | } | |
1255 | ||
1256 | /** | |
1257 | * Gets back the value of the UID component. There is only one | |
1258 | * allowed per vCard. | |
1259 | * | |
1260 | * @access public | |
1261 | * @return string The value of this component. | |
1262 | */ | |
1263 | function getUniqueID() | |
1264 | { | |
1265 | return $this->getMeta('UID') . $this->getValue('UID', 0, 0); | |
1266 | } | |
1267 | ||
1268 | /** | |
1269 | * Sets the value of the AGENT component. There is only one allowed | |
1270 | * per vCard. | |
1271 | * | |
1272 | * @param string $text The value to set for this component. | |
1273 | * | |
1274 | * @access public | |
1275 | * @return void | |
1276 | */ | |
1277 | function setAgent($text) | |
1278 | { | |
1279 | $this->autoparam = 'AGENT'; | |
1280 | $this->setValue('AGENT', 0, 0, $text); | |
1281 | } | |
1282 | ||
1283 | /** | |
1284 | * Gets back the value of the AGENT component. There is only one | |
1285 | * allowed per vCard. | |
1286 | * | |
1287 | * @access public | |
1288 | * @return string The value of this component. | |
1289 | */ | |
1290 | function getAgent() | |
1291 | { | |
1292 | return $this->getMeta('AGENT') . $this->getValue('AGENT', 0, 0); | |
1293 | } | |
1294 | ||
1295 | /** | |
1296 | * Sets the value of both parts of the GEO component. There is only | |
1297 | * one GEO component allowed per vCard. | |
1298 | * | |
1299 | * @param string $lat The value to set for the longitude part | |
1300 | * (decimal, + or -). | |
1301 | * @param string $lon The value to set for the latitude part | |
1302 | * (decimal, + or -). | |
1303 | * | |
1304 | * @access public | |
1305 | * @return void | |
1306 | */ | |
1307 | function setGeo($lat, $lon) | |
1308 | { | |
1309 | $this->autoparam = 'GEO'; | |
1310 | $this->setValue('GEO', 0, VCARD_GEO_LAT, $lat); | |
1311 | $this->setValue('GEO', 0, VCARD_GEO_LON, $lon); | |
1312 | } | |
1313 | ||
1314 | /** | |
1315 | * Gets back the value of the GEO component. There is only one | |
1316 | * allowed per vCard. | |
1317 | * | |
1318 | * @access public | |
1319 | * @return string The value of this component. | |
1320 | */ | |
1321 | function getGeo() | |
1322 | { | |
1323 | return $this->getMeta('GEO', 0) . | |
1324 | $this->getValue('GEO', 0, VCARD_GEO_LAT, 0) . ';' . | |
1325 | $this->getValue('GEO', 0, VCARD_GEO_LON, 0); | |
1326 | } | |
1327 | ||
1328 | /** | |
1329 | * Sets the value of one entire ADR iteration. There can be zero, | |
1330 | * one, or more ADR components in a vCard. | |
1331 | * | |
1332 | * @param mixed $pob String (one repetition) or array (multiple | |
1333 | * repetitions) of the p.o. box part of the ADR | |
1334 | * component iteration. | |
1335 | * @param mixed $extend String (one repetition) or array (multiple | |
1336 | * repetitions) of the "extended address" part | |
1337 | * of the ADR component iteration. | |
1338 | * @param mixed $street String (one repetition) or array (multiple | |
1339 | * repetitions) of the street address part of | |
1340 | * the ADR component iteration. | |
1341 | * @param mixed $locality String (one repetition) or array (multiple | |
1342 | * repetitions) of the locailty (e.g., city) part of the | |
1343 | * ADR component iteration. | |
1344 | * @param mixed $region String (one repetition) or array (multiple | |
1345 | * repetitions) of the region (e.g., state, province, or | |
1346 | * governorate) part of the ADR component iteration. | |
1347 | * @param mixed $postcode String (one repetition) or array (multiple | |
1348 | * repetitions) of the postal code (e.g., ZIP code) part | |
1349 | * of the ADR component iteration. | |
1350 | * @param mixed $country String (one repetition) or array (multiple | |
1351 | * repetitions) of the country-name part of the ADR | |
1352 | * component iteration. | |
1353 | * | |
1354 | * @access public | |
1355 | * @return void | |
1356 | */ | |
1357 | function addAddress($pob, $extend, $street, $locality, $region, | |
1358 | $postcode, $country) | |
1359 | { | |
1360 | $this->autoparam = 'ADR'; | |
1361 | $iter = $this->countIter('ADR'); | |
1362 | $this->setValue('ADR', $iter, VCARD_ADR_POB, $pob); | |
1363 | $this->setValue('ADR', $iter, VCARD_ADR_EXTEND, $extend); | |
1364 | $this->setValue('ADR', $iter, VCARD_ADR_STREET, $street); | |
1365 | $this->setValue('ADR', $iter, VCARD_ADR_LOCALITY, $locality); | |
1366 | $this->setValue('ADR', $iter, VCARD_ADR_REGION, $region); | |
1367 | $this->setValue('ADR', $iter, VCARD_ADR_POSTCODE, $postcode); | |
1368 | $this->setValue('ADR', $iter, VCARD_ADR_COUNTRY, $country); | |
1369 | } | |
1370 | ||
1371 | /** | |
1372 | * Gets back the value of one ADR component iteration. | |
1373 | * | |
1374 | * @param int $iter The component iteration-number to get the value | |
1375 | * for. | |
1376 | * | |
1377 | * @access public | |
1378 | * @return mixed The value of this component iteration, or a | |
1379 | * PEAR_Error if the iteration is not valid. | |
1380 | */ | |
1381 | function getAddress($iter) | |
1382 | { | |
1383 | if (! is_integer($iter) || $iter < 0) { | |
1384 | return $this->raiseError('ADR iteration number not valid.'); | |
1385 | } | |
1386 | return $this->getMeta('ADR', $iter) . | |
1387 | $this->getValue('ADR', $iter, VCARD_ADR_POB) . ';' . | |
1388 | $this->getValue('ADR', $iter, VCARD_ADR_EXTEND) . ';' . | |
1389 | $this->getValue('ADR', $iter, VCARD_ADR_STREET) . ';' . | |
1390 | $this->getValue('ADR', $iter, VCARD_ADR_LOCALITY) . ';' . | |
1391 | $this->getValue('ADR', $iter, VCARD_ADR_REGION) . ';' . | |
1392 | $this->getValue('ADR', $iter, VCARD_ADR_POSTCODE) . ';' . | |
1393 | $this->getValue('ADR', $iter, VCARD_ADR_COUNTRY); | |
1394 | } | |
1395 | ||
1396 | /** | |
1397 | * Sets the value of one LABEL component iteration. There can be | |
1398 | * zero, one, or more component iterations in a vCard. | |
1399 | * | |
1400 | * @param string $text The value to set for this component. | |
1401 | * | |
1402 | * @access public | |
1403 | * @return void | |
1404 | */ | |
1405 | function addLabel($text) | |
1406 | { | |
1407 | $this->autoparam = 'LABEL'; | |
1408 | $iter = $this->countIter('LABEL'); | |
1409 | $this->setValue('LABEL', $iter, 0, $text); | |
1410 | } | |
1411 | ||
1412 | /** | |
1413 | * Gets back the value of one iteration of the LABEL component. | |
1414 | * There can be zero, one, or more component iterations in a vCard. | |
1415 | * | |
1416 | * @param int $iter The component iteration-number to get the value | |
1417 | * for. | |
1418 | * | |
1419 | * @access public | |
1420 | * @return mixed The value of this component, or a PEAR_Error if | |
1421 | * the iteration number is not valid. | |
1422 | */ | |
1423 | function getLabel($iter) | |
1424 | { | |
1425 | if (! is_integer($iter) || $iter < 0) { | |
1426 | return $this->raiseError('LABEL iteration number not valid.'); | |
1427 | } | |
1428 | return $this->getMeta('LABEL', $iter) . | |
1429 | $this->getValue('LABEL', $iter, 0); | |
1430 | } | |
1431 | ||
1432 | /** | |
1433 | * Sets the value of one component iteration. There can be zero, | |
1434 | * one, or more component iterations in a vCard. This function also | |
1435 | * takes a type argument to be able to add mobiles, fax and voice | |
1436 | * as well. | |
1437 | * | |
1438 | * @param string $text The value to set for this component. | |
1439 | * @param string $type The type: phone, mobile, fax or voice | |
1440 | * | |
1441 | * @access public | |
1442 | * @return mixed void on success, PEAR_Error on failure | |
1443 | * @uses self::_getTelephoneType() | |
1444 | */ | |
1445 | function addTelephone($text, $type = 'phone') | |
1446 | { | |
1447 | $autoparam = $this->_getTelephoneType($type); | |
1448 | if (PEAR::isError($autoparam)) { | |
1449 | return $autoparam; | |
1450 | } | |
1451 | ||
1452 | $iter = $this->countIter($autoparam); | |
1453 | $this->setValue($autoparam, $iter, 0, $text); | |
1454 | ||
1455 | $this->autoparam = $autoparam; | |
1456 | } | |
1457 | ||
1458 | /** | |
1459 | * Gets back the value of one iteration of the TEL component. There | |
1460 | * can be zero, one, or more component iterations in a vCard. | |
1461 | * | |
1462 | * @param int $iter The component iteration-number to get the value | |
1463 | * for. | |
1464 | * @param string $type The type: phone, mobile, fax, voice | |
1465 | * | |
1466 | * @access public | |
1467 | * @return mixed The value of this component, or a PEAR_Error if the | |
1468 | * iteration number is not valid. | |
1469 | * @uses self::_getTelephoneType() | |
1470 | */ | |
1471 | function getTelephone($iter, $type = 'phone') | |
1472 | { | |
1473 | $autoparam = $this->_getTelephoneType($type); | |
1474 | if (PEAR::isError($autoparam)) { | |
1475 | return $autoparam; | |
1476 | } | |
1477 | ||
1478 | if (!is_integer($iter) || $iter < 0) { | |
1479 | return $this->raiseError($autoparam . ' iteration number not valid.'); | |
1480 | } | |
1481 | ||
1482 | return $this->getMeta($autoparam, $iter) . | |
1483 | $this->getValue($autoparam, $iter, 0); | |
1484 | } | |
1485 | ||
1486 | /** | |
1487 | * Sets the value of one EMAIL component iteration. There can be zero, | |
1488 | * one, or more component iterations in a vCard. | |
1489 | * | |
1490 | * @param string $text The value to set for this component. | |
1491 | * | |
1492 | * @access public | |
1493 | * @return void | |
1494 | */ | |
1495 | function addEmail($text) | |
1496 | { | |
1497 | $this->autoparam = 'EMAIL'; | |
1498 | $iter = $this->countIter('EMAIL'); | |
1499 | $this->setValue('EMAIL', $iter, 0, $text); | |
1500 | } | |
1501 | ||
1502 | /** | |
1503 | * Gets back the value of one iteration of the EMAIL component. There can | |
1504 | * be zero, one, or more component iterations in a vCard. | |
1505 | * | |
1506 | * @param int $iter The component iteration-number to get the value | |
1507 | * for. | |
1508 | * | |
1509 | * @access public | |
1510 | * | |
1511 | * @return mixed The value of this component, or a PEAR_Error if the | |
1512 | * iteration number is not valid. | |
1513 | * | |
1514 | */ | |
1515 | function getEmail($iter) | |
1516 | { | |
1517 | if (! is_integer($iter) || $iter < 0) { | |
1518 | return $this->raiseError('EMAIL iteration number not valid.'); | |
1519 | } | |
1520 | return $this->getMeta('EMAIL', $iter) . | |
1521 | $this->getValue('EMAIL', $iter, 0); | |
1522 | } | |
1523 | ||
1524 | /** | |
1525 | * Sets the full value of the NICKNAME component. There is only one | |
1526 | * component iteration allowed per vCard, but there may be multiple | |
1527 | * value repetitions in the iteration. | |
1528 | * | |
1529 | * @param mixed $text String (one repetition) or array (multiple | |
1530 | * reptitions) of the component iteration value. | |
1531 | * | |
1532 | * @access public | |
1533 | * @return void | |
1534 | */ | |
1535 | function addNickname($text) | |
1536 | { | |
1537 | $this->autoparam = 'NICKNAME'; | |
1538 | $this->addValue('NICKNAME', 0, 0, $text); | |
1539 | } | |
1540 | ||
1541 | /** | |
1542 | * Gets back the value of the NICKNAME component. There is only one | |
1543 | * component allowed per vCard, but there may be multiple value | |
1544 | * repetitions in the iteration. | |
1545 | * | |
1546 | * @access public | |
1547 | * @return string The value of this component. | |
1548 | */ | |
1549 | function getNickname() | |
1550 | { | |
1551 | return $this->getMeta('NICKNAME') . $this->getValue('NICKNAME', 0, 0); | |
1552 | } | |
1553 | ||
1554 | /** | |
1555 | * Sets the full value of the CATEGORIES component. There is only | |
1556 | * one component iteration allowed per vCard, but there may be | |
1557 | * multiple value repetitions in the iteration. | |
1558 | * | |
1559 | * @param mixed $text String (one repetition) or array (multiple reptitions) | |
1560 | * of the component iteration value. | |
1561 | * | |
1562 | * @access public | |
1563 | * @return void | |
1564 | */ | |
1565 | function addCategories($text) | |
1566 | { | |
1567 | $this->autoparam = 'CATEGORIES'; | |
1568 | $this->addValue('CATEGORIES', 0, 0, $text); | |
1569 | } | |
1570 | ||
1571 | /** | |
1572 | * Gets back the value of the CATEGORIES component. There is only | |
1573 | * one component allowed per vCard, but there may be multiple value | |
1574 | * repetitions in the iteration. | |
1575 | * | |
1576 | * @access public | |
1577 | * @return string The value of this component. | |
1578 | */ | |
1579 | function getCategories() | |
1580 | { | |
1581 | return $this->getMeta('CATEGORIES', 0) . | |
1582 | $this->getValue('CATEGORIES', 0, 0); | |
1583 | } | |
1584 | ||
1585 | /** | |
1586 | * Sets the full value of the ORG component. There can be only one | |
1587 | * ORG component in a vCard. | |
1588 | * | |
1589 | * The ORG component can have one or more parts (as opposed to | |
1590 | * repetitions of values within those parts). The first part is the | |
1591 | * highest-level organization, the second part is the next-highest, | |
1592 | * the third part is the third-highest, and so on. There can by any | |
1593 | * number of parts in one ORG iteration. (This is different from | |
1594 | * other components, such as NICKNAME, where an iteration has only | |
1595 | * one part but may have many repetitions within that part.) | |
1596 | * | |
1597 | * @param mixed $text String (one ORG part) or array (of ORG parts) to | |
1598 | * use as the value for the component iteration. | |
1599 | * | |
1600 | * @access public | |
1601 | * @return void | |
1602 | */ | |
1603 | function addOrganization($text) | |
1604 | { | |
1605 | $this->autoparam = 'ORG'; | |
1606 | ||
1607 | settype($text, 'array'); | |
1608 | ||
1609 | $base = $this->countRept('ORG', 0); | |
1610 | ||
1611 | // start at the original base point, and add | |
1612 | // new parts | |
1613 | foreach ($text as $part => $val) { | |
1614 | $this->setValue('ORG', 0, $base + $part, $val); | |
1615 | } | |
1616 | } | |
1617 | ||
1618 | /** | |
1619 | * Gets back the value of the ORG component. | |
1620 | * | |
1621 | * @return string The value of this component. | |
1622 | * @access public | |
1623 | */ | |
1624 | function getOrganization() | |
1625 | { | |
1626 | $text = $this->getMeta('ORG', 0); | |
1627 | ||
1628 | $k = $this->countRept('ORG', 0); | |
1629 | $last = $k - 1; | |
1630 | ||
1631 | for ($part = 0; $part < $k; $part++) { | |
1632 | ||
1633 | $text .= $this->getValue('ORG', 0, $part); | |
1634 | ||
1635 | if ($part != $last) { | |
1636 | $text .= ';'; | |
1637 | } | |
1638 | ||
1639 | } | |
1640 | ||
1641 | return $text; | |
1642 | } | |
1643 | ||
1644 | /** | |
1645 | * Builds a vCard from a Contact_Vcard_Parse result array. Only send | |
1646 | * one vCard from the parse-results. | |
1647 | * | |
1648 | * Usage (to build from first vCard in parsed results): | |
1649 | * | |
1650 | * $parse = new Contact_Vcard_Parse(); // new parser | |
1651 | * $info = $parse->fromFile('sample.vcf'); // parse file | |
1652 | * | |
1653 | * $vcard = new Contact_Vcard_Build(); // new builder | |
1654 | * $vcard->setFromArray($info[0]); // [0] is the first card | |
1655 | * | |
1656 | * @param array $src One vCard entry as parsed using | |
1657 | * Contact_Vcard_Parse. | |
1658 | * | |
1659 | * @access public | |
1660 | * @return void | |
1661 | * @see Contact_Vcard_Parse::fromFile() | |
1662 | * @see Contact_Vcard_Parse::fromText() | |
1663 | */ | |
1664 | function setFromArray($src) | |
1665 | { | |
1666 | // reset to a blank values and params | |
1667 | $this->value = array(); | |
1668 | $this->param = array(); | |
1669 | ||
1670 | // loop through components (N, ADR, TEL, etc) | |
1671 | foreach ($src as $comp => $comp_val) { | |
1672 | ||
1673 | // set the autoparam property. not really needed, but let's | |
1674 | // behave after an expected fashion, shall we? ;-) | |
1675 | $this->autoparam = $comp; | |
1676 | ||
1677 | // iteration number of each component | |
1678 | foreach ($comp_val as $iter => $iter_val) { | |
1679 | ||
1680 | // value or param? | |
1681 | foreach ($iter_val as $kind => $kind_val) { | |
1682 | ||
1683 | // part number | |
1684 | foreach ($kind_val as $part => $part_val) { | |
1685 | ||
1686 | // repetition number and text value | |
1687 | foreach ($part_val as $rept => $text) { | |
1688 | ||
1689 | // ignore data when $kind is neither 'value' | |
1690 | // nor 'param' | |
1691 | if (strtolower($kind) == 'value') { | |
1692 | $this->_setValue($comp, $iter, $part, $rept, $text); | |
1693 | } elseif (strtolower($kind) == 'param') { | |
1694 | $this->_setParam($comp, $iter, $part, $rept, $text); | |
1695 | } | |
1696 | } | |
1697 | } | |
1698 | } | |
1699 | } | |
1700 | } | |
1701 | } | |
1702 | ||
1703 | ||
1704 | /** | |
1705 | * Fetches a full vCard text block based on $this->value and | |
1706 | * $this->param. The order of the returned components is similar to | |
1707 | * their order in RFC 2426. Honors the value of | |
1708 | * $this->value['VERSION'] to determine which vCard components are | |
1709 | * returned (2.1- or 3.0-compliant). | |
1710 | * | |
1711 | * @access public | |
1712 | * @return string A properly formatted vCard text block. | |
1713 | */ | |
1714 | function fetch() | |
1715 | { | |
1716 | // vCard version is required | |
1717 | if (! is_array($this->value['VERSION'])) { | |
1718 | return $this->raiseError('VERSION not set (required).'); | |
1719 | } | |
1720 | ||
1721 | // FN component is required | |
1722 | if (! is_array($this->value['FN'])) { | |
1723 | return $this->raiseError('FN component not set (required).'); | |
1724 | } | |
1725 | ||
1726 | // N component is required | |
1727 | if (! is_array($this->value['N'])) { | |
1728 | return $this->raiseError('N component not set (required).'); | |
1729 | } | |
1730 | ||
1731 | // initialize the vCard lines | |
1732 | $lines = array(); | |
1733 | ||
1734 | // begin (required) | |
1735 | $lines[] = "BEGIN:VCARD"; | |
1736 | ||
1737 | // version (required) | |
1738 | // available in both 2.1 and 3.0 | |
1739 | $lines[] = $this->getVersion(); | |
1740 | ||
1741 | // profile (3.0 only) | |
1742 | if ($this->value['VERSION'][0][0][0] == '3.0') { | |
1743 | $lines[] = "PROFILE:VCARD"; | |
1744 | } | |
1745 | ||
1746 | // formatted name (required) | |
1747 | // available in both 2.1 and 3.0 | |
1748 | $lines[] = $this->getFormattedName(); | |
1749 | ||
1750 | // structured name (required) | |
1751 | // available in both 2.1 and 3.0 | |
1752 | $lines[] = $this->getName(); | |
1753 | ||
1754 | // displayed name of the data source (3.0 only) | |
1755 | if (isset($this->value['NAME']) && | |
1756 | $this->value['VERSION'][0][0][0] == '3.0') { | |
1757 | $lines[] = $this->getSourceName(); | |
1758 | } | |
1759 | ||
1760 | // data source (3.0 only) | |
1761 | if (isset($this->value['SOURCE']) && | |
1762 | $this->value['VERSION'][0][0][0] == '3.0') { | |
1763 | $lines[] = $this->getSource(); | |
1764 | } | |
1765 | ||
1766 | // nicknames (3.0 only) | |
1767 | if (isset($this->value['NICKNAME']) && | |
1768 | $this->value['VERSION'][0][0][0] == '3.0') { | |
1769 | $lines[] = $this->getNickname(); | |
1770 | } | |
1771 | ||
1772 | // personal photo | |
1773 | // available in both 2.1 and 3.0 | |
1774 | $_photo = $this->getPhoto(); | |
1775 | if ($_photo !== false) { | |
1776 | $lines[] = $_photo; | |
1777 | } | |
1778 | ||
1779 | // bday | |
1780 | // available in both 2.1 and 3.0 | |
1781 | if (isset($this->value['BDAY'])) { | |
1782 | $lines[] = $this->getBirthday(); | |
1783 | } | |
1784 | ||
1785 | // adr | |
1786 | // available in both 2.1 and 3.0 | |
1787 | if (isset($this->value['ADR'])) { | |
1788 | foreach ($this->value['ADR'] as $key => $val) { | |
1789 | $lines[] = $this->getAddress($key); | |
1790 | } | |
1791 | } | |
1792 | ||
1793 | // label | |
1794 | // available in both 2.1 and 3.0 | |
1795 | if (isset($this->value['LABEL'])) { | |
1796 | foreach ($this->value['LABEL'] as $key => $val) { | |
1797 | $lines[] = $this->getLabel($key); | |
1798 | } | |
1799 | } | |
1800 | ||
1801 | // tel | |
1802 | // available in both 2.1 and 3.0 | |
1803 | if (isset($this->value['TEL'])) { | |
1804 | foreach ($this->value['TEL'] as $key => $val) { | |
1805 | $lines[] = $this->getTelephone($key); | |
1806 | } | |
1807 | } | |
1808 | ||
1809 | // mobiles | |
1810 | if (isset($this->value['TEL;PREF;CELL'])) { | |
1811 | foreach ($this->value['TEL;PREF;CELL'] as $key => $val) { | |
1812 | $lines[] = $this->getTelephone($key, 'mobile'); | |
1813 | } | |
1814 | } | |
1815 | ||
1816 | // voice | |
1817 | if (isset($this->value['TEL;PREF;VOICE'])) { | |
1818 | foreach ($this->value['TEL;PREF;VOICE'] as $key => $val) { | |
1819 | $lines[] = $this->getTelephone($key, 'voice'); | |
1820 | } | |
1821 | } | |
1822 | ||
1823 | // fax | |
1824 | if (isset($this->value['TEL;PREF;FAX'])) { | |
1825 | foreach ($this->value['TEL;PREF;FAX'] as $key => $val) { | |
1826 | $lines[] = $this->getTelephone($key, 'fax'); | |
1827 | } | |
1828 | } | |
1829 | ||
1830 | ||
1831 | // available in both 2.1 and 3.0 | |
1832 | if (isset($this->value['EMAIL'])) { | |
1833 | foreach ($this->value['EMAIL'] as $key => $val) { | |
1834 | $lines[] = $this->getEmail($key); | |
1835 | } | |
1836 | } | |
1837 | ||
1838 | // mailer | |
1839 | // available in both 2.1 and 3.0 | |
1840 | if (isset($this->value['MAILER'])) { | |
1841 | $lines[] = $this->getMailer(); | |
1842 | } | |
1843 | ||
1844 | // tz | |
1845 | // available in both 2.1 and 3.0 | |
1846 | if (isset($this->value['TZ'])) { | |
1847 | $lines[] = $this->getTZ(); | |
1848 | } | |
1849 | ||
1850 | // geo | |
1851 | // available in both 2.1 and 3.0 | |
1852 | if (isset($this->value['GEO'])) { | |
1853 | $lines[] = $this->getGeo(); | |
1854 | } | |
1855 | ||
1856 | // title | |
1857 | // available in both 2.1 and 3.0 | |
1858 | if (isset($this->value['TITLE'])) { | |
1859 | $lines[] = $this->getTitle(); | |
1860 | } | |
1861 | ||
1862 | // role | |
1863 | // available in both 2.1 and 3.0 | |
1864 | if (isset($this->value['ROLE'])) { | |
1865 | $lines[] = $this->getRole(); | |
1866 | } | |
1867 | ||
1868 | // company logo | |
1869 | // available in both 2.1 and 3.0 | |
1870 | if (isset($this->value['LOGO'])) { | |
1871 | $lines[] = $this->getLogo(); | |
1872 | } | |
1873 | ||
1874 | // agent | |
1875 | // available in both 2.1 and 3.0 | |
1876 | if (isset($this->value['AGENT'])) { | |
1877 | $lines[] = $this->getAgent(); | |
1878 | } | |
1879 | ||
1880 | // org | |
1881 | // available in both 2.1 and 3.0 | |
1882 | if (isset($this->value['ORG'])) { | |
1883 | $lines[] = $this->getOrganization(); | |
1884 | } | |
1885 | ||
1886 | // categories (3.0 only) | |
1887 | if (isset($this->value['CATEGORIES']) && | |
1888 | $this->value['VERSION'][0][0][0] == '3.0') { | |
1889 | $lines[] = $this->getCategories(); | |
1890 | } | |
1891 | ||
1892 | // note | |
1893 | // available in both 2.1 and 3.0 | |
1894 | if (isset($this->value['NOTE'])) { | |
1895 | $lines[] = $this->getNote(); | |
1896 | } | |
1897 | ||
1898 | // prodid (3.0 only) | |
1899 | if (isset($this->value['PRODID']) && | |
1900 | $this->value['VERSION'][0][0][0] == '3.0') { | |
1901 | $lines[] = $this->getProductID(); | |
1902 | } | |
1903 | ||
1904 | // rev | |
1905 | // available in both 2.1 and 3.0 | |
1906 | if (isset($this->value['REV'])) { | |
1907 | $lines[] = $this->getRevision(); | |
1908 | } | |
1909 | ||
1910 | // sort-string (3.0 only) | |
1911 | if (isset($this->value['SORT-STRING']) && | |
1912 | $this->value['VERSION'][0][0][0] == '3.0') { | |
1913 | $lines[] = $this->getSortString(); | |
1914 | } | |
1915 | ||
1916 | // name-pronounciation sound | |
1917 | // available in both 2.1 and 3.0 | |
1918 | if (isset($this->value['SOUND'])) { | |
1919 | $lines[] = $this->getSound(); | |
1920 | } | |
1921 | ||
1922 | // uid | |
1923 | // available in both 2.1 and 3.0 | |
1924 | if (isset($this->value['UID'])) { | |
1925 | $lines[] = $this->getUniqueID(); | |
1926 | } | |
1927 | ||
1928 | // url | |
1929 | // available in both 2.1 and 3.0 | |
1930 | if (isset($this->value['URL'])) { | |
1931 | $lines[] = $this->getURL(); | |
1932 | } | |
1933 | ||
1934 | // class (3.0 only) | |
1935 | if (isset($this->value['CLASS']) && | |
1936 | $this->value['VERSION'][0][0][0] == '3.0') { | |
1937 | $lines[] = $this->getClass(); | |
1938 | } | |
1939 | ||
1940 | // key | |
1941 | // available in both 2.1 and 3.0 | |
1942 | if (isset($this->value['KEY'])) { | |
1943 | $lines[] = $this->getKey(); | |
1944 | } | |
1945 | ||
1946 | // required | |
1947 | $lines[] = "END:VCARD"; | |
1948 | ||
1949 | // version 3.0 uses \n for new lines, | |
1950 | // version 2.1 uses \r\n | |
1951 | $newline = "\n"; | |
1952 | if ($this->value['VERSION'][0][0][0] == '2.1') { | |
1953 | $newline = "\r\n"; | |
1954 | } | |
1955 | ||
1956 | // fold lines at 75 characters | |
1957 | // commented out as a possible fix for Outlook compatibility | |
1958 | // $regex = "(.{1,75})"; | |
1959 | // foreach ($lines as $key => $val) { | |
1960 | // if (strlen($val) > 75) { | |
1961 | // // we trim to drop the last newline, which will be added | |
1962 | // // again by the implode function at the end of fetch() | |
1963 | // $lines[$key] = trim(preg_replace("/$regex/i", "\\1$newline ", $val)); | |
1964 | // } | |
1965 | // } | |
1966 | ||
1967 | // recode the lines from UTF-8 to lowest covering charset | |
1968 | $lines = $this->charsetRecode($lines); | |
1969 | ||
1970 | // compile the array of lines into a single text block | |
1971 | // and return (with a trailing newline) | |
1972 | return implode($newline, $lines). $newline; | |
1973 | } | |
1974 | ||
1975 | /** | |
1976 | * Send the vCard as a downloadable file. | |
1977 | * | |
1978 | * @param string $filename The file name to give the vCard. | |
1979 | * @param string $disposition How the file should be sent, either | |
1980 | * 'inline' or 'attachment'. | |
1981 | * @param string $charset The character set to use, defaults to | |
1982 | * 'us-ascii'. | |
1983 | * | |
1984 | * @access public | |
1985 | * @return void or Pear_Error in case of an error. | |
1986 | */ | |
1987 | function send($filename, $disposition = 'attachment', $charset = 'us-ascii') | |
1988 | { | |
1989 | $vcard = $this->fetch(); | |
1990 | if (PEAR::isError($vcard)) { | |
1991 | return $vcard; | |
1992 | } | |
1993 | ||
1994 | header('Content-Type: application/directory; ' . | |
1995 | 'profile="vcard"; ' . | |
1996 | 'charset=' . $charset); | |
1997 | ||
1998 | header('Cache-Control: must-revalidate,post-check=0, pre-check=0'); | |
1999 | header('Pragma: public'); | |
2000 | header('Content-Length: ' . strlen($vcard)); | |
2001 | header("Content-Disposition: $disposition; filename=\"$filename\""); | |
2002 | ||
2003 | echo $vcard; | |
2004 | } | |
2005 | ||
2006 | /** | |
2007 | * Gets the left-side/prefix/before-the-colon (metadata) part of a | |
2008 | * vCard line, including the component identifier, the parameter | |
2009 | * list, and a colon. | |
2010 | * | |
2011 | * @param string $comp The component to get metadata for (ADR, TEL, etc). | |
2012 | * @param int $iter The vCard component iteration to get the metadata | |
2013 | * for. E.g., if you have more than one ADR component, | |
2014 | * 0 refers to the first ADR, 1 to the second ADR, | |
2015 | * and so on. | |
2016 | * | |
2017 | * @access public | |
2018 | * @return string The line prefix metadata. | |
2019 | */ | |
2020 | function getMeta($comp, $iter = 0) | |
2021 | { | |
2022 | $params = $this->getParam($comp, $iter); | |
2023 | ||
2024 | if (trim($params) == '') { | |
2025 | // no parameters | |
2026 | $text = $comp . ':'; | |
2027 | } else { | |
2028 | // has parameters. put an extra semicolon in. | |
2029 | $text = $comp . ';' . $params . ':'; | |
2030 | } | |
2031 | ||
2032 | return $text; | |
2033 | } | |
2034 | ||
2035 | /** | |
2036 | * Recode the lines to the 'smallest' encoding and add the charset info | |
2037 | * | |
2038 | * As, surprise surprise, Microsoft Outlook does not seem to be able to | |
2039 | * handle properly tagged UTF-8 vCards, we try to represent the text in | |
2040 | * smallest charset 'covering' the text in full (currently the test goes | |
2041 | * 'US-ASCII' -> 'ISO-8859-1' -> 'CP1250' and falls back to 'UTF-8') | |
2042 | * | |
2043 | * @param array $lines the vCard's lines | |
2044 | * | |
2045 | * @return array the recoded and properly tagged lines | |
2046 | */ | |
2047 | function charsetRecode($lines) { | |
2048 | ||
2049 | $charsets = array('US-ASCII', 'ISO-8859-1', 'CP1250'); | |
2050 | ||
2051 | if ((function_exists('iconv_strlen') or function_exists('mb_strlen')) and function_exists('iconv')) { | |
2052 | ||
2053 | // for each line, get the character length of the UTF-8 string | |
2054 | // and try to recode it to every charset in turn; iconv() returns | |
2055 | // truncated strings on recode errors, so if the character length | |
2056 | // after the recode equals the one before - we've found a valid | |
2057 | // charset | |
2058 | foreach ($lines as $number => $line) { | |
2059 | $lineCharset = 'UTF-8'; | |
2060 | if (function_exists('iconv_strlen')) { | |
2061 | $strlen = iconv_strlen($line, 'UTF-8'); | |
2062 | } else { | |
2063 | $strlen = mb_strlen($line, 'UTF-8'); | |
2064 | } | |
2065 | foreach ($charsets as $charset) { | |
2066 | $iconvd = iconv('UTF-8', $charset, $line); | |
2067 | if (strlen($iconvd) == $strlen) { | |
2068 | $lineCharset = $charset; | |
2069 | $line = $iconvd; | |
2070 | break; | |
2071 | } | |
2072 | } | |
2073 | // tag the non-US-ASCII-only, recoded lines properly | |
2074 | if ($lineCharset != 'US-ASCII') { | |
2075 | $lines[$number] = preg_replace('/:/', ";ENCODING=8BIT;CHARSET=$lineCharset:", $line, 1); | |
2076 | } | |
2077 | } | |
2078 | ||
2079 | } else { | |
2080 | ||
2081 | // if there's no mb_strings or iconv support, | |
2082 | // simply tag the non-US-ASCII-only lines as UTF-8 | |
2083 | foreach ($lines as $number => $line) { | |
2084 | if (preg_match('/[^\x00-\x7f]/', $line)) { | |
2085 | $lines[$number] = preg_replace('/:/', ";ENCODING=8BIT;CHARSET=UTF-8:", $line, 1); | |
2086 | } | |
2087 | } | |
2088 | ||
2089 | } | |
2090 | ||
2091 | return $lines; | |
2092 | } | |
2093 | ||
2094 | /** | |
2095 | * Count the number of iterations for an element type. | |
2096 | * | |
2097 | * @param string $type The element type to count iterations for | |
2098 | * (ADR, ORG, etc). | |
2099 | * | |
2100 | * @access public | |
2101 | * @return int The number of iterations for that type. | |
2102 | */ | |
2103 | function countIter($type) | |
2104 | { | |
2105 | if (!isset($this->value[$type])) { | |
2106 | return 0; | |
2107 | } | |
2108 | return count($this->value[$type]); | |
2109 | } | |
2110 | ||
2111 | /** | |
2112 | * Count the number of repetitions for an element type and iteration | |
2113 | * number. | |
2114 | * | |
2115 | * @param string $type The element type to count iterations for | |
2116 | * (ADR, ORG, etc). | |
2117 | * @param int $rept The iteration number to count repetitions for. | |
2118 | * | |
2119 | * @access public | |
2120 | * @return int The number of repetitions for that type and iteration. | |
2121 | */ | |
2122 | function countRept($type, $rept) | |
2123 | { | |
2124 | if (!isset($this->value[$type][$rept])) { | |
2125 | return 0; | |
2126 | } | |
2127 | return count($this->value[$type][$rept]); | |
2128 | } | |
2129 | ||
2130 | /** | |
2131 | * Emulated destructor. | |
2132 | * | |
2133 | * @access private | |
2134 | * @return boolean true | |
2135 | */ | |
2136 | function _Contact_Vcard_Build() | |
2137 | { | |
2138 | return true; | |
2139 | } | |
2140 | ||
2141 | /** | |
2142 | * _setValue | |
2143 | * | |
2144 | * @param string $comp The component to set the value for ('N', | |
2145 | * 'ADR', etc). | |
2146 | * @param int $iter The component-iteration to set the value for. | |
2147 | * the value for. | |
2148 | * @param int $part The part number of the component-iteration to set | |
2149 | * @param mixed $rept The repetition number within the part to get; | |
2150 | * if null, get all repetitions of the part within the | |
2151 | * iteration. | |
2152 | * @param mixed $text A string or array; the set of repeated values | |
2153 | * for this component-iteration part. | |
2154 | * | |
2155 | * @access protected | |
2156 | * @return void | |
2157 | */ | |
2158 | function _setValue($comp, $iter, $part, $rept, $text) | |
2159 | { | |
2160 | $this->value[strtoupper($comp)][$iter][$part][$rept] = $text; | |
2161 | } | |
2162 | ||
2163 | /** | |
2164 | * _setParam | |
2165 | * | |
2166 | * @param string $comp The component to set the param for. | |
2167 | * @param int $iter The component-iteration to set the param for. | |
2168 | * @param int $part The part number of the component-iteration to set | |
2169 | * the param for. | |
2170 | * @param mixed $rept The repetition number within the part to get; | |
2171 | * if null, get all repetitions of the part within the | |
2172 | * iteration. | |
2173 | * @param mixed $text A string or array; the set of repeated values | |
2174 | * for this component-iteration part. | |
2175 | * | |
2176 | * @access protected | |
2177 | * @return void | |
2178 | */ | |
2179 | function _setParam($comp, $iter, $part, $rept, $text) | |
2180 | { | |
2181 | $this->param[strtoupper($comp)][$iter][$part][$rept] = $text; | |
2182 | } | |
2183 | ||
2184 | /** | |
2185 | * _getTelephoneType | |
2186 | * | |
2187 | * Resolves a HR friendly type to the internal | |
2188 | * type used in the VCARD spec. | |
2189 | * | |
2190 | * @param string $type The type?! | |
2191 | * | |
2192 | * @access private | |
2193 | * @return mixed string $type or Pear_Error | |
2194 | * @see self::addTelephone() | |
2195 | * @ses self::getTelephone() | |
2196 | * @since 1.1.2 | |
2197 | */ | |
2198 | function _getTelephoneType($type) | |
2199 | { | |
2200 | switch ($type) { | |
2201 | ||
2202 | case 'phone': | |
2203 | return 'TEL'; | |
2204 | break; | |
2205 | ||
2206 | case 'mobile': | |
2207 | return 'TEL;PREF;CELL'; | |
2208 | break; | |
2209 | ||
2210 | case 'voice': | |
2211 | return 'TEL;PREF;VOICE'; | |
2212 | break; | |
2213 | ||
2214 | case 'fax': | |
2215 | return 'TEL;PREF;FAX'; | |
2216 | break; | |
2217 | ||
2218 | default: | |
2219 | $msg = 'Type: ' . $type . ' is not yet implemented.'; | |
2220 | return $this->raiseError($msg); | |
2221 | break; | |
2222 | } | |
2223 | } | |
2224 | } | |
2225 | ?> |