Context Navigation

source: trunk/lib/Utilities.inc.php @ 518

Last change on this file since 518 was 518, checked in by anonymous, 9 years ago
Non-breaking function changes to App and Utilities.
File size: 44.7 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	* Utilities.inc.php
25	*/
26
27
28	/**
29	* Print variable dump.
30	*
31	* @param mixed $var The variable to dump.
32	* @param bool $display Print the dump in <pre> tags or hide it in html comments (non-CLI only).
33	* @param bool $var_dump Use var_dump instead of print_r.
34	* @param string $file Value of __FILE__.
35	* @param string $line Value of __LINE__
36	*/
37	function dump($var, $display=false, $var_dump=false, $file='', $line='')
38	{
39	if (defined('_CLI')) {
40	echo "DUMP FROM: $file $line\n";
41	} else {
42	echo $display ? "\n<br />DUMP <strong>$file $line</strong><br /><pre>\n" : "\n<!-- DUMP $file $line\n";
43	}
44	if ($var_dump) {
45	var_dump($var);
46	} else {
47	// Print human-readable descriptions of invisible types.
48	if (null === $var) {
49	echo '(null)';
50	} else if (true === $var) {
51	echo '(bool: true)';
52	} else if (false === $var) {
53	echo '(bool: false)';
54	} else if (is_scalar($var) && '' === $var) {
55	echo '(empty string)';
56	} else if (is_scalar($var) && preg_match('/^\s+$/', $var)) {
57	echo '(only white space)';
58	} else {
59	print_r($var);
60	}
61	}
62	if (defined('_CLI')) {
63	echo "\n";
64	} else {
65	echo $display ? "\n</pre><br />\n" : "\n-->\n";
66	}
67	}
68
69	/*
70	* Log a PHP variable to javascript console. Relies on getDump(), below.
71	*
72	* @access public
73	* @param mixed $var The variable to dump.
74	* @param string $prefix A short note to print before the output to make identifying output easier.
75	* @param string $file The value of __FILE__.
76	* @param string $line The value of __LINE__.
77	* @return null
78	* @author Quinn Comendant <quinn@strangecode.com>
79	*/
80	function jsDump($var, $prefix='jsDump', $file='-', $line='-')
81	{
82	if (!empty($var)) {
83	?>
84	<script type="text/javascript">
85	/* <![CDATA[ */
86	console.log('<?php printf('%s: %s (on line %s of %s)', $prefix, str_replace("'", "\\'", getDump($var, true)), $line, $file); ?>');
87	/* ]]> */
88	</script>
89	<?php
90	}
91	}
92
93	/*
94	* Return a string version of any variable, optionally serialized on one line.
95	*
96	* @access public
97	* @param mixed $var The variable to dump.
98	* @param bool $serialize If true, remove line-endings. Useful for logging variables.
99	* @return string The dumped variable.
100	* @author Quinn Comendant <quinn@strangecode.com>
101	*/
102	function getDump($var, $serialize=false)
103	{
104	ob_start();
105	print_r($var);
106	$d = ob_get_contents();
107	ob_end_clean();
108	return $serialize ? preg_replace('/\s+/m', ' ', $d) : $d;
109	}
110
111	/**
112	* Return dump as cleaned text. Useful for dumping data into emails.
113	*
114	* @param array $var Variable to dump.
115	* @param strong $indent A string to prepend indented lines (tab for example).
116	* @return string Dump of var.
117	*/
118	function fancyDump($var, $indent='')
119	{
120	$output = '';
121	if (is_array($var)) {
122	foreach ($var as $k=>$v) {
123	$k = ucfirst(mb_strtolower(str_replace(array('_', ' '), ' ', $k)));
124	if (is_array($v)) {
125	$output .= sprintf("\n%s%s: %s\n", $indent, $k, fancyDump($v, $indent . $indent));
126	} else {
127	$output .= sprintf("%s%s: %s\n", $indent, $k, $v);
128	}
129	}
130	} else {
131	$output .= sprintf("%s%s\n", $indent, $var);
132	}
133	return $output;
134	}
135
136	/**
137	* Returns text with appropriate html translations (a smart wrapper for htmlspecialchars()).
138	*
139	* @param string $text Text to clean.
140	* @param bool $preserve_html If set to true, oTxt will not translate <, >, ", or '
141	* characters into HTML entities. This allows HTML to pass through undisturbed.
142	* @return string HTML-safe text.
143	*/
144	function oTxt($text, $preserve_html=false)
145	{
146	$app =& App::getInstance();
147
148	$search = array();
149	$replace = array();
150
151	// Make converted ampersand entities into normal ampersands (they will be done manually later) to retain HTML entities.
152	$search['retain_ampersand'] = '/&/';
153	$replace['retain_ampersand'] = '&';
154
155	if ($preserve_html) {
156	// Convert characters that must remain non-entities for displaying HTML.
157	$search['retain_left_angle'] = '/</';
158	$replace['retain_left_angle'] = '<';
159
160	$search['retain_right_angle'] = '/>/';
161	$replace['retain_right_angle'] = '>';
162
163	$search['retain_single_quote'] = '/'/';
164	$replace['retain_single_quote'] = "'";
165
166	$search['retain_double_quote'] = '/"/';
167	$replace['retain_double_quote'] = '"';
168	}
169
170	// & becomes &. Exclude any occurrence where the & is followed by a alphanum or unicode character.
171	$search['ampersand'] = '/&(?![\w\d#]{1,10};)/';
172	$replace['ampersand'] = '&';
173
174	return preg_replace($search, $replace, htmlspecialchars($text, ENT_QUOTES, $app->getParam('character_set')));
175	}
176
177	/**
178	* Returns text with stylistic modifications. Warning: this will break some HTML attributes!
179	* TODO: Allow a string such as this to be passed: <a href="javascript:openPopup('/foo/bar.php')">Click here</a>
180	*
181	* @param string $text Text to clean.
182	* @return string Cleaned text.
183	*/
184	function fancyTxt($text)
185	{
186	$search = array();
187	$replace = array();
188
189	// "double quoted text" becomes “double quoted text”
190	$search['double_quotes'] = '/(^\|[^\w=])(?:"\|"\|"\|"\|“)([^"]+?)(?:"\|"\|"\|"\|”)([^\w]\|$)/ms'; // " is the same as " and " and "
191	$replace['double_quotes'] = '$1“$2”$3';
192
193	// text's apostrophes become text’s apostrophes
194	$search['apostrophe'] = '/(\w)(?:\'\|'\|')(\w)/ms';
195	$replace['apostrophe'] = '$1’$2';
196
197	// 'single quoted text' becomes ‘single quoted text’
198	$search['single_quotes'] = '/(^\|[^\w=])(?:\'\|'\|‘)([^\']+?)(?:\'\|'\|’)([^\w]\|$)/ms';
199	$replace['single_quotes'] = '$1‘$2’$3';
200
201	// plural posessives' apostrophes become posessives’
202	$search['apostrophes'] = '/(s)(?:\'\|'\|')(\s)/ms';
203	$replace['apostrophes'] = '$1’$2';
204
205	// em--dashes become em—dashes
206	$search['em_dash'] = '/(\s[^!<-])--([^>-]\s)/';
207	$replace['em_dash'] = '$1—$2';
208
209	return preg_replace($search, $replace, $text);
210	}
211
212	/*
213	* Finds all URLs in text and hyperlinks them.
214	*
215	* @access public
216	* @param string $text Text to search for URLs.
217	* @param mixed $length Number of characters to truncate URL, or NULL to disable truncating.
218	* @param string $delim Delimiter to append, indicate truncation.
219	* @return string Same input text, but URLs hyperlinked.
220	* @author Quinn Comendant <quinn@strangecode.com>
221	* @version 1.0
222	* @since 22 Mar 2015 23:29:04
223	*/
224	function hyperlinkTxt($text, $length=null, $delim='âŠ')
225	{
226	return preg_replace_callback(
227	// Inspired by @stephenhay's regex from https://mathiasbynens.be/demo/url-regex
228	// Here we capture the full URL into the first match and only the first X characters into the second match.
229	sprintf('@\b(?<!")(?<!\')(?<!=)(((?:https?\|s?ftps?)://[^\s/$.?#].[^\s]{0,%s})[^\s]*)@iS', $length),
230	// Use an anonymous function to decide when to append the delim.
231	// Also encode special chars with oTxt().
232	function ($m) use ($length, $delim) {
233	if (is_null($length) \|\| $m[1] == $m[2]) {
234	// If not truncating, or URL was not truncated.
235	return sprintf('<a href="%s">%s</a>', oTxt($m[1]), oTxt($m[1]));
236	} else {
237	// Truncated URL.
238	return sprintf('<a href="%s">%s%s</a>', oTxt($m[1]), oTxt(trim($m[2])), $delim);
239	}
240	},
241	$text
242	);
243	}
244
245	/**
246	* Applies a class to search terms to highlight them ala google results.
247	*
248	* @param string $text Input text to search.
249	* @param string $search String of word(s) that will be highlighted.
250	* @param string $class CSS class to apply.
251	* @return string Text with searched words wrapped in <span>.
252	*/
253	function highlightWords($text, $search, $class='sc-highlightwords')
254	{
255	$words = preg_split('/[^\w]/', $search, -1, PREG_SPLIT_NO_EMPTY);
256
257	$search = array();
258	$replace = array();
259
260	foreach ($words as $w) {
261	if ('' != trim($w)) {
262	$search[] = '/\b(' . preg_quote($w) . ')\b/i';
263	$replace[] = '<span class="' . $class . '">$1</span>';
264	}
265	}
266
267	return empty($replace) ? $text : preg_replace($search, $replace, $text);
268	}
269
270	/**
271	* Generates a hexadecimal html color based on provided word.
272	*
273	* @access public
274	* @param string $text A string for which to convert to color.
275	* @return string A hexadecimal html color.
276	*/
277	function getTextColor($text, $method=1)
278	{
279	$hash = md5($text);
280	$rgb = array(
281	mb_substr($hash, 0, 1),
282	mb_substr($hash, 1, 1),
283	mb_substr($hash, 2, 1),
284	mb_substr($hash, 3, 1),
285	mb_substr($hash, 4, 1),
286	mb_substr($hash, 5, 1),
287	);
288
289	switch ($method) {
290	case 1 :
291	default :
292	// Reduce all hex values slightly to avoid all white.
293	array_walk($rgb, create_function('&$v', '$v = dechex(round(hexdec($v) * 0.87));'));
294	break;
295	case 2 :
296	foreach ($rgb as $i => $v) {
297	if (hexdec($v) > hexdec('c')) {
298	$rgb[$i] = dechex(hexdec('f') - hexdec($v));
299	}
300	}
301	break;
302	}
303
304	return join('', $rgb);
305	}
306
307	/**
308	* Encodes a string into unicode values 128-255.
309	* Useful for hiding an email address from spambots.
310	*
311	* @access public
312	* @param string $text A line of text to encode.
313	* @return string Encoded text.
314	*/
315	function encodeAscii($text)
316	{
317	$output = '';
318	$num = mb_strlen($text);
319	for ($i=0; $i<$num; $i++) {
320	$output .= sprintf('&#%03s', ord($text{$i}));
321	}
322	return $output;
323	}
324
325	/**
326	* Encodes an email into a "user at domain dot com" format.
327	*
328	* @access public
329	* @param string $email An email to encode.
330	* @param string $at Replaces the @.
331	* @param string $dot Replaces the ..
332	* @return string Encoded email.
333	*/
334	function encodeEmail($email, $at=' at ', $dot=' dot ')
335	{
336	$search = array('/@/', '/\./');
337	$replace = array($at, $dot);
338	return preg_replace($search, $replace, $email);
339	}
340
341	/**
342	* Truncates "a really long string" into a string of specified length
343	* at the beginning: "âŠlong string"
344	* at the middle: "a reaâŠstring"
345	* or at the end: "a reallyâŠ".
346	*
347	* The regular expressions below first match and replace the string to the specified length and position,
348	* and secondly they remove any whitespace from around the delimiter (to avoid "this âŠ " from happening).
349	*
350	* @access public
351	* @param string $str Input string
352	* @param int $len Maximum string length.
353	* @param string $where Where to cut the string. One of: 'start', 'middle', or 'end'.
354	* @return string Truncated output string.
355	* @author Quinn Comendant <quinn@strangecode.com>
356	* @since 29 Mar 2006 13:48:49
357	*/
358	function truncate($str, $len=50, $where='end', $delim='âŠ')
359	{
360	$dlen = mb_strlen($delim);
361	if ($len <= $dlen \|\| mb_strlen($str) <= $dlen) {
362	return substr($str, 0, $len);
363	}
364	$part1 = floor(($len - $dlen) / 2);
365	$part2 = ceil(($len - $dlen) / 2);
366	switch ($where) {
367	case 'start' :
368	return preg_replace(array(sprintf('/^.{%s,}(.{%s})$/sU', $dlen + 1, $part1 + $part2), sprintf('/\s%s{%s,}\s/sU', preg_quote($delim), $dlen)), array($delim . '$1', $delim), $str);
369
370	case 'middle' :
371	return preg_replace(array(sprintf('/^(.{%s}).{%s,}(.{%s})$/sU', $part1, $dlen + 1, $part2), sprintf('/\s%s{%s,}\s/sU', preg_quote($delim), $dlen)), array('$1' . $delim . '$2', $delim), $str);
372
373	case 'end' :
374	default :
375	return preg_replace(array(sprintf('/^(.{%s}).{%s,}$/sU', $part1 + $part2, $dlen + 1), sprintf('/\s%s{%s,}\s/sU', preg_quote($delim), $dlen)), array('$1' . $delim, $delim), $str);
376	}
377	}
378
379	/*
380	* A substitution for the missing mb_ucfirst function.
381	*
382	* @access public
383	* @param string $string The string
384	* @return string String with upper-cased first character.
385	* @author Quinn Comendant <quinn@strangecode.com>
386	* @version 1.0
387	* @since 06 Dec 2008 17:04:01
388	*/
389	if (!function_exists('mb_ucfirst')) {
390	function mb_ucfirst($string)
391	{
392	return mb_strtoupper(mb_substr($string, 0, 1)) . mb_substr($string, 1, mb_strlen($string));
393	}
394	}
395
396	/*
397	* A substitution for the missing mb_strtr function.
398	*
399	* @access public
400	* @param string $string The string
401	* @param string $from String of characters to translate from
402	* @param string $to String of characters to translate to
403	* @return string String with translated characters.
404	* @author Quinn Comendant <quinn@strangecode.com>
405	* @version 1.0
406	* @since 20 Jan 2013 12:33:26
407	*/
408	if (!function_exists('mb_strtr')) {
409	function mb_strtr($string, $from, $to)
410	{
411	return str_replace(mb_split('.', $from), mb_split('.', $to), $string);
412	}
413	}
414
415	/*
416	* A substitution for the missing mb_str_pad function.
417	*
418	* @access public
419	* @param string $input The string that receives padding.
420	* @param string $pad_length Total length of resultant string.
421	* @param string $pad_string The string to use for padding
422	* @param string $pad_type Flags STR_PAD_RIGHT or STR_PAD_LEFT or STR_PAD_BOTH
423	* @return string String with translated characters.
424	* @author Quinn Comendant <quinn@strangecode.com>
425	* @version 1.0
426	* @since 20 Jan 2013 12:33:26
427	*/
428	if (!function_exists('mb_str_pad')) {
429	function mb_str_pad($input, $pad_length, $pad_string=' ', $pad_type=STR_PAD_RIGHT) {
430	$diff = strlen($input) - mb_strlen($input);
431	return str_pad($input, $pad_length + $diff, $pad_string, $pad_type);
432	}
433	}
434
435	/*
436	* Converts a string into a URL-safe slug, removing spaces and non word characters.
437	*
438	* @access public
439	* @param string $str String to convert.
440	* @return string URL-safe slug.
441	* @author Quinn Comendant <quinn@strangecode.com>
442	* @version 1.0
443	* @since 18 Aug 2014 12:54:29
444	*/
445	function URLSlug($str)
446	{
447	$slug = preg_replace(array('/[^\w]+/', '/^-+\|-+$/'), array('-', ''), $str);
448	$slug = strtolower($slug);
449	return $slug;
450	}
451
452	/**
453	* Return a human readable disk space measurement. Input value measured in bytes.
454	*
455	* @param int $size Size in bytes.
456	* @param int $unit The maximum unit
457	* @param int $format The return string format
458	* @author Aidan Lister <aidan@php.net>
459	* @author Quinn Comendant <quinn@strangecode.com>
460	* @version 1.2.0
461	*/
462	function humanFileSize($size, $format='%01.2f %s', $max_unit=null, $multiplier=1024)
463	{
464	// Units
465	$units = array('B', 'KB', 'MB', 'GB', 'TB');
466	$ii = count($units) - 1;
467
468	// Max unit
469	$max_unit = array_search((string) $max_unit, $units);
470	if ($max_unit === null \|\| $max_unit === false) {
471	$max_unit = $ii;
472	}
473
474	// Loop
475	$i = 0;
476	while ($max_unit != $i && $size >= $multiplier && $i < $ii) {
477	$size /= $multiplier;
478	$i++;
479	}
480
481	return sprintf($format, $size, $units[$i]);
482	}
483
484	/*
485	* Returns a human readable amount of time for the given amount of seconds.
486	*
487	* 45 seconds
488	* 12 minutes
489	* 3.5 hours
490	* 2 days
491	* 1 week
492	* 4 months
493	*
494	* Months are calculated using the real number of days in a year: 365.2422 / 12.
495	*
496	* @access public
497	* @param int $seconds Seconds of time.
498	* @param string $max_unit Key value from the $units array.
499	* @param string $format Sprintf formatting string.
500	* @return string Value of units elapsed.
501	* @author Quinn Comendant <quinn@strangecode.com>
502	* @version 1.0
503	* @since 23 Jun 2006 12:15:19
504	*/
505	function humanTime($seconds, $max_unit=null, $format='%01.1f')
506	{
507	// Units: array of seconds in the unit, singular and plural unit names.
508	$units = array(
509	'second' => array(1, _("second"), _("seconds")),
510	'minute' => array(60, _("minute"), _("minutes")),
511	'hour' => array(3600, _("hour"), _("hours")),
512	'day' => array(86400, _("day"), _("days")),
513	'week' => array(604800, _("week"), _("weeks")),
514	'month' => array(2629743.84, _("month"), _("months")),
515	'year' => array(31556926.08, _("year"), _("years")),
516	'decade' => array(315569260.8, _("decade"), _("decades")),
517	'century' => array(3155692608, _("century"), _("centuries")),
518	);
519
520	// Max unit to calculate.
521	$max_unit = isset($units[$max_unit]) ? $max_unit : 'year';
522
523	$final_time = $seconds;
524	$final_unit = 'second';
525	foreach ($units as $k => $v) {
526	if ($seconds >= $v[0]) {
527	$final_time = $seconds / $v[0];
528	$final_unit = $k;
529	}
530	if ($max_unit == $final_unit) {
531	break;
532	}
533	}
534	$final_time = sprintf($format, $final_time);
535	return sprintf('%s %s', $final_time, (1 == $final_time ? $units[$final_unit][1] : $units[$final_unit][2]));
536	}
537
538	/**
539	* Removes non-latin characters from file name, using htmlentities to convert known weirdos into regular squares.
540	*
541	* @access public
542	* @param string $file_name A name of a file.
543	* @return string The same name, but cleaned.
544	*/
545	function cleanFileName($file_name)
546	{
547	$app =& App::getInstance();
548
549	$file_name = preg_replace(array(
550	'/&([a-z]{1,2})(?:acute\|cedil\|circ\|grave\|lig\|orn\|ring\|slash\|th\|tilde\|uml\|caron);/ui',
551	'/&(?:amp);/ui',
552	'/[&;]+/u',
553	'/[^a-zA-Z0-9()@._=+-]+/u',
554	'/^_+\|_+$/u'
555	), array(
556	'$1',
557	'and',
558	'',
559	'_',
560	''
561	), htmlentities($file_name, ENT_NOQUOTES \| ENT_IGNORE, $app->getParam('character_set')));
562	return mb_substr($file_name, 0, 250);
563	}
564
565	/*
566	* Convert a php.ini value (8M, 512K, etc), into integer value of bytes.
567	*
568	* @access public
569	* @param string $val Value from php config, e.g., upload_max_filesize.
570	* @return int Value converted to bytes as an integer.
571	* @author Quinn Comendant <quinn@strangecode.com>
572	* @version 1.0
573	* @since 20 Aug 2014 14:32:41
574	*/
575	function phpIniGetBytes($val)
576	{
577	$val = trim(ini_get($val));
578	if ($val != '') {
579	$last = strtolower($val{strlen($val) - 1});
580	} else {
581	$last = '';
582	}
583	switch ($last) {
584	// The 'G' modifier is available since PHP 5.1.0
585	case 'g':
586	$val *= 1024;
587	case 'm':
588	$val *= 1024;
589	case 'k':
590	$val *= 1024;
591	}
592
593	return (int)$val;
594	}
595
596	/**
597	* Tests the existence of a file anywhere in the include path.
598	*
599	* @param string $file File in include path.
600	* @return mixed False if file not found, the path of the file if it is found.
601	* @author Quinn Comendant <quinn@strangecode.com>
602	* @since 03 Dec 2005 14:23:26
603	*/
604	function fileExistsIncludePath($file)
605	{
606	$app =& App::getInstance();
607
608	foreach (explode(PATH_SEPARATOR, get_include_path()) as $path) {
609	$fullpath = $path . DIRECTORY_SEPARATOR . $file;
610	if (file_exists($fullpath)) {
611	$app->logMsg(sprintf('Found file "%s" at path: %s', $file, $fullpath), LOG_DEBUG, __FILE__, __LINE__);
612	return $fullpath;
613	} else {
614	$app->logMsg(sprintf('File "%s" not found in include_path: %s', $file, get_include_path()), LOG_DEBUG, __FILE__, __LINE__);
615	return false;
616	}
617	}
618	}
619
620	/**
621	* Returns stats of a file from the include path.
622	*
623	* @param string $file File in include path.
624	* @param mixed $stat Which statistic to return (or null to return all).
625	* @return mixed Value of requested key from fstat(), or false on error.
626	* @author Quinn Comendant <quinn@strangecode.com>
627	* @since 03 Dec 2005 14:23:26
628	*/
629	function statIncludePath($file, $stat=null)
630	{
631	// Open file pointer read-only using include path.
632	if ($fp = fopen($file, 'r', true)) {
633	// File opened successfully, get stats.
634	$stats = fstat($fp);
635	fclose($fp);
636	// Return specified stats.
637	return is_null($stat) ? $stats : $stats[$stat];
638	} else {
639	return false;
640	}
641	}
642
643	/*
644	* Writes content to the specified file. This function emulates the functionality of file_put_contents from PHP 5.
645	* It makes an exclusive lock on the file while writing.
646	*
647	* @access public
648	* @param string $filename Path to file.
649	* @param string $content Data to write into file.
650	* @return bool Success or failure.
651	* @author Quinn Comendant <quinn@strangecode.com>
652	* @since 11 Apr 2006 22:48:30
653	*/
654	function filePutContents($filename, $content)
655	{
656	$app =& App::getInstance();
657
658	// Open file for writing and truncate to zero length.
659	if ($fp = fopen($filename, 'w')) {
660	if (flock($fp, LOCK_EX)) {
661	if (!fwrite($fp, $content, mb_strlen($content))) {
662	$app->logMsg(sprintf('Failed writing to file: %s', $filename), LOG_ERR, __FILE__, __LINE__);
663	fclose($fp);
664	return false;
665	}
666	flock($fp, LOCK_UN);
667	} else {
668	$app->logMsg(sprintf('Could not lock file for writing: %s', $filename), LOG_ERR, __FILE__, __LINE__);
669	fclose($fp);
670	return false;
671	}
672	fclose($fp);
673	// Success!
674	$app->logMsg(sprintf('Wrote to file: %s', $filename), LOG_DEBUG, __FILE__, __LINE__);
675	return true;
676	} else {
677	$app->logMsg(sprintf('Could not open file for writing: %s', $filename), LOG_ERR, __FILE__, __LINE__);
678	return false;
679	}
680	}
681
682	/**
683	* If $var is net set or null, set it to $default. Otherwise leave it alone.
684	* Returns the final value of $var. Use to find a default value of one is not available.
685	*
686	* @param mixed $var The variable that is being set.
687	* @param mixed $default What to set it to if $val is not currently set.
688	* @return mixed The resulting value of $var.
689	*/
690	function setDefault(&$var, $default='')
691	{
692	if (!isset($var)) {
693	$var = $default;
694	}
695	return $var;
696	}
697
698	/**
699	* Like preg_quote() except for arrays, it takes an array of strings and puts
700	* a backslash in front of every character that is part of the regular
701	* expression syntax.
702	*
703	* @param array $array input array
704	* @param array $delim optional character that will also be escaped.
705	* @return array an array with the same values as $array1 but shuffled
706	*/
707	function pregQuoteArray($array, $delim='/')
708	{
709	if (!empty($array)) {
710	if (is_array($array)) {
711	foreach ($array as $key=>$val) {
712	$quoted_array[$key] = preg_quote($val, $delim);
713	}
714	return $quoted_array;
715	} else {
716	return preg_quote($array, $delim);
717	}
718	}
719	}
720
721	/**
722	* Converts a PHP Array into encoded URL arguments and return them as an array.
723	*
724	* @param mixed $data An array to transverse recursively, or a string
725	* to use directly to create url arguments.
726	* @param string $prefix The name of the first dimension of the array.
727	* If not specified, the first keys of the array will be used.
728	* @return array URL with array elements as URL key=value arguments.
729	*/
730	function urlEncodeArray($data, $prefix='', $_return=true)
731	{
732	// Data is stored in static variable.
733	static $args;
734
735	if (is_array($data)) {
736	foreach ($data as $key => $val) {
737	// If the prefix is empty, use the $key as the name of the first dimension of the "array".
738	// ...otherwise, append the key as a new dimension of the "array".
739	$new_prefix = ('' == $prefix) ? urlencode($key) : $prefix . '[' . urlencode($key) . ']';
740	// Enter recursion.
741	urlEncodeArray($val, $new_prefix, false);
742	}
743	} else {
744	// We've come to the last dimension of the array, save the "array" and its value.
745	$args[$prefix] = urlencode($data);
746	}
747
748	if ($_return) {
749	// This is not a recursive execution. All recursion is complete.
750	// Reset static var and return the result.
751	$ret = $args;
752	$args = array();
753	return is_array($ret) ? $ret : array();
754	}
755	}
756
757	/**
758	* Converts a PHP Array into encoded URL arguments and return them in a string.
759	*
760	* @param mixed $data An array to transverse recursively, or a string
761	* to use directly to create url arguments.
762	* @param string $prefix The name of the first dimension of the array.
763	* If not specified, the first keys of the array will be used.
764	* @return string url A string ready to append to a url.
765	*/
766	function urlEncodeArrayToString($data, $prefix='')
767	{
768
769	$array_args = urlEncodeArray($data, $prefix);
770	$url_args = '';
771	$delim = '';
772	foreach ($array_args as $key=>$val) {
773	$url_args .= $delim . $key . '=' . $val;
774	$delim = ini_get('arg_separator.output');
775	}
776	return $url_args;
777	}
778
779	/**
780	* Fills an array with the result from a multiple ereg search.
781	* Courtesy of Bruno - rbronosky@mac.com - 10-May-2001
782	*
783	* @param mixed $pattern regular expression needle
784	* @param mixed $string haystack
785	* @return array populated with each found result
786	*/
787	function eregAll($pattern, $string)
788	{
789	do {
790	if (!mb_ereg($pattern, $string, $temp)) {
791	continue;
792	}
793	$string = str_replace($temp[0], '', $string);
794	$results[] = $temp;
795	} while (mb_ereg($pattern, $string, $temp));
796	return $results;
797	}
798
799	/**
800	* Prints the word "checked" if a variable is set, and optionally matches
801	* the desired value, otherwise prints nothing,
802	* used for printing the word "checked" in a checkbox form input.
803	*
804	* @param mixed $var the variable to compare
805	* @param mixed $value optional, what to compare with if a specific value is required.
806	*/
807	function frmChecked($var, $value=null)
808	{
809	if (func_num_args() == 1 && $var) {
810	// 'Checked' if var is true.
811	echo ' checked="checked" ';
812	} else if (func_num_args() == 2 && $var == $value) {
813	// 'Checked' if var and value match.
814	echo ' checked="checked" ';
815	} else if (func_num_args() == 2 && is_array($var)) {
816	// 'Checked' if the value is in the key or the value of an array.
817	if (isset($var[$value])) {
818	echo ' checked="checked" ';
819	} else if (in_array($value, $var)) {
820	echo ' checked="checked" ';
821	}
822	}
823	}
824
825	/**
826	* prints the word "selected" if a variable is set, and optionally matches
827	* the desired value, otherwise prints nothing,
828	* otherwise prints nothing, used for printing the word "checked" in a
829	* select form input
830	*
831	* @param mixed $var the variable to compare
832	* @param mixed $value optional, what to compare with if a specific value is required.
833	*/
834	function frmSelected($var, $value=null)
835	{
836	if (func_num_args() == 1 && $var) {
837	// 'selected' if var is true.
838	echo ' selected="selected" ';
839	} else if (func_num_args() == 2 && $var == $value) {
840	// 'selected' if var and value match.
841	echo ' selected="selected" ';
842	} else if (func_num_args() == 2 && is_array($var)) {
843	// 'selected' if the value is in the key or the value of an array.
844	if (isset($var[$value])) {
845	echo ' selected="selected" ';
846	} else if (in_array($value, $var)) {
847	echo ' selected="selected" ';
848	}
849	}
850	}
851
852	/**
853	* Adds slashes to values of an array and converts the array to a comma
854	* delimited list. If value provided is a string return the string
855	* escaped. This is useful for putting values coming in from posted
856	* checkboxes into a SET column of a database.
857	*
858	*
859	* @param array $in Array to convert.
860	* @return string Comma list of array values.
861	*/
862	function escapedList($in, $separator="', '")
863	{
864	$db =& DB::getInstance();
865
866	if (is_array($in) && !empty($in)) {
867	return join($separator, array_map(array($db, 'escapeString'), $in));
868	} else {
869	return $db->escapeString($in);
870	}
871	}
872
873	/**
874	* Converts a human string date into a SQL-safe date. Dates nearing
875	* infinity use the date 2038-01-01 so conversion to unix time format
876	* remain within valid range.
877	*
878	* @param array $date String date to convert.
879	* @param array $format Date format to pass to date().
880	* Default produces MySQL datetime: 0000-00-00 00:00:00.
881	* @return string SQL-safe date.
882	*/
883	function strToSQLDate($date, $format='Y-m-d H:i:s')
884	{
885	// Translate the human string date into SQL-safe date format.
886	if (empty($date) \|\| mb_strpos($date, '0000-00-00') !== false \|\| strtotime($date) === -1 \|\| strtotime($date) === false) {
887	// Return a string of zero time, formatted the same as $format.
888	return strtr($format, array(
889	'Y' => '0000',
890	'm' => '00',
891	'd' => '00',
892	'H' => '00',
893	'i' => '00',
894	's' => '00',
895	));
896	} else {
897	return date($format, strtotime($date));
898	}
899	}
900
901	/**
902	* If magic_quotes_gpc is in use, run stripslashes() on $var. If $var is an
903	* array, stripslashes is run on each value, recursively, and the stripped
904	* array is returned.
905	*
906	* @param mixed $var The string or array to un-quote, if necessary.
907	* @return mixed $var, minus any magic quotes.
908	*/
909	function dispelMagicQuotes($var)
910	{
911	static $magic_quotes_gpc;
912
913	if (!isset($magic_quotes_gpc)) {
914	$magic_quotes_gpc = get_magic_quotes_gpc();
915	}
916
917	if ($magic_quotes_gpc) {
918	if (!is_array($var)) {
919	$var = stripslashes($var);
920	} else {
921	foreach ($var as $key=>$val) {
922	if (is_array($val)) {
923	$var[$key] = dispelMagicQuotes($val);
924	} else {
925	$var[$key] = stripslashes($val);
926	}
927	}
928	}
929	}
930	return $var;
931	}
932
933	/**
934	* Get a form variable from GET or POST data, stripped of magic
935	* quotes if necessary.
936	*
937	* @param string $var (optional) The name of the form variable to look for.
938	* @param string $default (optional) The value to return if the
939	* variable is not there.
940	* @return mixed A cleaned GET or POST if no $var specified.
941	* @return string A cleaned form $var if found, or $default.
942	*/
943	function getFormData($var=null, $default=null)
944	{
945	if ('POST' == getenv('REQUEST_METHOD') && is_null($var)) {
946	return dispelMagicQuotes($_POST);
947	} else if ('GET' == getenv('REQUEST_METHOD') && is_null($var)) {
948	return dispelMagicQuotes($_GET);
949	}
950	if (isset($_POST[$var])) {
951	return dispelMagicQuotes($_POST[$var]);
952	} else if (isset($_GET[$var])) {
953	return dispelMagicQuotes($_GET[$var]);
954	} else {
955	return $default;
956	}
957	}
958	function getPost($var=null, $default=null)
959	{
960	if (is_null($var)) {
961	return dispelMagicQuotes($_POST);
962	}
963	if (isset($_POST[$var])) {
964	return dispelMagicQuotes($_POST[$var]);
965	} else {
966	return $default;
967	}
968	}
969	function getGet($var=null, $default=null)
970	{
971	if (is_null($var)) {
972	return dispelMagicQuotes($_GET);
973	}
974	if (isset($_GET[$var])) {
975	return dispelMagicQuotes($_GET[$var]);
976	} else {
977	return $default;
978	}
979	}
980
981	/*
982	* Sets a $_GET or $_POST variable.
983	*
984	* @access public
985	* @param string $key The key of the request array to set.
986	* @param mixed $val The value to save in the request array.
987	* @return void
988	* @author Quinn Comendant <quinn@strangecode.com>
989	* @version 1.0
990	* @since 01 Nov 2009 12:25:29
991	*/
992	function putFormData($key, $val)
993	{
994	if ('POST' == getenv('REQUEST_METHOD')) {
995	$_POST[$key] = $val;
996	} else if ('GET' == getenv('REQUEST_METHOD')) {
997	$_GET[$key] = $val;
998	}
999	}
1000
1001	/**
1002	* Signs a value using md5 and a simple text key. In order for this
1003	* function to be useful (i.e. secure) the salt must be kept secret, which
1004	* means keeping it as safe as database credentials. Putting it into an
1005	* environment variable set in httpd.conf is a good place.
1006	*
1007	* @access public
1008	* @param string $val The string to sign.
1009	* @param string $salt (Optional) A text key to use for computing the signature.
1010	* @param string $length (Optional) The length of the added signature. Longer signatures are safer. Must match the length passed to verifySignature() for the signatures to match.
1011	* @return string The original value with a signature appended.
1012	*/
1013	function addSignature($val, $salt=null, $length=18)
1014	{
1015	$app =& App::getInstance();
1016
1017	if ('' == trim($val)) {
1018	$app->logMsg(sprintf('Cannot add signature to an empty string.', null), LOG_INFO, __FILE__, __LINE__);
1019	return '';
1020	}
1021
1022	if (!isset($salt)) {
1023	$salt = $app->getParam('signing_key');
1024	}
1025
1026	switch ($app->getParam('signing_method')) {
1027	case 'sha512+base64':
1028	return $val . '-' . mb_substr(preg_replace('/[^\w]/', '', base64_encode(hash('sha512', $val . $salt, true))), 0, $length);
1029
1030	case 'md5':
1031	default:
1032	return $val . '-' . mb_strtolower(mb_substr(md5($salt . md5($val . $salt)), 0, $length));
1033	}
1034	}
1035
1036	/**
1037	* Strips off the signature appended by addSignature().
1038	*
1039	* @access public
1040	* @param string $signed_val The string to sign.
1041	* @return string The original value with a signature removed.
1042	*/
1043	function removeSignature($signed_val)
1044	{
1045	if (empty($signed_val) \|\| mb_strpos($signed_val, '-') === false) {
1046	return '';
1047	}
1048	return mb_substr($signed_val, 0, mb_strrpos($signed_val, '-'));
1049	}
1050
1051	/**
1052	* Verifies a signature appended to a value by addSignature().
1053	*
1054	* @access public
1055	* @param string $signed_val A value with appended signature.
1056	* @param string $salt (Optional) A text key to use for computing the signature.
1057	* @param string $length (Optional) The length of the added signature.
1058	* @return bool True if the signature matches the var.
1059	*/
1060	function verifySignature($signed_val, $salt=null, $length=18)
1061	{
1062	// Strip the value from the signed value.
1063	$val = removeSignature($signed_val);
1064	// If the signed value matches the original signed value we consider the value safe.
1065	if ($signed_val == addSignature($val, $salt, $length)) {
1066	// Signature verified.
1067	return true;
1068	} else {
1069	$app =& App::getInstance();
1070	$app->logMsg(sprintf('Failed signature (%s should be %s)', $signed_val, addSignature($val, $salt, $length)), LOG_DEBUG, __FILE__, __LINE__);
1071	return false;
1072	}
1073	}
1074
1075	/**
1076	* Sends empty output to the browser and flushes the php buffer so the client
1077	* will see data before the page is finished processing.
1078	*/
1079	function flushBuffer()
1080	{
1081	echo str_repeat(' ', 205);
1082	flush();
1083	}
1084
1085	/**
1086	* Adds email address to mailman mailing list. Requires /etc/sudoers entry for apache to sudo execute add_members.
1087	* Don't forget to allow php_admin_value open_basedir access to "/var/mailman/bin".
1088	*
1089	* @access public
1090	* @param string $email Email address to add.
1091	* @param string $list Name of list to add to.
1092	* @param bool $send_welcome_message True to send welcome message to subscriber.
1093	* @return bool True on success, false on failure.
1094	*/
1095	function mailmanAddMember($email, $list, $send_welcome_message=false)
1096	{
1097	$app =& App::getInstance();
1098
1099	$add_members = '/usr/lib/mailman/bin/add_members';
1100	// FIXME: checking of executable is disabled.
1101	if (true \|\| is_executable($add_members) && is_readable($add_members)) {
1102	$welcome_msg = $send_welcome_message ? 'y' : 'n';
1103	exec(sprintf("/bin/echo '%s' \| /usr/bin/sudo %s -r - --welcome-msg=%s --admin-notify=n '%s'", escapeshellarg($email), escapeshellarg($add_members), $welcome_msg, escapeshellarg($list)), $stdout, $return_code);
1104	if (0 == $return_code) {
1105	$app->logMsg(sprintf('Mailman add member success for list: %s, user: %s', $list, $email), LOG_INFO, __FILE__, __LINE__);
1106	return true;
1107	} else {
1108	$app->logMsg(sprintf('Mailman add member failed for list: %s, user: %s, with message: %s', $list, $email, getDump($stdout)), LOG_WARNING, __FILE__, __LINE__);
1109	return false;
1110	}
1111	} else {
1112	$app->logMsg(sprintf('Mailman add member program not executable: %s', $add_members), LOG_ALERT, __FILE__, __LINE__);
1113	return false;
1114	}
1115	}
1116
1117	/**
1118	* Removes email address from mailman mailing list. Requires /etc/sudoers entry for apache to sudo execute add_members.
1119	* Don't forget to allow php_admin_value open_basedir access to "/var/mailman/bin".
1120	*
1121	* @access public
1122	* @param string $email Email address to add.
1123	* @param string $list Name of list to add to.
1124	* @param bool $send_user_ack True to send goodbye message to subscriber.
1125	* @return bool True on success, false on failure.
1126	*/
1127	function mailmanRemoveMember($email, $list, $send_user_ack=false)
1128	{
1129	$app =& App::getInstance();
1130
1131	$remove_members = '/usr/lib/mailman/bin/remove_members';
1132	// FIXME: checking of executable is disabled.
1133	if (true \|\| is_executable($remove_members) && is_readable($remove_members)) {
1134	$userack = $send_user_ack ? '' : '--nouserack';
1135	exec(sprintf("/usr/bin/sudo %s %s --noadminack '%s' '%s'", escapeshellarg($remove_members), $userack, escapeshellarg($list), escapeshellarg($email)), $stdout, $return_code);
1136	if (0 == $return_code) {
1137	$app->logMsg(sprintf('Mailman remove member success for list: %s, user: %s', $list, $email), LOG_INFO, __FILE__, __LINE__);
1138	return true;
1139	} else {
1140	$app->logMsg(sprintf('Mailman remove member failed for list: %s, user: %s, with message: %s', $list, $email, $stdout), LOG_WARNING, __FILE__, __LINE__);
1141	return false;
1142	}
1143	} else {
1144	$app->logMsg(sprintf('Mailman remove member program not executable: %s', $remove_members), LOG_ALERT, __FILE__, __LINE__);
1145	return false;
1146	}
1147	}
1148
1149	/*
1150	* Returns the remote IP address, taking into consideration proxy servers.
1151	*
1152	* If strict checking is enabled, we will only trust REMOTE_ADDR or an HTTP header
1153	* value if REMOTE_ADDR is a trusted proxy (configured as an array in $cfg['trusted_proxies']).
1154	*
1155	* @access public
1156	* @param bool $dolookup Resolve to IP to a hostname?
1157	* @param bool $trust_all_proxies Should we trust any IP address set in HTTP_* variables? Set to FALSE for secure usage.
1158	* @return mixed Canonicalized IP address (or a corresponding hostname if $dolookup is true), or false if no IP was found.
1159	* @author Alix Axel <http://stackoverflow.com/a/2031935/277303>
1160	* @author Corey Ballou <http://blackbe.lt/advanced-method-to-obtain-the-client-ip-in-php/>
1161	* @author Quinn Comendant <quinn@strangecode.com>
1162	* @version 1.0
1163	* @since 12 Sep 2014 19:07:46
1164	*/
1165	function getRemoteAddr($dolookup=false, $trust_all_proxies=true)
1166	{
1167	global $cfg;
1168
1169	if (!isset($_SERVER['REMOTE_ADDR'])) {
1170	// In some cases this won't be set, e.g., CLI scripts.
1171	return null;
1172	}
1173
1174	// Use an HTTP header value only if $trust_all_proxies is true or when REMOTE_ADDR is in our $cfg['trusted_proxies'] array.
1175	// $cfg['trusted_proxies'] is an array of proxy server addresses we expect to see in REMOTE_ADDR.
1176	if ($trust_all_proxies \|\| isset($cfg['trusted_proxies']) && is_array($cfg['trusted_proxies']) && in_array($_SERVER['REMOTE_ADDR'], $cfg['trusted_proxies'], true)) {
1177	// Then it's probably safe to use an IP address value set in an HTTP header.
1178	// Loop through possible IP address headers.
1179	foreach (array('HTTP_CLIENT_IP', 'HTTP_X_FORWARDED_FOR', 'HTTP_X_FORWARDED', 'HTTP_X_CLUSTER_CLIENT_IP', 'HTTP_FORWARDED_FOR', 'HTTP_FORWARDED') as $key) {
1180	// Loop through and if
1181	if (array_key_exists($key, $_SERVER)) {
1182	foreach (explode(',', $_SERVER[$key]) as $addr) {
1183	$addr = canonicalIPAddr(trim($addr));
1184	if (false !== filter_var($addr, FILTER_VALIDATE_IP, FILTER_FLAG_IPV4 \| FILTER_FLAG_NO_PRIV_RANGE \| FILTER_FLAG_NO_RES_RANGE)) {
1185	return $dolookup && '' != $addr ? gethostbyaddr($addr) : $addr;
1186	}
1187	}
1188	}
1189	}
1190	}
1191
1192	$addr = canonicalIPAddr(trim($_SERVER['REMOTE_ADDR']));
1193	return $dolookup && $addr ? gethostbyaddr($addr) : $addr;
1194	}
1195
1196	/*
1197	* Converts an ipv4 IP address in hexadecimal form into canonical form (i.e., it removes the prefix).
1198	*
1199	* @access public
1200	* @param string $addr IP address.
1201	* @return string Canonical IP address.
1202	* @author Sander Steffann <http://stackoverflow.com/a/12436099/277303>
1203	* @author Quinn Comendant <quinn@strangecode.com>
1204	* @version 1.0
1205	* @since 15 Sep 2012
1206	*/
1207	function canonicalIPAddr($addr)
1208	{
1209	// Known prefix
1210	$v4mapped_prefix_bin = pack('H*', '00000000000000000000ffff');
1211
1212	// Parse
1213	$addr_bin = inet_pton($addr);
1214
1215	// Check prefix
1216	if (substr($addr_bin, 0, strlen($v4mapped_prefix_bin)) == $v4mapped_prefix_bin) {
1217	// Strip prefix
1218	$addr_bin = substr($addr_bin, strlen($v4mapped_prefix_bin));
1219	}
1220
1221	// Convert back to printable address in canonical form
1222	return inet_ntop($addr_bin);
1223	}
1224
1225	/**
1226	* Tests whether a given IP address can be found in an array of IP address networks.
1227	* Elements of networks array can be single IP addresses or an IP address range in CIDR notation
1228	* See: http://en.wikipedia.org/wiki/Classless_inter-domain_routing
1229	*
1230	* @access public
1231	* @param string IP address to search for.
1232	* @param array Array of networks to search within.
1233	* @return mixed Returns the network that matched on success, false on failure.
1234	*/
1235	function ipInRange($addr, $networks)
1236	{
1237	if (!is_array($networks)) {
1238	$networks = array($networks);
1239	}
1240
1241	$addr_binary = sprintf('%032b', ip2long($addr));
1242	foreach ($networks as $network) {
1243	if (preg_match('![\d\.]{7,15}/\d{1,2}!', $network)) {
1244	// IP is in CIDR notation.
1245	list($cidr_ip, $cidr_bitmask) = explode('/', $network);
1246	$cidr_ip_binary = sprintf('%032b', ip2long($cidr_ip));
1247	if (mb_substr($addr_binary, 0, $cidr_bitmask) === mb_substr($cidr_ip_binary, 0, $cidr_bitmask)) {
1248	// IP address is within the specified IP range.
1249	return $network;
1250	}
1251	} else {
1252	if ($addr === $network) {
1253	// IP address exactly matches.
1254	return $network;
1255	}
1256	}
1257	}
1258
1259	return false;
1260	}
1261
1262	/**
1263	* If the given $url is on the same web site, return true. This can be used to
1264	* prevent from sending sensitive info in a get query (like the SID) to another
1265	* domain.
1266	*
1267	* @param string $url the URI to test.
1268	* @return bool True if given $url is our domain or has no domain (is a relative url), false if it's another.
1269	*/
1270	function isMyDomain($url)
1271	{
1272	static $urls = array();
1273
1274	if (!isset($urls[$url])) {
1275	if (!preg_match('\|https?://[\w.]+/\|', $url)) {
1276	// If we can't find a domain we assume the URL is local (i.e. "/my/url/path/" or "../img/file.jpg").
1277	$urls[$url] = true;
1278	} else {
1279	$urls[$url] = preg_match('\|https?://[\w.]*' . preg_quote(getenv('HTTP_HOST'), '\|') . '\|i', $url);
1280	}
1281	}
1282	return $urls[$url];
1283	}
1284
1285	/**
1286	* Takes a URL and returns it without the query or anchor portion
1287	*
1288	* @param string $url any kind of URI
1289	* @return string the URI with ? or # and everything after removed
1290	*/
1291	function stripQuery($url)
1292	{
1293	return preg_replace('/[?#].*$/', '', $url);
1294	}
1295
1296	/**
1297	* Returns a fully qualified URL to the current script, including the query.
1298	*
1299	* @return string a full url to the current script
1300	*/
1301	function absoluteMe()
1302	{
1303	$protocol = ('on' == getenv('HTTPS')) ? 'https://' : 'http://';
1304	return $protocol . getenv('HTTP_HOST') . getenv('REQUEST_URI');
1305	}
1306
1307	/**
1308	* Compares the current url with the referring url.
1309	*
1310	* @param bool $exclude_query Remove the query string first before comparing.
1311	* @return bool True if the current URL is the same as the referring URL, false otherwise.
1312	*/
1313	function refererIsMe($exclude_query=false)
1314	{
1315	if ($exclude_query) {
1316	return (stripQuery(absoluteMe()) == stripQuery(getenv('HTTP_REFERER')));
1317	} else {
1318	return (absoluteMe() == getenv('HTTP_REFERER'));
1319	}
1320	}

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

Download in other formats: