Context Navigation

source: trunk/lib/App.inc.php @ 722

Last change on this file since 722 was 720, checked in by anonymous, 4 years ago
Update CSS reset with inspiration from https://github.com/hankchizljaw/modern-css-reset
File size: 87.1 KB

Line
1	<?php
2	/**
3	* The Strangecode Codebase - a general application development framework for PHP
4	* For details visit the project site: <http://trac.strangecode.com/codebase/>
5	* Copyright 2001-2012 Strangecode, LLC
6	*
7	* This file is part of The Strangecode Codebase.
8	*
9	* The Strangecode Codebase is free software: you can redistribute it and/or
10	* modify it under the terms of the GNU General Public License as published by the
11	* Free Software Foundation, either version 3 of the License, or (at your option)
12	* any later version.
13	*
14	* The Strangecode Codebase is distributed in the hope that it will be useful, but
15	* WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
16	* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
17	* details.
18	*
19	* You should have received a copy of the GNU General Public License along with
20	* The Strangecode Codebase. If not, see <http://www.gnu.org/licenses/>.
21	*/
22
23	/**
24	* App.inc.php
25	*
26	* Primary application framework class.
27	*
28	* @author Quinn Comendant <quinn@strangecode.com>
29	* @version 2.1
30	*/
31
32	// Message Types.
33	define('MSG_ERR', 1);
34	define('MSG_ERROR', MSG_ERR);
35	define('MSG_WARNING', 2);
36	define('MSG_NOTICE', 4);
37	define('MSG_SUCCESS', 8);
38	define('MSG_ALL', MSG_SUCCESS \| MSG_NOTICE \| MSG_WARNING \| MSG_ERROR);
39
40	require_once dirname(__FILE__) . '/Utilities.inc.php';
41
42	class App
43	{
44	// Minimum version of PHP required for this version of the Codebase.
45	const CODEBASE_MIN_PHP_VERSION = '5.3.0';
46
47	// A place to keep an object instance for the singleton pattern.
48	protected static $instance = null;
49
50	// Namespace of this application instance.
51	protected $_ns;
52
53	// If $app->start has run successfully.
54	public $running = false;
55
56	// Instance of database object (from mysql_connect() PHP version < 7).
57	public $db;
58
59	// Instance of PDO object.
60	public $pdo;
61
62	// Instance of database session handler object.
63	public $db_session;
64
65	// Array of query arguments will be carried persistently between requests.
66	protected $_carry_queries = array();
67
68	// Array of raised message counters.
69	protected $_raised_msg_counter = array(MSG_NOTICE => 0, MSG_SUCCESS => 0, MSG_WARNING => 0, MSG_ERR => 0);
70
71	// We're running as CLI. Public because we must force this as false when testing sessions via CLI.
72	public $cli = false;
73
74	// Dictionary of global application parameters.
75	protected $_params = array();
76
77	// Default parameters.
78	protected $_param_defaults = array(
79
80	// Public name and email address for this application.
81	'site_name' => null,
82	'site_email' => '', // Set to no-reply@HTTP_HOST if not set here.
83	'site_hostname' => '', // The hostname of this application (if not set, derived from HTTP_HOST).
84	'site_port' => '', // The hostname of this application (if not set, derived from HTTP_HOST).
85	'site_url' => '', // URL to the root of the site (created during App->start()).
86	'page_url' => '', // URL to the current page (created during App->start()).
87	'images_path' => '', // Location for codebase-generated interface widgets (ex: "/admin/i").
88	'site_version' => '', // Version of this application (set automatically during start() if site_version_file is used).
89	'site_version_file' => 'docs/version.txt', // File containing version number of this app, relative to the include path.
90
91	// The location the user will go if the system doesn't know where else to send them.
92	'redirect_home_url' => '/',
93
94	// Use CSRF tokens. See notes in the getCSRFToken() method.
95	'csrf_token_enabled' => true,
96	// Form tokens will expire after this duration, in seconds.
97	'csrf_token_timeout' => 259200, // 259200 seconds = 3 days.
98	'csrf_token_name' => 'csrf_token',
99
100	// HMAC signing method
101	'signing_method' => 'sha512+base64',
102
103	// Content type of output sent in the Content-type: http header.
104	'content_type' => 'text/html',
105
106	// Allow HTTP caching with max-age setting. Possible values:
107	// >= 1 Allow HTTP caching with this value set as the max-age (in seconds, i.e., 3600 = 1 hour).
108	// 0 Disallow HTTP caching.
109	// false Don't send any cache-related HTTP headers (if you want to control this via server config or custom headers)
110	// This should be '0' for websites that use authentication or have frequently changing dynamic content.
111	'http_cache_headers' => 0,
112
113	// Character set for page output. Used in the Content-Type header and the HTML <meta content-type> tag.
114	'character_set' => 'utf-8',
115
116	// Human-readable format used to display dates.
117	'date_format' => 'd M Y',
118	'time_format' => 'h:i:s A',
119	'lc_date_format' => '%e %b %Y', // Localized date for strftime() https://www.php.net/manual/en/function.strftime.php
120	'lc_time_format' => '%k:%M', // Localized time for strftime() https://www.php.net/manual/en/function.strftime.php
121	'sql_date_format' => '%e %b %Y',
122	'sql_time_format' => '%k:%i',
123
124	// Timezone support. No codebase apps currently support switching timezones, but we explicitly set these so they're consistent.
125	'user_timezone' => 'UTC',
126	'php_timezone' => 'UTC',
127	'db_timezone' => 'UTC',
128
129	// Use php sessions?
130	'enable_session' => false,
131	'session_name' => '_session',
132	'session_use_cookies' => true,
133
134	// Pass the session-id through URLs if cookies are not enabled?
135	// Disable this to prevent session ID theft.
136	'session_use_trans_sid' => false,
137
138	// Use database?
139	'enable_db' => false,
140	'enable_db_pdo' => false,
141
142	// Use db-based sessions?
143	'enable_db_session_handler' => false,
144
145	// db_* parameters are passed to the DB object in $app->start().
146	// DB credentials should be set as apache environment variables in httpd.conf, readable only by root.
147	'db_server' => null,
148	'db_name' => null,
149	'db_user' => null,
150	'db_pass' => null,
151	'db_character_set' => '',
152	'db_collation' => '',
153
154	// CLI scripts will need this JSON file in the include path.
155	'db_auth_file' => 'db_auth.json',
156
157	// Database debugging.
158	'db_always_debug' => false, // TRUE = display all SQL queries.
159	'db_debug' => false, // TRUE = display db errors.
160	'db_die_on_failure' => false, // TRUE = script stops on db error.
161
162	// For classes that require db tables, do we check that a table exists and create if missing?
163	'db_create_tables' => true,
164
165	// The level of error reporting. Don't change this to suppress messages, instead use display_errors to control display.
166	'error_reporting' => E_ALL,
167
168	// Don't display errors by default; it is preferable to log them to a file. For CLI scripts, set this to the string 'stderr'.
169	'display_errors' => false,
170
171	// Directory in which to store log files.
172	'log_directory' => '',
173
174	// PHP error log.
175	'php_error_log' => 'php_error_log',
176
177	// General application log.
178	'log_filename' => 'app_log',
179
180	// Don't email or SMS duplicate messages that happen more often than this value (in seconds).
181	'log_multiple_timeout' => 3600, // Hourly
182
183	// Logging priority can be any of the following, or false to deactivate:
184	// LOG_EMERG system is unusable
185	// LOG_ALERT action must be taken immediately
186	// LOG_CRIT critical conditions
187	// LOG_ERR error conditions
188	// LOG_WARNING warning conditions
189	// LOG_NOTICE normal, but significant, condition
190	// LOG_INFO informational message
191	// LOG_DEBUG debug-level message
192	'log_file_priority' => LOG_INFO,
193	'log_email_priority' => false,
194	'log_sms_priority' => false,
195	'log_screen_priority' => false,
196
197	// Email address to receive log event emails. Use multiple addresses by separating them with commas.
198	'log_to_email_address' => null,
199
200	// SMS Email address to receive log event SMS messages. Use multiple addresses by separating them with commas.
201	'log_to_sms_address' => null,
202
203	// Should we avoid logging repeated logMsg() events? You might want to set this false if you need to see more accurate logging, particularly for long-running scripts.
204	'log_ignore_repeated_events' => true,
205
206	// Maximum length of log messages, in bytes.
207	'log_message_max_length' => 1024,
208
209	// Strip line-endings from log messages.
210	'log_serialize' => true,
211
212	// Temporary files directory.
213	'tmp_dir' => '/tmp',
214
215	// Session files directory. If not defined, the default value from php.ini will be used.
216	'session_dir' => '',
217
218	// A key for calculating simple cryptographic signatures. Set using as an environment variables in the httpd.conf with 'SetEnv SIGNING_KEY <key>'.
219	// Existing password hashes rely on the same key/salt being used to compare encryptions.
220	// Don't change this unless you know existing hashes or signatures will not be affected!
221	'signing_key' => 'aae6abd6209d82a691a9f96384a7634a',
222
223	// Force getFormData, getPost, and getGet to always run dispelMagicQuotes() with stripslashes().
224	// This should be set to 'true' when using the codebase with Wordpress because
225	// WP forcefully adds slashes to all input despite the setting of magic_quotes_gpc.
226	'always_dispel_magicquotes' => false,
227	);
228
229	/**
230	* Constructor.
231	*/
232	public function __construct($namespace='')
233	{
234	// Initialize default parameters.
235	$this->_params = array_merge($this->_params, array('namespace' => $namespace), $this->_param_defaults);
236
237	// Begin timing script.
238	require_once dirname(__FILE__) . '/ScriptTimer.inc.php';
239	$this->timer = new ScriptTimer();
240	$this->timer->start('_app');
241
242	// Are we running as a CLI?
243	$this->cli = ('cli' === php_sapi_name() \|\| defined('_CLI'));
244	}
245
246	/**
247	* This method enforces the singleton pattern for this class. Only one application is running at a time.
248	*
249	* $param string $namespace Name of this application.
250	* @return object Reference to the global Cache object.
251	* @access public
252	* @static
253	*/
254	public static function &getInstance($namespace='')
255	{
256	if (self::$instance === null) {
257	// FIXME: Yep, having a namespace with one singleton instance is not very useful. This is a design flaw with the Codebase.
258	// We're currently getting instances of App throughout the codebase using `$app =& App::getInstance();`
259	// with no way to determine what the namespace of the containing application is (e.g., `public` vs. `admin`).
260	// Option 1: provide the project namespace to all classes that use App, and then instantiate with `$app =& App::getInstance($this->_ns);`.
261	// In this case the namespace of the App and the namespace of the auxiliary class must match.
262	// Option 2: may be to clone a specific instance to the "default" instance, so, e.g., `$app =& App::getInstance();`
263	// refers to the same namespace as `$app =& App::getInstance('admin');`
264	// Option 3: is to check if there is only one instance, and return it if an unspecified namespace is requested.
265	// However, in the case when multiple namespaces are in play at the same time, this will fail; unspecified namespaces
266	// would cause the creation of an additional instance, since there would not be an obvious named instance to return.
267	self::$instance = new self($namespace);
268	}
269
270	if ('' != $namespace) {
271	// We may not be able to request a specific instance, but we can specify a specific namespace.
272	// We're ignoring all instance requests with a blank namespace, so we use the last given one.
273	self::$instance->_ns = $namespace;
274	}
275
276	return self::$instance;
277	}
278
279	/**
280	* Set (or overwrite existing) parameters by passing an array of new parameters.
281	*
282	* @access public
283	* @param array $param Array of parameters (key => val pairs).
284	*/
285	public function setParam($param=null)
286	{
287	if (isset($param) && is_array($param)) {
288	// Merge new parameters with old overriding old ones that are passed.
289	$this->_params = array_merge($this->_params, $param);
290
291	if ($this->running) {
292	// Params that require additional processing if set during runtime.
293	foreach ($param as $key => $val) {
294	switch ($key) {
295	case 'namespace':
296	$this->logMsg(sprintf('Setting namespace not allowed', null), LOG_WARNING, __FILE__, __LINE__);
297	return false;
298
299	case 'session_name':
300	session_name($val);
301	return true;
302
303	case 'session_use_cookies':
304	if (session_status() !== PHP_SESSION_ACTIVE) {
305	ini_set('session.use_cookies', $val);
306	} else {
307	$this->logMsg('Unable to set session_use_cookies; session is already active', LOG_NOTICE, __FILE__, __LINE__);
308	}
309	return true;
310
311	case 'error_reporting':
312	ini_set('error_reporting', $val);
313	return true;
314
315	case 'display_errors':
316	ini_set('display_errors', $val);
317	return true;
318
319	case 'log_errors':
320	ini_set('log_errors', true);
321	return true;
322
323	case 'log_directory':
324	if (is_dir($val) && is_writable($val)) {
325	ini_set('error_log', $val . '/' . $this->getParam('php_error_log'));
326	}
327	return true;
328	}
329	}
330	}
331	}
332	}
333
334	/**
335	* Return the value of a parameter.
336	*
337	* @access public
338	* @param string $param The key of the parameter to return.
339	* @return mixed Parameter value, or null if not existing.
340	*/
341	public function getParam($param=null)
342	{
343	if ($param === null) {
344	return $this->_params;
345	} else if (array_key_exists($param, $this->_params)) {
346	return $this->_params[$param];
347	} else {
348	return null;
349	}
350	}
351
352	/**
353	* Begin running this application.
354	*
355	* @access public
356	* @author Quinn Comendant <quinn@strangecode.com>
357	* @since 15 Jul 2005 00:32:21
358	*/
359	public function start()
360	{
361	if ($this->running) {
362	return false;
363	}
364
365	// Error reporting.
366	ini_set('error_reporting', $this->getParam('error_reporting'));
367	ini_set('display_errors', $this->getParam('display_errors'));
368	ini_set('log_errors', true);
369	if (is_dir($this->getParam('log_directory')) && is_writable($this->getParam('log_directory'))) {
370	ini_set('error_log', $this->getParam('log_directory') . '/' . $this->getParam('php_error_log'));
371	}
372
373	// Set character set to use for multi-byte string functions.
374	mb_internal_encoding($this->getParam('character_set'));
375	ini_set('default_charset', $this->getParam('character_set'));
376	switch (mb_strtolower($this->getParam('character_set'))) {
377	case 'utf-8' :
378	mb_language('uni');
379	break;
380
381	case 'iso-2022-jp' :
382	mb_language('ja');
383	break;
384
385	case 'iso-8859-1' :
386	default :
387	mb_language('en');
388	break;
389	}
390
391	// Server timezone used internally by PHP.
392	if ($this->getParam('php_timezone')) {
393	$this->setTimezone($this->getParam('php_timezone'));
394	}
395
396	// If external request was HTTPS but internal request is HTTP, set $_SERVER['HTTPS']='on', which is used by the application to determine that TLS features should be enabled.
397	if (strtolower(getenv('HTTP_X_FORWARDED_PROTO')) == 'https' && strtolower(getenv('REQUEST_SCHEME')) == 'http') {
398	$this->logMsg(sprintf('Detected HTTPS via X-Forwarded-Proto; setting HTTPS=on', null), LOG_DEBUG, __FILE__, __LINE__);
399	putenv('HTTPS=on'); // Available via getenv(âŠ)
400	isset($_SERVER['HTTPS']) && $_SERVER['HTTPS'] = 'on'; // Available via $_SERVER[âŠ]
401	}
402
403	/**
404	* 1. Start Database.
405	*/
406
407	if (true === $this->getParam('enable_db') \|\| true === $this->getParam('enable_db_pdo')) {
408
409	// DB connection parameters taken from environment variables in the server httpd.conf file (readable only by root)âŠ
410	if (!empty($_SERVER['DB_SERVER']) && !$this->getParam('db_server')) {
411	$this->setParam(array('db_server' => $_SERVER['DB_SERVER']));
412	}
413	if (!empty($_SERVER['DB_NAME']) && !$this->getParam('db_name')) {
414	$this->setParam(array('db_name' => $_SERVER['DB_NAME']));
415	}
416	if (!empty($_SERVER['DB_USER']) && !$this->getParam('db_user')) {
417	$this->setParam(array('db_user' => $_SERVER['DB_USER']));
418	}
419	if (!empty($_SERVER['DB_PASS']) && !$this->getParam('db_pass')) {
420	$this->setParam(array('db_pass' => $_SERVER['DB_PASS']));
421	}
422
423	// DB credentials for CLI scripts stored in a JSON file with read rights given only to the user who will be executing the scripts: -r--------
424	// But not if all DB credentials have been defined already by other means.
425	if ($this->cli && (!$this->getParam('db_server') \|\| !$this->getParam('db_name') \|\| !$this->getParam('db_user') \|\| !$this->getParam('db_pass'))) {
426	if (false !== $db_auth_file = stream_resolve_include_path($this->getParam('db_auth_file'))) {
427	if (is_readable($db_auth_file)) {
428	$db_auth = json_decode(file_get_contents($db_auth_file), true);
429	if (is_null($db_auth)) {
430	$app->logMsg(sprintf('Unable to decode json in DB auth file: %s', $db_auth_file), LOG_ERR, __FILE__, __LINE__);
431	} else {
432	$this->setParam($db_auth);
433	}
434	} else {
435	$this->logMsg(sprintf('Unable to read DB auth file: %s', $db_auth_file), LOG_ERR, __FILE__, __LINE__);
436	}
437	} else {
438	$this->logMsg(sprintf('DB auth file not found: %s', $this->getParam('db_auth_file')), LOG_ERR, __FILE__, __LINE__);
439	}
440	}
441
442	// If the app wants a DB connection, always set up a PDO object.
443	require_once dirname(__FILE__) . '/PDO.inc.php';
444	$this->pdo =& \Strangecode\Codebase\PDO::getInstance();
445	$this->pdo->setParam(array(
446	'db_server' => $this->getParam('db_server'),
447	'db_name' => $this->getParam('db_name'),
448	'db_user' => $this->getParam('db_user'),
449	'db_pass' => $this->getParam('db_pass'),
450	'db_always_debug' => $this->getParam('db_always_debug'),
451	'db_debug' => $this->getParam('db_debug'),
452	'db_die_on_failure' => $this->getParam('db_die_on_failure'),
453	'timezone' => $this->getParam('db_timezone'),
454	'character_set' => $this->getParam('db_character_set'),
455	'collation' => $this->getParam('db_collation'),
456	));
457	$this->pdo->connect();
458
459	// Only create a legacy mysql_* DB object if it is explicitly requested.
460	if (true === $this->getParam('enable_db')) {
461	require_once dirname(__FILE__) . '/../polyfill/mysql.inc.php';
462	require_once dirname(__FILE__) . '/DB.inc.php';
463	$this->db =& DB::getInstance();
464	$this->db->setParam(array(
465	'db_server' => $this->getParam('db_server'),
466	'db_name' => $this->getParam('db_name'),
467	'db_user' => $this->getParam('db_user'),
468	'db_pass' => $this->getParam('db_pass'),
469	'db_always_debug' => $this->getParam('db_always_debug'),
470	'db_debug' => $this->getParam('db_debug'),
471	'db_die_on_failure' => $this->getParam('db_die_on_failure'),
472	'timezone' => $this->getParam('db_timezone'),
473	'character_set' => $this->getParam('db_character_set'),
474	'collation' => $this->getParam('db_collation'),
475	));
476	$this->db->connect();
477	}
478	}
479
480
481	/**
482	* 2. Start PHP session.
483	*/
484
485	// Use sessions if enabled and not a CLI script.
486	if (true === $this->getParam('enable_session') && !$this->cli) {
487
488	// Session parameters.
489	// https://www.php.net/manual/en/session.security.ini.php
490	ini_set('session.cookie_httponly', true);
491	ini_set('session.cookie_secure', getenv('HTTPS') == 'on');
492	ini_set('session.cookie_samesite', 'Strict'); // Only PHP >= 7.3
493	// TODO: Reliance on gc_maxlifetime is not recommended. Developers should manage the lifetime of sessions with a timestamp by themselves.
494	ini_set('session.cookie_lifetime', 604800); // 7 days.
495	ini_set('session.gc_maxlifetime', 604800); // 7 days.
496	ini_set('session.gc_divisor', 1000);
497	ini_set('session.gc_probability', 1);
498	ini_set('session.use_cookies', $this->getParam('session_use_cookies'));
499	ini_set('session.use_only_cookies', true);
500	ini_set('session.use_trans_sid', false);
501	ini_set('session.use_strict_mode', true);
502	ini_set('session.entropy_file', '/dev/urandom');
503	ini_set('session.entropy_length', '512');
504	ini_set('session.sid_length', '48'); // Only PHP >= 7.1
505	ini_set('session.cache_limiter', 'nocache');
506	if ('' != $this->getParam('session_dir') && is_dir($this->getParam('session_dir'))) {
507	ini_set('session.save_path', $this->getParam('session_dir'));
508	}
509	session_name($this->getParam('session_name'));
510
511	if (true === $this->getParam('enable_db_session_handler') && true === $this->getParam('enable_db')) {
512	// Database session handling.
513	require_once dirname(__FILE__) . '/DBSessionHandler.inc.php';
514	$this->db_session = new DBSessionHandler($this->db, array(
515	'db_table' => 'session_tbl',
516	'create_table' => $this->getParam('db_create_tables'),
517	));
518	}
519
520	// Start the session.
521	session_start();
522
523	if (!isset($_SESSION['_app'][$this->_ns])) {
524	// Access session data using: $_SESSION['...'].
525	// Initialize here _after_ session has started.
526	$_SESSION['_app'][$this->_ns] = array(
527	'messages' => array(),
528	'boomerang' => array(),
529	);
530	}
531	}
532
533
534	/**
535	* 3. Misc setup.
536	*/
537
538	// To get a safe hostname, remove port and invalid hostname characters.
539	$safe_http_host = preg_replace('/[^a-z\d.:-]/u', '', strtok(getenv('HTTP_HOST'), ':')); // FIXME: strtok shouldn't be used if there is a chance HTTP_HOST may be empty except for the port, e.g., `:80` will return `80`
540	// If strtok() matched a ':' in the previous line, the rest of the string contains the port number (or FALSE)
541	$safe_http_port = preg_replace('/[^0-9]/u', '', strtok(''));
542	if ('' != $safe_http_host && '' == $this->getParam('site_hostname')) {
543	$this->setParam(array('site_hostname' => $safe_http_host));
544	}
545	if ('' != $safe_http_port && '' == $this->getParam('site_port')) {
546	$this->setParam(array('site_port' => $safe_http_port));
547	}
548
549	// Site URL will become something like http://host.name.tld (no ending slash)
550	// and is used whenever a URL need be used to the current site.
551	// Not available on CLI scripts obviously.
552	if ('' != $safe_http_host && '' == $this->getParam('site_url')) {
553	$this->setParam(array('site_url' => sprintf('%s://%s%s', (getenv('HTTPS') ? 'https' : 'http'), $safe_http_host, (preg_match('/^(\|80\|443)$/', $safe_http_port) ? '' : ':' . $safe_http_port))));
554	}
555
556	// Page URL will become a permalink to the current page.
557	// Also not available on CLI scripts obviously.
558	if ('' != $safe_http_host) {
559	$this->setParam(array('page_url' => sprintf('%s%s', $this->getParam('site_url'), getenv('REQUEST_URI'))));
560	}
561
562	// In case site_email isn't set, use something halfway presentable.
563	if ('' != $safe_http_host && '' == $this->getParam('site_email')) {
564	$this->setParam(array('site_email' => sprintf('no-reply@%s', $safe_http_host)));
565	}
566
567	// A key for calculating simple cryptographic signatures.
568	if (isset($_SERVER['SIGNING_KEY'])) {
569	$this->setParam(array('signing_key' => $_SERVER['SIGNING_KEY']));
570	}
571
572	// Character set. This should also be printed in the html header template.
573	if (!$this->cli) {
574	if (!headers_sent($h_file, $h_line)) {
575	header(sprintf('Content-type: %s; charset=%s', $this->getParam('content_type'), $this->getParam('character_set')));
576	} else {
577	$this->logMsg(sprintf('Unable to set Content-type; headers already sent (output started in %s : %s)', $h_file, $h_line), LOG_DEBUG, __FILE__, __LINE__);
578	}
579	}
580
581	// Cache control headers.
582	if (!$this->cli && false !== $this->getParam('http_cache_headers')) {
583	if (!headers_sent($h_file, $h_line)) {
584	if ($this->getParam('http_cache_headers') > 0) {
585	// Allow HTTP caching, for this many seconds.
586	header(sprintf('Cache-Control: no-transform, public, max-age=%d', $this->getParam('http_cache_headers')));
587	header('Vary: Accept-Encoding');
588	} else {
589	// Disallow HTTP caching entirely. http://stackoverflow.com/a/2068407
590	header('Cache-Control: no-cache, no-store, must-revalidate'); // HTTP 1.1.
591	header('Pragma: no-cache'); // HTTP 1.0.
592	header('Expires: 0'); // Proxies.
593	}
594	} else {
595	$this->logMsg(sprintf('Unable to set Cache-Control; headers already sent (output started in %s : %s)', $h_file, $h_line), LOG_DEBUG, __FILE__, __LINE__);
596	}
597	}
598
599	// Set the version of the codebase we're using.
600	$codebase_version_file = dirname(__FILE__) . '/../docs/version.txt';
601	$codebase_version = '';
602	if (is_readable($codebase_version_file) && !is_dir($codebase_version_file)) {
603	$codebase_version = trim(file_get_contents($codebase_version_file));
604	$this->setParam(array('codebase_version' => $codebase_version));
605	if (!$this->cli && $this->getParam('codebase_version')) {
606	if (!headers_sent($h_file, $h_line)) {
607	header(sprintf('X-Codebase-Version: %s', $this->getParam('codebase_version')));
608	} else {
609	$this->logMsg(sprintf('Unable to set X-Codebase-Version; headers already sent (output started in %s : %s)', $h_file, $h_line), LOG_DEBUG, __FILE__, __LINE__);
610	}
611	}
612	}
613
614	if (version_compare(PHP_VERSION, self::CODEBASE_MIN_PHP_VERSION, '<')) {
615	$this->logMsg(sprintf('PHP %s required for Codebase %s, using %s; some things will break.', self::CODEBASE_MIN_PHP_VERSION, $codebase_version, PHP_VERSION), LOG_NOTICE, __FILE__, __LINE__);
616	}
617
618	// Set the application version if defined.
619	if (false !== $site_version_file = stream_resolve_include_path($this->getParam('site_version_file'))) {
620	if (mb_strpos($site_version_file, '.json') !== false) {
621	$version_json = json_decode(trim(file_get_contents($site_version_file)), true);
622	$site_version = isset($version_json['version']) ? $version_json['version'] : null;
623	} else {
624	$site_version = trim(file_get_contents($site_version_file));
625	}
626	$this->setParam(array('site_version' => $site_version));
627	}
628	if (!$this->cli && $this->getParam('site_version')) {
629	if (!headers_sent($h_file, $h_line)) {
630	header(sprintf('X-Site-Version: %s', $this->getParam('site_version')));
631	} else {
632	$this->logMsg(sprintf('Unable to set X-Site-Version; headers already sent (output started in %s : %s)', $h_file, $h_line), LOG_DEBUG, __FILE__, __LINE__);
633	}
634	}
635
636	// Unset environment variables we're done with.
637	unset($_SERVER['DB_SERVER'], $_SERVER['DB_NAME'], $_SERVER['DB_USER'], $_SERVER['DB_PASS'], $_SERVER['SIGNING_KEY']);
638
639	$this->running = true;
640	return true;
641	}
642
643	/**
644	* Stop running this application.
645	*
646	* @access public
647	* @author Quinn Comendant <quinn@strangecode.com>
648	* @since 17 Jul 2005 17:20:18
649	*/
650	public function stop()
651	{
652	session_write_close();
653	$this->running = false;
654	$num_queries = 0;
655	if ($this->db instanceof \DB && true === $this->getParam('enable_db')) {
656	$num_queries += $this->db->numQueries();
657	if ($num_queries > 0 && true === $this->getParam('enable_db_pdo')) {
658	// If the app wants to use PDO, warn if any legacy db queries are made.
659	$this->logMsg(sprintf('%s queries using legacy DB functions', $num_queries), LOG_WARNING, __FILE__, __LINE__);
660	}
661	$this->db->close();
662	}
663	if ($this->pdo instanceof \Strangecode\Codebase\PDO && (true === $this->getParam('enable_db') \|\| true === $this->getParam('enable_db_pdo'))) {
664	$num_queries += $this->pdo->numQueries();
665	$this->pdo->close();
666	}
667	$mem_current = memory_get_usage();
668	$mem_peak = memory_get_peak_usage();
669	$this->timer->stop('_app');
670	$this->logMsg(sprintf('Script ended gracefully. Execution time: %s. Number of db queries: %s. Memory usage: %s. Peak memory: %s.', $this->timer->getTime('_app'), $num_queries, $mem_current, $mem_peak), LOG_DEBUG, __FILE__, __LINE__);
671	}
672
673	/*
674	* @access public
675	* @return bool True if running in the context of a CLI script.
676	* @author Quinn Comendant <quinn@strangecode.com>
677	* @since 10 Feb 2019 12:31:59
678	*/
679	public function isCLI()
680	{
681	return $this->cli;
682	}
683
684	/**
685	* Add a message to the session, which is printed in the header.
686	* Just a simple way to print messages to the user.
687	*
688	* @access public
689	*
690	* @param string $message The text description of the message.
691	* @param int $type The type of message: MSG_NOTICE,
692	* MSG_SUCCESS, MSG_WARNING, or MSG_ERR.
693	* @param string $file __FILE__.
694	* @param string $line __LINE__.
695	*/
696	public function raiseMsg($message, $type=MSG_NOTICE, $file=null, $line=null)
697	{
698	$message = trim($message);
699
700	if (!$this->running) {
701	$this->logMsg(sprintf('Canceled %s, application not running.', __METHOD__), LOG_NOTICE, __FILE__, __LINE__);
702	return false;
703	}
704
705	if (!$this->getParam('enable_session')) {
706	$this->logMsg(sprintf('Canceled %s, session not enabled.', __METHOD__), LOG_NOTICE, __FILE__, __LINE__);
707	return false;
708	}
709
710	if ('' == trim($message)) {
711	$this->logMsg(sprintf('Raised message is an empty string.', null), LOG_NOTICE, __FILE__, __LINE__);
712	return false;
713	}
714
715	// Avoid duplicate full-stops..
716	$message = trim(preg_replace('/\.{2}$/', '.', $message));
717
718	// Save message in session under unique key to avoid duplicate messages.
719	$msg_id = md5($type . $message);
720	if (!isset($_SESSION['_app'][$this->_ns]['messages'][$msg_id])) {
721	$_SESSION['_app'][$this->_ns]['messages'][$msg_id] = array(
722	'type' => $type,
723	'message' => $message,
724	'file' => $file,
725	'line' => $line,
726	'count' => (isset($_SESSION['_app'][$this->_ns]['messages'][$msg_id]['count']) ? (1 + $_SESSION['_app'][$this->_ns]['messages'][$msg_id]['count']) : 1)
727	);
728	}
729
730	if (!in_array($type, array(MSG_NOTICE, MSG_SUCCESS, MSG_WARNING, MSG_ERR))) {
731	$this->logMsg(sprintf('Invalid MSG_* type: %s', $type), LOG_NOTICE, __FILE__, __LINE__);
732	}
733
734	// Increment the counter for this message type.
735	$this->_raised_msg_counter[$type] += 1;
736	}
737
738	/*
739	* Returns the number of raised message (all, or by type) for the current script execution (this number may not match the total number of messages stored in session for multiple script executions)
740	*
741	* @access public
742	* @param
743	* @return
744	* @author Quinn Comendant <quinn@strangecode.com>
745	* @version 1.0
746	* @since 30 Apr 2015 17:13:03
747	*/
748	public function getRaisedMessageCount($type='all')
749	{
750	if ('all' == $type) {
751	return array_sum($this->_raised_msg_counter);
752	} else if (isset($this->_raised_msg_counter[$type])) {
753	return $this->_raised_msg_counter[$type];
754	} else {
755	$this->logMsg(sprintf('Cannot return count of unknown raised message type: %s', $type), LOG_WARNING, __FILE__, __LINE__);
756	return false;
757	}
758	}
759
760	/**
761	* Returns an array of the raised messages.
762	*
763	* @access public
764	* @return array List of messages in FIFO order.
765	* @author Quinn Comendant <quinn@strangecode.com>
766	* @since 21 Dec 2005 13:09:20
767	*/
768	public function getRaisedMessages()
769	{
770	if (!$this->running) {
771	$this->logMsg(sprintf('Canceled %s, application not running.', __METHOD__), LOG_NOTICE, __FILE__, __LINE__);
772	return false;
773	}
774	return isset($_SESSION['_app'][$this->_ns]['messages']) ? $_SESSION['_app'][$this->_ns]['messages'] : array();
775	}
776
777	/**
778	* Resets the message list.
779	*
780	* @access public
781	* @author Quinn Comendant <quinn@strangecode.com>
782	* @since 21 Dec 2005 13:21:54
783	*/
784	public function clearRaisedMessages()
785	{
786	if (!$this->running) {
787	$this->logMsg(sprintf('Canceled %s, application not running.', __METHOD__), LOG_NOTICE, __FILE__, __LINE__);
788	return false;
789	}
790
791	$_SESSION['_app'][$this->_ns]['messages'] = array();
792	}
793
794	/**
795	* Prints the HTML for displaying raised messages.
796	*
797	* @param string $above Additional message to print above error messages (e.g. "Oops!").
798	* @param string $below Additional message to print below error messages (e.g. "Please fix and resubmit").
799	* @param string $print_gotohash_js Print a line of javascript that scrolls the browser window down to view any error messages.
800	* @param string $hash The #hashtag to scroll to.
801	* @access public
802	* @author Quinn Comendant <quinn@strangecode.com>
803	* @since 15 Jul 2005 01:39:14
804	*/
805	public function printRaisedMessages($above='', $below='', $print_gotohash_js=false, $hash='sc-msg')
806	{
807
808	if (!$this->running) {
809	$this->logMsg(sprintf('Canceled %s, application not running.', __METHOD__), LOG_NOTICE, __FILE__, __LINE__);
810	return false;
811	}
812
813	$messages = $this->getRaisedMessages();
814	if (!empty($messages)) {
815	?><div id="sc-msg" class="sc-msg"><?php
816	if ('' != $above) {
817	?><div class="sc-above"><?php echo oTxt($above); ?></div><?php
818	}
819	foreach ($messages as $m) {
820	if (error_reporting() > 0 && $this->getParam('display_errors') && isset($m['file']) && isset($m['line'])) {
821	echo "\n<!-- [" . $m['file'] . ' : ' . $m['line'] . '] -->';
822	}
823	switch ($m['type']) {
824	case MSG_ERR:
825	echo '<div data-alert data-closable class="sc-msg-error alert-box callout alert">' . $m['message'] . '<a class="close close-button" aria-label="Dismiss alert" data-close><span aria-hidden="true">×</span></a></div>';
826	break;
827
828	case MSG_WARNING:
829	echo '<div data-alert data-closable class="sc-msg-warning alert-box callout warning">' . $m['message'] . '<a class="close close-button" aria-label="Dismiss alert" data-close><span aria-hidden="true">×</span></a></div>';
830	break;
831
832	case MSG_SUCCESS:
833	echo '<div data-alert data-closable class="sc-msg-success alert-box callout success">' . $m['message'] . '<a class="close close-button" aria-label="Dismiss alert" data-close><span aria-hidden="true">×</span></a></div>';
834	break;
835
836	case MSG_NOTICE:
837	default:
838	echo '<div data-alert data-closable class="sc-msg-notice alert-box callout primary info">' . $m['message'] . '<a class="close close-button" aria-label="Dismiss alert" data-close><span aria-hidden="true">×</span></a></div>';
839	break;
840	}
841	}
842	if ('' != $below) {
843	?><div class="sc-below"><?php echo oTxt($below); ?></div><?php
844	}
845	?></div><?php
846	if ($print_gotohash_js) {
847	?>
848	<script type="text/javascript">
849	/* <![CDATA[ */
850	window.location.hash = '#<?php echo urlencode($hash); ?>';
851	/* ]]> */
852	</script>
853	<?php
854	}
855	}
856	$this->clearRaisedMessages();
857	}
858
859	/**
860	* Logs messages to defined channels: file, email, sms, and screen. Repeated messages are
861	* not repeated but printed once with count. Log events that match a sendable channel (email or SMS)
862	* are sent once per 'log_multiple_timeout' setting (to avoid a flood of error emails).
863	*
864	* @access public
865	* @param string $message The text description of the message.
866	* @param int $priority The type of message priority (in descending order):
867	* LOG_EMERG 0 system is unusable
868	* LOG_ALERT 1 action must be taken immediately
869	* LOG_CRIT 2 critical conditions
870	* LOG_ERR 3 error conditions
871	* LOG_WARNING 4 warning conditions
872	* LOG_NOTICE 5 normal, but significant, condition
873	* LOG_INFO 6 informational message
874	* LOG_DEBUG 7 debug-level message
875	* @param string $file The file where the log event occurs.
876	* @param string $line The line of the file where the log event occurs.
877	* @param string $url The URL where the log event occurs ($_SERVER['REQUEST_URI'] will be used if left null).
878	*/
879	public function logMsg($message, $priority=LOG_INFO, $file=null, $line=null, $url=null)
880	{
881	static $previous_events = array();
882
883	// If priority is not specified, assume the worst.
884	if (!$this->logPriorityToString($priority)) {
885	$this->logMsg(sprintf('Log priority %s not defined. (Message: %s)', $priority, $message), LOG_EMERG, $file, $line);
886	$priority = LOG_EMERG;
887	}
888
889	// In case __FILE__ and __LINE__ are not provided, note that fact.
890	$file = '' == $file ? 'unknown-file' : $file;
891	$line = '' == $line ? 'unknown-line' : $line;
892
893	// Get the URL, or used the provided value.
894	if (!isset($url)) {
895	$url = isset($_SERVER['REQUEST_URI']) ? mb_substr($_SERVER['REQUEST_URI'], 0, $this->getParam('log_message_max_length')) : '';
896	}
897
898	// If log file is not specified, don't log to a file.
899	if (!$this->getParam('log_directory') \|\| !$this->getParam('log_filename') \|\| !is_dir($this->getParam('log_directory')) \|\| !is_writable($this->getParam('log_directory'))) {
900	$this->setParam(array('log_file_priority' => false));
901	// We must use trigger_error to report this problem rather than calling $app->logMsg, which might lead to an infinite loop.
902	trigger_error(sprintf('Codebase error: log directory (%s) not found or writable.', $this->getParam('log_directory')), E_USER_NOTICE);
903	}
904
905	// Before we get any further, let's see if ANY log events are configured to be reported.
906	if ((false === $this->getParam('log_file_priority') \|\| $priority > $this->getParam('log_file_priority'))
907	&& (false === $this->getParam('log_email_priority') \|\| $priority > $this->getParam('log_email_priority'))
908	&& (false === $this->getParam('log_sms_priority') \|\| $priority > $this->getParam('log_sms_priority'))
909	&& (false === $this->getParam('log_screen_priority') \|\| $priority > $this->getParam('log_screen_priority'))) {
910	// This event would not be recorded, skip it entirely.
911	return false;
912	}
913
914	if ($this->getParam('log_serialize')) {
915	// Serialize multi-line messages.
916	$message = preg_replace('/\s+/m', ' ', trim($message));
917	}
918
919	// Store this event under a unique key, counting each time it occurs so that it only gets reported a limited number of times.
920	$msg_id = md5($message . $priority . $file . $line);
921	if ($this->getParam('log_ignore_repeated_events') && isset($previous_events[$msg_id])) {
922	$previous_events[$msg_id]++;
923	if ($previous_events[$msg_id] == 2) {
924	$this->logMsg(sprintf('%s (Event repeated %s or more times)', $message, $previous_events[$msg_id]), $priority, $file, $line);
925	}
926	return false;
927	} else {
928	$previous_events[$msg_id] = 1;
929	}
930
931	// For email and SMS notification types use "lock" files to prevent sending email and SMS notices ad infinitum.
932	if ((false !== $this->getParam('log_email_priority') && $priority <= $this->getParam('log_email_priority'))
933	\|\| (false !== $this->getParam('log_sms_priority') && $priority <= $this->getParam('log_sms_priority'))) {
934	// This event will generate a "send" notification. Prepare lock file.
935	$site_hash = md5(empty($_SERVER['SERVER_NAME']) ? $_SERVER['SCRIPT_FILENAME'] : $_SERVER['SERVER_NAME']);
936	$lock_dir = $this->getParam('tmp_dir') . "/codebase_msgs_$site_hash/";
937	// Just use the file and line for the msg_id to limit the number of possible messages
938	// (the message string itself shan't be used as it may contain innumerable combinations).
939	$lock_file = $lock_dir . md5($file . ':' . $line);
940	if (!is_dir($lock_dir)) {
941	mkdir($lock_dir);
942	}
943	$send_notifications = true;
944	if (is_file($lock_file)) {
945	$msg_last_sent = filectime($lock_file);
946	// Has this message been sent more recently than the timeout?
947	if ((time() - $msg_last_sent) <= $this->getParam('log_multiple_timeout')) {
948	// This message was already sent recently.
949	$send_notifications = false;
950	} else {
951	// Timeout has expired; send notifications again and reset timeout.
952	touch($lock_file);
953	}
954	} else {
955	touch($lock_file);
956	}
957	}
958
959	// Make sure to log in the system's locale.
960	$locale = setlocale(LC_TIME, 0);
961	setlocale(LC_TIME, 'C');
962
963	// Data to be stored for a log event.
964	$event = array(
965	'date' => date('Y-m-d H:i:s'),
966	'remote ip' => getRemoteAddr(),
967	'pid' => getmypid(),
968	'type' => $this->logPriorityToString($priority),
969	'file:line' => "$file : $line",
970	'url' => $url,
971	'message' => mb_substr($message, 0, $this->getParam('log_message_max_length')),
972	);
973	// Here's a shortened version of event data.
974	$event_short = $event;
975	$event_short['url'] = truncate($event_short['url'], 120);
976
977	// Restore original locale.
978	setlocale(LC_TIME, $locale);
979
980	// FILE ACTION
981	if (false !== $this->getParam('log_file_priority') && $priority <= $this->getParam('log_file_priority')) {
982	$event_str = '[' . join('] [', $event_short) . ']';
983	error_log("$event_str\n", 3, $this->getParam('log_directory') . '/' . $this->getParam('log_filename'));
984	}
985
986	// EMAIL ACTION
987	if (false !== $this->getParam('log_email_priority') && $priority <= $this->getParam('log_email_priority') && $send_notifications) {
988	$hostname = ('' != $this->getParam('site_hostname')) ? $this->getParam('site_hostname') : php_uname('n');
989	$subject = sprintf('[%s %s] %s', $hostname, $event['type'], mb_substr($event['message'], 0, 64));
990	$email_msg = sprintf("A log event of type '%s' occurred on %s\n\n", $event['type'], $hostname);
991	$headers = 'From: ' . $this->getParam('site_email');
992	foreach ($event as $k=>$v) {
993	$email_msg .= sprintf("%-16s %s\n", $k, $v);
994	}
995	$email_msg .= sprintf("%-16s %s\n", 'codebase version', $this->getParam('codebase_version'));
996	$email_msg .= sprintf("%-16s %s\n", 'site version', $this->getParam('site_version'));
997	mb_send_mail($this->getParam('log_to_email_address'), $subject, $email_msg, $headers);
998	}
999
1000	// SMS ACTION
1001	if (false !== $this->getParam('log_sms_priority') && $priority <= $this->getParam('log_sms_priority') && $send_notifications) {
1002	$hostname = ('' != $this->getParam('site_hostname')) ? $this->getParam('site_hostname') : php_uname('n');
1003	$subject = sprintf('[%s %s]', $hostname, $priority);
1004	$sms_msg = sprintf('%s [%s:%s]', mb_substr($event_short['message'], 0, 64), basename($file), $line);
1005	$headers = 'From: ' . $this->getParam('site_email');
1006	mb_send_mail($this->getParam('log_to_sms_address'), $subject, $sms_msg, $headers);
1007	}
1008
1009	// SCREEN ACTION
1010	if (false !== $this->getParam('log_screen_priority') && $priority <= $this->getParam('log_screen_priority')) {
1011	file_put_contents('php://stderr', "[{$event['type']}] [{$event['message']}]\n", FILE_APPEND);
1012	}
1013
1014	return true;
1015	}
1016
1017	/**
1018	* Returns the string representation of a LOG_* integer constant.
1019	* Updated: also returns the LOG_* integer constant if passed a string log value ('info' returns 6).
1020	*
1021	* @param int $priority The LOG_* integer constant (to return the string name), or a string name of a log priority to return the integer LOG_* value..
1022	*
1023	* @return The string representation of $priority (if integer given), or integer representation (if string given).
1024	*/
1025	public function logPriorityToString($priority) {
1026	$priorities = array(
1027	LOG_EMERG => 'emergency',
1028	LOG_ALERT => 'alert',
1029	LOG_CRIT => 'critical',
1030	LOG_ERR => 'error',
1031	LOG_WARNING => 'warning',
1032	LOG_NOTICE => 'notice',
1033	LOG_INFO => 'info',
1034	LOG_DEBUG => 'debug'
1035	);
1036	if (isset($priorities[$priority])) {
1037	return $priorities[$priority];
1038	} else if (is_string($priority) && false !== ($key = array_search($priority, $priorities))) {
1039	return $key;
1040	} else {
1041	return false;
1042	}
1043	}
1044
1045	/**
1046	* Forcefully set a query argument even if one currently exists in the request.
1047	* Values in the _carry_queries array will be copied to URLs (via $app->url()) and
1048	* to hidden input values (via printHiddenSession()).
1049	*
1050	* @access public
1051	* @param mixed $query_key The key (or keys, as an array) of the query argument to save.
1052	* @param mixed $val The new value of the argument key.
1053	* @author Quinn Comendant <quinn@strangecode.com>
1054	* @since 13 Oct 2007 11:34:51
1055	*/
1056	public function setQuery($query_key, $val)
1057	{
1058	if (!is_array($query_key)) {
1059	$query_key = array($query_key);
1060	}
1061	foreach ($query_key as $k) {
1062	// Set the value of the specified query argument into the _carry_queries array.
1063	$this->_carry_queries[$k] = $val;
1064	}
1065	}
1066
1067	/**
1068	* Specify which query arguments will be carried persistently between requests.
1069	* Values in the _carry_queries array will be copied to URLs (via $app->url()) and
1070	* to hidden input values (via printHiddenSession()).
1071	*
1072	* @access public
1073	* @param mixed $query_key The key (or keys, as an array) of the query argument to save.
1074	* @param mixed $default If the key is not available, set to this default value.
1075	* @author Quinn Comendant <quinn@strangecode.com>
1076	* @since 14 Nov 2005 19:24:52
1077	*/
1078	public function carryQuery($query_key, $default=false)
1079	{
1080	if (!is_array($query_key)) {
1081	$query_key = array($query_key);
1082	}
1083	foreach ($query_key as $k) {
1084	// If not already set, and there is a non-empty value provided in the request...
1085	if (isset($k) && '' != $k && !isset($this->_carry_queries[$k]) && false !== getFormData($k, $default)) {
1086	// Copy the value of the specified query argument into the _carry_queries array.
1087	$this->_carry_queries[$k] = getFormData($k, $default);
1088	$this->logMsg(sprintf('Carrying query: %s => %s', $k, truncate(getDump($this->_carry_queries[$k], true), 128, 'end')), LOG_DEBUG, __FILE__, __LINE__);
1089	}
1090	}
1091	}
1092
1093	/**
1094	* dropQuery() is the opposite of carryQuery(). The specified value will not appear in
1095	* url()/ohref()/printHiddenSession() modified URLs unless explicitly written in.
1096	*
1097	* @access public
1098	* @param mixed $query_key The key (or keys, as an array) of the query argument to remove.
1099	* @param bool $unset Remove any values set in the request matching the given $query_key.
1100	* @author Quinn Comendant <quinn@strangecode.com>
1101	* @since 18 Jun 2007 20:57:29
1102	*/
1103	public function dropQuery($query_key, $unset=false)
1104	{
1105	if (!is_array($query_key)) {
1106	$query_key = array($query_key);
1107	}
1108	foreach ($query_key as $k) {
1109	if (array_key_exists($k, $this->_carry_queries)) {
1110	// Remove the value of the specified query argument from the _carry_queries array.
1111	$this->logMsg(sprintf('Dropping carried query: %s => %s', $k, $this->_carry_queries[$k]), LOG_DEBUG, __FILE__, __LINE__);
1112	unset($this->_carry_queries[$k]);
1113	}
1114	if ($unset && (isset($_REQUEST) && array_key_exists($k, $_REQUEST))) {
1115	unset($_REQUEST[$k], $_GET[$k], $_POST[$k], $_COOKIE[$k]);
1116	}
1117	}
1118	}
1119
1120	/**
1121	* Outputs a fully qualified URL with a query of all the used (ie: not empty)
1122	* keys and values, including optional queries. This allows mindless retention
1123	* of query arguments across page requests. If cookies are not
1124	* used and session_use_trans_sid=true the session id will be propagated in the URL.
1125	*
1126	* @param string $url The initial url
1127	* @param mixed $carry_args Additional url arguments to carry in the query,
1128	* or FALSE to prevent carrying queries. Can be any of the following formats:
1129	* array('key1', key2', key3') <-- to save these keys if in the form data.
1130	* array('key1'=>'value', key2'='value') <-- to set keys to default values if not present in form data.
1131	* false <-- To not carry any queries. If URL already has queries those will be retained.
1132	*
1133	* @param mixed $always_include_sid Always add the session id, even if using_trans_sid = true. This is required when
1134	* URL starts with http, since PHP using_trans_sid doesn't do those and also for
1135	* header('Location...') redirections.
1136	*
1137	* @param bool $include_csrf_token Set to true to include the csrf_token in the form. Only use this for forms with action="post" to prevent the token from being revealed in the URL.
1138	* @return string url with attached queries and, if not using cookies, the session id
1139	*/
1140	public function url($url='', $carry_args=null, $always_include_sid=false, $include_csrf_token=false)
1141	{
1142	if (!$this->running) {
1143	$this->logMsg(sprintf('Canceled %s, application not running.', __METHOD__), LOG_NOTICE, __FILE__, __LINE__);
1144	return false;
1145	}
1146
1147	if ($this->getParam('csrf_token_enabled') && $include_csrf_token) {
1148	// Include the csrf_token as a carried query argument.
1149	// This token can be validated upon form submission with $app->verifyCSRFToken() or $app->requireValidCSRFToken()
1150	$carry_args = is_array($carry_args) ? $carry_args : array();
1151	$carry_args = array_merge($carry_args, array($this->getParam('csrf_token_name') => $this->getCSRFToken()));
1152	}
1153
1154	// Get any provided query arguments to include in the final URL.
1155	// If FALSE is a provided here, DO NOT carry the queries.
1156	$do_carry_queries = true;
1157	$one_time_carry_queries = array();
1158	if (!is_null($carry_args)) {
1159	if (is_array($carry_args)) {
1160	if (!empty($carry_args)) {
1161	foreach ($carry_args as $key=>$arg) {
1162	// Get query from appropriate source.
1163	if (false === $arg) {
1164	$do_carry_queries = false;
1165	} else if (false !== getFormData($arg, false)) {
1166	$one_time_carry_queries[$arg] = getFormData($arg); // Set arg to form data if available.
1167	} else if (!is_numeric($key) && '' != $arg) {
1168	$one_time_carry_queries[$key] = getFormData($key, $arg); // Set to arg to default if specified (overwritten by form data).
1169	}
1170	}
1171	}
1172	} else if (false !== getFormData($carry_args, false)) {
1173	$one_time_carry_queries[$carry_args] = getFormData($carry_args);
1174	} else if (false === $carry_args) {
1175	$do_carry_queries = false;
1176	}
1177	}
1178
1179	// If the URL is empty, use REQUEST_URI stripped of its query string.
1180	if ('' == $url) {
1181	$url = (strstr(getenv('REQUEST_URI'), '?', true) ?: getenv('REQUEST_URI')); // strstr() returns false if '?' is not found, so use a shorthand ternary operator.
1182	}
1183
1184	// Get the first delimiter that is needed in the url.
1185	$delim = mb_strpos($url, '?') !== false ? ini_get('arg_separator.output') : '?';
1186
1187	$q = '';
1188	if ($do_carry_queries) {
1189	// Join the global _carry_queries and local one_time_carry_queries.
1190	$query_args = urlEncodeArray(array_merge($this->_carry_queries, $one_time_carry_queries));
1191	foreach ($query_args as $key=>$val) {
1192	// Avoid indexed-array query params because in a URL array param keys should all match.
1193	// I.e, we want to use `array[]=A&array[]=B` instead of `array[0]=A&array[1]=B`.
1194	$key = preg_replace('/\[\d+\]$/u', '[]', $key);
1195	// Check value is set and value does not already exist in the url.
1196	if (!preg_match('/[?&]' . preg_quote($key) . '=/', $url)) {
1197	$q .= $delim . $key . '=' . $val;
1198	$delim = ini_get('arg_separator.output');
1199	}
1200	}
1201	}
1202
1203	// Pop off any named anchors to push them back on after appending additional query args.
1204	$parts = explode('#', $url, 2);
1205	$url = $parts[0];
1206	$anchor = isset($parts[1]) ? $parts[1] : '';
1207
1208	// Include the necessary SID if the following is true:
1209	// - no cookie in http request OR cookies disabled in App
1210	// - sessions are enabled
1211	// - the link stays on our site
1212	// - transparent SID propagation with session.use_trans_sid is not being used OR url begins with protocol (using_trans_sid has no effect here)
1213	// OR
1214	// - we must include the SID because we say so (it's used in a context where cookies will not be effective, ie. moving from http to https)
1215	// AND
1216	// - the SID is not already in the query.
1217	if (
1218	(
1219	(
1220	(
1221	!isset($_COOKIE[session_name()])
1222	\|\| !$this->getParam('session_use_cookies')
1223	)
1224	&& $this->getParam('session_use_trans_sid')
1225	&& $this->getParam('enable_session')
1226	&& isMyDomain($url)
1227	&& (
1228	!ini_get('session.use_trans_sid')
1229	\|\| preg_match('!^(http\|https)://!i', $url)
1230	)
1231	)
1232	\|\| $always_include_sid
1233	)
1234	&& !preg_match('/[?&]' . preg_quote(session_name()) . '=/', $url)
1235	) {
1236	$url = sprintf('%s%s%s%s=%s%s', $url, $q, $delim, session_name(), session_id(), ('' == $anchor ? '' : "#$anchor"));
1237	} else {
1238	$url = sprintf('%s%s%s', $url, $q, ('' == $anchor ? '' : "#$anchor"));
1239	}
1240
1241	if ('' == $url) {
1242	$this->logMsg(sprintf('Generated empty URL. Args: %s', getDump(func_get_args())), LOG_NOTICE, __FILE__, __LINE__);
1243	}
1244
1245	return $url;
1246	}
1247
1248	/**
1249	* Returns a HTML-friendly URL processed with $app->url and & replaced with &
1250	*
1251	* @access public
1252	* @param (see param reference for url() method)
1253	* @return string URL passed through $app->url() with ampersands transformed to $amp;
1254	* @author Quinn Comendant <quinn@strangecode.com>
1255	* @since 09 Dec 2005 17:58:45
1256	*/
1257	public function oHREF($url='', $carry_args=null, $always_include_sid=false, $include_csrf_token=false)
1258	{
1259	// Process the URL.
1260	$url = $this->url($url, $carry_args, $always_include_sid, $include_csrf_token);
1261
1262	// Replace any & not followed by an html or unicode entity with its & equivalent.
1263	$url = preg_replace('/&(?![\w\d#]{1,10};)/u', '&', $url);
1264
1265	return $url;
1266	}
1267
1268	/*
1269	* Returns a string containing <input type="hidden" > for session, carried queries, and CSRF token.
1270	*
1271	* @access public
1272	* @param (see printHiddenSession)
1273	* @return string
1274	* @author Quinn Comendant <quinn@strangecode.com>
1275	* @since 25 May 2019 15:01:40
1276	*/
1277	public function getHiddenSession($carry_args=null, $include_csrf_token=false)
1278	{
1279	if (!$this->running) {
1280	$this->logMsg(sprintf('Canceled %s, application not running.', __METHOD__), LOG_NOTICE, __FILE__, __LINE__);
1281	return false;
1282	}
1283
1284	$out = '';
1285
1286	// Get any provided query arguments to include in the final hidden form data.
1287	// If FALSE is a provided here, DO NOT carry the queries.
1288	$do_carry_queries = true;
1289	$one_time_carry_queries = array();
1290	if (!is_null($carry_args)) {
1291	if (is_array($carry_args)) {
1292	if (!empty($carry_args)) {
1293	foreach ($carry_args as $key=>$arg) {
1294	// Get query from appropriate source.
1295	if (false === $arg) {
1296	$do_carry_queries = false;
1297	} else if (false !== getFormData($arg, false)) {
1298	$one_time_carry_queries[$arg] = getFormData($arg); // Set arg to form data if available.
1299	} else if (!is_numeric($key) && '' != $arg) {
1300	$one_time_carry_queries[$key] = getFormData($key, $arg); // Set to arg to default if specified (overwritten by form data).
1301	}
1302	}
1303	}
1304	} else if (false !== getFormData($carry_args, false)) {
1305	$one_time_carry_queries[$carry_args] = getFormData($carry_args);
1306	} else if (false === $carry_args) {
1307	$do_carry_queries = false;
1308	}
1309	}
1310
1311	// For each existing request value, we create a hidden input to carry it through a form.
1312	if ($do_carry_queries) {
1313	// Join the global _carry_queries and local one_time_carry_queries.
1314	// urlencode is not used here, not for form data!
1315	$query_args = array_merge($this->_carry_queries, $one_time_carry_queries);
1316	foreach ($query_args as $key => $val) {
1317	if (is_array($val)) {
1318	foreach ($val as $subval) {
1319	if ('' != $key && '' != $subval) {
1320	$out .= sprintf('<input type="hidden" name="%s[]" value="%s" />', $key, $subval);
1321	}
1322	}
1323	} else if ('' != $key && '' != $val) {
1324	$out .= sprintf('<input type="hidden" name="%s" value="%s" />', $key, $val);
1325	}
1326	}
1327	unset($query_args, $key, $val, $subval);
1328	}
1329
1330	// Include the SID if:
1331	// * cookies are disabled
1332	// * the system isn't automatically adding trans_sid
1333	// * the session is enabled
1334	// * and we're configured to use trans_sid
1335	if (!isset($_COOKIE[session_name()])
1336	&& !ini_get('session.use_trans_sid')
1337	&& $this->getParam('enable_session')
1338	&& $this->getParam('session_use_trans_sid')
1339	) {
1340	$out .= sprintf('<input type="hidden" name="%s" value="%s" />', session_name(), session_id());
1341	}
1342
1343	// Include the csrf_token in the form.
1344	// This token can be validated upon form submission with $app->verifyCSRFToken() or $app->requireValidCSRFToken()
1345	if ($this->getParam('csrf_token_enabled') && $include_csrf_token) {
1346	$out .= sprintf('<input type="hidden" name="%s" value="%s" />', $this->getParam('csrf_token_name'), $this->getCSRFToken());
1347	}
1348
1349	return $out;
1350	}
1351
1352	/**
1353	* Prints a hidden form element with the PHPSESSID when cookies are not used, as well
1354	* as hidden form elements for GET_VARS that might be in use.
1355	*
1356	* @param mixed $carry_args Additional url arguments to carry in the query,
1357	* or FALSE to prevent carrying queries. Can be any of the following formats:
1358	* array('key1', key2', key3') <-- to save these keys if in the form data.
1359	* array('key1'=>'value', key2'='value') <-- to set keys to default values if not present in form data.
1360	* false <-- To not carry any queries. If URL already has queries those will be retained.
1361	* @param bool $include_csrf_token Set to true to include the csrf_token in the form. Only use this for forms with action="post" to prevent the token from being revealed in the URL.
1362	*/
1363	public function printHiddenSession($carry_args=null, $include_csrf_token=false)
1364	{
1365	echo $this->getHiddenSession($carry_args, $include_csrf_token);
1366	}
1367
1368	/*
1369	* Return a URL with a version number attached. This is useful for overriding network caches ("cache buster") for sourced media, e.g., /style.css?812763482
1370	*
1371	* @access public
1372	* @param string $url URL to media (e.g., /foo.js)
1373	* @return string URL with cache-busting version appended (/foo.js?v=1234567890)
1374	* @author Quinn Comendant <quinn@strangecode.com>
1375	* @version 1.0
1376	* @since 03 Sep 2014 22:40:24
1377	*/
1378	public function cacheBustURL($url)
1379	{
1380	// Get the first delimiter that is needed in the url.
1381	$delim = mb_strpos($url, '?') !== false ? ini_get('arg_separator.output') : '?';
1382	$v = crc32($this->getParam('codebase_version') . '\|' . $this->getParam('site_version'));
1383	return sprintf('%s%sv=%s', $url, $delim, $v);
1384	}
1385
1386	/*
1387	* Generate a csrf_token if it doesn't exist or is expired, save it to the session and return its value.
1388	* Otherwise just return the current token.
1389	* Details on the synchronizer token pattern:
1390	* https://www.owasp.org/index.php/Cross-Site_Request_Forgery_(CSRF)_Prevention_Cheat_Sheet#General_Recommendation:_Synchronizer_Token_Pattern
1391	*
1392	* @access public
1393	* @return string The new or current csrf_token
1394	* @author Quinn Comendant <quinn@strangecode.com>
1395	* @version 1.0
1396	* @since 15 Nov 2014 17:57:17
1397	*/
1398	public function getCSRFToken()
1399	{
1400	if (!isset($_SESSION['_app'][$this->_ns]['csrf_token']) \|\| (removeSignature($_SESSION['_app'][$this->_ns]['csrf_token']) + $this->getParam('csrf_token_timeout') < time())) {
1401	// No token, or token is expired; generate one and return it.
1402	return $_SESSION['_app'][$this->_ns]['csrf_token'] = addSignature(time(), null, 64);
1403	}
1404	// Current token is not expired; return it.
1405	return $_SESSION['_app'][$this->_ns]['csrf_token'];
1406	}
1407
1408	/*
1409	* Compares the given csrf_token with the current or previous one saved in the session.
1410	*
1411	* @access public
1412	* @param string $user_submitted_csrf_token The user-submitted token to compare with the session token.
1413	* @param string $csrf_token The token to compare with the session token.
1414	* @return bool True if the tokens match, false otherwise.
1415	* @author Quinn Comendant <quinn@strangecode.com>
1416	* @version 1.0
1417	* @since 15 Nov 2014 18:06:55
1418	*/
1419	public function verifyCSRFToken($user_submitted_csrf_token)
1420	{
1421
1422	if (!$this->getParam('csrf_token_enabled')) {
1423	$this->logMsg(sprintf('%s called, but csrf_token_enabled=false', __METHOD__), LOG_ERR, __FILE__, __LINE__);
1424	return true;
1425	}
1426	if ('' == trim($user_submitted_csrf_token)) {
1427	$this->logMsg(sprintf('Empty string failed CSRF verification.', null), LOG_NOTICE, __FILE__, __LINE__);
1428	return false;
1429	}
1430	if (!verifySignature($user_submitted_csrf_token, null, 64)) {
1431	$this->logMsg(sprintf('Input failed CSRF verification (invalid signature in %s).', $user_submitted_csrf_token), LOG_WARNING, __FILE__, __LINE__);
1432	return false;
1433	}
1434	$csrf_token = $this->getCSRFToken();
1435	if ($user_submitted_csrf_token != $csrf_token) {
1436	$this->logMsg(sprintf('Input failed CSRF verification (%s not in %s).', $user_submitted_csrf_token, $csrf_token), LOG_WARNING, __FILE__, __LINE__);
1437	return false;
1438	}
1439	$this->logMsg(sprintf('Verified CSRF token %s', $user_submitted_csrf_token), LOG_DEBUG, __FILE__, __LINE__);
1440	return true;
1441	}
1442
1443	/*
1444	* Bounce user if they submit a token that doesn't match the one saved in the session.
1445	* Because this function calls dieURL() it must be called before any other HTTP header output.
1446	*
1447	* @access public
1448	* @param string $message Optional message to display to the user (otherwise default message will display). Set to an empty string to display no message.
1449	* @param int $type The type of message: MSG_NOTICE,
1450	* MSG_SUCCESS, MSG_WARNING, or MSG_ERR.
1451	* @param string $file __FILE__.
1452	* @param string $line __LINE__.
1453	* @return void
1454	* @author Quinn Comendant <quinn@strangecode.com>
1455	* @version 1.0
1456	* @since 15 Nov 2014 18:10:17
1457	*/
1458	public function requireValidCSRFToken($message=null, $type=MSG_NOTICE, $file=null, $line=null)
1459	{
1460	if (!$this->verifyCSRFToken(getFormData($this->getParam('csrf_token_name')))) {
1461	$message = isset($message) ? $message : _("Sorry, the form token expired. Please try again.");
1462	$this->raiseMsg($message, $type, $file, $line);
1463	$this->dieBoomerangURL();
1464	}
1465	}
1466
1467	/**
1468	* Uses an http header to redirect the client to the given $url. If sessions are not used
1469	* and the session is not already defined in the given $url, the SID is appended as a URI query.
1470	* As with all header generating functions, make sure this is called before any other output.
1471	* Using relative URI with Location: header is valid as per https://tools.ietf.org/html/rfc7231#section-7.1.2
1472	*
1473	* @param string $url The URL the client will be redirected to.
1474	* @param mixed $carry_args Additional url arguments to carry in the query,
1475	* or FALSE to prevent carrying queries. Can be any of the following formats:
1476	* -array('key1', key2', key3') <-- to save these keys if in the form data.
1477	* -array('key1' => 'value', key2' => 'value') <-- to set keys to default values if not present in form data.
1478	* -false <-- To not carry any queries. If URL already has queries those will be retained.
1479	* @param bool $always_include_sid Force session id to be added to Location header.
1480	*/
1481	public function dieURL($url, $carry_args=null, $always_include_sid=false)
1482	{
1483	if (!$this->running) {
1484	$this->logMsg(sprintf('Canceled %s, application not running.', __METHOD__), LOG_NOTICE, __FILE__, __LINE__);
1485	return false;
1486	}
1487
1488	if ('' == $url) {
1489	// If URL is not specified, use the redirect_home_url.
1490	$url = $this->getParam('redirect_home_url');
1491	}
1492
1493	$url = $this->url($url, $carry_args, $always_include_sid);
1494
1495	// Should we send a "303 See Other" header here instead of relying on the 302 sent automatically by PHP?
1496	if (!headers_sent($h_file, $h_line)) {
1497	header(sprintf('Location: %s', $url));
1498	$this->logMsg(sprintf('dieURL: %s', $url), LOG_DEBUG, __FILE__, __LINE__);
1499	} else {
1500	// Fallback: die using meta refresh instead.
1501	printf('<meta http-equiv="refresh" content="0;url=%s" />', $url);
1502	$this->logMsg(sprintf('dieURL (refresh): %s; headers already sent (output started in %s : %s)', $url, $h_file, $h_line), LOG_NOTICE, __FILE__, __LINE__);
1503	}
1504
1505	// End application.
1506	// Recommended, although I'm not sure it's necessary: https://www.php.net/session_write_close
1507	$this->stop();
1508	die;
1509	}
1510
1511	/*
1512	* Redirects a user by calling $app->dieURL(). It will use:
1513	* 1. the stored boomerang URL, it it exists
1514	* 2. a specified $default_url, it it exists
1515	* 3. the referring URL, it it exists.
1516	* 4. redirect_home_url configuration variable.
1517	*
1518	* @access public
1519	* @param string $id Identifier for this script.
1520	* @param mixed $carry_args Additional arguments to carry in the URL automatically (see $app->url()).
1521	* @param string $default_url A default URL if there is not a valid specified boomerang URL.
1522	* @param bool $queryless_referrer_comparison Exclude the URL query from the refererIsMe() comparison.
1523	* @return bool False if the session is not running. No return otherwise.
1524	* @author Quinn Comendant <quinn@strangecode.com>
1525	* @since 31 Mar 2006 19:17:00
1526	*/
1527	public function dieBoomerangURL($id=null, $carry_args=null, $default_url=null, $queryless_referrer_comparison=false)
1528	{
1529	if (!$this->running) {
1530	$this->logMsg(sprintf('Canceled %s, application not running.', __METHOD__), LOG_NOTICE, __FILE__, __LINE__);
1531	return false;
1532	}
1533
1534	// Get URL from stored boomerang. Allow non specific URL if ID not valid.
1535	if ($this->validBoomerangURL($id, true)) {
1536	if (isset($id) && isset($_SESSION['_app'][$this->_ns]['boomerang'][$id])) {
1537	$url = $_SESSION['_app'][$this->_ns]['boomerang'][$id]['url'];
1538	$this->logMsg(sprintf('dieBoomerangURL(%s) found: %s', $id, $url), LOG_DEBUG, __FILE__, __LINE__);
1539	} else {
1540	$url = end($_SESSION['_app'][$this->_ns]['boomerang'])['url'];
1541	$this->logMsg(sprintf('dieBoomerangURL(%s) using: %s', $id, $url), LOG_DEBUG, __FILE__, __LINE__);
1542	}
1543	// Delete stored boomerang.
1544	$this->deleteBoomerangURL($id);
1545	} else if (isset($default_url)) {
1546	$url = $default_url;
1547	} else if (!refererIsMe(true === $queryless_referrer_comparison) && '' != ($url = getenv('HTTP_REFERER'))) {
1548	// Ensure that the redirecting page is not also the referrer.
1549	$this->logMsg(sprintf('dieBoomerangURL(%s) using referrer: %s', $id, $url), LOG_DEBUG, __FILE__, __LINE__);
1550	} else {
1551	// If URL is not specified, use the redirect_home_url.
1552	$url = $this->getParam('redirect_home_url');
1553	$this->logMsg(sprintf('dieBoomerangURL(%s) using redirect_home_url: %s', $id, $url), LOG_DEBUG, __FILE__, __LINE__);
1554	}
1555
1556	// A redirection will never happen immediately twice. Set the time so we can ensure this doesn't happen.
1557	$_SESSION['_app'][$this->_ns]['boomerang_last_redirect_time'] = time();
1558
1559	// Do it.
1560	$this->dieURL($url, $carry_args);
1561	}
1562
1563	/**
1564	* Set the URL to return to when $app->dieBoomerangURL() is called.
1565	*
1566	* @param string $url A fully validated URL.
1567	* @param bool $id An identification tag for this url.
1568	* FIXME: url garbage collection?
1569	*/
1570	public function setBoomerangURL($url=null, $id=null)
1571	{
1572	if (!$this->running) {
1573	$this->logMsg(sprintf('Canceled %s, application not running.', __METHOD__), LOG_NOTICE, __FILE__, __LINE__);
1574	return false;
1575	}
1576
1577	if ('' != $url && is_string($url)) {
1578	// Delete any boomerang request keys in the query string (along with any trailing delimiters after the deletion).
1579	$url = preg_replace(array('/([&?])boomerang=[^&?]+[&?]?/u', '/[&?]$/'), array('$1', ''), $url);
1580
1581	if (isset($_SESSION['_app'][$this->_ns]['boomerang']) && is_array($_SESSION['_app'][$this->_ns]['boomerang']) && !empty($_SESSION['_app'][$this->_ns]['boomerang'])) {
1582	// If the ID already exists in the boomerang array, delete it.
1583	foreach (array_keys($_SESSION['_app'][$this->_ns]['boomerang']) as $existing_id) {
1584	// $existing_id could be null if existing boomerang URL was set without an ID.
1585	if ($existing_id === $id) {
1586	$this->logMsg(sprintf('Deleted existing boomerang URL matching ID: %s=>%s', $id, $url), LOG_DEBUG, __FILE__, __LINE__);
1587	unset($_SESSION['_app'][$this->_ns]['boomerang'][$existing_id]);
1588	}
1589	}
1590	}
1591
1592	// A redirection will never happen immediately after setting the boomerang URL.
1593	// Set the time so ensure this doesn't happen. See $app->validBoomerangURL for more.
1594	if (isset($id)) {
1595	$_SESSION['_app'][$this->_ns]['boomerang'][$id] = array(
1596	'url' => $url,
1597	'added_time' => time(),
1598	);
1599	} else {
1600	$_SESSION['_app'][$this->_ns]['boomerang'][] = array(
1601	'url' => $url,
1602	'added_time' => time(),
1603	);
1604	}
1605
1606	$this->logMsg(sprintf('setBoomerangURL(%s): %s', $id, $url), LOG_DEBUG, __FILE__, __LINE__);
1607	return true;
1608	} else {
1609	$this->logMsg(sprintf('setBoomerangURL(%s) is empty!', $id, $url), LOG_NOTICE, __FILE__, __LINE__);
1610	return false;
1611	}
1612	}
1613
1614	/**
1615	* Return the URL set for the specified $id, or an empty string if one isn't set.
1616	*
1617	* @param string $id An identification tag for this url.
1618	*/
1619	public function getBoomerangURL($id=null)
1620	{
1621	if (!$this->running) {
1622	$this->logMsg(sprintf('Canceled %s, application not running.', __METHOD__), LOG_NOTICE, __FILE__, __LINE__);
1623	return false;
1624	}
1625
1626	if (isset($id)) {
1627	if (isset($_SESSION['_app'][$this->_ns]['boomerang'][$id])) {
1628	return $_SESSION['_app'][$this->_ns]['boomerang'][$id]['url'];
1629	} else {
1630	return '';
1631	}
1632	} else if (isset($_SESSION['_app'][$this->_ns]['boomerang']) && is_array($_SESSION['_app'][$this->_ns]['boomerang']) && !empty($_SESSION['_app'][$this->_ns]['boomerang'])) {
1633	return end($_SESSION['_app'][$this->_ns]['boomerang'])['url'];
1634	} else {
1635	return false;
1636	}
1637	}
1638
1639	/**
1640	* Delete the URL set for the specified $id.
1641	*
1642	* @param string $id An identification tag for this url.
1643	*/
1644	public function deleteBoomerangURL($id=null)
1645	{
1646	if (!$this->running) {
1647	$this->logMsg(sprintf('Canceled %s, application not running.', __METHOD__), LOG_NOTICE, __FILE__, __LINE__);
1648	return false;
1649	}
1650
1651	if (isset($id) && isset($_SESSION['_app'][$this->_ns]['boomerang'][$id])) {
1652	$url = $this->getBoomerangURL($id);
1653	unset($_SESSION['_app'][$this->_ns]['boomerang'][$id]);
1654	} else if (is_array($_SESSION['_app'][$this->_ns]['boomerang'])) {
1655	$url = array_pop($_SESSION['_app'][$this->_ns]['boomerang'])['url'];
1656	}
1657	$this->logMsg(sprintf('deleteBoomerangURL(%s): %s', $id, $url), LOG_DEBUG, __FILE__, __LINE__);
1658	}
1659
1660	/**
1661	* Check if a valid boomerang URL value has been set. A boomerang URL is considered
1662	* valid if: 1) it is not empty, 2) it is not the current URL, and 3) has not been accessed within n seconds.
1663	*
1664	* @return bool True if it is set and valid, false otherwise.
1665	*/
1666	public function validBoomerangURL($id=null, $use_nonspecificboomerang=false)
1667	{
1668	if (!$this->running) {
1669	$this->logMsg(sprintf('Canceled %s, application not running.', __METHOD__), LOG_NOTICE, __FILE__, __LINE__);
1670	return false;
1671	}
1672
1673	if (!isset($_SESSION['_app'][$this->_ns]['boomerang']) \|\| !is_array($_SESSION['_app'][$this->_ns]['boomerang']) \|\| empty($_SESSION['_app'][$this->_ns]['boomerang'])) {
1674	$this->logMsg(sprintf('validBoomerangURL(%s) no boomerang URL set, not an array, or empty.', $id), LOG_DEBUG, __FILE__, __LINE__);
1675	return false;
1676	}
1677
1678	$url = '';
1679	if (isset($id) && isset($_SESSION['_app'][$this->_ns]['boomerang'][$id])) {
1680	$url = $_SESSION['_app'][$this->_ns]['boomerang'][$id]['url'];
1681	$added_time = $_SESSION['_app'][$this->_ns]['boomerang'][$id]['added_time'];
1682	} else if (!isset($id) \|\| $use_nonspecificboomerang) {
1683	// Use most recent, non-specific boomerang if available.
1684	$url = end($_SESSION['_app'][$this->_ns]['boomerang'])['url'];
1685	$added_time = end($_SESSION['_app'][$this->_ns]['boomerang'])['added_time'];
1686	}
1687
1688	if ('' == trim($url)) {
1689	$this->logMsg(sprintf('validBoomerangURL(%s) not valid, empty!', $id), LOG_DEBUG, __FILE__, __LINE__);
1690	return false;
1691	}
1692
1693	if ($url == absoluteMe() \|\| $url == getenv('REQUEST_URI')) {
1694	// The URL we are directing to is the current page.
1695	$this->logMsg(sprintf('validBoomerangURL(%s) not valid, same as absoluteMe or REQUEST_URI: %s', $id, $url), LOG_DEBUG, __FILE__, __LINE__);
1696	return false;
1697	}
1698
1699	// Last redirect time is the time stamp of the last boomerangURL redirection, if any. A boomerang redirection should always occur at least several seconds after the last boomerang redirect (time it takes to load a page and receive user interaction).
1700	$boomerang_last_redirect_time = isset($_SESSION['_app'][$this->_ns]['boomerang_last_redirect_time']) ? $_SESSION['_app'][$this->_ns]['boomerang_last_redirect_time'] : null;
1701	if (isset($boomerang_last_redirect_time) && $boomerang_last_redirect_time >= (time() - 2)) {
1702	// Last boomerang direction was less than 2 seconds ago.
1703	$this->logMsg(sprintf('validBoomerangURL(%s) not valid, boomerang_last_redirect_time too short: %s seconds', $id, time() - $boomerang_last_redirect_time), LOG_DEBUG, __FILE__, __LINE__);
1704	return false;
1705	}
1706
1707	if (isset($added_time) && $added_time < (time() - 72000)) {
1708	// Last boomerang direction was more than 20 hours ago.
1709	$this->logMsg(sprintf('validBoomerangURL(%s) not valid, added_time too old: %s seconds', $id, time() - $added_time), LOG_DEBUG, __FILE__, __LINE__);
1710	// Delete this defunct boomerang.
1711	$this->deleteBoomerangURL($id);
1712	return false;
1713	}
1714
1715	$this->logMsg(sprintf('validBoomerangURL(%s) is valid: %s', $id, $url), LOG_DEBUG, __FILE__, __LINE__);
1716	return true;
1717	}
1718
1719	/**
1720	* This function has changed to do nothing. SSL redirection should happen at the server layer, doing so here may result in a redirect loop.
1721	*/
1722	public function sslOn()
1723	{
1724	$app =& App::getInstance();
1725	$app->logMsg(sprintf('sslOn was called and ignored.', null), LOG_DEBUG, __FILE__, __LINE__);
1726	}
1727
1728	/**
1729	* This function has changed to do nothing. There is no reason to prefer a non-SSL connection, and doing so may result in a redirect loop.
1730	*/
1731	public function sslOff()
1732	{
1733	$app =& App::getInstance();
1734	$app->logMsg(sprintf('sslOff was called and ignored.', null), LOG_DEBUG, __FILE__, __LINE__);
1735	}
1736
1737	/*
1738	* Sets a cookie, with error checking and some sane defaults.
1739	*
1740	* @access public
1741	* @param string $name The name of the cookie.
1742	* @param string $value The value of the cookie.
1743	* @param string $expire The time the cookie expires, as a unix timestamp or string value passed to strtotime.
1744	* @param string $path The path on the server in which the cookie will be available on.
1745	* @param string $domain The domain that the cookie is available to.
1746	* @param bool $secure Indicates that the cookie should only be transmitted over a secure HTTPS connection from the client.
1747	* @param bool $httponly When TRUE the cookie will be made accessible only through the HTTP protocol (makes cookies unreadable to javascript).
1748	* @param string $samesite Value of the SameSite key ('None', 'Lax', or 'Strict'). PHP 7.3+ only.
1749	* @return bool True on success, false on error.
1750	* @author Quinn Comendant <quinn@strangecode.com>
1751	* @version 1.0
1752	* @since 02 May 2014 16:36:34
1753	*/
1754	public function setCookie($name, $value, $expire='+10 years', $path='/', $domain=null, $secure=null, $httponly=null, $samesite=null)
1755	{
1756	if (!is_scalar($name)) {
1757	$this->logMsg(sprintf('Cookie name must be scalar, is not: %s', getDump($name)), LOG_NOTICE, __FILE__, __LINE__);
1758	return false;
1759	}
1760	if (!is_scalar($value)) {
1761	$this->logMsg(sprintf('Cookie "%s" value must be scalar, is not: %s', $name, getDump($value)), LOG_NOTICE, __FILE__, __LINE__);
1762	return false;
1763	}
1764
1765	// Defaults.
1766	$expire = (is_numeric($expire) ? $expire : (is_string($expire) ? strtotime($expire) : $expire));
1767	$secure = $secure ?: getenv('HTTPS') == 'on';
1768	$httponly = $httponly ?: true;
1769	$samesite = $samesite ?: 'Lax';
1770
1771	// Make sure the expiration date is a valid 32bit integer.
1772	if (is_int($expire) && $expire > 2147483647) {
1773	$this->logMsg(sprintf('Cookie "%s" expire time exceeds a 32bit integer (%s)', $key, date('r', $expire)), LOG_NOTICE, __FILE__, __LINE__);
1774	}
1775
1776	// Measure total cookie length and warn if larger than max recommended size of 4093.
1777	// https://stackoverflow.com/questions/640938/what-is-the-maximum-size-of-a-web-browsers-cookies-key
1778	// The date and header name adds 51 bytes: Set-Cookie: ; expires=Fri, 03-May-2024 00:04:47 GMT
1779	$cookielen = strlen($name . $value . $path . $domain . ($secure ? '; secure' : '') . ($httponly ? '; httponly' : '') . ($samesite ? '; SameSite=' . $samesite : '')) + 51;
1780	if ($cookielen > 4093) {
1781	$this->logMsg(sprintf('Cookie "%s" has a size greater than 4093 bytes (is %s bytes)', $key, $cookielen), LOG_NOTICE, __FILE__, __LINE__);
1782	}
1783
1784	// Ensure PHP version allow use of httponly.
1785	if (version_compare(PHP_VERSION, '7.3.0', '>=')) {
1786	$ret = setcookie($name, $value, [
1787	'expires' => $expire,
1788	'path' => $path,
1789	'domain' => $domain,
1790	'secure' => $secure,
1791	'httponly' => $httponly,
1792	'samesite' => $samesite,
1793	]);
1794	} else if (version_compare(PHP_VERSION, '5.2.0', '>=')) {
1795	$ret = setcookie($name, $value, $expire, $path, $domain, $secure, $httponly);
1796	} else {
1797	$ret = setcookie($name, $value, $expire, $path, $domain, $secure);
1798	}
1799
1800	if (false === $ret) {
1801	$this->logMsg(sprintf('Failed to set cookie (%s=%s) probably due to output before headers.', $name, $value), LOG_NOTICE, __FILE__, __LINE__);
1802	}
1803	return $ret;
1804	}
1805
1806	/*
1807	* Set timezone used internally by PHP. See full list at https://www.php.net/manual/en/timezones.php
1808	*
1809	* @access public
1810	* @param string $tz Timezone, e.g., America/Mexico_City
1811	* @return
1812	* @author Quinn Comendant <quinn@strangecode.com>
1813	* @since 28 Jan 2019 16:38:38
1814	*/
1815	public function setTimezone($tz)
1816	{
1817	// Set timezone for PHP.
1818	if (date_default_timezone_set($tz)) {
1819	$this->logMsg(sprintf('Using php timezone: %s', $tz), LOG_DEBUG, __FILE__, __LINE__);
1820	} else {
1821	// Failed!
1822	$this->logMsg(sprintf('Failed to set php timezone: %s', $tz), LOG_WARNING, __FILE__, __LINE__);
1823	}
1824	}
1825
1826	/*
1827	*
1828	*
1829	* @access public
1830	* @param
1831	* @return
1832	* @author Quinn Comendant <quinn@strangecode.com>
1833	* @since 17 Feb 2019 13:11:20
1834	*/
1835	public function colorCLI($color)
1836	{
1837	switch ($color) {
1838	case 'white':
1839	echo "\033[0;37m";
1840	break;
1841	case 'black':
1842	echo "\033[0;30m";
1843	break;
1844	case 'red':
1845	echo "\033[0;31m";
1846	break;
1847	case 'yellow':
1848	echo "\033[0;33m";
1849	break;
1850	case 'green':
1851	echo "\033[0;32m";
1852	break;
1853	case 'cyan':
1854	echo "\033[0;36m";
1855	break;
1856	case 'blue':
1857	echo "\033[0;34m";
1858	break;
1859	case 'purple':
1860	echo "\033[0;35m";
1861	break;
1862	case 'off':
1863	default:
1864	echo "\033[0m";
1865	break;
1866	}
1867	}
1868	} // End.

Note: See TracBrowser for help on using the repository browser.

Download in other formats: