Releasing 1.0.4

Author: technicalguru

README.md

@@ -6,7 +6,10 @@ This is a collection of useful classes and functions for every day PHP life. It
 * Logging to error_log with different levels
 * Notification to users across various requests within a session
 * Extracting information from the current HTTP request
+* Obfuscating sensitive information to protect data against spambots
+* Slugifying strings for usage in URLs
 * Generating random strings
+* Formatting prices and units
 
 These classes are no rocket science, just simple helpers that prevent from wiriting the
 same code in various flavours over and over again.
@@ -80,8 +83,13 @@ Logging is very simple. Set your log level (if not INFO) and start logging:
 ```
 use TgLog\Log;
 
-// Set the log level
-Log::setLogLevel(Log::ERROR);
+// Set default settings before using the log:
+Log::setDefaultLogLevel(Log::ERROR);
+Log::setDefaultAppName('MyApplication');
+
+// Or just on the singleton logging instance
+Log::instance()->setLogLevel(Log::ERROR);
+Log::instance()->setAppName('MyAppName');
 
 // Simple line
 Log::error('A simple error message');
@@ -116,6 +124,16 @@ $stacktrace = Log::getStackTrace();
 Log::infoStackTrace();
 ```
 
+Finally, you can create your special instances of a log for some modules and log from there, e.g.
+
+```
+$moduleLog = new Log(Log::ERROR, 'MyAppModule');
+
+$moduleLog->logInfo('Module started');
+$moduleLog->logError('Exception occurred:', $exception);
+
+```
+
 ## User Notifications
 
 Sometimes it is hard to display success or error messages because the message needs to
