1<?php
2/**
3 * Provides array access to Kolab objects.
4 *
5 * PHP version 5
6 *
7 * @category Kolab
8 * @package  Kolab_Server
9 * @author   Gunnar Wrobel <wrobel@pardus.de>
10 * @license  http://www.horde.org/licenses/lgpl21 LGPL 2.1
11 * @link     http://pear.horde.org/index.php?package=Kolab_Server
12 */
13
14/**
15 * Provides array access to Kolab objects.
16 *
17 * Copyright 2008-2016 Horde LLC (http://www.horde.org/)
18 *
19 * See the enclosed file COPYING for license information (LGPL). If you
20 * did not receive this file, see http://www.horde.org/licenses/lgpl21.
21 *
22 * @category Kolab
23 * @package  Kolab_Server
24 * @author   Gunnar Wrobel <wrobel@pardus.de>
25 * @license  http://www.horde.org/licenses/lgpl21 LGPL 2.1
26 * @link     http://pear.horde.org/index.php?package=Kolab_Server
27 */
28class Horde_Kolab_Server_Object_Hash
29implements Horde_Kolab_Server_Object_Interface
30//@todo: Implement ArrayAccess
31{
32    /**
33     * Link to the decorated object.
34     *
35     * @var Horde_Kolab_Server_Object
36     */
37    private $_object;
38
39    /**
40     * Initialize the Kolab Object. Provide either the GUID
41     *
42     * @param Horde_Kolab_Server_Object $object The represented object.
43     */
44    public function __construct(
45        Horde_Kolab_Server_Object_Interface $object
46    ) {
47        $this->_object = $object;
48    }
49
50    /**
51     * Get the GUID of this object
52     *
53     * @return string the GUID of this object
54     */
55    public function getGuid()
56    {
57        return $this->_object->getGuid();
58    }
59
60    /**
61     * Get the external attributes supported by this object.
62     *
63     * @return array The external attributes supported by this object. This is
64     * an association of attribute names and attribute handler class names.
65     */
66    public function getExternalAttributes()
67    {
68        return $this->_object->getExternalAttributes();
69    }
70
71    /**
72     * Get the internal attributes supported by this object.
73     *
74     * @return array The internal attributes supported by this object.
75     */
76    public function getInternalAttributes()
77    {
78        return $this->_object->getInternalAttributes();
79    }
80
81    /**
82     * Does the object exist?
83     *
84     * @return NULL
85     */
86    public function exists()
87    {
88        return $this->_object->exists();
89    }
90
91    /**
92     * Read the object into the cache
93     *
94     * @return array The read data.
95     */
96    public function readInternal()
97    {
98        return $this->_object->readInternal();
99    }
100
101    /**
102     * Get the specified internal attributes.
103     *
104     * @param array $attributes The internal attribute.
105     *
106     * @return array The value(s) of these attribute
107     */
108    public function getInternal(array $attributes)
109    {
110        return $this->_object->getInternal($attributes);
111    }
112
113    /**
114     * Get the specified attribute of this object.
115     *
116     * @param string $attr The attribute to read.
117     *
118     * @return mixed The value of this attribute.
119     */
120    public function getExternal($attr)
121    {
122        return $this->_object->getExternal($attr);
123    }
124
125    /**
126     * Get the specified attribute of this object and ensure that only a single
127     * value is being returned.
128     *
129     * @param string $attr The attribute to read.
130     *
131     * @return mixed The value of this attribute.
132     */
133    public function getSingle($attr)
134    {
135        $value = $this->getExternal($attr);
136        //@todo: Check if that can actually be something other than an array.
137        if (is_array($value)) {
138            return array_shift($value);
139        } else {
140            return $value;
141        }
142    }
143
144    /**
145     * Convert the object attributes to a hash.
146     *
147     * @param array   $attrs  The attributes to return.
148     * @param boolean $single Should only a single attribute be returned?
149     *
150     * @return array|PEAR_Error The hash representing this object.
151     */
152    public function toHash(array $attrs = array(), $single = true)
153    {
154        $result = array();
155
156        /**
157         * Return all supported attributes if no specific attributes were
158         * requested.
159         */
160        if (empty($attrs)) {
161            $attrs = array_keys($this->attributes);
162        }
163
164        foreach ($attrs as $key) {
165            if ($single) {
166                $result[$key] = $this->getSingle($key);
167            } else {
168                $result[$key] = $this->getExternal($key);
169            }
170        }
171        return $result;
172    }
173
174    /**
175     * Saves object information. This may either create a new entry or modify an
176     * existing entry.
177     *
178     * Please note that fields with multiple allowed values require the callee
179     * to provide the full set of values for the field. Any old values that are
180     * not resubmitted will be considered to be deleted.
181     *
182     * @param array $info The information about the object.
183     *
184     * @return NULL
185     *
186     * @throws Horde_Kolab_Server_Exception If saving the data failed.
187     */
188    public function save(array $info)
189    {
190        $this->_object->save($info);
191    }
192
193    /**
194     * Delete this object.
195     *
196     * @return NULL
197     *
198     * @throws Horde_Kolab_Server_Exception If deleting the object failed.
199     */
200    public function delete()
201    {
202        $this->_object->delete();
203    }
204
205    /**
206     * Generates an ID for the given information.
207     *
208     * @param array &$info The data of the object.
209     *
210     * @return string The ID.
211     */
212    public function generateId(array &$info)
213    {
214        $this->_object->generateId($info);
215    }
216
217    /**
218     * Distill the server side object information to save.
219     *
220     * @param array &$info The information about the object.
221     *
222     * @return NULL.
223     *
224     * @throws Horde_Kolab_Server_Exception If the given information contains errors.
225     */
226    public function prepareObjectInformation(array &$info)
227    {
228        $this->_object->prepareObjectInformation($info);
229    }
230
231    /**
232     * Returns the set of actions supported by this object type.
233     *
234     * @return array An array of supported actions.
235     */
236    public function getActions()
237    {
238        $this->_object->getActions();
239    }
240}
241