Merge branch '3.0.x' into 3.1.x

classes/bench/datespan.php

@@ -29,7 +29,7 @@ public function __construct()
 	public static function bench_span_original($remote, $local = NULL, $output = 'years,months,weeks,days,hours,minutes,seconds')
 	{
 		// Array with the output formats
-		$output = preg_split('/[^a-z]+/', strtolower((string) $output));
+		$output = preg_split('/[^a-z]+/', strtolower( (string) $output));
 
 		// Invalid output
 		if (empty($output))
@@ -116,7 +116,7 @@ public static function bench_span_original($remote, $local = NULL, $output = 'ye
 	public static function bench_span_use_array($remote, $local = NULL, $output = 'years,months,weeks,days,hours,minutes,seconds')
 	{
 		// Array with the output formats
-		$output = preg_split('/[^a-z]+/', strtolower((string) $output));
+		$output = preg_split('/[^a-z]+/', strtolower( (string) $output));
 
 		// Invalid output
 		if (empty($output))

classes/controller/codebench.php

@@ -17,7 +17,9 @@ public function action_index($class)
 	{
 		// Convert submitted class name to URI segment
 		if (isset($_POST['class']))
+		{
 			$this->request->redirect('codebench/'.trim($_POST['class']));
+		}
 
 		// Pass the class name on to the view
 		$this->template->class = (string) $class;

classes/kohana/codebench.php

@@ -155,10 +155,10 @@ public function run()
 		foreach ($codebench['benchmarks'] as & $method)
 		{
 			// Calculate percentage difference relative to fastest and slowest methods
-			$method['percent']['fastest']['time']   = (empty($fastest_method['time']))   ? 0 : $method['time']   / $fastest_method['time']   * 100;
-			$method['percent']['fastest']['memory'] = (empty($fastest_method['memory'])) ? 0 : $method['memory'] / $fastest_method['memory'] * 100;
-			$method['percent']['slowest']['time']   = (empty($slowest_method['time']))   ? 0 : $method['time']   / $slowest_method['time']   * 100;
-			$method['percent']['slowest']['memory'] = (empty($slowest_method['memory'])) ? 0 : $method['memory'] / $slowest_method['memory'] * 100;
+			$method['percent']['fastest']['time']   = (empty($fastest_method['time']))   ? 0 : ($method['time']   / $fastest_method['time']   * 100);
+			$method['percent']['fastest']['memory'] = (empty($fastest_method['memory'])) ? 0 : ($method['memory'] / $fastest_method['memory'] * 100);
+			$method['percent']['slowest']['time']   = (empty($slowest_method['time']))   ? 0 : ($method['time']   / $slowest_method['time']   * 100);
+			$method['percent']['slowest']['memory'] = (empty($slowest_method['memory'])) ? 0 : ($method['memory'] / $slowest_method['memory'] * 100);
 
 			// Assign a grade for time and memory to each method
 			$method['grade']['time']   = $this->_grade($method['percent']['fastest']['time']);
@@ -168,10 +168,10 @@ public function run()
 			foreach ($method['subjects'] as & $subject)
 			{
 				// Calculate percentage difference relative to fastest and slowest subjects for this method
-				$subject['percent']['fastest']['time']   = (empty($fastest_subject['time']))   ? 0 : $subject['time']   / $fastest_subject['time']   * 100;
-				$subject['percent']['fastest']['memory'] = (empty($fastest_subject['memory'])) ? 0 : $subject['memory'] / $fastest_subject['memory'] * 100;
-				$subject['percent']['slowest']['time']   = (empty($slowest_subject['time']))   ? 0 : $subject['time']   / $slowest_subject['time']   * 100;
-				$subject['percent']['slowest']['memory'] = (empty($slowest_subject['memory'])) ? 0 : $subject['memory'] / $slowest_subject['memory'] * 100;
+				$subject['percent']['fastest']['time']   = (empty($fastest_subject['time']))   ? 0 : ($subject['time']   / $fastest_subject['time']   * 100);
+				$subject['percent']['fastest']['memory'] = (empty($fastest_subject['memory'])) ? 0 : ($subject['memory'] / $fastest_subject['memory'] * 100);
+				$subject['percent']['slowest']['time']   = (empty($slowest_subject['time']))   ? 0 : ($subject['time']   / $slowest_subject['time']   * 100);
+				$subject['percent']['slowest']['memory'] = (empty($slowest_subject['memory'])) ? 0 : ($subject['memory'] / $slowest_subject['memory'] * 100);
 
 				// Assign a grade letter for time and memory to each subject
 				$subject['grade']['time']   = $this->_grade($subject['percent']['fastest']['time']);

config/userguide.php

@@ -0,0 +1,23 @@
+<?php defined('SYSPATH') or die('No direct script access.');
+
+return array(
+	// Leave this alone
+	'modules' => array(
+
+		// This should be the path to this modules userguide pages, without the 'guide/'. Ex: '/guide/modulename/' would be 'modulename'
+		'codebench' => array(
+
+			// Whether this modules userguide pages should be shown
+			'enabled' => TRUE,
+
+			// The name that should show up on the userguide index page
+			'name' => 'Codebench',
+
+			// A short description of this module, shown on the index page
+			'description' => 'Code benchmarking tool.',
+
+			// Copyright message, shown in the footer for this module
+			'copyright' => '&copy; 2008–2010 Kohana Team',
+		)	
+	)
+);

guide/codebench/index.md

@@ -0,0 +1,76 @@
+# Using Codebench
+
+[!!] The contents of this page are taken (with some minor changes) from <http://www.geertdedeckere.be/article/introducing-codebench> and are copyright Geert De Deckere.
+
+For a long time I have been using a quick-and-dirty `benchmark.php` file to optimize bits of PHP code, many times regex-related stuff. The file contained not much more than a [gettimeofday](http://php.net/gettimeofday) function wrapped around a `for` loop. It worked, albeit not very efficiently. Something more solid was needed. I set out to create a far more usable piece of software to aid in the everlasting quest to squeeze every millisecond out of those regular expressions.
+
+## Codebench Goals
+
+### Benchmark multiple regular expressions at once
+
+Being able to compare the speed of an arbitrary amount of regular expressions would be tremendously useful. In case you are wondering—yes, I had been writing down benchmark times for each regex, uncommenting them one by one. You get the idea. Those days should be gone forever now.
+
+### Benchmark multiple subjects at once
+
+What gets overlooked too often when testing and optimizing regular expressions is the fact that speed can vastly differ depending on the subjects, also known as input or target strings. Just because your regular expression matches, say, a valid email address quickly, does not necessarily mean it will quickly realize when an invalid email is provided. I plan to write a follow-up article with hands-on regex examples to demonstrate this point. Anyway, Codebench allows you to create an array of subjects which will be passed to each benchmark.
+
+### Make it flexible enough to work for all PCRE functions
+
+Initially I named the module “Regexbench”. I quickly realized, though, it would be flexible enough to benchmark all kinds of PHP code, hence the change to “Codebench”. While tools specifically built to help profiling PCRE functions, like [preg_match](http://php.net/preg_match) or [preg_replace](http://php.net/preg_replace), definitely have their use, more flexibility was needed here. You should be able to compare all kinds of constructions like combinations of PCRE functions and native PHP string functions.
+
+### Create clean and portable benchmark cases
+
+Throwing valuable benchmark data away every time I needed to optimize another regular expression had to stop. A clean file containing the complete set of all regex variations to compare, together with the set of subjects to test them against, would be more than welcome. Moreover, it would be easy to exchange benchmark cases with others.
+
+### Visualize the benchmarks
+
+Obviously providing a visual representation of the benchmark results, via simple graphs, would make interpreting them easier. Having not to think about Internet Explorer for once, made writing CSS a whole lot more easy and fun. It resulted in some fine graphs which are fully resizable.
+
+Below are two screenshots of Codebench in action. `Valid_Color` is a class made for benchmarking different ways to validate hexadecimal HTML color values, e.g. `#FFF`. If you are interested in the story behind the actual regular expressions, take a look at [this topic in the Kohana forums](http://forum.kohanaphp.com/comments.php?DiscussionID=2192).
+
+![Benchmarking several ways to validate HTML color values](codebench_screenshot1.png)
+**Benchmarking seven ways to validate HTML color values**
+
+![Collapsable results per subject for each method](codebench_screenshot2.png)
+**Collapsable results per subject for each method**
+
+## Working with Codebench
+
+Codebench is included in Kohana 3, but if you need you [can download it](http://github.com/kohana/codebench/) from GitHub. Be sure Codebench is activated in your `application/bootstrap.php`.
+
+Creating your own benchmarks is just a matter of creating a class that extends the Codebench class.  The class should go in `classes/bench` and the class name should have the `Bench_` prefix.  Put the code parts you want to compare into separate methods. Be sure to prefix those methods with `bench_`, other methods will not be benchmarked. Glance at the files in `modules/codebench/classes/bench/` for more examples.
+
+Here is another short example with some extra explanations.
+
+	// classes/bench/ltrimdigits.php
+	class Bench_LtrimDigits extends Codebench {
+
+		// Some optional explanatory comments about the benchmark file.
+		// HTML allowed. URLs will be converted to links automatically.
+		public $description = 'Chopping off leading digits: regex vs ltrim.';
+
+		// How many times to execute each method per subject.
+		// Total loops = loops * number of methods * number of subjects
+		public $loops = 100000;
+
+		// The subjects to supply iteratively to your benchmark methods.
+		public $subjects = array
+		(
+			'123digits',
+			'no-digits',
+		);
+
+		public function bench_regex($subject)
+		{
+			return preg_replace('/^\d+/', '', $subject);
+		}
+
+		public function bench_ltrim($subject)
+		{
+			return ltrim($subject, '0..9');
+		}
+	}
+
+
+
+And the winner is… [ltrim](http://php.net/ltrim). Happy benchmarking!

guide/codebench/menu.md

@@ -0,0 +1 @@
+## [Codebench]()

views/codebench.php

@@ -14,7 +14,9 @@
 <head>
 
 	<meta charset="utf-8" />
-	<title><?php if ($class !== '') echo $class, ' · ' ?>Codebench</title>
+	<title><?php if ($class !== ''): ?>
+			<?php echo $class, ' · ' ?>
+		<?php endif; ?>Codebench</title>
 
 	<style>
 		/* General styles*/