aboutsummaryrefslogtreecommitdiffhomepage
path: root/application/History.php
blob: 1be955c57dffac27b0595ef0f65c354a445341bc (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
<?php

namespace Shaarli;

use DateTime;
use Exception;
use Shaarli\Bookmark\Bookmark;
use Shaarli\Helper\FileUtils;

/**
 * Class History
 *
 * Handle the history file tracing events in Shaarli.
 * The history is stored as JSON in a file set by 'resource.history' setting.
 *
 * Available data:
 *   - event: event key
 *   - datetime: event date, in ISO8601 format.
 *   - id: event item identifier (currently only link IDs).
 *
 * Available event keys:
 *   - CREATED: new link
 *   - UPDATED: link updated
 *   - DELETED: link deleted
 *   - SETTINGS: the settings have been updated through the UI.
 *   - IMPORT: bulk bookmarks import
 *
 * Note: new events are put at the beginning of the file and history array.
 */
class History
{
    /**
     * @var string Action key: a new link has been created.
     */
    const CREATED = 'CREATED';

    /**
     * @var string Action key: a link has been updated.
     */
    const UPDATED = 'UPDATED';

    /**
     * @var string Action key: a link has been deleted.
     */
    const DELETED = 'DELETED';

    /**
     * @var string Action key: settings have been updated.
     */
    const SETTINGS = 'SETTINGS';

    /**
     * @var string Action key: a bulk import has been processed.
     */
    const IMPORT = 'IMPORT';

    /**
     * @var string History file path.
     */
    protected $historyFilePath;

    /**
     * @var array History data.
     */
    protected $history;

    /**
     * @var int History retention time in seconds (1 month).
     */
    protected $retentionTime = 2678400;

    /**
     * History constructor.
     *
     * @param string $historyFilePath History file path.
     * @param int    $retentionTime   History content retention time in seconds.
     *
     * @throws Exception if something goes wrong.
     */
    public function __construct($historyFilePath, $retentionTime = null)
    {
        $this->historyFilePath = $historyFilePath;
        if ($retentionTime !== null) {
            $this->retentionTime = $retentionTime;
        }
    }

    /**
     * Initialize: read history file.
     *
     * Allow lazy loading (don't read the file if it isn't necessary).
     */
    protected function initialize()
    {
        $this->check();
        $this->read();
    }

    /**
     * Add Event: new link.
     *
     * @param Bookmark $link Link data.
     */
    public function addLink($link)
    {
        $this->addEvent(self::CREATED, $link->getId());
    }

    /**
     * Add Event: update existing link.
     *
     * @param Bookmark $link Link data.
     */
    public function updateLink($link)
    {
        $this->addEvent(self::UPDATED, $link->getId());
    }

    /**
     * Add Event: delete existing link.
     *
     * @param Bookmark $link Link data.
     */
    public function deleteLink($link)
    {
        $this->addEvent(self::DELETED, $link->getId());
    }

    /**
     * Add Event: settings updated.
     */
    public function updateSettings()
    {
        $this->addEvent(self::SETTINGS);
    }

    /**
     * Add Event: bulk import.
     *
     * Note: we don't store bookmarks add/update one by one since it can have a huge impact on performances.
     */
    public function importLinks()
    {
        $this->addEvent(self::IMPORT);
    }

    /**
     * Save a new event and write it in the history file.
     *
     * @param string $status Event key, should be defined as constant.
     * @param mixed  $id     Event item identifier (e.g. link ID).
     */
    protected function addEvent($status, $id = null)
    {
        if ($this->history === null) {
            $this->initialize();
        }

        $item = [
            'event' => $status,
            'datetime' => new DateTime(),
            'id' => $id !== null ? $id : '',
        ];
        $this->history = array_merge([$item], $this->history);
        $this->write();
    }

    /**
     * Check that the history file is writable.
     * Create the file if it doesn't exist.
     *
     * @throws Exception if it isn't writable.
     */
    protected function check()
    {
        if (!is_file($this->historyFilePath)) {
            FileUtils::writeFlatDB($this->historyFilePath, []);
        }

        if (!is_writable($this->historyFilePath)) {
            throw new Exception(t('History file isn\'t readable or writable'));
        }
    }

    /**
     * Read JSON history file.
     */
    protected function read()
    {
        $this->history = FileUtils::readFlatDB($this->historyFilePath, []);
        if ($this->history === false) {
            throw new Exception(t('Could not parse history file'));
        }
    }

    /**
     * Write JSON history file and delete old entries.
     */
    protected function write()
    {
        $comparaison = new DateTime('-' . $this->retentionTime . ' seconds');
        foreach ($this->history as $key => $value) {
            if ($value['datetime'] < $comparaison) {
                unset($this->history[$key]);
            }
        }
        FileUtils::writeFlatDB($this->historyFilePath, array_values($this->history));
    }

    /**
     * Get the History.
     *
     * @return array
     */
    public function getHistory()
    {
        if ($this->history === null) {
            $this->initialize();
        }

        return $this->history;
    }
}