@@ -159,11 +177,58 @@ A simple authentication helper interface along with a default implementation is
 * [TgUtils\Auth\CredentialsProvider](https://github.com/technicalguru/php-utils/blob/src/TgUtils/Auth/CredentialsProvider.php) - Interface to provide username and password to other objects
 * [TgUtils\Auth\DefaultCredentialsProvider](https://github.com/technicalguru/php-utils/blob/src/TgUtils/Auth/DefaultCredentialsProvider.php) - Simple default implementation of the interface
 
+## Sensitive Data Obfuscation
+
+Publishing sensitive data such as e-mail addresses and phone numbers is dangerous nowadays as spammers
+grab such information automatically from websites. The utils package provides a javascript-based way
+to obfuscate this information on websites. Its' idea is based on the rot13 obfuscation method but uses a
+random character mapping instead of a fixed rotation. This idea was chosen because rot13 seems to be a kind of standard
+in obfuscation and spammers might already be able to read them.
+
+It shall be noted that it is still not impossible to read the information even when obfuscated. But it requires
+a bit more sophisticated effort (Javascript execution) to gain the sensitive information.
+
+**Idea:** The text to be obfuscated is replaced - char by char - by other characters from a map. This map is
+generated uniquely for this special obfuscation instance. Other obfuscations on the same page will use different
+maps. The HTML source displays only: `[javascript protected]`. However, a special javascript will run after
+the page loaded and replace exactly this text with the real content.
+
+Two obfuscation methods exists: a simple text obfuscation and an e-mail obfuscation which also creates a mailto: link
+that the user can click.
+
+Here is how you use it:
+
+```
+user \TgUtils\Obfuscation;
+
+/*** Just create everything and put it in your HTML page **/
+$htmlSource = Obfuscation::obfuscateText('+49 555 0123456');
+$emailLink  = Obfuscation::obfuscateEmail('[email protected]');
+
+/*************************** OR ***************************/
+// Use your own tag ID 
+$id         = Obfuscation::generateObfuscationId();
+
+// Use this ID to get the bot-resistent HTML source
+$htmlSource = Obfuscation::getObfuscatedHtmlSpan($id);
+
+// And get the javascript
+$textJavascript   = Obfuscation::obfuscateText('+49 555 0123456', $id);
+$emailJavascript  = Obfuscation::obfuscateEmail('[email protected]', $id);
+
+```
+
+Please notice that not all characters are supported in the default character map. It covers mainly
+e-mail addresses and phone numbers. However, you can pass your own character set to the obfuscate methods
+as third argument. Please consult the [source code](https://github.com/technicalguru/php-utils/blob/src/TgUtils/Obfuscation.php) for more details.
+
 ## Other Utils
 There are some daily tasks that need to be done in applications. The `Utils` class addresses a few of them:
 
 ```
 use TgUtils\Utils;
+use TgUtils\FormatUtils;
+use TgUtils\Slugify;
 
 // create a random string
 $myId = Utils::generateRandomString(20);
@@ -188,6 +253,15 @@ $allNames = Utils::extractAttributeFromList($objectList, 'name');
 
 // Mask a sensitive string
 $masked = Utils::anonymize($aPhoneNumber);
+
+// Slugify a string
+$slug = Slugify::slugify('A text that turn into an URL');
+
+// Format a price
+$priceString = FormatUtils::formatPrice(3000.643, 'EUR');
+
+// Format a file size
+$fileSize = FormatUtils::formatUnit(3000643, 'B');
 ```
 
 Inspect the [source code](https://github.com/technicalguru/php-utils/blob/src/TgUtils/Utils.php) to find more about the methods available.

src/TgLog/Log.php

@@ -21,34 +21,76 @@ class Log {
     /** The available log priorities */
     protected static $logPriorities;
     /** The log level to issue in error_log */
-	protected static $logLevel;
+	protected static $defaultLogLevel;
+	/** The name of the application to prefix log entries */
+	protected static $defaultAppName;
 
 	/** The single instance of the log */
 	public    static $instance;
 
 	/** All log messages that were issued */
 	public    $messages;
+	/** The log level of the instance */
+	protected $logLevel;
+	/** The app name to prefix lof entries with */
+	protected $appName;
 
 	/**
 	 * Returns the single instance.
 	 * @return Log - single Log instance 
 	 */
     public static function instance() {
-		if (self::$logLevel == null) {
-			self::$logLevel == self::INFO;
+		if (self::$defaultLogLevel == null) {
+			self::$defaultLogLevel = self::INFO;
 		}
 		if (self::$instance == null) {
-			self::$instance = new Log();
+			self::$instance = new Log(self::$defaultLogLevel, self::$defaultAppName);
 		}
 		return self::$instance;
 	}
 
+	/**
+	 * Returns the log level of this instance.
+	 * @return string the current log level
+	 */
+	public function getLogLevel() {
+	    return $this->logLevel;
+	}
+	
+	/**
+	 * Sets the log level of this instance.
+	 * @param string $level - the new log level
+	 */
+	public function setLogLevel($level) {
+	    $this->logLevel = $level;
+	}
+	
+	/**
+	 * Returns the prefix for log entries.
+	 * @return string the current prefix
+	 */
+	public function getAppName() {
+	    return $this->appName;
+	}
+	
+	/**
+	 * Sets the prefix that log entries shall be given.
+	 * @param string $appName - the new prefix
+	 */
+	public function setAppName($appName) {
+	    $this->appName = $appName;
+	}
+	
 	/**
 	 * Public constructor.
+	 * @param string $logLevel - the log level for this instance (optional, default is Log::INFO)
+	 * @param string $appName  - the prefix for the log entry (optional)
 	 * <p>Usually you don't need to instantiate it yourself but use the single instance.</p> 
 	 */
-    public function __construct() {
+    public function __construct($logLevel = self::INFO, $appName = NULL) {
 		$this->messages = array();
+		$this->logLevel = $logLevel;
+		$this->appName  = $appName != NULL ? $appName : self::$defaultAppName;
 	}
 
 	/**
@@ -67,7 +109,8 @@ protected function log($sev, $s, $o = null) {
 			}
 		}
 		$this->messages[$sev][] = $s;
-		if (self::isLogLevelIncluded($sev)) error_log('[WebApp - '.strtoupper($sev).'] '.$s);
+		$prefix = $this->getAppName() != NULL ? '['.$this->getAppName().']' : '';
+		if ($this->isLogLevelIncluded($sev)) error_log($prefix.'['.strtoupper($sev).'] '.$s);
 	}
 
 	/**
@@ -78,7 +121,7 @@ protected function log($sev, $s, $o = null) {
 	public function logStackTrace($sev, $excludeFile = NULL) {
 		$trace = $this->getStackTrace($excludeFile);
 		$this->log($sev, 'Stacktrace:');
-		foreach ($trace AS $idx => $line) {
+		foreach ($trace AS $line) {
 			$this->log($sev, '   '.$line);
 		}
 	}
@@ -109,7 +152,16 @@ public function getStackTrace($excludeFile = NULL) {
 	 * @param mixed  $o - an oject to be dumped along with message. An Exception object will cause a stacktrace dump (optional).
 	 */
 	public static function debug($s, $o = null) {
-		self::instance()->log(self::DEBUG, $s, $o);
+		self::instance()->logDebug($s, $o);
+	}
+
+	/**
+	 * Debug message into log.
+	 * @param string $s - the message
+	 * @param mixed  $o - an oject to be dumped along with message. An Exception object will cause a stacktrace dump (optional).
+	 */
+	public function logDebug($s, $o = null) {
+		$this->log(self::DEBUG, $s, $o);
 	}
 
 	/**
@@ -118,7 +170,16 @@ public static function debug($s, $o = null) {
 	 * @param mixed  $o - an oject to be dumped along with message. An Exception object will cause a stacktrace dump (optional).
 	 */
 	public static function info($s, $o = null) {
-		self::instance()->log(self::INFO, $s, $o);
+		self::instance()->logInfo($s, $o);
+	}
+
+	/**
+	 * Info message into log.
+	 * @param string $s - the message
+	 * @param mixed  $o - an oject to be dumped along with message. An Exception object will cause a stacktrace dump (optional).
+	 */
+	public function logInfo($s, $o = null) {
+		$this->log(self::INFO, $s, $o);
 	}
 
 	/**
@@ -127,7 +188,16 @@ public static function info($s, $o = null) {
 	 * @param mixed  $o - an oject to be dumped along with message. An Exception object will cause a stacktrace dump (optional).
 	 */
 	public static function warn($s, $o = null) {
-		self::instance()->log(self::WARN, $s, $o);
+		self::instance()->logWarn($s, $o);
+	}
+
+	/**
+	 * Warning message into log.
+	 * @param string $s - the message
+	 * @param mixed  $o - an oject to be dumped along with message. An Exception object will cause a stacktrace dump (optional).
+	 */
+	public function logWarn($s, $o = null) {
+		$this->log(self::WARN, $s, $o);
 	}
 
 	/**
@@ -136,7 +206,16 @@ public static function warn($s, $o = null) {
 	 * @param mixed  $o - an oject to be dumped along with message. An Exception object will cause a stacktrace dump (optional).
 	 */
 	public static function error($s, $o = null) {
-		self::instance()->log(self::ERROR, $s, $o);
+		self::instance()->logError($s, $o);
+	}
+
+	/**
+	 * Error message into log.
+	 * @param string $s - the message
+	 * @param mixed  $o - an oject to be dumped along with message. An Exception object will cause a stacktrace dump (optional).
+	 */
+	public function logError($s, $o = null) {
+		$this->log(self::ERROR, $s, $o);
 	}
 
 	/**
@@ -175,8 +254,16 @@ public static function errorStackTrace($excludeFile = NULL) {
 	 * Set the global log level.
 	 * @param $sev - shall be debug, info, warn, error or none.
 	 */
-	public static function setLogLevel($sev) {
-		self::$logLevel = $sev;
+	public static function setDefaultLogLevel($sev) {
+		self::$defaultLogLevel = $sev;
+	}
+	
+	/**
+	 * Set the global log entry prefix.
+	 * @param $appName - default prefix for log entries.
+	 */
+	public static function setDefaultAppName($appName) {
+		self::$defaultAppName = $appName;
 	}
 
 	/**
@@ -214,11 +301,11 @@ public static function get() {
 	 * @param string $sev - the log level to check
 	 * @return TRUE when the current loglevel allows logging.
 	 */
-	protected static function isLogLevelIncluded($sev) {
+	protected function isLogLevelIncluded($sev) {
 		if (self::$logPriorities == null) {
 			self::$logPriorities = array(self::NONE, self::DEBUG, self::INFO, self::WARN, self::ERROR);
 		}
-		$logIndex = array_search(self::$logLevel, self::$logPriorities);
+		$logIndex = array_search($this->logLevel, self::$logPriorities);
 		$sevIndex = array_search($sev, self::$logPriorities);
 		return $logIndex <= $sevIndex;
 	}

src/TgUtils/FormatUtils.php

@@ -0,0 +1,62 @@
+<?php
+
+namespace TgUtils;
+
+use \TgI18n\I18N;
+
+I18N::addI18nFile(__DIR__ . '/../utils_i18n.php', FALSE);
+
+/**
+ * Provides some formatting utils.
+ * @author ralph
+ *        
+ */
+class FormatUtils {
+
+	/**
+	 * Format a price value using localization.
+	 * @param float $value - the value
+	 * @param string $currency - the currency
+	 * @param string $language - the language code (optional, default language of I18N class).
+	 * @param string $spaceChar - the space character to be used between value and currency (optional, default is HTML non-breaking space).
+	 * @return string the formatted price in localized manner.
+	 */
+    public static function formatPrice($value, $currency, $language = null, $spaceChar = '&nbsp;') {
+		return number_format(floatval($value), 2, I18N::_('decimal_point', $language), I18N::_('thousand_sep', $language)).$spaceChar.$currency;
+	}
+	
+	/**
+	 * Format a unit by using prefixes (decimal and computer bytes only).
+	 * @param int $size - the size to be formatted
+	 * @param string $unit - the unit string
+	 * @param int $precision - how many digits after decimal point shall be displayed (optional, default is 1)
+	 * @param string $language - the language to be used for number formatting separators (optional, default is NULL)
+	 * @param bool $bytes - TRUE when computer byte counting is used, FALSE when decimal base shall be applied (optional, default is TRUE)
+	 * @return string a formatted string
+	 */
+	public static function formatUnit($size, $unit, $precision = 1, $language = NULL, $bytes = TRUE) {
+	    $prefixes = $bytes ? array('K', 'M', 'G', 'T' ) : array('k', 'M', 'G', 'T');  
+	    $rc       = $unit;
+	    $base     = $bytes ? 1024 : 1000;
+		// Only until GB
+		if ($size > $base) {
+			$size = $size/$base;
+			$rc   = $prefixes[0].$unit;
+		}
+		if ($size > $base) {
+			$size = $size/$base;
+			$rc   = $prefixes[1].$unit;
+		}
+		if ($size > $base) {
+			$size = $size/$base;
+			$rc   = $prefixes[2].$unit;
+		}
+		if ($size > $base) {
+			$size = $size/$base;
+			$rc   = $prefixes[3].$unit;
+		}
+		$size = $rc != $unit ? number_format($size, $precision, I18N::_('decimal_point', $language), I18N::_('thousand_sep', $language)) : number_format($size, 0, I18N::_('decimal_point', $language), I18N::_('thousand_sep', $language));
+		return $size.' '.$rc;
+	}
+}
+