Location: PHPKode > projects > SchlAdmin > schladmin-0.7.1/src/include/functions.inc.php
<?php

/******
 * This file is part of the free and open source project SchlAdmin.
 * To retrieve all source code with git: `git clone https://github.com/duncannz/schladmin.git`
 * 
 * SchlAdmin is free software: you can redistribute it and/or modify it under the terms of the 
 * GNU General Public License as published by the Free Software Foundation, either version 3
 * of the License, or (at your option) any later version.
 * 
 * SchlAdmin is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;
 * without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
 * See the GNU General Public License for more details.
 * 
 * You should have received a copy of the GNU General Public License along with SchlAdmin.
 * If not, see <http://www.gnu.org/licenses/gpl.txt>.
 *****/

/**
 * functions.inc.php
 * contains various misc. functions that are used around the site
 */


/* A shorthand function for escaping data to go into HTML
 * Safe for inside and outside attributes
 */
function html( $string )
{
	return htmlspecialchars( $string, ENT_QUOTES, 'UTF-8' );
}

/* The translation function.
 * ALL human-readable text must be wrapped in this.
 * 
 * Examples:
 * 
 * <?=__('Hello')?>
 * <?=__('Your name is {first} {last}.', array(
 *     'first' => 'Peter',
 *     'last' => 'Peterson'
 * ))?>
 * 
 * This function sanitizes the *arguments* for HTML automatically by default, but not the format string.
 * Always wrap the function in html() to go in HTML *attributes*, addslashes() for JS, and urlencode() for URL paramaters.
 */
function __( $format_string, $args = array() )
{
	//translate the format string
	$format_string = gettext( $format_string );
	
	//do the replacements of anything in curly braces to the values for them in the array
	//that means that this can work: __('Your name is {first} {last}.', array('first' => "Peter", 'last' => "Peterson"))
	//also sanitize for HTML the paramaters (but not the format string)
	if( count( $args ) > 0 )
	{
		foreach( $args as $key => $value )
		{
			$tmp[ '{' . $key . '}' ] = html( $value );
		}
	}
	else $tmp = array();
    
    //now use str_replace to replace the array keys of $tmp (ie. '{first}', '{last}')
    //with the array values of $tmp (ie. 'Peter', 'Peterson') in $format_string
    return str_replace( array_keys( $tmp ), array_values( $tmp ), $format_string );
}

/* A shortcut function to quote and escape something for SQL
 */
function quote( $string )
{
	//because MySQL does allow quoting numbers, it's safer to always do so, to sanitize stuff like "1 or 1=1"
	global $sql;
	return '\'' . $sql->real_escape_string( $string ) . '\'';
}

/* A function to redirect the user to a different page
 * Set $header to false if the redirect should use JS (ie. because headers cannot be used as content has already been sent)
 */
function redirect( $url, $header_redirect = true )
{
	if( $header_redirect )
	{
		header( "Location: $url" );
		die;
	}
	else
	{
		echo "<script>document.location.replace('" . addslashes( $url ) . "')</script>"
		, "<a href='" . html( $url ) . "'>continue</a>";
	}
}

/* A shortcut function to filter something to just letters and numbers,
 * plus some extra letters in the second argument
 */
function filter_to_alphanumeric( $string, $extra_allowed_characters = ',_ ' )
{
	return preg_replace( '/[^a-z0-9' . preg_quote( $extra_allowed_characters ) . ']/i', "", $string );
}

/* Get a date in the YYYY-MM-DD format (which the SchlAdmin API accepts)
 * 
 * Examples:
 * date_for_schladmin( 1 ); //tomorrow
 * date_for_schladmin( 0 ); //today
 * date_for_schladmin( -2 ); //two days ago
 */
function date_for_schladmin( $number_of_days = 0 )
{
	return date( 'Y-m-d', time() + $number_of_days * 60 * 60 * 24 );
}

/* A function to output the HTML for a Gravatar of a given email address
 * It should only be used inside an if( !empty($config['gravatars']) ) { ... }
 */
function gravatar( $email, $size = 80, $extra_css = '' )
{
	if( is_null( $size ) ) $size = 80;
	if( is_null( $extra_css ) ) $extra_css = '';
	
	return "<img src='http://www.gravatar.com/avatar/" . md5( $email ) . "?d=mm&amp;s=$size' " .
	"class='gravatar' width='$size' height='$size' alt='Gravatar' style='$extra_css'>";
	
}

/* A function to pluralise something properly
 * The placeholder for the number must be '{number}' for it to work.
 * 
 * Examples:
 * pluralise( 0, __('{number} apple'), __('{number} apples'), __('no apples') ); //no apples
 * pluralise( 1, __('{number} apple'), __('{number} apples'), __('no apples') ); //1 apple
 * pluralise( 6, __('{number} apple'), __('{number} apples'), __('no apples') ); //6 apples
 */
function pluralise( $number, $format_string_if_single, $format_string_if_plural, $text_if_zero )
{
	//non-strict comparisons as the number might be a string
	//if the value was zero return $text_if_zero as-is
	if( $number == 0 ) return $text_if_zero;
	
	//if it was one (or minus one??) return a translated version of it using the format string for if it was singular
	else if( $number == 1 || $number == -1 ) return str_replace( '{number}', $number, $format_string_if_single );
	
	//otherwise do the same for the plural format string
	else return str_replace( '{number}', $number, $format_string_if_plural );
}

/* A function to mask a password with a character (default is asterixes)
 * Examples:
 * password_mask( "hello" ); //*****
 * password_mask( "hello this is over 15 characters long" ); //*************** (15 not 19 asterixes)
 * password_mask( "hello this is over 10 characters long", 10 ); //********** (10 not 19 asterixes)
 * password_mask( "passw0rd", null, "·" ); //········
 * password_mask( "this will go on forever without being shortened", 0 ); //***********************************************
 */
function password_mask( $password, $max_length = 15, $replacement_character = '*' )
{
	if( is_null( $max_length ) ) $max_length = 15;
	if( is_null( $replacement_character ) ) $replacement_character = '*';
	
	$retval = "";
	$password_length = strlen( $password );
	
	if( $max_length > 0 && $password_length > $max_length )
	{
		for( $i = 0; $i < $max_length; $i++ ) $retval .= $replacement_character;
	}
	else
	{
		for( $i = 0; $i < $password_length; $i++ ) $retval .= $replacement_character;
	}
	
	return $retval;
}

/* A function for *replacement* of newlines with <br> tags
 * (nl2br only adds the <br>s, it doesn't remove the newlines)
 * It is safer in most cases to actually replace them, since, for example, JavaScript doesn't allow newline characters
 */
function newline_to_br( $string )
{
	return preg_replace( '/(\n)/', "<br>", $string );
}
Return current item: SchlAdmin