1: <?php
2: /**
3: * Class that can be extended to save arbitrary information as part of a stored
4: * object.
5: *
6: * @author Stephane Huther <shuther1@free.fr>
7: * @author Chuck Hagenbuch <chuck@horde.org>
8: * @package DataTree
9: */
10: class Horde_DataTreeObject {
11:
12: /**
13: * This object's Horde_DataTree instance.
14: *
15: * @var Horde_DataTree
16: */
17: var $datatree;
18:
19: /**
20: * Key-value hash that will be serialized.
21: *
22: * @see getData()
23: * @var array
24: */
25: var $data = array();
26:
27: /**
28: * The unique name of this object.
29: * These names have the same requirements as other object names - they must
30: * be unique, etc.
31: *
32: * @var string
33: */
34: var $name;
35:
36: /**
37: * If this object has ordering data, store it here.
38: *
39: * @var integer
40: */
41: var $order = null;
42:
43: /**
44: * Horde_DataTreeObject constructor.
45: * Just sets the $name parameter.
46: *
47: * @param string $name The object name.
48: */
49: function __construct($name)
50: {
51: $this->setName($name);
52: }
53:
54: /**
55: * Sets the {@link Horde_DataTree} instance used to retrieve this object.
56: *
57: * @param Horde_DataTree $datatree A {@link Horde_DataTree} instance.
58: */
59: function setDataTree(&$datatree)
60: {
61: $this->datatree = &$datatree;
62: }
63:
64: /**
65: * Gets the name of this object.
66: *
67: * @return string The object name.
68: */
69: function getName()
70: {
71: return $this->name;
72: }
73:
74: /**
75: * Sets the name of this object.
76: *
77: * NOTE: Use with caution. This may throw out of sync the cached datatree
78: * tables if not used properly.
79: *
80: * @param string $name The name to set this object's name to.
81: */
82: function setName($name)
83: {
84: $this->name = $name;
85: }
86:
87: /**
88: * Gets the short name of this object.
89: * For display purposes only.
90: *
91: * @return string The object's short name.
92: */
93: function getShortName()
94: {
95: return Horde_DataTree::getShortName($this->name);
96: }
97:
98: /**
99: * Gets the ID of this object.
100: *
101: * @return string The object's ID.
102: */
103: function getId()
104: {
105: return $this->datatree->getId($this);
106: }
107:
108: /**
109: * Gets the data array.
110: *
111: * @return array The internal data array.
112: */
113: function getData()
114: {
115: return $this->data;
116: }
117:
118: /**
119: * Sets the data array.
120: *
121: * @param array The data array to store internally.
122: */
123: function setData($data)
124: {
125: $this->data = $data;
126: }
127:
128: /**
129: * Sets the order of this object in its object collection.
130: *
131: * @param integer $order
132: */
133: function setOrder($order)
134: {
135: $this->order = $order;
136: }
137:
138: /**
139: * Returns this object's parent.
140: *
141: * @param string $class Subclass of Horde_DataTreeObject to use. Defaults to
142: * Horde_DataTreeObject. Null forces the driver to look
143: * into the attributes table to determine the
144: * subclass to use. If none is found it uses
145: * Horde_DataTreeObject.
146: *
147: * @return Horde_DataTreeObject This object's parent
148: */
149: function &getParent($class = 'Horde_DataTreeObject')
150: {
151: $id = $this->datatree->getParent($this);
152: if (is_a($id, 'PEAR_Error')) {
153: return $id;
154: }
155: return $this->datatree->getObjectById($id, $class);
156: }
157:
158: /**
159: * Returns a child of this object.
160: *
161: * @param string $name The child's name.
162: * @param boolean $autocreate If true and no child with the given name
163: * exists, one gets created.
164: */
165: function &getChild($name, $autocreate = true)
166: {
167: $name = $this->getShortName() . ':' . $name;
168:
169: /* If the child shouldn't get created, we don't check for its
170: * existance to return the "not found" error of
171: * getObject(). */
172: if (!$autocreate || $this->datatree->exists($name)) {
173: $child = &$this->datatree->getObject($name);
174: } else {
175: $child = new Horde_DataTreeObject($name);
176: $child->setDataTree($this->datatree);
177: $this->datatree->add($child);
178: }
179:
180: return $child;
181: }
182:
183: /**
184: * Saves any changes to this object to the backend permanently. New objects
185: * are added instead.
186: *
187: * @return boolean|PEAR_Error PEAR_Error on failure.
188: */
189: function save()
190: {
191: if ($this->datatree->exists($this)) {
192: return $this->datatree->updateData($this);
193: } else {
194: return $this->datatree->add($this);
195: }
196: }
197:
198: /**
199: * Delete this object from the backend permanently.
200: *
201: * @return boolean|PEAR_Error PEAR_Error on failure.
202: */
203: function delete()
204: {
205: return $this->datatree->remove($this);
206: }
207:
208: /**
209: * Gets one of the attributes of the object, or null if it isn't defined.
210: *
211: * @param string $attribute The attribute to get.
212: *
213: * @return mixed The value of the attribute, or null.
214: */
215: function get($attribute)
216: {
217: return isset($this->data[$attribute])
218: ? $this->data[$attribute]
219: : null;
220: }
221:
222: /**
223: * Sets one of the attributes of the object.
224: *
225: * @param string $attribute The attribute to set.
226: * @param mixed $value The value for $attribute.
227: */
228: function set($attribute, $value)
229: {
230: $this->data[$attribute] = $value;
231: }
232:
233: }
234: