1<?php
2/**
3 * Copyright 2012-2017 Horde LLC (http://www.horde.org/)
4 *
5 * See the enclosed file LICENSE for license information (BSD). If you
6 * did not receive this file, see http://www.horde.org/licenses/bsd.
7 *
8 * @category  Horde
9 * @copyright 2012-2017 Horde LLC
10 * @license   http://www.horde.org/licenses/bsd New BSD License
11 * @package   Mail
12 */
13
14/**
15 * Object representation of an RFC 822 element.
16 *
17 * @author    Michael Slusarz <slusarz@horde.org>
18 * @category  Horde
19 * @copyright 2012-2017 Horde LLC
20 * @license   http://www.horde.org/licenses/bsd New BSD License
21 * @package   Mail
22 */
23abstract class Horde_Mail_Rfc822_Object
24{
25    /**
26     * String representation of object.
27     *
28     * @return string  Returns the full e-mail address.
29     */
30    public function __toString()
31    {
32        return $this->writeAddress();
33    }
34
35    /**
36     * Write an address given information in this part.
37     *
38     * @param mixed $opts  If boolean true, is equivalent to passing true for
39     *                     both 'encode' and 'idn'. If an array, these
40     *                     keys are supported:
41     *   - comment: (boolean) If true, include comment(s) in output?
42     *              @since 2.6.0
43     *              DEFAULT: false
44     *   - encode: (mixed) MIME encode the personal/groupname parts?
45     *             If boolean true, encodes in 'UTF-8'.
46     *             If a string, encodes using this charset.
47     *             DEFAULT: false
48     *   - idn: (boolean) If true, encodes IDN domain names (RFC 3490).
49     *          DEFAULT: false
50     *   - noquote: (boolean) If true, don't quote personal part. [@since
51     *              2.4.0]
52     *              DEFAULT: false
53     *
54     * @return string  The correctly escaped/quoted address.
55     */
56    public function writeAddress($opts = array())
57    {
58        if ($opts === true) {
59            $opts = array(
60                'encode' => 'UTF-8',
61                'idn' => true
62            );
63        } elseif (!empty($opts['encode']) && ($opts['encode'] === true)) {
64            $opts['encode'] = 'UTF-8';
65        }
66
67        return $this->_writeAddress($opts);
68    }
69
70    /**
71     * Class-specific implementation of writeAddress().
72     *
73     * @see writeAddress()
74     *
75     * @param array $opts  See writeAddress().
76     *
77     * @return string  The correctly escaped/quoted address.
78     */
79    abstract protected function _writeAddress($opts);
80
81    /**
82     * Compare this object against other data.
83     *
84     * @param mixed $ob  Address data.
85     *
86     * @return boolean  True if the data reflects the same canonical address.
87     */
88    abstract public function match($ob);
89
90}
91