1: <?php
  2: /**
  3:  * Preferences storage implementation for a Kolab IMAP server.
  4:  *
  5:  * Copyright 2007-2012 Horde LLC (http://www.horde.org/)
  6:  *
  7:  * See the enclosed file COPYING for license information (LGPL). If you
  8:  * did not receive this file, see http://www.horde.org/licenses/lgpl21.
  9:  *
 10:  * @author   Gunnar Wrobel <p@rdus.de>
 11:  * @category Horde
 12:  * @license  http://www.horde.org/licenses/lgpl21 LGPL 2.1
 13:  * @package  Prefs
 14:  */
 15: class Horde_Prefs_Storage_KolabImap extends Horde_Prefs_Storage_Base
 16: {
 17:     /**
 18:      * Handle for the current Kolab connection.
 19:      *
 20:      * @var Horde_Kolab_Storage
 21:      */
 22:     protected $_kolab;
 23: 
 24:     /**
 25:      * Name of the preferences default folder
 26:      *
 27:      * @var string
 28:      */
 29:     protected $_folder;
 30: 
 31:     /**
 32:      * Log handler.
 33:      *
 34:      * @var Horde_Log_Logger
 35:      */
 36:     protected $_logger;
 37: 
 38:     /**
 39:      * Constructor.
 40:      *
 41:      * @param string $user   The username.
 42:      * @param array $params  Configuration parameters.
 43:      * <pre>
 44:      * 'kolab'  - (Horde_Kolab_Storage) [REQUIRED] The storage backend.
 45:      * 'folder' - (string) The default name of the preferences folder.
 46:      *            DEFAULT: _('Preferences')
 47:      * </pre>
 48:      *
 49:      * @throws InvalidArgumentException
 50:      */
 51:     public function __construct($user, array $params = array())
 52:     {
 53:         if (!isset($params['kolab'])) {
 54:             throw new InvalidArgumentException('Missing "kolab" parameter.');
 55:         }
 56:         $this->_kolab = $params['kolab'];
 57:         unset($params['kolab']);
 58: 
 59:         if (isset($params['logger'])) {
 60:             $this->_logger = $params['logger'];
 61:         }
 62: 
 63:         if (isset($params['folder'])) {
 64:             $this->_folder = $params['folder'];
 65:         } else {
 66:             $this->_folder = Horde_Prefs_Translation::t("Preferences");
 67:         }
 68: 
 69:         parent::__construct($user, $params);
 70:     }
 71: 
 72:     /**
 73:      * Retrieves the requested preferences scope from the storage backend.
 74:      *
 75:      * @param Horde_Prefs_Scope $scope_ob  The scope object.
 76:      *
 77:      * @return Horde_Prefs_Scope  The modified scope object.
 78:      * @throws Horde_Prefs_Exception
 79:      */
 80:     public function get($scope_ob)
 81:     {
 82:         try {
 83:             $data = $this->_getStorage();
 84:         } catch (Horde_Prefs_Exception $e) {
 85:             $this->_logMissingStorage($e);
 86:             return $scope_ob;
 87:         }
 88: 
 89:         /** This may not fail (or if it does it is okay to pass the error up */
 90:         $query = $data->getQuery(Horde_Kolab_Storage_Data::QUERY_PREFS);
 91: 
 92:         try {
 93:             $pref = $query->getApplicationPreferences($scope_ob->scope);
 94:         } catch (Horde_Kolab_Storage_Exception $e) {
 95:             $this->_logMissingScope($e, $scope_ob->scope);
 96:             return $scope_ob;
 97:         }
 98: 
 99:         foreach ($this->_prefToArray($pref['pref']) as $key => $value) {
100:             $scope_ob->set($key, $value);
101:         }
102:         return $scope_ob;
103:     }
104: 
105:     /**
106:      * Stores changed preferences in the storage backend.
107:      *
108:      * @param Horde_Prefs_Scope $scope_ob  The scope object.
109:      *
110:      * @throws Horde_Prefs_Exception
111:      */
112:     public function store($scope_ob)
113:     {
114:         /** This *must* succeed */
115:         $data = $this->_getStorage(true);
116:         $query = $data->getQuery(Horde_Kolab_Storage_Data::QUERY_PREFS);
117: 
118:         try {
119:             $pref = $query->getApplicationPreferences($scope_ob->scope);
120:         } catch (Horde_Kolab_Storage_Exception $e) {
121:             $pref = array('application' => $scope_ob->scope);
122:         }
123: 
124:         if (isset($pref['pref'])) {
125:             $new = $this->_prefToArray($pref['pref']);
126:         } else {
127:             $new = array();
128:         }
129:         foreach ($scope_ob->getDirty() as $name) {
130:             $new[$name] = $scope_ob->get($name);
131:         }
132:         $pref['pref'] = $this->_arrayToPref($new);
133:         try {
134:             if (!isset($pref['uid'])) {
135:                 $data->create($pref);
136:             } else {
137:                 $data->modify($pref);
138:             }
139:         } catch (Horde_Kolab_Storage_Exception $e) {
140:             throw new Horde_Prefs_Exception($e);
141:         }
142:     }
143: 
144:     /**
145:      * Removes preferences from the backend.
146:      *
147:      * @param string $scope  The scope of the prefs to clear. If null, clears
148:      *                       all scopes.
149:      * @param string $pref   The pref to clear. If null, clears the entire
150:      *                       scope.
151:      *
152:      * @throws Horde_Prefs_Exception
153:      */
154:     public function remove($scope = null, $pref = null)
155:     {
156:         try {
157:             $data = $this->_getStorage();
158:         } catch (Horde_Prefs_Exception $e) {
159:             $this->_logMissingStorage($e);
160:             return;
161:         }
162: 
163:         if ($scope === null) {
164:             $data->deleteAll();
165:             return;
166:         }
167: 
168:         $query = $data->getQuery(Horde_Kolab_Storage_Data::QUERY_PREFS);
169: 
170:         try {
171:             $pref = $query->getApplicationPreferences($scope);
172:         } catch (Horde_Kolab_Storage_Exception $e) {
173:             $this->_logMissingScope($e, $scope);
174:             return;
175:         }
176: 
177:         if ($pref === null) {
178:             $data->delete($pref['uid']);
179:             return;
180:         }
181: 
182:         $new = $this->_prefToArray($pref);
183:         unset($new[$pref]);
184:         $pref['pref'] = $this->_arrayToPref($new);
185: 
186:         try {
187:             $data->modify($pref);
188:         } catch (Horde_Kolab_Storage_Exception $e) {
189:             throw new Horde_Prefs_Exception($e);
190:         }
191:     }
192: 
193:     /**
194:      * Lists all available scopes.
195:      *
196:      * @since Horde_Prefs 1.1.0
197:      *
198:      * @return array The list of scopes stored in the backend.
199:      */
200:     public function listScopes()
201:     {
202:         try {
203:             $data = $this->_getStorage();
204:         } catch (Horde_Prefs_Exception $e) {
205:             $this->_logMissingStorage($e);
206:             return;
207:         }
208: 
209:         return $data->getQuery(Horde_Kolab_Storage_Data::QUERY_PREFS)
210:             ->getApplications();
211:     }
212: 
213:     /* Helper functions. */
214: 
215:     /**
216:      * Opens a connection to the Kolab server.
217:      *
218:      * @param boolean $create_missing Create a preferences folder if it is
219:      *                                missing.
220:      *
221:      * @return Horde_Kolab_Storage_Data The storage backend.
222:      *
223:      * @throws Horde_Prefs_Exception
224:      */
225:     protected function _getStorage($create_missing = false)
226:     {
227:         $query = $this->_kolab->getList()->getQuery();
228:         if ($folder = $query->getDefault('h-prefs')) {
229:             return $this->_kolab->getData($folder);
230:         }
231:         $folders = $query->listByType('h-prefs');
232:         if (!empty($folders)) {
233:             return $this->_kolab->getData($folders[0]);
234:         }
235:         if (!$create_missing) {
236:             throw new Horde_Prefs_Exception(
237:                 'No Kolab storage backend available.'
238:             );
239:         }
240:         $params = $this->getParams();
241:         $folder = $this->_kolab->getList()
242:             ->getNamespace()
243:             ->constructFolderName($params['user'], $this->_folder);
244:         $this->_kolab->getList()->createFolder($folder, 'h-prefs.default');
245:         if ($this->_logger !== null) {
246:             $this->_logger->info(
247:                 sprintf(
248:                     __CLASS__ . ': Created default Kolab preferences folder "%s".',
249:                     $this->_folder
250:                 )
251:             );
252:         }
253:         return $this->_kolab->getData($folder);
254:     }
255: 
256:     /**
257:      * Convert Kolab preferences data to an array.
258:      *
259:      * @param array $pref The preferences list.
260:      *
261:      * @return array The preferences data as array.
262:      */
263:     private function _prefToArray($pref)
264:     {
265:         $result = array();
266:         foreach ($pref as $prefstr) {
267:             /** If the string doesn't contain a colon delimiter, skip it. */
268:             if (strpos($prefstr, ':') !== false) {
269:                 /** Split the string into its name:value components. */
270:                 list($name, $val) = explode(':', $prefstr, 2);
271:                 $result[$name] = base64_decode($val);
272:             }
273:         }
274:         return $result;
275:     }
276: 
277:     /**
278:      * Convert a key => value list of preferences to the Kolab preferences.
279:      *
280:      * @param array $pref The preferences.
281:      *
282:      * @return array The preferences data as list.
283:      */
284:     private function _arrayToPref($pref)
285:     {
286:         $result = array();
287:         foreach ($pref as $name => $value) {
288:             if ($value !== null) {
289:                 $result[] = $name . ':' . base64_encode($value);
290:             }
291:         }
292:         return $result;
293:     }
294: 
295:     /**
296:      * Log the missing backend.
297:      *
298:      * @param Exception $e The exception that occurred.
299:      *
300:      * @return NULL
301:      */
302:     private function _logMissingStorage(Exception $e)
303:     {
304:         if ($this->_logger !== null) {
305:             $this->_logger->debug(
306:                 sprintf(
307:                     __CLASS__ . ': Failed retrieving Kolab preferences data storage (%s)',
308:                     $e->getMessage()
309:                 )
310:             );
311:         }
312:     }
313: 
314:     /**
315:      * Log the missing scope.
316:      *
317:      * @param Exception $e     The exception that occurred.
318:      * @param string    $scope The scope that was attempted to get.
319:      *
320:      * @return NULL
321:      */
322:     private function _logMissingScope(Exception $e, $scope)
323:     {
324:         if ($this->_logger !== null) {
325:             $this->_logger->debug(
326:                 sprintf(
327:                     __CLASS__ . ': No preference information available for scope %s (%s).',
328:                     $scope,
329:                     $e->getMessage()
330:                 )
331:             );
332:         }
333:     }
334: }
335: