1: <?php
  2: /**
  3:  * Ingo_Storage:: defines an API to store the various filter rules.
  4:  *
  5:  * See the enclosed file LICENSE for license information (ASL).  If you
  6:  * did not receive this file, see http://www.horde.org/licenses/apache.
  7:  *
  8:  * @author  Michael Slusarz <slusarz@horde.org>
  9:  * @author  Jan Schneider <jan@horde.org>
 10:  * @package Ingo
 11:  */
 12: class Ingo_Storage
 13: {
 14:     /**
 15:      * Ingo_Storage:: 'combine' constants
 16:      */
 17:     const COMBINE_ALL = 1;
 18:     const COMBINE_ANY = 2;
 19: 
 20:     /**
 21:      * Ingo_Storage:: 'action' constants
 22:      */
 23:     const ACTION_FILTERS = 0;
 24:     const ACTION_KEEP = 1;
 25:     const ACTION_MOVE = 2;
 26:     const ACTION_DISCARD = 3;
 27:     const ACTION_REDIRECT = 4;
 28:     const ACTION_REDIRECTKEEP = 5;
 29:     const ACTION_REJECT = 6;
 30:     const ACTION_BLACKLIST = 7;
 31:     const ACTION_VACATION = 8;
 32:     const ACTION_WHITELIST = 9;
 33:     const ACTION_FORWARD = 10;
 34:     const ACTION_MOVEKEEP = 11;
 35:     const ACTION_FLAGONLY = 12;
 36:     const ACTION_NOTIFY = 13;
 37:     const ACTION_SPAM = 14;
 38: 
 39:     /**
 40:      * Ingo_Storage:: 'flags' constants
 41:      */
 42:     const FLAG_ANSWERED = 1;
 43:     const FLAG_DELETED = 2;
 44:     const FLAG_FLAGGED = 4;
 45:     const FLAG_SEEN = 8;
 46: 
 47:     /**
 48:      * Ingo_Storage:: 'type' constants.
 49:      */
 50:     const TYPE_HEADER = 1;
 51:     const TYPE_SIZE = 2;
 52:     const TYPE_BODY = 3;
 53: 
 54:     /**
 55:      * Driver specific parameters.
 56:      *
 57:      * @var array
 58:      */
 59:     protected $_params = array();
 60: 
 61:     /**
 62:      * Cached rule objects.
 63:      *
 64:      * @var array
 65:      */
 66:     protected $_cache = array();
 67: 
 68:     /**
 69:      * Attempts to return a concrete Ingo_Storage instance based on $driver.
 70:      *
 71:      * @param string $driver  The type of concrete Ingo_Storage subclass to
 72:      *                        return.  This is based on the storage driver
 73:      *                        ($driver).  The code is dynamically included.
 74:      * @param array $params   A hash containing any additional configuration or
 75:      *                        connection parameters a subclass might need.
 76:      *
 77:      * @return mixed  The newly created concrete Ingo_Storage instance, or
 78:      *                false on an error.
 79:      */
 80:     static public function factory($driver = null, $params = null)
 81:     {
 82:         if (is_null($driver)) {
 83:             $driver = $GLOBALS['conf']['storage']['driver'];
 84:         }
 85: 
 86:         $driver = basename($driver);
 87: 
 88:         if (is_null($params)) {
 89:             $params = Horde::getDriverConfig('storage', $driver);
 90:         }
 91: 
 92:         $class = 'Ingo_Storage_' . ucfirst($driver);
 93:         return class_exists($class)
 94:             ? new $class($params)
 95:             : false;
 96:     }
 97: 
 98:     /**
 99:      * Constructor.
100:      */
101:     public function __construct()
102:     {
103:         register_shutdown_function(array($this, 'shutdown'));
104:     }
105: 
106:     /**
107:      * Shutdown function.
108:      */
109:     public function shutdown()
110:     {
111:         /* Store the current objects. */
112:         foreach ($this->_cache as $key => $val) {
113:             if ($val['mod'] || !$GLOBALS['session']->exists('ingo', 'storage/' . $key)) {
114:                 $GLOBALS['session']->set('ingo', 'storage/' . $key, $GLOBALS['session']->store($val['ob'], false));
115:             }
116:         }
117:     }
118: 
119:     /**
120:      * Retrieves the specified data.
121:      *
122:      * @param integer $field     The field name of the desired data
123:      *                           (ACTION_* constants).
124:      * @param boolean $cache     Use the cached object?
125:      * @param boolean $readonly  Whether to disable any write operations.
126:      *
127:      * @return Ingo_Storage_Rule|Ingo_Storage_Filters  The specified object.
128:      * @throws Ingo_Exception
129:      */
130:     public function retrieve($field, $cache = true, $readonly = false)
131:     {
132:         /* Don't cache if using shares. */
133:         if ($cache && empty($GLOBALS['ingo_shares'])) {
134:             if (!isset($this->_cache[$field])) {
135:                 $cached = $GLOBALS['session']->retrieve($GLOBALS['session']->get('ingo', 'storage/' . $field));
136:                 $this->_cache[$field] = array(
137:                     'mod' => false,
138:                     'ob' => $cached ? $cached : $this->_retrieve($field, $readonly)
139:                 );
140:             }
141:             $ob = $this->_cache[$field]['ob'];
142:         } else {
143:             $ob = $this->_retrieve($field, $readonly);
144:         }
145: 
146:         return $ob;
147:     }
148: 
149:     /**
150:      * Retrieves the specified data from the storage backend.
151:      *
152:      * @param integer $field     The field name of the desired data.
153:      *                           See lib/Storage.php for the available fields.
154:      * @param boolean $readonly  Whether to disable any write operations.
155:      *
156:      * @return Ingo_Storage_Rule|Ingo_Storage_Filters  The specified data.
157:      */
158:     protected function _retrieve($field, $readonly = false)
159:     {
160:         return false;
161:     }
162: 
163:     /**
164:      * Stores the specified data.
165:      *
166:      * @param Ingo_Storage_Rule|Ingo_Storage_Filters $ob  The object to store.
167:      * @param boolean $cache                              Cache the object?
168:      *
169:      * @throws Ingo_Exception
170:      */
171:     public function store($ob, $cache = true)
172:     {
173:         $type = $ob->obType();
174:         if (in_array($type, array(self::ACTION_BLACKLIST,
175:                                   self::ACTION_VACATION,
176:                                   self::ACTION_WHITELIST,
177:                                   self::ACTION_FORWARD,
178:                                   self::ACTION_SPAM))) {
179:             $filters = $this->retrieve(self::ACTION_FILTERS);
180:             if ($filters->findRuleId($type) === null) {
181:                 switch ($type) {
182:                 case self::ACTION_BLACKLIST:
183:                     $name = 'Blacklist';
184:                     break;
185: 
186:                 case self::ACTION_VACATION:
187:                     $name = 'Vacation';
188:                     break;
189: 
190:                 case self::ACTION_WHITELIST:
191:                     $name = 'Whitelist';
192:                     break;
193: 
194:                 case self::ACTION_FORWARD:
195:                     $name = 'Forward';
196:                     break;
197: 
198:                 case self::ACTION_SPAM:
199:                     $name = 'Spam Filter';
200:                     break;
201:                 }
202:                 $filters->addRule(array('action' => $type, 'name' => $name));
203:                 $this->store($filters, $cache);
204:             }
205:         }
206: 
207:         $this->_store($ob);
208:         if ($cache) {
209:             $this->_cache[$ob->obType()] = array('ob' => $ob, 'mod' => true);
210:         }
211:     }
212: 
213:     /**
214:      * Stores the specified data in the storage backend.
215:      *
216:      * @param Ingo_Storage_Rule|Ingo_Storage_Filters $ob  The object to store.
217:      */
218:     protected function _store($ob)
219:     {
220:     }
221: 
222:     /**
223:      * Returns information on a given action constant.
224:      *
225:      * @param integer $action  The ACTION_* value.
226:      *
227:      * @return stdClass  Object with the following values:
228:      * <pre>
229:      * 'flags' => (boolean) Does this action allow flags to be set?
230:      * 'label' => (string) The label for this action.
231:      * 'type'  => (string) Either 'folder', 'text', or empty.
232:      * </pre>
233:      */
234:     public function getActionInfo($action)
235:     {
236:         $ob = new stdClass;
237:         $ob->flags = false;
238:         $ob->type = 'text';
239: 
240:         switch ($action) {
241:         case self::ACTION_KEEP:
242:             $ob->label = _("Deliver into my Inbox");
243:             $ob->type = false;
244:             $ob->flags = true;
245:             break;
246: 
247:         case self::ACTION_MOVE:
248:             $ob->label = _("Deliver to folder...");
249:             $ob->type = 'folder';
250:             $ob->flags = true;
251:             break;
252: 
253:         case self::ACTION_DISCARD:
254:             $ob->label = _("Delete message completely");
255:             $ob->type = false;
256:             break;
257: 
258:         case self::ACTION_REDIRECT:
259:             $ob->label = _("Redirect to...");
260:             break;
261: 
262:         case self::ACTION_REDIRECTKEEP:
263:             $ob->label = _("Deliver into my Inbox and redirect to...");
264:             $ob->flags = true;
265:             break;
266: 
267:         case self::ACTION_MOVEKEEP:
268:             $ob->label = _("Deliver into my Inbox and copy to...");
269:             $ob->type = 'folder';
270:             $ob->flags = true;
271:             break;
272: 
273:         case self::ACTION_REJECT:
274:             $ob->label = _("Reject with reason...");
275:             break;
276: 
277:         case self::ACTION_FLAGONLY:
278:             $ob->label = _("Only flag the message");
279:             $ob->type = false;
280:             $ob->flags = true;
281:             break;
282: 
283:         case self::ACTION_NOTIFY:
284:             $ob->label = _("Notify email address...");
285:             break;
286:         }
287: 
288:         return $ob;
289:     }
290: 
291:     /**
292:      * Returns information on a given test string.
293:      *
294:      * @param string $action  The test string.
295:      *
296:      * @return stdClass  Object with the following values:
297:      * <pre>
298:      * 'label' => (string) The label for this action.
299:      * 'type'  => (string) Either 'int', 'none', or 'text'.
300:      * </pre>
301:      */
302:     public function getTestInfo($test)
303:     {
304:         /* Mapping of gettext strings -> labels. */
305:         $labels = array(
306:             'contains' => _("Contains"),
307:             'not contain' =>  _("Doesn't contain"),
308:             'is' => _("Is"),
309:             'not is' => _("Isn't"),
310:             'begins with' => _("Begins with"),
311:             'not begins with' => _("Doesn't begin with"),
312:             'ends with' => _("Ends with"),
313:             'not ends with' => _("Doesn't end with"),
314:             'exists' =>  _("Exists"),
315:             'not exist' => _("Doesn't exist"),
316:             'regex' => _("Regular expression"),
317:             'matches' => _("Matches (with placeholders)"),
318:             'not matches' => _("Doesn't match (with placeholders)"),
319:             'less than' => _("Less than"),
320:             'less than or equal to' => _("Less than or equal to"),
321:             'greater than' => _("Greater than"),
322:             'greater than or equal to' => _("Greater than or equal to"),
323:             'equal' => _("Equal to"),
324:             'not equal' => _("Not equal to")
325:         );
326: 
327:         /* The type of tests available. */
328:         $types = array(
329:             'int'  => array(
330:                 'less than', 'less than or equal to', 'greater than',
331:                 'greater than or equal to', 'equal', 'not equal'
332:             ),
333:             'none' => array(
334:                 'exists', 'not exist'
335:             ),
336:             'text' => array(
337:                 'contains', 'not contain', 'is', 'not is', 'begins with',
338:                 'not begins with', 'ends with', 'not ends with', 'regex',
339:                 'matches', 'not matches'
340:             )
341:         );
342: 
343:         /* Create the information object. */
344:         $ob = new stdClass;
345:         $ob->label = $labels[$test];
346:         foreach ($types as $key => $val) {
347:             if (in_array($test, $val)) {
348:                 $ob->type = $key;
349:                 break;
350:             }
351:         }
352: 
353:         return $ob;
354:     }
355: 
356:     /**
357:      * Removes the user data from the storage backend.
358:      * Stub for child class to override if it can implement.
359:      *
360:      * @param string $user  The user name to delete filters for.
361:      *
362:      * @throws Ingo_Exception
363:      */
364:     public function removeUserData($user)
365:     {
366:         throw new Ingo_Exception(_("Removing user data is not supported with the current filter storage backend."));
367:     }
368: 
369: }
370: