7 use Shaarli\Bookmark\Bookmark
;
8 use Shaarli\Helper\FileUtils
;
13 * Handle the history file tracing events in Shaarli.
14 * The history is stored as JSON in a file set by 'resource.history' setting.
18 * - datetime: event date, in ISO8601 format.
19 * - id: event item identifier (currently only link IDs).
21 * Available event keys:
23 * - UPDATED: link updated
24 * - DELETED: link deleted
25 * - SETTINGS: the settings have been updated through the UI.
26 * - IMPORT: bulk bookmarks import
28 * Note: new events are put at the beginning of the file and history array.
33 * @var string Action key: a new link has been created.
35 public const CREATED
= 'CREATED';
38 * @var string Action key: a link has been updated.
40 public const UPDATED
= 'UPDATED';
43 * @var string Action key: a link has been deleted.
45 public const DELETED
= 'DELETED';
48 * @var string Action key: settings have been updated.
50 public const SETTINGS
= 'SETTINGS';
53 * @var string Action key: a bulk import has been processed.
55 public const IMPORT
= 'IMPORT';
58 * @var string History file path.
60 protected $historyFilePath;
63 * @var array History data.
68 * @var int History retention time in seconds (1 month).
70 protected $retentionTime = 2678400;
73 * History constructor.
75 * @param string $historyFilePath History file path.
76 * @param int $retentionTime History content retention time in seconds.
78 * @throws Exception if something goes wrong.
80 public function __construct($historyFilePath, $retentionTime = null)
82 $this->historyFilePath
= $historyFilePath;
83 if ($retentionTime !== null) {
84 $this->retentionTime
= $retentionTime;
89 * Initialize: read history file.
91 * Allow lazy loading (don't read the file if it isn't necessary).
93 protected function initialize()
100 * Add Event: new link.
102 * @param Bookmark $link Link data.
104 public function addLink($link)
106 $this->addEvent(self
::CREATED
, $link->getId());
110 * Add Event: update existing link.
112 * @param Bookmark $link Link data.
114 public function updateLink($link)
116 $this->addEvent(self
::UPDATED
, $link->getId());
120 * Add Event: delete existing link.
122 * @param Bookmark $link Link data.
124 public function deleteLink($link)
126 $this->addEvent(self
::DELETED
, $link->getId());
130 * Add Event: settings updated.
132 public function updateSettings()
134 $this->addEvent(self
::SETTINGS
);
138 * Add Event: bulk import.
140 * Note: we don't store bookmarks add/update one by one since it can have a huge impact on performances.
142 public function importLinks()
144 $this->addEvent(self
::IMPORT
);
148 * Save a new event and write it in the history file.
150 * @param string $status Event key, should be defined as constant.
151 * @param mixed $id Event item identifier (e.g. link ID).
153 protected function addEvent($status, $id = null)
155 if ($this->history
=== null) {
161 'datetime' => new DateTime(),
162 'id' => $id !== null ? $id : '',
164 $this->history
= array_merge([$item], $this->history
);
169 * Check that the history file is writable.
170 * Create the file if it doesn't exist.
172 * @throws Exception if it isn't writable.
174 protected function check()
176 if (!is_file($this->historyFilePath
)) {
177 FileUtils
::writeFlatDB($this->historyFilePath
, []);
180 if (!is_writable($this->historyFilePath
)) {
181 throw new Exception(t('History file isn\'t readable or writable'));
186 * Read JSON history file.
188 protected function read()
190 $this->history
= FileUtils
::readFlatDB($this->historyFilePath
, []);
191 if ($this->history
=== false) {
192 throw new Exception(t('Could not parse history file'));
197 * Write JSON history file and delete old entries.
199 protected function write()
201 $comparaison = new DateTime('-' . $this->retentionTime
. ' seconds');
202 foreach ($this->history
as $key => $value) {
203 if ($value['datetime'] < $comparaison) {
204 unset($this->history
[$key]);
207 FileUtils
::writeFlatDB($this->historyFilePath
, array_values($this->history
));
215 public function getHistory()
217 if ($this->history
=== null) {
221 return $this->history
;