1: <?php
2: /**
3: * Hermes_Driver:: defines an API for implementing storage backends
4: * for Hermes.
5: *
6: * See the enclosed file LICENSE for license information (BSD). If you
7: * did not receive this file, see http://www.horde.org/licenses/bsdl.php.
8: *
9: * @author Chuck Hagenbuch <chuck@horde.org>
10: * @author Michael J. Rubinsky <mrubinsk@horde.org>
11: * @package Hermes
12: */
13: abstract class Hermes_Driver
14: {
15: const SORT_ORDER_ASC = 'ASC';
16: const SORT_ORDER_DESC = 'DESC';
17:
18: /**
19: * Parameters
20: *
21: * @var array
22: */
23: protected $_params;
24:
25: /**
26: * Constructor
27: *
28: */
29: public function __construct($params = array())
30: {
31: $this->_params = $params;
32: }
33:
34: /**
35: * Retrieve a specific job type record.
36: *
37: * @param integer $jobTypeID The ID of the job type.
38: *
39: * @return array Hash of job type properties.
40: * @throws Horde_Exception_NotFound
41: */
42: public function getJobTypeByID($jobTypeID)
43: {
44: $jobtypes = $this->listJobTypes(array('id' => $jobTypeID));
45: if (!isset($jobtypes[$jobTypeID])) {
46: throw new Horde_Exception_NotFound(sprintf(_("No job type with ID \"%s\"."), $jobTypeID));
47: }
48:
49: return $jobtypes[$jobTypeID];
50: }
51:
52: /**
53: * Retrieve a deliverable by ID.
54: *
55: * @param integer $deliverableID The ID of the deliverable to retrieve.
56: *
57: * @return array Hash of deliverable's properties.
58: * @throws Horde_Exception_NotFound
59: */
60: public function getDeliverableByID($deliverableID)
61: {
62: $deliverables = $this->listDeliverables(array('id' => $deliverableID));
63: if (!isset($deliverables[$deliverableID])) {
64: throw new Horde_Exception_NotFound(sprintf(_("Deliverable %d not found."), $deliverableID));
65: }
66:
67: return $deliverables[$deliverableID];
68: }
69:
70: /**
71: * Add or update a job type record.
72: *
73: * @param array $jobtype A hash of job type properties:
74: * 'id' => The ID of the job, if updating. If not
75: * present, a new job type is created.
76: * 'name' => The job type's name.
77: * 'enabled' => Whether the job type is enabled for new
78: * time entry.
79: *
80: * @return The job's ID.
81: */
82: abstract public function updateJobType($jobtype);
83:
84: /**
85: * @TODO
86: *
87: */
88: abstract public function deleteJobType($jobTypeID);
89:
90: /**
91: * Retrieve list of job types.
92: *
93: * @param array $criteria Hash of filter criteria:
94: *
95: * 'enabled' => If present, only retrieve enabled
96: * or disabled job types.
97: *
98: * @return array Hash of job type.
99: */
100: abstract public function listJobTypes(array $criteria = array());
101:
102:
103: /**
104: * Add or update a deliverable.
105: *
106: * @param array $deliverable A hash of deliverable properties:
107: * 'id' => The ID of the deliverable, if
108: * updating. If not present, a new
109: * ID is allocated.
110: * 'name' => The deliverable's display name.
111: * 'client_id' => The assigned client ID.
112: * 'parent' => ID of the deliverables parent
113: * deliverable (if a child).
114: * 'estimate' => Estimated number of hours for
115: * completion of the deliverable.
116: * 'active' => Whether this deliverable is active.
117: * 'description' => Text description (notes) for this
118: * deliverable.
119: *
120: * @return integer ID of new or saved deliverable.
121: */
122: abstract public function updateDeliverable($deliverable);
123:
124: /**
125: * Retrieve list of deliverables.
126: *
127: * @param array $criteria A hash of search criteria:
128: * 'id' => If present, only deliverable with
129: * specified ID is searched for.
130: * 'client_id' => If present, list is filtered by
131: * client ID.
132: *
133: * @return array Hash of job types.
134: */
135: abstract public function listDeliverables($criteria = array());
136:
137: /**
138: * Delete a deliverable.
139: *
140: * @param integer $deliverableID The ID of the deliverable.
141: *
142: * @return void
143: */
144: abstract public function deleteDeliverable($deliverableID);
145:
146: /**
147: * @TODO:
148: *
149: */
150: abstract public function markAs($field, $hours);
151:
152: /**
153: * @TODO
154: */
155: abstract public function getClientSettings($clientID);
156:
157: /**
158: * @TODO
159: */
160: abstract public function updateClientSettings($clientID, $enterDescription = 1, $exportID = null);
161:
162: /**
163: * @TODO
164: */
165: abstract public function purge();
166:
167: /**
168: * Save a row of billing information.
169: *
170: * @param string $employee The Horde ID of the person who worked the
171: * hours.
172: * @param array $entries The billing information to enter. Each array
173: * row must contain the following entries:
174: * 'date' The day the hours were worked (ISO format)
175: * 'client' The id of the client the work was done for.
176: * 'type' The type of work done.
177: * 'hours' The number of hours worked
178: * 'rate' The hourly rate the work was done at.
179: * 'billable' (optional) Whether or not the work is
180: * billable hours.
181: * 'description' A short description of the work.
182: *
183: * @return integer The new timeslice_id of the newly entered slice
184: * @throws Hermes_Exception
185: */
186: abstract public function enterTime($employee, $info);
187:
188: /**
189: * Update a set of billing information.
190: *
191: * @param array $entries The billing information to enter. Each array row
192: * must contain the following entries:
193: * 'id' The id of this time entry.
194: * 'date' The day the hours were worked (ISO format)
195: * 'client' The id of the client the work was done for.
196: * 'type' The type of work done.
197: * 'hours' The number of hours worked
198: * 'rate' The hourly rate the work was done at.
199: * 'billable' Whether or not the work is billable hours.
200: * 'description' A short description of the work.
201: *
202: * If any rows contain a 'delete' entry, those rows
203: * will be deleted instead of updated.
204: *
205: * @return mixed boolean
206: * @throws Horde_Exception_PermissionDenied
207: * @throws Hermes_Exception
208: */
209: abstract public function updateTime($entries);
210:
211: }
212: