class-updraft-semaphore.php — UpdraftPlus: WP Backup & Migration Plugin 1.26.4

updraftplus / includes / class-updraft-semaphore.php

updraftplus / includes Last commit date

class-updraft-semaphore.php

214 lines

1	<?php
2
3	if (!defined('ABSPATH')) die('No direct access.');
4
5	/**
6	* Class Updraft_Semaphore_3_0
7	*
8	* This class is much simpler to use than the the previous series, as it has dropped support for complicated cases that were not being used. It also now only uses a single row in the options database, and takes care of creating it itself internally.
9	*
10	* Logging, though, may be noisier, unless your loggers are taking note of the log level and only registering what is required.
11	*
12	* Example of use (a lock that will expire if not released within 300 seconds)
13	*
14	* See test.php for a longer example (including logging).
15	*
16	* $my_lock = new Updraft_Semaphore_3_0('my_lock_name', 300);
17	* // If getting the lock does not succeed first time, try again up to twice
18	* if ($my_lock->lock(2)) {
19	* try {
20	* // do stuff ...
21	* } catch (Exception $e) {
22	* // We are making sure we release the lock in case of an error
23	* } catch (Error $e) {
24	* // We are making sure we release the lock in case of an error
25	* }
26	* $my_lock->release();
27	* } else {
28	* error_log("Sorry, could not get the lock");
29	* }
30	*/
31	class Updraft_Semaphore_3_0 {
32
33	// Time after which the lock will expire (in seconds)
34	protected $locked_for;
35
36	// Name for the lock in the WP options table
37	protected $option_name;
38
39	// Lock status - a boolean
40	protected $acquired = false;
41
42	// An array of loggers
43	protected $loggers = array();
44
45	/**
46	* Constructor. Instantiating does not lock anything, but sets up the details for future operations.
47	*
48	* @param String $name - a unique (across the WP site) name for the lock. Should be no more than 51 characters in length (because of the use of the WP options table, with some further characters used internally)
49	* @param Integer $locked_for - time (in seconds) after which the lock will expire if not released. This needs to be positive if you don't want bad things to happen.
50	* @param Array $loggers - an array of loggers
51	*/
52	public function __construct($name, $locked_for = 300, $loggers = array()) {
53	$this->option_name = 'updraft_lock_'.$name;
54	$this->locked_for = $locked_for;
55	$this->loggers = $loggers;
56	}
57
58	/**
59	* Internal function to make sure that the lock is set up in the database
60	*
61	* @return Integer - 0 means 'failed' (which could include that someone else concurrently created it); 1 means 'already existed'; 2 means 'exists, because we created it). The intention is that non-zero results mean that the lock exists.
62	*/
63	private function ensure_database_initialised() {
64
65	global $wpdb;
66
67	$sql = $wpdb->prepare("SELECT COUNT(*) FROM {$wpdb->options} WHERE option_name = %s", $this->option_name);
68
69	if (1 === (int) $wpdb->get_var($sql)) {
70	$this->log('Lock option ('.$this->option_name.', '.$wpdb->options.') already existed in the database', 'debug');
71	return 1;
72	}
73
74	$sql = $wpdb->prepare("INSERT INTO {$wpdb->options} (option_name, option_value, autoload) VALUES(%s, '0', 'no');", $this->option_name);
75
76	$rows_affected = $wpdb->query($sql);
77
78	if ($rows_affected > 0) {
79	$this->log('Lock option ('.$this->option_name.', '.$wpdb->options.') was created in the database', 'debug');
80	} else {
81	$this->log('Lock option ('.$this->option_name.', '.$wpdb->options.') failed to be created in the database (could already exist)', 'notice');
82	}
83
84	return ($rows_affected > 0) ? 2 : 0;
85	}
86
87	/**
88	* Attempt to acquire the lock. If it was already acquired, then nothing extra will be done (the method will be a no-op).
89	*
90	* @param Integer $retries - how many times to retry (after a 1 second sleep each time)
91	*
92	* @return Boolean - whether the lock was successfully acquired or not
93	*/
94	public function lock($retries = 0) {
95
96	if ($this->acquired) return true;
97
98	global $wpdb;
99
100	$time_now = time();
101	$acquire_until = $time_now + $this->locked_for;
102
103	$sql = $wpdb->prepare("UPDATE {$wpdb->options} SET option_value = %s WHERE option_name = %s AND option_value < %d", $acquire_until, $this->option_name, $time_now);
104
105	if (1 === $wpdb->query($sql)) {
106	$this->log('Lock ('.$this->option_name.', '.$wpdb->options.') acquired', 'info');
107	$this->acquired = true;
108	return true;
109	}
110
111	// See if the failure was caused by the row not existing (we check this only after failure, because it should only occur once on the site)
112	if (!$this->ensure_database_initialised()) return false;
113
114	do {
115	// Now that the row has been created, try again
116	if (1 === $wpdb->query($sql)) {
117	$this->log('Lock ('.$this->option_name.', '.$wpdb->options.') acquired after initialising the database', 'info');
118	$this->acquired = true;
119	return true;
120	}
121	$retries--;
122	if ($retries >=0) {
123	$this->log('Lock ('.$this->option_name.', '.$wpdb->options.') not yet acquired; sleeping', 'debug');
124	sleep(1);
125	// As a second has passed, update the time we are aiming for
126	$time_now = time();
127	$acquire_until = $time_now + $this->locked_for;
128	$sql = $wpdb->prepare("UPDATE {$wpdb->options} SET option_value = %s WHERE option_name = %s AND option_value < %d", $acquire_until, $this->option_name, $time_now);
129	}
130	} while ($retries >= 0);
131
132	$this->log('Lock ('.$this->option_name.', '.$wpdb->options.') could not be acquired (it is locked)', 'info');
133
134	return false;
135	}
136
137	/**
138	* Release the lock
139	*
140	* N.B. We don't attempt to unlock it unless we locked it. i.e. Lost locks are left to expire rather than being forced. (If we want to force them, we'll need to introduce a new parameter).
141	*
142	* @return Boolean - if it returns false, then the lock was apparently not locked by us (and the caller will most likely therefore ignore the result, whatever it is).
143	*/
144	public function release() {
145	if (!$this->acquired) return false;
146	global $wpdb;
147	$sql = $wpdb->prepare("UPDATE {$wpdb->options} SET option_value = '0' WHERE option_name = %s", $this->option_name);
148
149	$this->log('Lock option ('.$this->option_name.', '.$wpdb->options.') released', 'info');
150
151	$result = (int) $wpdb->query($sql) === 1;
152
153	$this->acquired = false;
154
155	return $result;
156	}
157
158	/**
159	* Cleans up the DB of any residual data. This should not be used as part of ordinary unlocking; only as part of deinstalling, or if you otherwise know that the lock will not be used again. If calling this, it's redundant to first unlock (and a no-op to attempt to do so afterwards).
160	*/
161	public function delete() {
162	$this->acquired = false;
163
164	global $wpdb;
165	$wpdb->query($wpdb->prepare("DELETE FROM {$wpdb->options} WHERE option_name = %s", $this->option_name));
166
167	$this->log('Lock option ('.$this->option_name.', '.$wpdb->options.') was deleted from the database');
168	}
169
170	/**
171	* Captures and logs any given messages
172	*
173	* @param String $message - the error message
174	* @param String $level - the message level (debug, notice, info, warning, error)
175	*/
176	public function log($message, $level = 'info') {
177	if (isset($this->loggers)) {
178	foreach ($this->loggers as $logger) {
179	$logger->log($message, $level);
180	}
181	}
182	}
183
184	/**
185	* Sets the list of loggers for this instance (removing any others).
186	*
187	* @param Array $loggers - the loggers for this task
188	*/
189	public function set_loggers($loggers) {
190	$this->loggers = array();
191	foreach ($loggers as $logger) {
192	$this->add_logger($logger);
193	}
194	}
195
196	/**
197	* Add a logger to loggers list
198	*
199	* @param Callable $logger - a logger (a method with a callable function 'log', taking string parameters $level $message)
200	*/
201	public function add_logger($logger) {
202	$this->loggers[] = $logger;
203	}
204
205	/**
206	* Return the current list of loggers
207	*
208	* @return Array
209	*/
210	public function get_loggers() {
211	return $this->loggers;
212	}
213	}
214