447 lines
12 KiB
PHP
447 lines
12 KiB
PHP
<?php namespace ProcessWire;
|
|
|
|
/**
|
|
* An individual notification item to be part of a NotificationArray for a Page
|
|
*
|
|
* @class Notification
|
|
*
|
|
* @property int $pages_id page ID notification is for (likely a User page)
|
|
* @property int $sort sort value, as required by Fieldtype
|
|
* @property int $src_id page ID when notification was generated
|
|
* @property string $title title/headline
|
|
* @property int $flags flags: see flag constants
|
|
* @property int $created datetime created (unix timestamp)
|
|
* @property int $modified datetime created (unix timestamp)
|
|
* @property int $qty quantity of times this notification has been repeated
|
|
* @property array $flagNames Notification flag names
|
|
*
|
|
* data encoded vars, all optional
|
|
* ===============================
|
|
* @property int $id unique ID (among others the user may have)
|
|
* @property string $text extended text
|
|
* @property string $html extended text as HTML markup
|
|
* @property string $from "from" text where applicable, like a class name
|
|
* @property string $icon fa-icon when applicable
|
|
* @property string $href clicking notification goes to this URL
|
|
* @property int $progress progress percent 0-100
|
|
* @property int $expires datetime after which will automatically be deleted
|
|
*
|
|
*/
|
|
class Notification extends WireData {
|
|
|
|
/**
|
|
* Flag constants for Notification objects
|
|
*
|
|
* Note that flags 2-32 line up with the same flags from Notice objects
|
|
*
|
|
*/
|
|
|
|
const flagDebug = 2; // Show/save only when the system is in debug mode
|
|
const flagLog = 8; // save to log and show
|
|
const flagLogOnly = 16; // save to log but don't show
|
|
const flagAllowMarkup = 32; // allow markup in the title
|
|
|
|
const flagMessage = 64; // informational
|
|
const flagWarning = 4; // warning
|
|
const flagError = 128; // error
|
|
|
|
const flagNotice = 256; // Show only as a single-request notice (not stored in DB)
|
|
const flagSession = 512; // Notification lasts for only this session (not stored in DB)
|
|
const flagEmail = 1024; // title and body will also be emailed to user (if page is user)
|
|
const flagOpen = 2048; // notification will automatically open the text/html area (no click required)
|
|
|
|
const flagNoGhost = 4096; // disable showing of a notification ghost
|
|
const flagAnnoy = 8192; // rather than just update bug counter, notification will pop up at top of screen
|
|
const flagShown = 16384; // has this flag once the notification has been sent to the UI at least once
|
|
const flagAlert = 32768; // show an alert that requires acknowledgement (use with flagSession only)
|
|
|
|
/**
|
|
* Provides a name for each of the flags
|
|
*
|
|
* @var array
|
|
*
|
|
*/
|
|
static protected $_flagNames = array(
|
|
self::flagDebug => 'debug',
|
|
self::flagLog => 'log',
|
|
self::flagLogOnly => 'log-only',
|
|
self::flagAllowMarkup => 'markup',
|
|
self::flagMessage => 'message',
|
|
self::flagWarning => 'warning',
|
|
self::flagError => 'error',
|
|
self::flagNotice => 'notice',
|
|
self::flagSession => 'session',
|
|
self::flagEmail => 'email',
|
|
self::flagOpen => 'open',
|
|
self::flagNoGhost => 'no-ghost',
|
|
self::flagAnnoy => 'annoy',
|
|
self::flagShown => 'shown',
|
|
self::flagAlert => 'alert',
|
|
);
|
|
|
|
/**
|
|
* Page that this Notification belongs to
|
|
*
|
|
* @var Page
|
|
*
|
|
*/
|
|
protected $page;
|
|
|
|
/**
|
|
* Construct a new Notification
|
|
*
|
|
*/
|
|
public function __construct() {
|
|
|
|
// db native vars
|
|
$this->set('pages_id', 0); // page ID notification is for (likely a User page)
|
|
$this->set('sort', 0); // sort value, as required by Fieldtype
|
|
$this->set('src_id', 0); // page ID when notification was generated
|
|
$this->set('title', ''); // title/headline
|
|
$this->set('flags', 0); // flags: see flag constants
|
|
$this->set('created', 0); // datetime created (unix timestamp)
|
|
$this->set('modified', 0); // datetime created (unix timestamp)
|
|
$this->set('qty', 1); // quantity of times this notification has been repeated
|
|
|
|
// data encoded vars, all optional
|
|
$this->set('id', ''); // unique ID (among others the user may have)
|
|
$this->set('text', ''); // extended text
|
|
$this->set('html', ''); // extended text as HTML markup
|
|
$this->set('from', ''); // "from" text where applicable, like a class name
|
|
$this->set('icon', ''); // fa-icon when applicable
|
|
$this->set('href', ''); // clicking notification goes to this URL
|
|
$this->set('progress', 0); // progress percent 0-100
|
|
$this->set('expires', 0); // datetime after which will automatically be deleted
|
|
|
|
}
|
|
|
|
/*
|
|
* Fluent interface methods
|
|
*
|
|
*/
|
|
|
|
public function title($value) { return $this->set('title', $value); }
|
|
public function text($value) { return $this->set('text', $value); }
|
|
public function html($value) { return $this->set('html', $value); }
|
|
public function from($value) { return $this->set('from', $value); }
|
|
public function icon($value) { return $this->set('icon', $value); }
|
|
public function href($value) { return $this->set('href', $value); }
|
|
public function progress($value) { return $this->set('progress', $value); }
|
|
public function expires($value) { return $this->set('expires', $value); }
|
|
public function flag($value) { return $this->setFlag($value, true); }
|
|
public function flags($value) { return $this->setFlags($value, true); }
|
|
|
|
/**
|
|
* Does this Notification match the given flag name(s)?
|
|
*
|
|
* @param string $name
|
|
* @return bool
|
|
*
|
|
*/
|
|
public function is($name) {
|
|
$flags = $this->flagNamesToFlags($name);
|
|
$is = 0;
|
|
foreach($flags as $flag) {
|
|
if($this->flags & $flag) $is++;
|
|
}
|
|
return $is == count($flags);
|
|
}
|
|
|
|
/**
|
|
* Given a flag name, return the corresponding flag value
|
|
*
|
|
* @param string $name
|
|
* @return int mixed
|
|
* @throws WireException if given unknown flag
|
|
*
|
|
*/
|
|
protected function flagNameToFlag($name) {
|
|
if(is_string($name)) {
|
|
$flag = array_search($name, self::$_flagNames);
|
|
if(!$flag) throw new WireException("Unknown flag: $name");
|
|
} else {
|
|
$flag = $name;
|
|
if(!isset(self::$_flagNames[$flag])) throw new WireException("Unknown flag: $flag");
|
|
}
|
|
return $flag;
|
|
}
|
|
|
|
/**
|
|
* Given multiple space separated flag names, return array of flag values
|
|
*
|
|
* @param string $names space separted, will also accept CSV
|
|
* @return array of flag name => flag value
|
|
*
|
|
*/
|
|
protected function flagNamesToFlags($names) {
|
|
if(strpos($names, ',') !== false) $names = str_replace(',', ' ', $names);
|
|
$names = explode(' ', $names);
|
|
$flags = array();
|
|
foreach($names as $name) {
|
|
if(empty($name)) continue;
|
|
$flag = $this->flagNameToFlag($name);
|
|
if($flag) $flags[$name] = $flag;
|
|
}
|
|
return $flags;
|
|
}
|
|
|
|
/**
|
|
* Set a named flag
|
|
*
|
|
* @param string|int $name Flag to set
|
|
* @param bool $add True to add flag, false to remove
|
|
* @return self
|
|
*
|
|
*/
|
|
public function setFlag($name, $add = true) {
|
|
|
|
$flag = ctype_digit("$name") ? (int) $name : $this->flagNameToFlag($name);
|
|
$flags = parent::get('flags');
|
|
|
|
if($add) {
|
|
// add flag
|
|
if($flags & $flag) {
|
|
// flag is already set
|
|
} else {
|
|
$flags = $flags | $flag;
|
|
parent::set('flags', $flags);
|
|
}
|
|
} else {
|
|
// remove flag
|
|
if($flags & $flag) {
|
|
// flag is set, remove it
|
|
$flags = $flags & ~$flag;
|
|
parent::set('flags', $flags);
|
|
} else {
|
|
// flag is not set
|
|
}
|
|
}
|
|
|
|
return $this;
|
|
}
|
|
|
|
/**
|
|
* Add the given flag name(s) (shortcut for setFlag)
|
|
*
|
|
* @param string $name One or more space-separated flag names
|
|
* @return self
|
|
*
|
|
*/
|
|
public function addFlag($name) {
|
|
return $this->setFlags($name, true);
|
|
}
|
|
|
|
/**
|
|
* Remove the given flag name(s) (shortcut for setFlag)
|
|
*
|
|
* @param string $name One or more space-separated flag names
|
|
* @return self
|
|
*
|
|
*/
|
|
public function removeFlag($name) {
|
|
return $this->setFlags($name, false);
|
|
}
|
|
|
|
/**
|
|
* Set multiple flags
|
|
*
|
|
* @param string $names space separated string of flag names
|
|
* @param bool $add True to add, false to remove
|
|
* @return self
|
|
*
|
|
*/
|
|
public function setFlags($names, $add = true) {
|
|
|
|
if(ctype_digit("$names")) {
|
|
// likely a flag or combined flags in bitmask
|
|
$flags = (int) $names;
|
|
// iterate through known flags to see which are set
|
|
foreach(self::$_flagNames as $flag => $name) {
|
|
// if it's a recognized/valid flag, set it
|
|
if($flags & $flag) $this->setFlag($flag, $add);
|
|
}
|
|
return $this;
|
|
}
|
|
|
|
// optimization if this was called with just one flag name
|
|
if(strpos($names, ',') === false && strpos($names, ' ') === false) {
|
|
$this->setFlag($names, $add);
|
|
}
|
|
|
|
// named flags
|
|
$flags = $this->flagNamesToFlags($names);
|
|
foreach($flags as $name => $flag) {
|
|
$this->setFlag($flag, $add);
|
|
}
|
|
|
|
return $this;
|
|
}
|
|
|
|
/**
|
|
* Set a value to the Notification
|
|
*
|
|
* Note: setting the 'expires' value accepts either a future date, or a quantity of seconds
|
|
* in the future relative to now.
|
|
*
|
|
* @param string $key
|
|
* @param mixed $value
|
|
* @return self|Notification|WireData
|
|
*
|
|
*/
|
|
public function set($key, $value) {
|
|
|
|
if($key == 'page') {
|
|
$this->page = $value;
|
|
return $this;
|
|
|
|
} else if($key == 'created' || $key == 'modified' || $key == 'expires') {
|
|
// convert date string to unix timestamp
|
|
if($value && !ctype_digit("$value")) $value = strtotime($value);
|
|
|
|
// sanitized date value is always an integer
|
|
$value = (int) $value;
|
|
|
|
if($key == 'expires' && $value > 0 && $value < strtotime("-10 YEARS")) {
|
|
// assume this is a time relative to now
|
|
$value = time() + $value;
|
|
}
|
|
|
|
} else if($key == 'title') {
|
|
if($this->flags & self::flagAllowMarkup) {
|
|
// accept value as-is
|
|
} else {
|
|
// regular text sanitizer
|
|
$value = $this->sanitizer->text($value);
|
|
}
|
|
|
|
} else if($key == 'from') {
|
|
// regular text sanitizer
|
|
$value = $this->sanitizer->text($value);
|
|
|
|
} else if($key == 'text') {
|
|
// regular text sanitizer
|
|
$value = $this->sanitizer->textarea($value);
|
|
|
|
} else if(in_array($key, array('pages_id', 'sort', 'src_id', 'flags', 'progress'))) {
|
|
$value = (int) $value;
|
|
}
|
|
|
|
return parent::set($key, $value);
|
|
}
|
|
|
|
/**
|
|
* Return an ID string/hash unique to this Notification within the page that its on
|
|
*
|
|
* The text/html, modified date, expires date, and icon may change without affecting the id.
|
|
*
|
|
* @return mixed|null|string
|
|
*
|
|
*/
|
|
public function getID() {
|
|
|
|
$id = parent::get('id');
|
|
if($id) return $id;
|
|
|
|
$id = parent::get('title') . ',' .
|
|
parent::get('created') . ',' .
|
|
parent::get('from') . ',' .
|
|
parent::get('src_id') . ',' .
|
|
($this->page ? $this->page->id : '?'); // . ',' .
|
|
//parent::get('flags');
|
|
|
|
return 'noID' . md5($id);
|
|
}
|
|
|
|
/**
|
|
* Return an string hash for comparing other notifications to see if they contain the same content
|
|
*
|
|
* Hash specifically excludes consideration of dates (created, modified, expires)
|
|
*
|
|
* @return string
|
|
*
|
|
*/
|
|
public function getHash() {
|
|
|
|
$id = trim(parent::get('title')) . ',' .
|
|
// parent::get('from') . ',' .
|
|
// parent::get('src_id') . ',' .
|
|
// ($this->page ? $this->page->id : '?') . ',' .
|
|
// parent::get('flags') . ',' .
|
|
// parent::get('icon') . ',' .
|
|
trim(parent::get('text')) . ',' .
|
|
trim(parent::get('html'));
|
|
|
|
return md5($id);
|
|
}
|
|
|
|
/**
|
|
* Retrieve a value from the Notification
|
|
*
|
|
* @param string $key
|
|
* @return mixed
|
|
*
|
|
*/
|
|
public function get($key) {
|
|
|
|
if($key == 'id') return $this->getID();
|
|
if($key == 'page') return $this->page;
|
|
if($key == 'hash') return $this->getHash();
|
|
|
|
if($key == 'flagNames') {
|
|
$flags = parent::get('flags');
|
|
$flagNames = array();
|
|
foreach(self::$_flagNames as $val => $name) {
|
|
if($flags & $val) $flagNames[$val] = $name;
|
|
}
|
|
return $flagNames;
|
|
}
|
|
|
|
$value = parent::get($key);
|
|
|
|
// if the page's output formatting is on, then we'll return formatted values
|
|
if($this->page && $this->page->of()) {
|
|
|
|
if($key == 'created' || $key == 'expires' || $key == 'modified') {
|
|
// format a unix timestamp to a date string
|
|
$value = date('Y-m-d H:i:s', $value);
|
|
|
|
} else if($key == 'title' || $key == 'text' || $key == 'from') {
|
|
// return entity encoded versions of strings
|
|
if($key == 'title' && ($this->flags & self::flagAllowMarkup)) {
|
|
// leave title alone when markup is allowed
|
|
} else {
|
|
$value = $this->sanitizer->entities($value);
|
|
}
|
|
}
|
|
} else {
|
|
if($key == 'created' && !$value) $value = time();
|
|
}
|
|
|
|
return $value;
|
|
}
|
|
|
|
/**
|
|
* Is this Notification expired?
|
|
*
|
|
* @return bool
|
|
*
|
|
*/
|
|
public function isExpired() {
|
|
return ($this->expires > 0 && $this->expires <= time());
|
|
}
|
|
|
|
/**
|
|
* String value of a Notification
|
|
*
|
|
* @return string
|
|
*
|
|
*/
|
|
public function __toString() {
|
|
$str = $this->title;
|
|
$str .= " (" . implode(', ', $this->get('flagNames')) . ")";
|
|
return $str;
|
|
}
|
|
|
|
|
|
}
|
|
|