Environment Tests
+ ++ The following tests have been run to determine if Kohana will work in your environment. + If any of the tests have failed, consult the documentation + for more information on how to correct the problem. +
+ + + +| PHP Version | + =')): ?> ++ + | Kohana requires PHP 5.2.3 or newer, this version is . | + +|
|---|---|---|---|
| System Directory | + ++ + | The configured system directory does not exist or does not contain required files. |
+
+ |
| Application Directory | + ++ + | The configured application directory does not exist or does not contain required files. |
+
+ |
| Cache Directory | + ++ + | The |
+
+ |
| Logs Directory | + ++ + | The |
+
+ |
| PCRE UTF-8 | + +PCRE has not been compiled with UTF-8 support. | + +PCRE has not been compiled with Unicode property support. | + +Pass | + +
| SPL Enabled | + +Pass | + +PHP SPL is either not loaded or not compiled in. | + +|
| Reflection Enabled | + +Pass | + +PHP reflection is either not loaded or not compiled in. | + +|
| Filters Enabled | + +Pass | + +The filter extension is either not loaded or not compiled in. | + +|
| Iconv Extension Loaded | + +Pass | + +The iconv extension is not loaded. | + +|
| Mbstring Not Overloaded | + +The mbstring extension is overloading PHP's native string functions. | + +Pass | + +|
| Character Type (CTYPE) Extension | + +The ctype extension is not enabled. | + +Pass | + +|
| URI Determination | + +Pass | + +Neither $_SERVER['REQUEST_URI'], $_SERVER['PHP_SELF'], or $_SERVER['PATH_INFO'] is available. |
+
+
✘ Kohana may not work correctly with your environment.
+ +✔ Your environment passed all requirements.
+ Remove or rename the install file now.
Optional Tests
+ ++ The following extensions are not required to run the Kohana core, but if enabled can provide access to additional classes. +
+ +| cURL Enabled | + +Pass | + +Kohana requires cURL for the Remote class. | + +
|---|---|---|
| mcrypt Enabled | + +Pass | + +Kohana requires mcrypt for the Encrypt class. | + +
| GD Enabled | + +Pass | + +Kohana requires GD v2 for the Image class. | + +
| PDO Enabled | + +Pass | + +Kohana can use PDO to support additional databases. | + +
Arr::callback():
+ http://github.com/shadowhand/kohana/commit/c3aaae849164bf92a486e29e736a265b350cb4da#L0R127';
+
+ public $loops = 10000;
+
+ public $subjects = array
+ (
+ // Valid callback strings
+ 'foo',
+ 'foo::bar',
+ 'foo[apple,orange]',
+ 'foo::bar[apple,orange]',
+ '[apple,orange]', // no command, only params
+ 'foo[[apple],[orange]]', // params with brackets inside
+
+ // Invalid callback strings
+ 'foo[apple,orange', // no closing bracket
+ );
+
+ public function bench_shadowhand($subject)
+ {
+ // The original regex we're trying to optimize
+ if (preg_match('/([^\[]*+)\[(.*)\]/', $subject, $match))
+ return $match;
+ }
+
+ public function bench_geert_regex_1($subject)
+ {
+ // Added ^ and $ around the whole pattern
+ if (preg_match('/^([^\[]*+)\[(.*)\]$/', $subject, $matches))
+ return $matches;
+ }
+
+ public function bench_geert_regex_2($subject)
+ {
+ // A rather experimental approach using \K which requires PCRE 7.2 ~ PHP 5.2.4
+ // Note: $matches[0] = params, $matches[1] = command
+ if (preg_match('/^([^\[]*+)\[\K.*(?=\]$)/', $subject, $matches))
+ return $matches;
+ }
+
+ public function bench_geert_str($subject)
+ {
+ // A native string function approach which beats all the regexes
+ if (strpos($subject, '[') !== FALSE AND substr($subject, -1) === ']')
+ return explode('[', substr($subject, 0, -1), 2);
+ }
+}
\ No newline at end of file
diff --git a/includes/kohana/modules/codebench/classes/bench/autolinkemails.php b/includes/kohana/modules/codebench/classes/bench/autolinkemails.php
new file mode 100644
index 00000000..46e7a158
--- /dev/null
+++ b/includes/kohana/modules/codebench/classes/bench/autolinkemails.php
@@ -0,0 +1,70 @@
+
+ */
+class Bench_AutoLinkEmails extends Codebench {
+
+ public $description =
+ 'Fixing #2772, and comparing some possibilities.';
+
+ public $loops = 1000;
+
+ public $subjects = array
+ (
+ '-
+
- voorzitter@xxxx.com +
- vicevoorzitter@xxxx.com +
Date::span().';
+
+ public $loops = 1000;
+
+ public $subjects = array();
+
+ public function __construct()
+ {
+ parent::__construct();
+
+ $this->subjects = array(
+ time(),
+ time() - Date::MONTH,
+ time() - Date::YEAR,
+ time() - Date::YEAR * 10,
+ );
+ }
+
+ // Original method
+ 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));
+
+ // Invalid output
+ if (empty($output))
+ return FALSE;
+
+ // Make the output values into keys
+ extract(array_flip($output), EXTR_SKIP);
+
+ if ($local === NULL)
+ {
+ // Calculate the span from the current time
+ $local = time();
+ }
+
+ // Calculate timespan (seconds)
+ $timespan = abs($remote - $local);
+
+ if (isset($years))
+ {
+ $timespan -= Date::YEAR * ($years = (int) floor($timespan / Date::YEAR));
+ }
+
+ if (isset($months))
+ {
+ $timespan -= Date::MONTH * ($months = (int) floor($timespan / Date::MONTH));
+ }
+
+ if (isset($weeks))
+ {
+ $timespan -= Date::WEEK * ($weeks = (int) floor($timespan / Date::WEEK));
+ }
+
+ if (isset($days))
+ {
+ $timespan -= Date::DAY * ($days = (int) floor($timespan / Date::DAY));
+ }
+
+ if (isset($hours))
+ {
+ $timespan -= Date::HOUR * ($hours = (int) floor($timespan / Date::HOUR));
+ }
+
+ if (isset($minutes))
+ {
+ $timespan -= Date::MINUTE * ($minutes = (int) floor($timespan / Date::MINUTE));
+ }
+
+ // Seconds ago, 1
+ if (isset($seconds))
+ {
+ $seconds = $timespan;
+ }
+
+ // Remove the variables that cannot be accessed
+ unset($timespan, $remote, $local);
+
+ // Deny access to these variables
+ $deny = array_flip(array('deny', 'key', 'difference', 'output'));
+
+ // Return the difference
+ $difference = array();
+ foreach ($output as $key)
+ {
+ if (isset($$key) AND ! isset($deny[$key]))
+ {
+ // Add requested key to the output
+ $difference[$key] = $$key;
+ }
+ }
+
+ // Invalid output formats string
+ if (empty($difference))
+ return FALSE;
+
+ // If only one output format was asked, don't put it in an array
+ if (count($difference) === 1)
+ return current($difference);
+
+ // Return array
+ return $difference;
+ }
+
+ // Using an array for the output
+ 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));
+
+ // Invalid output
+ if (empty($output))
+ return FALSE;
+
+ // Convert the list of outputs to an associative array
+ $output = array_combine($output, array_fill(0, count($output), 0));
+
+ // Make the output values into keys
+ extract(array_flip($output), EXTR_SKIP);
+
+ if ($local === NULL)
+ {
+ // Calculate the span from the current time
+ $local = time();
+ }
+
+ // Calculate timespan (seconds)
+ $timespan = abs($remote - $local);
+
+ if (isset($output['years']))
+ {
+ $timespan -= Date::YEAR * ($output['years'] = (int) floor($timespan / Date::YEAR));
+ }
+
+ if (isset($output['months']))
+ {
+ $timespan -= Date::MONTH * ($output['months'] = (int) floor($timespan / Date::MONTH));
+ }
+
+ if (isset($output['weeks']))
+ {
+ $timespan -= Date::WEEK * ($output['weeks'] = (int) floor($timespan / Date::WEEK));
+ }
+
+ if (isset($output['days']))
+ {
+ $timespan -= Date::DAY * ($output['days'] = (int) floor($timespan / Date::DAY));
+ }
+
+ if (isset($output['hours']))
+ {
+ $timespan -= Date::HOUR * ($output['hours'] = (int) floor($timespan / Date::HOUR));
+ }
+
+ if (isset($output['minutes']))
+ {
+ $timespan -= Date::MINUTE * ($output['minutes'] = (int) floor($timespan / Date::MINUTE));
+ }
+
+ // Seconds ago, 1
+ if (isset($output['seconds']))
+ {
+ $output['seconds'] = $timespan;
+ }
+
+ if (count($output) === 1)
+ {
+ // Only a single output was requested, return it
+ return array_pop($output);
+ }
+
+ // Return array
+ return $output;
+ }
+
+}
\ No newline at end of file
diff --git a/includes/kohana/modules/codebench/classes/bench/explodelimit.php b/includes/kohana/modules/codebench/classes/bench/explodelimit.php
new file mode 100644
index 00000000..4bf2acc2
--- /dev/null
+++ b/includes/kohana/modules/codebench/classes/bench/explodelimit.php
@@ -0,0 +1,34 @@
+
+ */
+class Bench_ExplodeLimit extends Codebench {
+
+ public $description =
+ 'Having a look at the effect of adding a limit to the explode function.+ http://stackoverflow.com/questions/1308149/how-to-get-a-part-of-url-between-4th-and-5th-slashes'; + + public $loops = 10000; + + public $subjects = array + ( + 'http://example.com/articles/123a/view', + 'http://example.com/articles/123a/view/x/x/x/x/x', + 'http://example.com/articles/123a/view/x/x/x/x/x/x/x/x/x/x/x/x/x/x/x/x/x/x', + ); + + public function bench_explode_without_limit($subject) + { + $parts = explode('/', $subject); + return $parts[4]; + } + + public function bench_explode_with_limit($subject) + { + $parts = explode('/', $subject, 6); + return $parts[4]; + } + +} \ No newline at end of file diff --git a/includes/kohana/modules/codebench/classes/bench/gruberurl.php b/includes/kohana/modules/codebench/classes/bench/gruberurl.php new file mode 100644 index 00000000..af239750 --- /dev/null +++ b/includes/kohana/modules/codebench/classes/bench/gruberurl.php @@ -0,0 +1,61 @@ + + */ +class Bench_GruberURL extends Codebench { + + public $description = + 'Optimization for http://daringfireball.net/2009/11/liberal_regex_for_matching_urls'; + + public $loops = 10000; + + public $subjects = array + ( + 'http://foo.com/blah_blah', + 'http://foo.com/blah_blah/', + '(Something like http://foo.com/blah_blah)', + 'http://foo.com/blah_blah_(wikipedia)', + '(Something like http://foo.com/blah_blah_(wikipedia))', + 'http://foo.com/blah_blah.', + 'http://foo.com/blah_blah/.', + '
doBaseURL() method of Kohana_Kodoc_Markdown
+ for the Kohana Userguide.';
+
+ public $loops = 10000;
+
+ public $subjects = array
+ (
+ // Valid matches
+ '[filesystem](about.filesystem)',
+ '[filesystem](about.filesystem "Optional title")',
+ '[same page link](#id)',
+ '[object oriented](http://wikipedia.org/wiki/Object-Oriented_Programming)',
+
+ // Invalid matches
+ '',
+ '[filesystem](about.filesystem',
+ );
+
+ public function bench_original($subject)
+ {
+ // The original regex contained a bug, which is fixed here for benchmarking purposes.
+ // At the very start of the regex, (?!!) has been replace by (?
+ */
+class Bench_MDDoImageURL extends Codebench {
+
+ public $description =
+ 'Optimization for the doImageURL() method of Kohana_Kodoc_Markdown
+ for the Kohana Userguide.';
+
+ public $loops = 10000;
+
+ public $subjects = array
+ (
+ // Valid matches
+ '',
+ '',
+ '',
+ '',
+ '![Alt text containing [square] brackets](img/install.png)',
+ '![Empty src]()',
+
+ // Invalid matches
+ '![Alt text](img/install.png "No closing parenthesis"',
+ );
+
+ public function bench_original($subject)
+ {
+ return preg_replace_callback('~!\[(.+?)\]\((\S*(?:\s*".+?")?)\)~', array($this, '_add_image_url_original'), $subject);
+ }
+ protected function _add_image_url_original($matches)
+ {
+ if ($matches[2] AND strpos($matches[2], '://') === FALSE)
+ {
+ // Add the base url to the link URL
+ $matches[2] = 'http://BASE/'.$matches[2];
+ }
+
+ // Recreate the link
+ return "![{$matches[1]}]({$matches[2]})";
+ }
+
+ public function bench_optimized_callback($subject)
+ {
+ // Moved the check for "://" to the regex, simplifying the callback function
+ return preg_replace_callback('~!\[(.+?)\]\((?!\w++://)(\S*(?:\s*+".+?")?)\)~', array($this, '_add_image_url_optimized'), $subject);
+ }
+ protected function _add_image_url_optimized($matches)
+ {
+ // Add the base url to the link URL
+ $matches[2] = 'http://BASE/'.$matches[2];
+
+ // Recreate the link
+ return "![{$matches[1]}]({$matches[2]})";
+ }
+
+ public function bench_callback_gone($subject)
+ {
+ // All the optimized callback was doing now, is prepend some text to the URL.
+ // We don't need a callback for that, and that should be clearly faster.
+ return preg_replace('~(!\[.+?\]\()(?!\w++://)(\S*(?:\s*+".+?")?\))~', '$1http://BASE/$2', $subject);
+ }
+
+}
\ No newline at end of file
diff --git a/includes/kohana/modules/codebench/classes/bench/mddoincludeviews.php b/includes/kohana/modules/codebench/classes/bench/mddoincludeviews.php
new file mode 100644
index 00000000..9cac3d60
--- /dev/null
+++ b/includes/kohana/modules/codebench/classes/bench/mddoincludeviews.php
@@ -0,0 +1,50 @@
+
+ */
+class Bench_MDDoIncludeViews extends Codebench {
+
+ public $description =
+ 'Optimization for the doIncludeViews() method of Kohana_Kodoc_Markdown
+ for the Kohana Userguide.';
+
+ public $loops = 10000;
+
+ public $subjects = array
+ (
+ // Valid matches
+ '{{one}} two {{three}}',
+ '{{userguide/examples/hello_world_error}}',
+
+ // Invalid matches
+ '{}',
+ '{{}}',
+ '{{userguide/examples/hello_world_error}',
+ '{{userguide/examples/hello_world_error }}',
+ '{{userguide/examples/{{hello_world_error }}',
+ );
+
+ public function bench_original($subject)
+ {
+ preg_match_all('/{{(\S+?)}}/m', $subject, $matches, PREG_SET_ORDER);
+ return $matches;
+ }
+
+ public function bench_possessive($subject)
+ {
+ // Using a possessive character class
+ // Removed useless /m modifier
+ preg_match_all('/{{([^\s{}]++)}}/', $subject, $matches, PREG_SET_ORDER);
+ return $matches;
+ }
+
+ public function bench_lookaround($subject)
+ {
+ // Using lookaround to move $mathes[1] into $matches[0]
+ preg_match_all('/(?<={{)[^\s{}]++(?=}})/', $subject, $matches, PREG_SET_ORDER);
+ return $matches;
+ }
+
+}
\ No newline at end of file
diff --git a/includes/kohana/modules/codebench/classes/bench/stripnullbytes.php b/includes/kohana/modules/codebench/classes/bench/stripnullbytes.php
new file mode 100644
index 00000000..4d28853e
--- /dev/null
+++ b/includes/kohana/modules/codebench/classes/bench/stripnullbytes.php
@@ -0,0 +1,37 @@
+
+ */
+class Bench_StripNullBytes extends Codebench {
+
+ public $description =
+ 'String replacement comparisons related to #2676.';
+
+ public $loops = 1000;
+
+ public $subjects = array
+ (
+ "\0",
+ "\0\0\0\0\0\0\0\0\0\0",
+ "bla\0bla\0bla\0bla\0bla\0bla\0bla\0bla\0bla\0bla",
+ "blablablablablablablablablablablablablablablabla",
+ );
+
+ public function bench_str_replace($subject)
+ {
+ return str_replace("\0", '', $subject);
+ }
+
+ public function bench_strtr($subject)
+ {
+ return strtr($subject, array("\0" => ''));
+ }
+
+ public function bench_preg_replace($subject)
+ {
+ return preg_replace('~\0+~', '', $subject);
+ }
+
+}
\ No newline at end of file
diff --git a/includes/kohana/modules/codebench/classes/bench/transliterate.php b/includes/kohana/modules/codebench/classes/bench/transliterate.php
new file mode 100644
index 00000000..aff86931
--- /dev/null
+++ b/includes/kohana/modules/codebench/classes/bench/transliterate.php
@@ -0,0 +1,65 @@
+
+ */
+class Bench_Transliterate extends Codebench {
+
+ public $description =
+ 'Inspired by:
+ http://forum.kohanaframework.org/comments.php?DiscussionID=6113';
+
+ public $loops = 10;
+
+ public $subjects = array
+ (
+ // ASCII
+ 'a', 'b', 'c', 'd', '1', '2', '3',
+
+ // Non-ASCII
+ 'à', 'ô', 'ď', 'ḟ', 'ë', 'š', 'ơ',
+ 'ß', 'ă', 'ř', 'ț', 'ň', 'ā', 'ķ',
+ 'ŝ', 'ỳ', 'ņ', 'ĺ', 'ħ', 'ṗ', 'ó',
+ 'ú', 'ě', 'é', 'ç', 'ẁ', 'ċ', 'õ',
+ 'ṡ', 'ø', 'ģ', 'ŧ', 'ș', 'ė', 'ĉ',
+ 'ś', 'î', 'ű', 'ć', 'ę', 'ŵ', 'ṫ',
+ 'ū', 'č', 'ö', 'è', 'ŷ', 'ą', 'ł',
+ 'ų', 'ů', 'ş', 'ğ', 'ļ', 'ƒ', 'ž',
+ 'ẃ', 'ḃ', 'å', 'ì', 'ï', 'ḋ', 'ť',
+ 'ŗ', 'ä', 'í', 'ŕ', 'ê', 'ü', 'ò',
+ 'ē', 'ñ', 'ń', 'ĥ', 'ĝ', 'đ', 'ĵ',
+ 'ÿ', 'ũ', 'ŭ', 'ư', 'ţ', 'ý', 'ő',
+ 'â', 'ľ', 'ẅ', 'ż', 'ī', 'ã', 'ġ',
+ 'ṁ', 'ō', 'ĩ', 'ù', 'į', 'ź', 'á',
+ 'û', 'þ', 'ð', 'æ', 'µ', 'ĕ', 'ı',
+ 'À', 'Ô', 'Ď', 'Ḟ', 'Ë', 'Š', 'Ơ',
+ 'Ă', 'Ř', 'Ț', 'Ň', 'Ā', 'Ķ', 'Ĕ',
+ 'Ŝ', 'Ỳ', 'Ņ', 'Ĺ', 'Ħ', 'Ṗ', 'Ó',
+ 'Ú', 'Ě', 'É', 'Ç', 'Ẁ', 'Ċ', 'Õ',
+ 'Ṡ', 'Ø', 'Ģ', 'Ŧ', 'Ș', 'Ė', 'Ĉ',
+ 'Ś', 'Î', 'Ű', 'Ć', 'Ę', 'Ŵ', 'Ṫ',
+ 'Ū', 'Č', 'Ö', 'È', 'Ŷ', 'Ą', 'Ł',
+ 'Ų', 'Ů', 'Ş', 'Ğ', 'Ļ', 'Ƒ', 'Ž',
+ 'Ẃ', 'Ḃ', 'Å', 'Ì', 'Ï', 'Ḋ', 'Ť',
+ 'Ŗ', 'Ä', 'Í', 'Ŕ', 'Ê', 'Ü', 'Ò',
+ 'Ē', 'Ñ', 'Ń', 'Ĥ', 'Ĝ', 'Đ', 'Ĵ',
+ 'Ÿ', 'Ũ', 'Ŭ', 'Ư', 'Ţ', 'Ý', 'Ő',
+ 'Â', 'Ľ', 'Ẅ', 'Ż', 'Ī', 'Ã', 'Ġ',
+ 'Ṁ', 'Ō', 'Ĩ', 'Ù', 'Į', 'Ź', 'Á',
+ 'Û', 'Þ', 'Ð', 'Æ', 'İ',
+ );
+
+ public function bench_utf8($subject)
+ {
+ return UTF8::transliterate_to_ascii($subject);
+ }
+
+ public function bench_iconv($subject)
+ {
+ // Note: need to suppress errors on iconv because some chars trigger the following notice:
+ // "Detected an illegal character in input string"
+ return preg_replace('~[^-a-z0-9]+~i', '', @iconv('UTF-8', 'ASCII//TRANSLIT', $subject));
+ }
+
+}
\ No newline at end of file
diff --git a/includes/kohana/modules/codebench/classes/bench/urlsite.php b/includes/kohana/modules/codebench/classes/bench/urlsite.php
new file mode 100644
index 00000000..0db347d8
--- /dev/null
+++ b/includes/kohana/modules/codebench/classes/bench/urlsite.php
@@ -0,0 +1,123 @@
+
+ */
+class Bench_URLSite extends Codebench {
+
+ public $description = 'http://dev.kohanaframework.org/issues/3110';
+
+ public $loops = 1000;
+
+ public $subjects = array
+ (
+ '',
+ 'news',
+ 'news/',
+ '/news/',
+ 'news/page/5',
+ 'news/page:5',
+ 'http://example.com/',
+ 'http://example.com/hello',
+ 'http://example.com:80/',
+ 'http://user:pass@example.com/',
+ );
+
+ public function __construct()
+ {
+ foreach ($this->subjects as $subject)
+ {
+ // Automatically create URIs with query string and/or fragment part appended
+ $this->subjects[] = $subject.'?query=string';
+ $this->subjects[] = $subject.'#fragment';
+ $this->subjects[] = $subject.'?query=string#fragment';
+ }
+
+ parent::__construct();
+ }
+
+ public function bench_original($uri)
+ {
+ // Get the path from the URI
+ $path = trim(parse_url($uri, PHP_URL_PATH), '/');
+
+ if ($query = parse_url($uri, PHP_URL_QUERY))
+ {
+ $query = '?'.$query;
+ }
+
+ if ($fragment = parse_url($uri, PHP_URL_FRAGMENT))
+ {
+ $fragment = '#'.$fragment;
+ }
+
+ return $path.$query.$fragment;
+ }
+
+ public function bench_explode($uri)
+ {
+ // Chop off possible scheme, host, port, user and pass parts
+ $path = preg_replace('~^[-a-z0-9+.]++://[^/]++/?~', '', trim($uri, '/'));
+
+ $fragment = '';
+ $explode = explode('#', $path, 2);
+ if (isset($explode[1]))
+ {
+ $path = $explode[0];
+ $fragment = '#'.$explode[1];
+ }
+
+ $query = '';
+ $explode = explode('?', $path, 2);
+ if (isset($explode[1]))
+ {
+ $path = $explode[0];
+ $query = '?'.$explode[1];
+ }
+
+ return $path.$query.$fragment;
+ }
+
+ public function bench_regex($uri)
+ {
+ preg_match('~^(?:[-a-z0-9+.]++://[^/]++/?)?([^?#]++)?(\?[^#]*+)?(#.*)?~', trim($uri, '/'), $matches);
+ $path = Arr::get($matches, 1, '');
+ $query = Arr::get($matches, 2, '');
+ $fragment = Arr::get($matches, 3, '');
+
+ return $path.$query.$fragment;
+ }
+
+ public function bench_regex_without_arrget($uri)
+ {
+ preg_match('~^(?:[-a-z0-9+.]++://[^/]++/?)?([^?#]++)?(\?[^#]*+)?(#.*)?~', trim($uri, '/'), $matches);
+ $path = isset($matches[1]) ? $matches[1] : '';
+ $query = isset($matches[2]) ? $matches[2] : '';
+ $fragment = isset($matches[3]) ? $matches[3] : '';
+
+ return $path.$query.$fragment;
+ }
+
+ // And then I thought, why do all the work of extracting the query and fragment parts and then reappending them?
+ // Just leaving them alone should be fine, right? As a bonus we get a very nice speed boost.
+ public function bench_less_is_more($uri)
+ {
+ // Chop off possible scheme, host, port, user and pass parts
+ $path = preg_replace('~^[-a-z0-9+.]++://[^/]++/?~', '', trim($uri, '/'));
+
+ return $path;
+ }
+
+ public function bench_less_is_more_with_strpos_optimization($uri)
+ {
+ if (strpos($uri, '://') !== FALSE)
+ {
+ // Chop off possible scheme, host, port, user and pass parts
+ $uri = preg_replace('~^[-a-z0-9+.]++://[^/]++/?~', '', trim($uri, '/'));
+ }
+
+ return $uri;
+ }
+
+}
\ No newline at end of file
diff --git a/includes/kohana/modules/codebench/classes/bench/userfuncarray.php b/includes/kohana/modules/codebench/classes/bench/userfuncarray.php
new file mode 100644
index 00000000..f53d0c66
--- /dev/null
+++ b/includes/kohana/modules/codebench/classes/bench/userfuncarray.php
@@ -0,0 +1,58 @@
+
+ */
+class Bench_UserFuncArray extends Codebench {
+
+ public $description =
+ 'Testing the speed difference of using call_user_func_array
+ compared to counting args and doing manual calls.';
+
+ public $loops = 100000;
+
+ public $subjects = array
+ (
+ // Argument sets
+ array(),
+ array('one'),
+ array('one', 'two'),
+ array('one', 'two', 'three'),
+ );
+
+ public function bench_count_args($args)
+ {
+ $name = 'callme';
+ switch (count($args))
+ {
+ case 1:
+ $this->$name($args[0]);
+ break;
+ case 2:
+ $this->$name($args[0], $args[1]);
+ break;
+ case 3:
+ $this->$name($args[0], $args[1], $args[2]);
+ break;
+ case 4:
+ $this->$name($args[0], $args[1], $args[2], $args[3]);
+ break;
+ default:
+ call_user_func_array(array($this, $name), $args);
+ break;
+ }
+ }
+
+ public function bench_direct_call($args)
+ {
+ $name = 'callme';
+ call_user_func_array(array($this, $name), $args);
+ }
+
+ protected function callme()
+ {
+ return count(func_get_args());
+ }
+
+}
\ No newline at end of file
diff --git a/includes/kohana/modules/codebench/classes/bench/validcolor.php b/includes/kohana/modules/codebench/classes/bench/validcolor.php
new file mode 100644
index 00000000..8d046089
--- /dev/null
+++ b/includes/kohana/modules/codebench/classes/bench/validcolor.php
@@ -0,0 +1,116 @@
+
+ */
+class Bench_ValidColor extends Codebench {
+
+ public $description =
+ 'Optimization for Validate::color().
+ See: http://forum.kohanaphp.com/comments.php?DiscussionID=2192.
+
+ Note that the methods with an _invalid suffix contain flawed regexes and should be
+ completely discarded. I left them in here for educational purposes, and to remind myself
+ to think harder and test more thoroughly. It can\'t be that I only found out so late in
+ the game. For the regex explanation have a look at the forum topic mentioned earlier.';
+
+ public $loops = 10000;
+
+ public $subjects = array
+ (
+ // Valid colors
+ 'aaA',
+ '123',
+ '000000',
+ '#123456',
+ '#abcdef',
+
+ // Invalid colors
+ 'ggg',
+ '1234',
+ '#1234567',
+ "#000\n",
+ '}§è!çà%$z',
+ );
+
+ // Note that I added the D modifier to corey's regexes. We need to match exactly
+ // the same if we want the benchmarks to be of any value.
+ public function bench_corey_regex_1_invalid($subject)
+ {
+ return (bool) preg_match('/^#?([0-9a-f]{1,2}){3}$/iD', $subject);
+ }
+
+ public function bench_corey_regex_2($subject)
+ {
+ return (bool) preg_match('/^#?([0-9a-f]){3}(([0-9a-f]){3})?$/iD', $subject);
+ }
+
+ // Optimized corey_regex_1
+ // Using non-capturing parentheses and a possessive interval
+ public function bench_geert_regex_1a_invalid($subject)
+ {
+ return (bool) preg_match('/^#?(?:[0-9a-f]{1,2}+){3}$/iD', $subject);
+ }
+
+ // Optimized corey_regex_2
+ // Removed useless parentheses, made the remaining ones non-capturing
+ public function bench_geert_regex_2a($subject)
+ {
+ return (bool) preg_match('/^#?[0-9a-f]{3}(?:[0-9a-f]{3})?$/iD', $subject);
+ }
+
+ // Optimized geert_regex_1a
+ // Possessive "#"
+ public function bench_geert_regex_1b_invalid($subject)
+ {
+ return (bool) preg_match('/^#?+(?:[0-9a-f]{1,2}+){3}$/iD', $subject);
+ }
+
+ // Optimized geert_regex_2a
+ // Possessive "#"
+ public function bench_geert_regex_2b($subject)
+ {
+ return (bool) preg_match('/^#?+[0-9a-f]{3}(?:[0-9a-f]{3})?$/iD', $subject);
+ }
+
+ // Using \z instead of $
+ public function bench_salathe_regex_1($subject)
+ {
+ return (bool) preg_match('/^#?+[0-9a-f]{3}(?:[0-9a-f]{3})?\z/i', $subject);
+ }
+
+ // Using \A instead of ^
+ public function bench_salathe_regex_2($subject)
+ {
+ return (bool) preg_match('/\A#?+[0-9a-f]{3}(?:[0-9a-f]{3})?\z/i', $subject);
+ }
+
+ // A solution without regex
+ public function bench_geert_str($subject)
+ {
+ if ($subject[0] === '#')
+ {
+ $subject = substr($subject, 1);
+ }
+
+ $strlen = strlen($subject);
+ return (($strlen === 3 OR $strlen === 6) AND ctype_xdigit($subject));
+ }
+
+ // An ugly, but fast, solution without regex
+ public function bench_salathe_str($subject)
+ {
+ if ($subject[0] === '#')
+ {
+ $subject = substr($subject, 1);
+ }
+
+ // TRUE if:
+ // 1. $subject is 6 or 3 chars long
+ // 2. $subject contains only hexadecimal digits
+ return (((isset($subject[5]) AND ! isset($subject[6])) OR
+ (isset($subject[2]) AND ! isset($subject[3])))
+ AND ctype_xdigit($subject));
+ }
+}
\ No newline at end of file
diff --git a/includes/kohana/modules/codebench/classes/bench/validurl.php b/includes/kohana/modules/codebench/classes/bench/validurl.php
new file mode 100644
index 00000000..3c88675d
--- /dev/null
+++ b/includes/kohana/modules/codebench/classes/bench/validurl.php
@@ -0,0 +1,105 @@
+
+ */
+class Bench_ValidURL extends Codebench {
+
+ public $description =
+ 'filter_var vs regex:
+ http://dev.kohanaframework.org/issues/2847';
+
+ public $loops = 1000;
+
+ public $subjects = array
+ (
+ // Valid
+ 'http://google.com',
+ 'http://google.com/',
+ 'http://google.com/?q=abc',
+ 'http://google.com/#hash',
+ 'http://localhost',
+ 'http://hello-world.pl',
+ 'http://hello--world.pl',
+ 'http://h.e.l.l.0.pl',
+ 'http://server.tld/get/info',
+ 'http://127.0.0.1',
+ 'http://127.0.0.1:80',
+ 'http://user@127.0.0.1',
+ 'http://user:pass@127.0.0.1',
+ 'ftp://my.server.com',
+ 'rss+xml://rss.example.com',
+
+ // Invalid
+ 'http://google.2com',
+ 'http://google.com?q=abc',
+ 'http://google.com#hash',
+ 'http://hello-.pl',
+ 'http://hel.-lo.world.pl',
+ 'http://ww£.google.com',
+ 'http://127.0.0.1234',
+ 'http://127.0.0.1.1',
+ 'http://user:@127.0.0.1',
+ "http://finalnewline.com\n",
+ );
+
+ public function bench_filter_var($url)
+ {
+ return (bool) filter_var($url, FILTER_VALIDATE_URL, FILTER_FLAG_HOST_REQUIRED);
+ }
+
+ public function bench_regex($url)
+ {
+ // Based on http://www.apps.ietf.org/rfc/rfc1738.html#sec-5
+ if ( ! preg_match(
+ '~^
+
+ # scheme
+ [-a-z0-9+.]++://
+
+ # username:password (optional)
+ (?:
+ [-a-z0-9$_.+!*\'(),;?&=%]++ # username
+ (?::[-a-z0-9$_.+!*\'(),;?&=%]++)? # password (optional)
+ @
+ )?
+
+ (?:
+ # ip address
+ \d{1,3}+(?:\.\d{1,3}+){3}+
+
+ | # or
+
+ # hostname (captured)
+ (
+ (?!-)[-a-z0-9]{1,63}+(? 253)
+ return FALSE;
+
+ // An extra check for the top level domain
+ // It must start with a letter
+ $tld = ltrim(substr($matches[1], (int) strrpos($matches[1], '.')), '.');
+ return ctype_alpha($tld[0]);
+ }
+
+}
\ No newline at end of file
diff --git a/includes/kohana/modules/codebench/classes/codebench.php b/includes/kohana/modules/codebench/classes/codebench.php
new file mode 100644
index 00000000..0f4c55cd
--- /dev/null
+++ b/includes/kohana/modules/codebench/classes/codebench.php
@@ -0,0 +1,3 @@
+request->redirect('codebench/'.trim($_POST['class']));
+
+ // Pass the class name on to the view
+ $this->template->class = (string) $class;
+
+ // Try to load the class, then run it
+ if (Kohana::auto_load($class) === TRUE)
+ {
+ $codebench = new $class;
+ $this->template->codebench = $codebench->run();
+ }
+ }
+}
diff --git a/includes/kohana/modules/codebench/classes/kohana/codebench.php b/includes/kohana/modules/codebench/classes/kohana/codebench.php
new file mode 100644
index 00000000..d8a71c17
--- /dev/null
+++ b/includes/kohana/modules/codebench/classes/kohana/codebench.php
@@ -0,0 +1,217 @@
+ 'A',
+ 150 => 'B',
+ 200 => 'C',
+ 300 => 'D',
+ 500 => 'E',
+ 'default' => 'F',
+ );
+
+ /**
+ * Constructor.
+ *
+ * @return void
+ */
+ public function __construct()
+ {
+ // Set the maximum execution time
+ set_time_limit(Kohana::config('codebench')->max_execution_time);
+ }
+
+ /**
+ * Runs Codebench on the extending class.
+ *
+ * @return array benchmark output
+ */
+ public function run()
+ {
+ // Array of all methods to loop over
+ $methods = array_filter(get_class_methods($this), array($this, '_method_filter'));
+
+ // Make sure the benchmark runs at least once,
+ // also if no subject data has been provided.
+ if (empty($this->subjects))
+ {
+ $this->subjects = array('NULL' => NULL);
+ }
+
+ // Initialize benchmark output
+ $codebench = array
+ (
+ 'class' => get_class($this),
+ 'description' => $this->description,
+ 'loops' => array
+ (
+ 'base' => (int) $this->loops,
+ 'total' => (int) $this->loops * count($this->subjects) * count($methods),
+ ),
+ 'subjects' => $this->subjects,
+ 'benchmarks' => array(),
+ );
+
+ // Benchmark each method
+ foreach ($methods as $method)
+ {
+ // Initialize benchmark output for this method
+ $codebench['benchmarks'][$method] = array('time' => 0, 'memory' => 0);
+
+ // Using Reflection because simply calling $this->$method($subject) in the loop below
+ // results in buggy benchmark times correlating to the length of the method name.
+ $reflection = new ReflectionMethod(get_class($this), $method);
+
+ // Benchmark each subject on each method
+ foreach ($this->subjects as $subject_key => $subject)
+ {
+ // Prerun each method/subject combo before the actual benchmark loop.
+ // This way relatively expensive initial processes won't be benchmarked, e.g. autoloading.
+ // At the same time we capture the return here so we don't have to do that in the loop anymore.
+ $return = $reflection->invoke($this, $subject);
+
+ // Start the timer for one subject
+ $token = Profiler::start('codebench', $method.$subject_key);
+
+ // The heavy work
+ for ($i = 0; $i < $this->loops; ++$i)
+ {
+ $reflection->invoke($this, $subject);
+ }
+
+ // Stop and read the timer
+ $benchmark = Profiler::total($token);
+
+ // Benchmark output specific to the current method and subject
+ $codebench['benchmarks'][$method]['subjects'][$subject_key] = array
+ (
+ 'return' => $return,
+ 'time' => $benchmark[0],
+ 'memory' => $benchmark[1],
+ );
+
+ // Update method totals
+ $codebench['benchmarks'][$method]['time'] += $benchmark[0];
+ $codebench['benchmarks'][$method]['memory'] += $benchmark[1];
+ }
+ }
+
+ // Initialize the fastest and slowest benchmarks for both methods and subjects, time and memory,
+ // these values will be overwritten using min() and max() later on.
+ // The 999999999 values look like a hack, I know, but they work,
+ // unless your method runs for more than 31 years or consumes over 1GB of memory.
+ $fastest_method = $fastest_subject = array('time' => 999999999, 'memory' => 999999999);
+ $slowest_method = $slowest_subject = array('time' => 0, 'memory' => 0);
+
+ // Find the fastest and slowest benchmarks, needed for the percentage calculations
+ foreach ($methods as $method)
+ {
+ // Update the fastest and slowest method benchmarks
+ $fastest_method['time'] = min($fastest_method['time'], $codebench['benchmarks'][$method]['time']);
+ $fastest_method['memory'] = min($fastest_method['memory'], $codebench['benchmarks'][$method]['memory']);
+ $slowest_method['time'] = max($slowest_method['time'], $codebench['benchmarks'][$method]['time']);
+ $slowest_method['memory'] = max($slowest_method['memory'], $codebench['benchmarks'][$method]['memory']);
+
+ foreach ($this->subjects as $subject_key => $subject)
+ {
+ // Update the fastest and slowest subject benchmarks
+ $fastest_subject['time'] = min($fastest_subject['time'], $codebench['benchmarks'][$method]['subjects'][$subject_key]['time']);
+ $fastest_subject['memory'] = min($fastest_subject['memory'], $codebench['benchmarks'][$method]['subjects'][$subject_key]['memory']);
+ $slowest_subject['time'] = max($slowest_subject['time'], $codebench['benchmarks'][$method]['subjects'][$subject_key]['time']);
+ $slowest_subject['memory'] = max($slowest_subject['memory'], $codebench['benchmarks'][$method]['subjects'][$subject_key]['memory']);
+ }
+ }
+
+ // Percentage calculations for methods
+ 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;
+
+ // Assign a grade for time and memory to each method
+ $method['grade']['time'] = $this->_grade($method['percent']['fastest']['time']);
+ $method['grade']['memory'] = $this->_grade($method['percent']['fastest']['memory']);
+
+ // Percentage calculations for subjects
+ 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;
+
+ // Assign a grade letter for time and memory to each subject
+ $subject['grade']['time'] = $this->_grade($subject['percent']['fastest']['time']);
+ $subject['grade']['memory'] = $this->_grade($subject['percent']['fastest']['memory']);
+ }
+ }
+
+ return $codebench;
+ }
+
+ /**
+ * Callback for array_filter().
+ * Filters out all methods not to benchmark.
+ *
+ * @param string method name
+ * @return boolean
+ */
+ protected function _method_filter($method)
+ {
+ // Only benchmark methods with the "bench" prefix
+ return (substr($method, 0, 5) === 'bench');
+ }
+
+ /**
+ * Returns the applicable grade letter for a score.
+ *
+ * @param integer|double score
+ * @return string grade letter
+ */
+ protected function _grade($score)
+ {
+ foreach ($this->grades as $max => $grade)
+ {
+ if ($max === 'default')
+ continue;
+
+ if ($score <= $max)
+ return $grade;
+ }
+
+ return $this->grades['default'];
+ }
+}
diff --git a/includes/kohana/modules/codebench/config/codebench.php b/includes/kohana/modules/codebench/config/codebench.php
new file mode 100644
index 00000000..590186da
--- /dev/null
+++ b/includes/kohana/modules/codebench/config/codebench.php
@@ -0,0 +1,16 @@
+ 0,
+
+ /**
+ * Expand all benchmark details by default.
+ */
+ 'expand_all' => FALSE,
+
+);
diff --git a/includes/kohana/modules/codebench/init.php b/includes/kohana/modules/codebench/init.php
new file mode 100644
index 00000000..866cc341
--- /dev/null
+++ b/includes/kohana/modules/codebench/init.php
@@ -0,0 +1,8 @@
+)')
+ ->defaults(array(
+ 'controller' => 'codebench',
+ 'action' => 'index',
+ 'class' => NULL));
diff --git a/includes/kohana/modules/codebench/views/codebench.php b/includes/kohana/modules/codebench/views/codebench.php
new file mode 100644
index 00000000..19619503
--- /dev/null
+++ b/includes/kohana/modules/codebench/views/codebench.php
@@ -0,0 +1,258 @@
+
+
+
+
+
+
+
+
+
+ Remember to prefix the methods you want to benchmark with “bench”.
+ You might also want to overwrite Codebench->method_filter().
+
+
-
+ $benchmark) { ?>
+
-
+
+
+ + + +% + +
+ +++ ++
+Benchmarks per subject for + ++ + + + + $subject) { ?> +subject → return ++ s ++ + + + ++ + [] → + + () + + ++ + + + + + ++ + + s + + + +
+
+
-
+
+
+
Response from Twitter:
+ + diff --git a/includes/kohana/modules/orm/classes/kohana/orm.php b/includes/kohana/modules/orm/classes/kohana/orm.php new file mode 100644 index 00000000..d5ee716c --- /dev/null +++ b/includes/kohana/modules/orm/classes/kohana/orm.php @@ -0,0 +1,1346 @@ +_object_name = strtolower(substr(get_class($this), 6)); + $this->_object_plural = Inflector::plural($this->_object_name); + + if ( ! isset($this->_sorting)) + { + // Default sorting + $this->_sorting = array($this->_primary_key => 'ASC'); + } + + if ( ! empty($this->_ignored_columns)) + { + // Optimize for performance + $this->_ignored_columns = array_combine($this->_ignored_columns, $this->_ignored_columns); + } + + // Initialize database + $this->_initialize(); + + // Clear the object + $this->clear(); + + if ($id !== NULL) + { + if (is_array($id)) + { + foreach ($id as $column => $value) + { + // Passing an array of column => values + $this->where($column, '=', $value); + } + + $this->find(); + } + else + { + // Passing the primary key + + // Set the object's primary key, but don't load it until needed + $this->_object[$this->_primary_key] = $id; + + // Object is considered saved until something is set + $this->_saved = TRUE; + } + } + elseif ( ! empty($this->_preload_data)) + { + // Load preloaded data from a database call cast + $this->_load_values($this->_preload_data); + + $this->_preload_data = array(); + } + } + + /** + * Checks if object data is set. + * + * @param string column name + * @return boolean + */ + public function __isset($column) + { + $this->_load(); + + return + ( + isset($this->_object[$column]) OR + isset($this->_related[$column]) OR + isset($this->_has_one[$column]) OR + isset($this->_belongs_to[$column]) OR + isset($this->_has_many[$column]) + ); + } + + /** + * Unsets object data. + * + * @param string column name + * @return void + */ + public function __unset($column) + { + $this->_load(); + + unset($this->_object[$column], $this->_changed[$column], $this->_related[$column]); + } + + /** + * Displays the primary key of a model when it is converted to a string. + * + * @return string + */ + public function __toString() + { + return (string) $this->pk(); + } + + /** + * Allows serialization of only the object data and state, to prevent + * "stale" objects being unserialized, which also requires less memory. + * + * @return array + */ + public function __sleep() + { + // Store only information about the object + return array('_object_name', '_object', '_changed', '_loaded', '_saved', '_sorting'); + } + + /** + * Prepares the database connection and reloads the object. + * + * @return void + */ + public function __wakeup() + { + // Initialize database + $this->_initialize(); + + if ($this->_reload_on_wakeup === TRUE) + { + // Reload the object + $this->reload(); + } + } + + /** + * Handles pass-through to database methods. Calls to query methods + * (query, get, insert, update) are not allowed. Query builder methods + * are chainable. + * + * @param string method name + * @param array method arguments + * @return mixed + */ + public function __call($method, array $args) + { + if (in_array($method, ORM::$_properties)) + { + if ($method === 'loaded') + { + if ( ! isset($this->_object_name)) + { + // Calling loaded method prior to the object being fully initialized + return FALSE; + } + + $this->_load(); + } + elseif ($method === 'validate') + { + if ( ! isset($this->_validate)) + { + // Initialize the validation object + $this->_validate(); + } + } + + // Return the property + return $this->{'_'.$method}; + } + elseif (in_array($method, ORM::$_db_methods)) + { + // Add pending database call which is executed after query type is determined + $this->_db_pending[] = array('name' => $method, 'args' => $args); + + return $this; + } + else + { + throw new Kohana_Exception('Invalid method :method called in :class', + array(':method' => $method, ':class' => get_class($this))); + } + } + + /** + * Handles retrieval of all model values, relationships, and metadata. + * + * @param string column name + * @return mixed + */ + public function __get($column) + { + if (array_key_exists($column, $this->_object)) + { + $this->_load(); + + return $this->_object[$column]; + } + elseif (isset($this->_related[$column]) AND $this->_related[$column]->_loaded) + { + // Return related model that has already been loaded + return $this->_related[$column]; + } + elseif (isset($this->_belongs_to[$column])) + { + $this->_load(); + + $model = $this->_related($column); + + // Use this model's column and foreign model's primary key + $col = $model->_table_name.'.'.$model->_primary_key; + $val = $this->_object[$this->_belongs_to[$column]['foreign_key']]; + + $model->where($col, '=', $val)->find(); + + return $this->_related[$column] = $model; + } + elseif (isset($this->_has_one[$column])) + { + $model = $this->_related($column); + + // Use this model's primary key value and foreign model's column + $col = $model->_table_name.'.'.$this->_has_one[$column]['foreign_key']; + $val = $this->pk(); + + $model->where($col, '=', $val)->find(); + + return $this->_related[$column] = $model; + } + elseif (isset($this->_has_many[$column])) + { + $model = ORM::factory($this->_has_many[$column]['model']); + + if (isset($this->_has_many[$column]['through'])) + { + // Grab has_many "through" relationship table + $through = $this->_has_many[$column]['through']; + + // Join on through model's target foreign key (far_key) and target model's primary key + $join_col1 = $through.'.'.$this->_has_many[$column]['far_key']; + $join_col2 = $model->_table_name.'.'.$model->_primary_key; + + $model->join($through)->on($join_col1, '=', $join_col2); + + // Through table's source foreign key (foreign_key) should be this model's primary key + $col = $through.'.'.$this->_has_many[$column]['foreign_key']; + $val = $this->pk(); + } + else + { + // Simple has_many relationship, search where target model's foreign key is this model's primary key + $col = $model->_table_name.'.'.$this->_has_many[$column]['foreign_key']; + $val = $this->pk(); + } + + return $model->where($col, '=', $val); + } + else + { + throw new Kohana_Exception('The :property property does not exist in the :class class', + array(':property' => $column, ':class' => get_class($this))); + } + } + + /** + * Handles setting of all model values, and tracks changes between values. + * + * @param string column name + * @param mixed column value + * @return void + */ + public function __set($column, $value) + { + if ( ! isset($this->_object_name)) + { + // Object not yet constructed, so we're loading data from a database call cast + $this->_preload_data[$column] = $value; + + return; + } + + if (array_key_exists($column, $this->_ignored_columns)) + { + // No processing for ignored columns, just store it + $this->_object[$column] = $value; + } + elseif (array_key_exists($column, $this->_object)) + { + $this->_object[$column] = $value; + + if (isset($this->_table_columns[$column])) + { + // Data has changed + $this->_changed[$column] = $column; + + // Object is no longer saved + $this->_saved = FALSE; + } + } + elseif (isset($this->_belongs_to[$column])) + { + // Update related object itself + $this->_related[$column] = $value; + + // Update the foreign key of this model + $this->_object[$this->_belongs_to[$column]['foreign_key']] = $value->pk(); + + $this->_changed[$column] = $this->_belongs_to[$column]['foreign_key']; + } + else + { + throw new Kohana_Exception('The :property: property does not exist in the :class: class', + array(':property:' => $column, ':class:' => get_class($this))); + } + } + + /** + * Set values from an array with support for one-one relationships. This method should be used + * for loading in post data, etc. + * + * @param array array of key => val + * @return ORM + */ + public function values($values) + { + foreach ($values as $key => $value) + { + if (array_key_exists($key, $this->_object) OR array_key_exists($key, $this->_ignored_columns)) + { + // Property of this model + $this->__set($key, $value); + } + elseif (isset($this->_belongs_to[$key]) OR isset($this->_has_one[$key])) + { + // Value is an array of properties for the related model + $this->_related[$key] = $value; + } + } + + return $this; + } + + /** + * Prepares the model database connection, determines the table name, + * and loads column information. + * + * @return void + */ + protected function _initialize() + { + if ( ! is_object($this->_db)) + { + // Get database instance + $this->_db = Database::instance($this->_db); + } + + if (empty($this->_table_name)) + { + // Table name is the same as the object name + $this->_table_name = $this->_object_name; + + if ($this->_table_names_plural === TRUE) + { + // Make the table name plural + $this->_table_name = Inflector::plural($this->_table_name); + } + } + + foreach ($this->_belongs_to as $alias => $details) + { + $defaults['model'] = $alias; + $defaults['foreign_key'] = $alias.$this->_foreign_key_suffix; + + $this->_belongs_to[$alias] = array_merge($defaults, $details); + } + + foreach ($this->_has_one as $alias => $details) + { + $defaults['model'] = $alias; + $defaults['foreign_key'] = $this->_object_name.$this->_foreign_key_suffix; + + $this->_has_one[$alias] = array_merge($defaults, $details); + } + + foreach ($this->_has_many as $alias => $details) + { + $defaults['model'] = Inflector::singular($alias); + $defaults['foreign_key'] = $this->_object_name.$this->_foreign_key_suffix; + $defaults['through'] = NULL; + $defaults['far_key'] = Inflector::singular($alias).$this->_foreign_key_suffix; + + $this->_has_many[$alias] = array_merge($defaults, $details); + } + + // Load column information + $this->reload_columns(); + } + + /** + * Initializes validation rules, callbacks, filters, and labels + * + * @return void + */ + protected function _validate() + { + $this->_validate = Validate::factory($this->_object); + + foreach ($this->_rules as $field => $rules) + { + $this->_validate->rules($field, $rules); + } + + foreach ($this->_filters as $field => $filters) + { + $this->_validate->filters($field, $filters); + } + + // Use column names by default for labels + $columns = array_keys($this->_table_columns); + + // Merge user-defined labels + $labels = array_merge(array_combine($columns, $columns), $this->_labels); + + foreach ($labels as $field => $label) + { + $this->_validate->label($field, $label); + } + + foreach ($this->_callbacks as $field => $callbacks) + { + foreach ($callbacks as $callback) + { + if (is_string($callback) AND method_exists($this, $callback)) + { + // Callback method exists in current ORM model + $this->_validate->callback($field, array($this, $callback)); + } + else + { + // Try global function + $this->_validate->callback($field, $callback); + } + } + } + } + + /** + * Returns the values of this object as an array, including any related one-one + * models that have already been loaded using with() + * + * @return array + */ + public function as_array() + { + $object = array(); + + foreach ($this->_object as $key => $val) + { + // Call __get for any user processing + $object[$key] = $this->__get($key); + } + + foreach ($this->_related as $key => $model) + { + // Include any related objects that are already loaded + $object[$key] = $model->as_array(); + } + + return $object; + } + + /** + * Binds another one-to-one object to this model. One-to-one objects + * can be nested using 'object1:object2' syntax + * + * @param string target model to bind to + * @return void + */ + public function with($target_path) + { + if (isset($this->_with_applied[$target_path])) + { + // Don't join anything already joined + return $this; + } + + // Split object parts + $aliases = explode(':', $target_path); + $target = $this; + foreach ($aliases as $alias) + { + // Go down the line of objects to find the given target + $parent = $target; + $target = $parent->_related($alias); + + if ( ! $target) + { + // Can't find related object + return $this; + } + } + + // Target alias is at the end + $target_alias = $alias; + + // Pop-off top alias to get the parent path (user:photo:tag becomes user:photo - the parent table prefix) + array_pop($aliases); + $parent_path = implode(':', $aliases); + + if (empty($parent_path)) + { + // Use this table name itself for the parent path + $parent_path = $this->_table_name; + } + else + { + if( ! isset($this->_with_applied[$parent_path])) + { + // If the parent path hasn't been joined yet, do it first (otherwise LEFT JOINs fail) + $this->with($parent_path); + } + } + + // Add to with_applied to prevent duplicate joins + $this->_with_applied[$target_path] = TRUE; + + // Use the keys of the empty object to determine the columns + foreach (array_keys($target->_object) as $column) + { + // Skip over ignored columns + if( ! in_array($column, $target->_ignored_columns)) + { + $name = $target_path.'.'.$column; + $alias = $target_path.':'.$column; + + // Add the prefix so that load_result can determine the relationship + $this->select(array($name, $alias)); + } + } + + if (isset($parent->_belongs_to[$target_alias])) + { + // Parent belongs_to target, use target's primary key and parent's foreign key + $join_col1 = $target_path.'.'.$target->_primary_key; + $join_col2 = $parent_path.'.'.$parent->_belongs_to[$target_alias]['foreign_key']; + } + else + { + // Parent has_one target, use parent's primary key as target's foreign key + $join_col1 = $parent_path.'.'.$parent->_primary_key; + $join_col2 = $target_path.'.'.$parent->_has_one[$target_alias]['foreign_key']; + } + + // Join the related object into the result + $this->join(array($target->_table_name, $target_path), 'LEFT')->on($join_col1, '=', $join_col2); + + return $this; + } + + /** + * Initializes the Database Builder to given query type + * + * @param int Type of Database query + * @return ORM + */ + protected function _build($type) + { + // Construct new builder object based on query type + switch ($type) + { + case Database::SELECT: + $this->_db_builder = DB::select(); + break; + case Database::UPDATE: + $this->_db_builder = DB::update($this->_table_name); + break; + case Database::DELETE: + $this->_db_builder = DB::delete($this->_table_name); + } + + // Process pending database method calls + foreach ($this->_db_pending as $method) + { + $name = $method['name']; + $args = $method['args']; + + $this->_db_applied[$name] = $name; + + call_user_func_array(array($this->_db_builder, $name), $args); + } + + return $this; + } + + /** + * Loads the given model + * + * @return ORM + */ + protected function _load() + { + if ( ! $this->_loaded AND ! $this->empty_pk() AND ! isset($this->_changed[$this->_primary_key])) + { + // Only load if it hasn't been loaded, and a primary key is specified and hasn't been modified + return $this->find($this->pk()); + } + } + + /** + * Finds and loads a single database row into the object. + * + * @chainable + * @param mixed primary key + * @return ORM + */ + public function find($id = NULL) + { + if ( ! empty($this->_load_with)) + { + foreach ($this->_load_with as $alias) + { + // Bind relationship + $this->with($alias); + } + } + + $this->_build(Database::SELECT); + + if ($id !== NULL) + { + // Search for a specific column + $this->_db_builder->where($this->_table_name.'.'.$this->_primary_key, '=', $id); + } + + return $this->_load_result(FALSE); + } + + /** + * Finds multiple database rows and returns an iterator of the rows found. + * + * @chainable + * @return Database_Result + */ + public function find_all() + { + if ( ! empty($this->_load_with)) + { + foreach ($this->_load_with as $alias) + { + // Bind relationship + $this->with($alias); + } + } + + $this->_build(Database::SELECT); + + return $this->_load_result(TRUE); + } + + /** + * Validates the current model's data + * + * @return boolean + */ + public function check() + { + if ( ! isset($this->_validate)) + { + // Initialize the validation object + $this->_validate(); + } + else + { + // Validation object has been created, just exchange the data array + $this->_validate->exchangeArray($this->_object); + } + + if ($this->_validate->check()) + { + // Fields may have been modified by filters + $this->_object = array_merge($this->_object, $this->_validate->getArrayCopy()); + + return TRUE; + } + else + { + return FALSE; + } + } + + /** + * Saves the current object. + * + * @chainable + * @return ORM + */ + public function save() + { + if (empty($this->_changed)) + return $this; + + $data = array(); + foreach ($this->_changed as $column) + { + // Compile changed data + $data[$column] = $this->_object[$column]; + } + + if ( ! $this->empty_pk() AND ! isset($this->_changed[$this->_primary_key])) + { + // Primary key isn't empty and hasn't been changed so do an update + + if (is_array($this->_updated_column)) + { + // Fill the updated column + $column = $this->_updated_column['column']; + $format = $this->_updated_column['format']; + + $data[$column] = $this->_object[$column] = ($format === TRUE) ? time() : date($format); + } + + $query = DB::update($this->_table_name) + ->set($data) + ->where($this->_primary_key, '=', $this->pk()) + ->execute($this->_db); + + // Object has been saved + $this->_saved = TRUE; + } + else + { + if (is_array($this->_created_column)) + { + // Fill the created column + $column = $this->_created_column['column']; + $format = $this->_created_column['format']; + + $data[$column] = $this->_object[$column] = ($format === TRUE) ? time() : date($format); + } + + $result = DB::insert($this->_table_name) + ->columns(array_keys($data)) + ->values(array_values($data)) + ->execute($this->_db); + + if ($result) + { + if ($this->empty_pk()) + { + // Load the insert id as the primary key + // $result is array(insert_id, total_rows) + $this->_object[$this->_primary_key] = $result[0]; + } + + // Object is now loaded and saved + $this->_loaded = $this->_saved = TRUE; + } + } + + if ($this->_saved === TRUE) + { + // All changes have been saved + $this->_changed = array(); + } + + return $this; + } + + /** + * Updates all existing records + * + * @chainable + * @return ORM + */ + public function save_all() + { + $this->_build(Database::UPDATE); + + if (empty($this->_changed)) + return $this; + + $data = array(); + foreach ($this->_changed as $column) + { + // Compile changed data omitting ignored columns + $data[$column] = $this->_object[$column]; + } + + if (is_array($this->_updated_column)) + { + // Fill the updated column + $column = $this->_updated_column['column']; + $format = $this->_updated_column['format']; + + $data[$column] = $this->_object[$column] = ($format === TRUE) ? time() : date($format); + } + + $this->_db_builder->set($data)->execute($this->_db); + + return $this; + } + + /** + * Deletes the current object from the database. This does NOT destroy + * relationships that have been created with other objects. + * + * @chainable + * @param mixed id to delete + * @return ORM + */ + public function delete($id = NULL) + { + if ($id === NULL) + { + // Use the the primary key value + $id = $this->pk(); + } + + if ( ! empty($id) OR $id === '0') + { + // Delete the object + DB::delete($this->_table_name) + ->where($this->_primary_key, '=', $id) + ->execute($this->_db); + } + + return $this; + } + + /** + * Delete all objects in the associated table. This does NOT destroy + * relationships that have been created with other objects. + * + * @chainable + * @return ORM + */ + public function delete_all() + { + $this->_build(Database::DELETE); + + $this->_db_builder->execute($this->_db); + + return $this->clear(); + } + + /** + * Unloads the current object and clears the status. + * + * @chainable + * @return ORM + */ + public function clear() + { + // Create an array with all the columns set to NULL + $values = array_combine(array_keys($this->_table_columns), array_fill(0, count($this->_table_columns), NULL)); + + // Replace the object and reset the object status + $this->_object = $this->_changed = $this->_related = array(); + + // Replace the current object with an empty one + $this->_load_values($values); + + $this->reset(); + + return $this; + } + + /** + * Reloads the current object from the database. + * + * @chainable + * @return ORM + */ + public function reload() + { + $primary_key = $this->pk(); + + // Replace the object and reset the object status + $this->_object = $this->_changed = $this->_related = array(); + + return $this->find($primary_key); + } + + /** + * Reload column definitions. + * + * @chainable + * @param boolean force reloading + * @return ORM + */ + public function reload_columns($force = FALSE) + { + if ($force === TRUE OR empty($this->_table_columns)) + { + if (isset(ORM::$_column_cache[$this->_object_name])) + { + // Use cached column information + $this->_table_columns = ORM::$_column_cache[$this->_object_name]; + } + else + { + // Grab column information from database + $this->_table_columns = $this->list_columns(TRUE); + + // Load column cache + ORM::$_column_cache[$this->_object_name] = $this->_table_columns; + } + } + + return $this; + } + + /** + * Tests if this object has a relationship to a different model. + * + * @param string alias of the has_many "through" relationship + * @param ORM related ORM model + * @return boolean + */ + public function has($alias, $model) + { + // Return count of matches as boolean + return (bool) DB::select(array('COUNT("*")', 'records_found')) + ->from($this->_has_many[$alias]['through']) + ->where($this->_has_many[$alias]['foreign_key'], '=', $this->pk()) + ->where($this->_has_many[$alias]['far_key'], '=', $model->pk()) + ->execute($this->_db) + ->get('records_found'); + } + + /** + * Adds a new relationship to between this model and another. + * + * @param string alias of the has_many "through" relationship + * @param ORM related ORM model + * @param array additional data to store in "through"/pivot table + * @return ORM + */ + public function add($alias, ORM $model, $data = NULL) + { + $columns = array($this->_has_many[$alias]['foreign_key'], $this->_has_many[$alias]['far_key']); + $values = array($this->pk(), $model->pk()); + + if ($data !== NULL) + { + // Additional data stored in pivot table + $columns = array_merge($columns, array_keys($data)); + $values = array_merge($values, array_values($data)); + } + + DB::insert($this->_has_many[$alias]['through']) + ->columns($columns) + ->values($values) + ->execute($this->_db); + + return $this; + } + + /** + * Removes a relationship between this model and another. + * + * @param string alias of the has_many "through" relationship + * @param ORM related ORM model + * @return ORM + */ + public function remove($alias, ORM $model) + { + DB::delete($this->_has_many[$alias]['through']) + ->where($this->_has_many[$alias]['foreign_key'], '=', $this->pk()) + ->where($this->_has_many[$alias]['far_key'], '=', $model->pk()) + ->execute($this->_db); + + return $this; + } + + /** + * Count the number of records in the table. + * + * @return integer + */ + public function count_all() + { + $selects = array(); + + foreach ($this->_db_pending as $key => $method) + { + if ($method['name'] == 'select') + { + // Ignore any selected columns for now + $selects[] = $method; + unset($this->_db_pending[$key]); + } + } + + $this->_build(Database::SELECT); + + $records = (int) $this->_db_builder->from($this->_table_name) + ->select(array('COUNT("*")', 'records_found')) + ->execute($this->_db) + ->get('records_found'); + + // Add back in selected columns + $this->_db_pending += $selects; + + $this->reset(); + + // Return the total number of records in a table + return $records; + } + + /** + * Proxy method to Database list_columns. + * + * @return array + */ + public function list_columns() + { + // Proxy to database + return $this->_db->list_columns($this->_table_name); + } + + /** + * Proxy method to Database field_data. + * + * @chainable + * @param string SQL query to clear + * @return ORM + */ + public function clear_cache($sql = NULL) + { + // Proxy to database + $this->_db->clear_cache($sql); + + ORM::$_column_cache = array(); + + return $this; + } + + /** + * Returns an ORM model for the given one-one related alias + * + * @param string alias name + * @return ORM + */ + protected function _related($alias) + { + if (isset($this->_related[$alias])) + { + return $this->_related[$alias]; + } + elseif (isset($this->_has_one[$alias])) + { + return $this->_related[$alias] = ORM::factory($this->_has_one[$alias]['model']); + } + elseif (isset($this->_belongs_to[$alias])) + { + return $this->_related[$alias] = ORM::factory($this->_belongs_to[$alias]['model']); + } + else + { + return FALSE; + } + } + + /** + * Loads an array of values into into the current object. + * + * @chainable + * @param array values to load + * @return ORM + */ + protected function _load_values(array $values) + { + if (array_key_exists($this->_primary_key, $values)) + { + // Set the loaded and saved object status based on the primary key + $this->_loaded = $this->_saved = ($values[$this->_primary_key] !== NULL); + } + + // Related objects + $related = array(); + + foreach ($values as $column => $value) + { + if (strpos($column, ':') === FALSE) + { + if ( ! isset($this->_changed[$column])) + { + $this->_object[$column] = $value; + } + } + else + { + list ($prefix, $column) = explode(':', $column, 2); + + $related[$prefix][$column] = $value; + } + } + + if ( ! empty($related)) + { + foreach ($related as $object => $values) + { + // Load the related objects with the values in the result + $this->_related($object)->_load_values($values); + } + } + + return $this; + } + + /** + * Loads a database result, either as a new object for this model, or as + * an iterator for multiple rows. + * + * @chainable + * @param boolean return an iterator or load a single row + * @return ORM for single rows + * @return ORM_Iterator for multiple rows + */ + protected function _load_result($multiple = FALSE) + { + $this->_db_builder->from($this->_table_name); + + if ($multiple === FALSE) + { + // Only fetch 1 record + $this->_db_builder->limit(1); + } + + // Select all columns by default + $this->_db_builder->select($this->_table_name.'.*'); + + if ( ! isset($this->_db_applied['order_by']) AND ! empty($this->_sorting)) + { + foreach ($this->_sorting as $column => $direction) + { + if (strpos($column, '.') === FALSE) + { + // Sorting column for use in JOINs + $column = $this->_table_name.'.'.$column; + } + + $this->_db_builder->order_by($column, $direction); + } + } + + if ($multiple === TRUE) + { + // Return database iterator casting to this object type + $result = $this->_db_builder->as_object(get_class($this))->execute($this->_db); + + $this->reset(); + + return $result; + } + else + { + // Load the result as an associative array + $result = $this->_db_builder->as_assoc()->execute($this->_db); + + $this->reset(); + + if ($result->count() === 1) + { + // Load object values + $this->_load_values($result->current()); + } + else + { + // Clear the object, nothing was found + $this->clear(); + } + + return $this; + } + } + + /** + * Returns the value of the primary key + * + * @return mixed primary key + */ + public function pk() + { + return $this->_object[$this->_primary_key]; + } + + /** + * Returns whether or not primary key is empty + * + * @return bool + */ + protected function empty_pk() + { + return (empty($this->_object[$this->_primary_key]) AND $this->_object[$this->_primary_key] !== '0'); + } + + /** + * Returns last executed query + * + * @return string + */ + public function last_query() + { + return $this->_db->last_query; + } + + /** + * Clears query builder. Passing FALSE is useful to keep the existing + * query conditions for another query. + * + * @param bool Pass FALSE to avoid resetting on the next call + */ + public function reset($next = TRUE) + { + if ($next AND $this->_db_reset) + { + $this->_db_pending = array(); + $this->_db_applied = array(); + $this->_db_builder = NULL; + $this->_with_applied = array(); + } + + // Reset on the next call? + $this->_db_reset = $next; + + return $this; + } + +} // End ORM diff --git a/includes/kohana/modules/orm/classes/orm.php b/includes/kohana/modules/orm/classes/orm.php new file mode 100644 index 00000000..63baa131 --- /dev/null +++ b/includes/kohana/modules/orm/classes/orm.php @@ -0,0 +1,3 @@ + array('source' => 'query_string', 'key' => 'page'), + 'total_items' => 0, + 'items_per_page' => 10, + 'view' => 'pagination/basic', + 'auto_hide' => TRUE, + 'first_page_in_url' => FALSE, + ); + + // Current page number + protected $current_page; + + // Total item count + protected $total_items; + + // How many items to show per page + protected $items_per_page; + + // Total page count + protected $total_pages; + + // Item offset for the first item displayed on the current page + protected $current_first_item; + + // Item offset for the last item displayed on the current page + protected $current_last_item; + + // Previous page number; FALSE if the current page is the first one + protected $previous_page; + + // Next page number; FALSE if the current page is the last one + protected $next_page; + + // First page number; FALSE if the current page is the first one + protected $first_page; + + // Last page number; FALSE if the current page is the last one + protected $last_page; + + // Query offset + protected $offset; + + /** + * Creates a new Pagination object. + * + * @param array configuration + * @return Pagination + */ + public static function factory(array $config = array()) + { + return new Pagination($config); + } + + /** + * Creates a new Pagination object. + * + * @param array configuration + * @return void + */ + public function __construct(array $config = array()) + { + // Overwrite system defaults with application defaults + $this->config = $this->config_group() + $this->config; + + // Pagination setup + $this->setup($config); + } + + /** + * Retrieves a pagination config group from the config file. One config group can + * refer to another as its parent, which will be recursively loaded. + * + * @param string pagination config group; "default" if none given + * @return array config settings + */ + public function config_group($group = 'default') + { + // Load the pagination config file + $config_file = Kohana::config('pagination'); + + // Initialize the $config array + $config['group'] = (string) $group; + + // Recursively load requested config groups + while (isset($config['group']) AND isset($config_file->$config['group'])) + { + // Temporarily store config group name + $group = $config['group']; + unset($config['group']); + + // Add config group values, not overwriting existing keys + $config += $config_file->$group; + } + + // Get rid of possible stray config group names + unset($config['group']); + + // Return the merged config group settings + return $config; + } + + /** + * Loads configuration settings into the object and (re)calculates pagination if needed. + * Allows you to update config settings after a Pagination object has been constructed. + * + * @param array configuration + * @return object Pagination + */ + public function setup(array $config = array()) + { + if (isset($config['group'])) + { + // Recursively load requested config groups + $config += $this->config_group($config['group']); + } + + // Overwrite the current config settings + $this->config = $config + $this->config; + + // Only (re)calculate pagination when needed + if ($this->current_page === NULL + OR isset($config['current_page']) + OR isset($config['total_items']) + OR isset($config['items_per_page'])) + { + // Retrieve the current page number + if ( ! empty($this->config['current_page']['page'])) + { + // The current page number has been set manually + $this->current_page = (int) $this->config['current_page']['page']; + } + else + { + switch ($this->config['current_page']['source']) + { + case 'query_string': + $this->current_page = isset($_GET[$this->config['current_page']['key']]) + ? (int) $_GET[$this->config['current_page']['key']] + : 1; + break; + + case 'route': + $this->current_page = (int) Request::current()->param($this->config['current_page']['key'], 1); + break; + } + } + + // Calculate and clean all pagination variables + $this->total_items = (int) max(0, $this->config['total_items']); + $this->items_per_page = (int) max(1, $this->config['items_per_page']); + $this->total_pages = (int) ceil($this->total_items / $this->items_per_page); + $this->current_page = (int) min(max(1, $this->current_page), max(1, $this->total_pages)); + $this->current_first_item = (int) min((($this->current_page - 1) * $this->items_per_page) + 1, $this->total_items); + $this->current_last_item = (int) min($this->current_first_item + $this->items_per_page - 1, $this->total_items); + $this->previous_page = ($this->current_page > 1) ? $this->current_page - 1 : FALSE; + $this->next_page = ($this->current_page < $this->total_pages) ? $this->current_page + 1 : FALSE; + $this->first_page = ($this->current_page === 1) ? FALSE : 1; + $this->last_page = ($this->current_page >= $this->total_pages) ? FALSE : $this->total_pages; + $this->offset = (int) (($this->current_page - 1) * $this->items_per_page); + } + + // Chainable method + return $this; + } + + /** + * Generates the full URL for a certain page. + * + * @param integer page number + * @return string page URL + */ + public function url($page = 1) + { + // Clean the page number + $page = max(1, (int) $page); + + // No page number in URLs to first page + if ($page === 1 AND ! $this->config['first_page_in_url']) + { + $page = NULL; + } + + switch ($this->config['current_page']['source']) + { + case 'query_string': + return URL::site(Request::current()->uri).URL::query(array($this->config['current_page']['key'] => $page)); + + case 'route': + return URL::site(Request::current()->uri(array($this->config['current_page']['key'] => $page))).URL::query(); + } + + return '#'; + } + + /** + * Checks whether the given page number exists. + * + * @param integer page number + * @return boolean + * @since 3.0.7 + */ + public function valid_page($page) + { + // Page number has to be a clean integer + if ( ! Validate::digit($page)) + return FALSE; + + return $page > 0 AND $page <= $this->total_pages; + } + + /** + * Renders the pagination links. + * + * @param mixed string of the view to use, or a Kohana_View object + * @return string pagination output (HTML) + */ + public function render($view = NULL) + { + // Automatically hide pagination whenever it is superfluous + if ($this->config['auto_hide'] === TRUE AND $this->total_pages <= 1) + return ''; + + if ($view === NULL) + { + // Use the view from config + $view = $this->config['view']; + } + + if ( ! $view instanceof Kohana_View) + { + // Load the view file + $view = View::factory($view); + } + + // Pass on the whole Pagination object + return $view->set(get_object_vars($this))->set('page', $this)->render(); + } + + /** + * Renders the pagination links. + * + * @return string pagination output (HTML) + */ + public function __toString() + { + return $this->render(); + } + + /** + * Returns a Pagination property. + * + * @param string URI of the request + * @return mixed Pagination property; NULL if not found + */ + public function __get($key) + { + return isset($this->$key) ? $this->$key : NULL; + } + + /** + * Updates a single config setting, and recalculates pagination if needed. + * + * @param string config key + * @param mixed config value + * @return void + */ + public function __set($key, $value) + { + $this->setup(array($key => $value)); + } + +} // End Pagination \ No newline at end of file diff --git a/includes/kohana/modules/pagination/classes/pagination.php b/includes/kohana/modules/pagination/classes/pagination.php new file mode 100644 index 00000000..6be4b159 --- /dev/null +++ b/includes/kohana/modules/pagination/classes/pagination.php @@ -0,0 +1,3 @@ + array( + 'current_page' => array('source' => 'query_string', 'key' => 'page'), // source: "query_string" or "route" + 'total_items' => 0, + 'items_per_page' => 10, + 'view' => 'pagination/basic', + 'auto_hide' => TRUE, + 'first_page_in_url' => FALSE, + ), + +); diff --git a/includes/kohana/modules/pagination/views/pagination/basic.php b/includes/kohana/modules/pagination/views/pagination/basic.php new file mode 100644 index 00000000..8ec73843 --- /dev/null +++ b/includes/kohana/modules/pagination/views/pagination/basic.php @@ -0,0 +1,37 @@ ++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
\ No newline at end of file diff --git a/includes/kohana/modules/pagination/views/pagination/floating.php b/includes/kohana/modules/pagination/views/pagination/floating.php new file mode 100644 index 00000000..f776fd14 --- /dev/null +++ b/includes/kohana/modules/pagination/views/pagination/floating.php @@ -0,0 +1,94 @@ += $n4); + +// Point $n3 between $n2 and $n4 +$n3 = (int) (($n2 + $n4) / 2); +$use_n3 = ($use_middle && (($n4 - $n2) > 1)); + +// Point $n6 between $n5 and $n7 +$n6 = (int) (($n5 + $n7) / 2); +$use_n6 = ($use_middle && (($n7 - $n5) > 1)); + +// Links to display as array(page => content) +$links = array(); + +// Generate links data in accordance with calculated numbers +for ($i = $n1; $i <= $n2; $i++) +{ + $links[$i] = $i; +} +if ($use_n3) +{ + $links[$n3] = '…'; +} +for ($i = $n4; $i <= $n5; $i++) +{ + $links[$i] = $i; +} +if ($use_n6) +{ + $links[$n6] = '…'; +} +for ($i = $n7; $i <= $n8; $i++) +{ + $links[$i] = $i; +} + +?> ++ + + + + + + + + + + + + + $content): ?> + + + + + + + + + + + + + + + + + + + + + +
\ No newline at end of file diff --git a/includes/kohana/modules/unittest/README.markdown b/includes/kohana/modules/unittest/README.markdown new file mode 100644 index 00000000..f19404a3 --- /dev/null +++ b/includes/kohana/modules/unittest/README.markdown @@ -0,0 +1,70 @@ +# Kohana-PHPUnit integration + +This module integrates PHPUnit with Kohana. + +If you look through any of the tests provided in this module you'll probably notice all theHorribleCamelCase. +I've chosen to do this because it's part of the PHPUnit coding conventions and is required for certain features such as auto documentation. + +## Requirements + +* [PHPUnit](http://www.phpunit.de/) >= 3.4 + +### Optional extras + +* The [Archive module](http://github.com/BRMatt/kohana-archive) is required if you want to download code coverage reports from the web ui, however you can also view them without downloading. + +## Installation + +**Step 0**: Download this module! + +To get it from git execute the following command in the root of your project: + + $ git submodule add git://github.com/kohana/unittest.git modules/unittest + +And watch the gitorious magic... + +Of course, you can always download the code from the [github project](http://github.com/kohana/unittest) as an archive. + +The following instructions will assume you've moved it to `modules/unittest`, if you haven't then you should update all paths accordingly. + +**Step 1**: Enable this module in your bootstrap file: + + /** + * Enable modules. Modules are referenced by a relative or absolute path. + */ + Kohana::modules(array( + 'unittest' => MODPATH.'unittest', // PHPUnit integration + )); + +**Step 2**: In your app's bootstrap file modify the lines where the request is handled, which by default looks like: + + /** + * Execute the main request using PATH_INFO. If no URI source is specified, + * the URI will be automatically detected. + */ + echo Request::instance($_SERVER['PATH_INFO']) + ->execute() + ->send_headers() + ->response; + +To: + + if ( ! defined('SUPPRESS_REQUEST')) + { + /** + * Execute the main request using PATH_INFO. If no URI source is specified, + * the URI will be automatically detected. + */ + echo Request::instance($_SERVER['PATH_INFO']) + ->execute() + ->send_headers() + ->response; + } + +**Step 3**: Create a folder called `unittest` in your app's cache dir (`APPPATH/cache`). If you don't want to use this path for storing generated reports, skip this step and change the config file. + +Note: make sure the settings in `config/unittest.php` are correct for your environment. If they aren't, copy the file to `application/config/unittest.php` and change the values accordingly. + +**Step 4**: Start testing! + +You can find more info and tutorials in the [guide/](http://github.com/kohana/unittest/tree/master/guide/) directory. diff --git a/includes/kohana/modules/unittest/classes/controller/unittest.php b/includes/kohana/modules/unittest/classes/controller/unittest.php new file mode 100644 index 00000000..283be07b --- /dev/null +++ b/includes/kohana/modules/unittest/classes/controller/unittest.php @@ -0,0 +1,359 @@ + + * @author Paul Banks + * @copyright (c) 2008-2009 Kohana Team + * @license http://kohanaphp.com/license + */ + +Class Controller_UnitTest extends Controller_Template +{ + /** + * Whether the archive module is available + * @var boolean + */ + protected $cc_archive_available = FALSE; + + /** + * Unittest config + * @var Kohana_Config + */ + protected $config = NULL; + + /** + * The uri by which the report uri will be executed + * @var string + */ + protected $report_uri = ''; + + /** + * The uri by which the run action will be executed + * @var string + */ + protected $run_uri = ''; + + /** + * Is the XDEBUG extension loaded? + * @var boolean + */ + protected $xdebug_loaded = FALSE; + + /** + * Template + * @var string + */ + public $template = 'unittest/layout'; + + /** + * Loads test suite + */ + public function before() + { + parent::before(); + + if ( ! Kohana_Tests::enabled()) + { + // Pretend this is a normal 404 error... + $this->status = 404; + + throw new Kohana_Request_Exception('Unable to find a route to match the URI: :uri', + array(':uri' => $this->request->uri)); + } + + // Prevent the whitelist from being autoloaded, but allow the blacklist + // to be loaded + Kohana_Tests::configure_environment(FALSE); + + $this->config = Kohana::config('unittest'); + + // This just stops some very very long lines + $route = Route::get('unittest'); + $this->report_uri = $route->uri(array('action' => 'report')); + $this->run_uri = $route->uri(array('action' => 'run')); + + // Switch used to disable cc settings + $this->xdebug_loaded = extension_loaded('xdebug'); + $this->cc_archive_enabled = class_exists('Archive'); + + Kohana_View::set_global('xdebug_enabled', $this->xdebug_loaded); + Kohana_View::set_global('cc_archive_enabled', $this->cc_archive_enabled); + } + + /** + * Handles index page for /unittest/ and /unittest/index/ + */ + public function action_index() + { + $this->template->body = View::factory('unittest/index') + ->set('run_uri', $this->run_uri) + ->set('report_uri', $this->report_uri) + ->set('whitelistable_items', $this->get_whitelistable_items()) + ->set('groups', $this->get_groups_list(Kohana_Tests::suite())); + } + + /** + * Handles report generation + */ + public function action_report() + { + // Fairly foolproof + if ( ! $this->config->cc_report_path AND ! class_exists('Archive')) + { + throw new Kohana_Exception('Cannot generate report'); + } + + // We don't want to use the HTML layout, we're sending the user 100111011100110010101100 + $this->auto_render = FALSE; + + $suite = Kohana_Tests::suite(); + $temp_path = rtrim($this->config->temp_path, '/').'/'; + $group = (array) Arr::get($_GET, 'group', array()); + + // Stop unittest from interpretting "all groups" as "no groups" + if (empty($group) OR empty($group[0])) + { + $group = array(); + } + + if (Arr::get($_GET, 'use_whitelist', FALSE)) + { + $this->whitelist(Arr::get($_GET, 'whitelist', array())); + } + + $runner = new Kohana_Unittest_Runner($suite); + + // If the user wants to download a report + if ($this->cc_archive_enabled AND Arr::get($_GET, 'archive') === '1') + { + // $report is the actual directory of the report, + // $folder is the name component of directory + list($report, $folder) = $runner->generate_report($group, $temp_path); + + $archive = Archive::factory('zip'); + + // TODO: Include the test results? + $archive->add($report, 'report', TRUE); + + $filename = $folder.'.zip'; + + $archive->save($temp_path.$filename); + + // It'd be nice to clear up afterwards but by deleting the report dir we corrupt the archive + // And once the archive has been sent to the user Request stops the script so we can't delete anything + // It'll be up to the user to delete files periodically + $this->request->send_file($temp_path.$filename, $filename); + } + else + { + $folder = trim($this->config->cc_report_path, '/').'/'; + $path = DOCROOT.$folder; + + if ( ! file_exists($path)) + { + throw new Kohana_Exception('Report directory :dir does not exist', array(':dir' => $path)); + } + + if ( ! is_writable($path)) + { + throw new Kohana_Exception('Script doesn\'t have permission to write to report dir :dir ', array(':dir' => $path)); + } + + $runner->generate_report($group, $path, FALSE); + + $this->request->redirect(URL::base(FALSE, TRUE).$folder.'index.html'); + } + } + + /** + * Handles test running interface + */ + public function action_run() + { + $this->template->body = View::factory('unittest/results'); + + // Get the test suite and work out which groups we're testing + $suite = Kohana_Tests::suite(); + $group = (array) Arr::get($_GET, 'group', array()); + + + // Stop phpunit from interpretting "all groups" as "no groups" + if (empty($group) OR empty($group[0])) + { + $group = array(); + } + + // Only collect code coverage if the user asked for it + $collect_cc = (bool) Arr::get($_GET, 'collect_cc', FALSE); + + if ($collect_cc AND Arr::get($_GET, 'use_whitelist', FALSE)) + { + $whitelist = $this->whitelist(Arr::get($_GET, 'whitelist', array())); + } + + $runner = new Kohana_Unittest_Runner($suite); + + try + { + $runner->run($group, $collect_cc); + + if ($collect_cc) + { + $this->template->body->set('coverage', $runner->calculate_cc_percentage()); + } + + if (isset($whitelist)) + { + $this->template->body->set('coverage_explanation', $this->nice_whitelist_explanation($whitelist)); + } + } + catch(Kohana_Exception $e) + { + // Code coverage is not allowed, possibly xdebug disabled? + // TODO: Tell the user this? + $runner->run($group); + } + + // Show some results + $this->template->body + ->set('results', $runner->results) + ->set('totals', $runner->totals) + ->set('time', $this->nice_time($runner->time)) + + // Sets group to the currently selected group, or default all groups + ->set('group', Arr::get($this->get_groups_list($suite), reset($group), 'All groups')) + ->set('groups', $this->get_groups_list($suite)) + + ->set('report_uri', $this->report_uri.url::query()) + + // Whitelist related stuff + ->set('whitelistable_items', $this->get_whitelistable_items()) + ->set('whitelisted_items', isset($whitelist) ? array_keys($whitelist) : array()) + ->set('whitelist', ! empty($whitelist)); + } + + /** + * Get the list of groups from the test suite, sorted with 'All groups' prefixed + * + * @return array Array of groups in the test suite + */ + protected function get_groups_list($suite) + { + // Make groups aray suitable for drop down + $groups = $suite->getGroups(); + if (count($groups) > 0) + { + sort($groups); + $groups = array_combine($groups, $groups); + } + return array('' => 'All Groups') + $groups; + } + + /** + * Gets a list of items that are whitelistable + * + * @return array + */ + protected function get_whitelistable_items() + { + static $whitelist; + + if (count($whitelist)) + { + return $whitelist; + } + + $whitelist = array(); + + $whitelist['k_app'] = 'Application'; + + $k_modules = array_keys(Kohana::modules()); + + $whitelist += array_map('ucfirst', array_combine($k_modules, $k_modules)); + + $whitelist['k_sys'] = 'Kohana Core'; + + return $whitelist; + } + + /** + * Whitelists a specified set of modules specified by the user + * + * @param array $modules + */ + protected function whitelist(array $modules) + { + $k_modules = Kohana::modules(); + $whitelist = array(); + + // Make sure our whitelist is valid + foreach ($modules as $item) + { + if (isset($k_modules[$item])) + { + $whitelist[$item] = $k_modules[$item]; + } + elseif ($item === 'k_app') + { + $whitelist[$item] = APPPATH; + } + elseif ($item === 'k_sys') + { + $whitelist[$item] = SYSPATH; + } + } + + if (count($whitelist)) + { + Kohana_Tests::whitelist($whitelist); + } + + return $whitelist; + } + + /** + * Prettifies the list of whitelisted modules + * + * @param array Array of whitelisted items + * @return string + */ + protected function nice_whitelist_explanation(array $whitelist) + { + $items = array_intersect_key($this->get_whitelistable_items(), $whitelist); + + return implode(', ', $items); + } + + protected function nice_time($time) + { + $parts = array(); + + if ($time > DATE::DAY) + { + $parts[] = floor($time/DATE::DAY).'d'; + $time = $time % DATE::DAY; + } + + if ($time > DATE::HOUR) + { + $parts[] = floor($time/DATE::HOUR).'h'; + $time = $time % DATE::HOUR; + } + + if ($time > DATE::MINUTE) + { + $parts[] = floor($time/DATE::MINUTE).'m'; + $time = $time % DATE::MINUTE; + } + + if ($time > 0) + { + $parts[] = round($time, 1).'s'; + } + + return implode(' ', $parts); + } +} // End Controller_PHPUnit diff --git a/includes/kohana/modules/unittest/classes/kohana/tests.php b/includes/kohana/modules/unittest/classes/kohana/tests.php new file mode 100644 index 00000000..39fa3640 --- /dev/null +++ b/includes/kohana/modules/unittest/classes/kohana/tests.php @@ -0,0 +1,263 @@ + + * @author Paul Banks + * @copyright (c) 2008-2009 Kohana Team + * @license http://kohanaphp.com/license + */ +class Kohana_Tests +{ + static protected $cache = array(); + + /** + * Loads test files if they cannot be found by kohana + * @param
+ * array(
+ * 'coverage' => $coverage_percent_for_file,
+ * 'loc' => $lines_of_code,
+ * 'locExecutable' => $lines_of_executable_code,
+ * 'locExecuted' => $lines_of_code_executed
+ * );
+ *
+ *
+ * @return array Statistics for code coverage of each file
+ */
+ public function calculate_cc()
+ {
+ if ($this->result->getCollectCodeCoverageInformation())
+ {
+ $coverage = $this->result->getCodeCoverageInformation();
+
+ $coverage_summary = PHPUnit_Util_CodeCoverage::getSummary($coverage);
+
+ $stats = array();
+
+ foreach ($coverage_summary as $file => $_lines)
+ {
+ $stats[$file] = PHPUnit_Util_CodeCoverage::getStatistics($coverage_summary, $file);
+ }
+
+ return $stats;
+ }
+
+ return FALSE;
+ }
+
+ /**
+ * Calculates the percentage code coverage information
+ *
+ * @return boolean|float FALSE if cc is not enabled, float for coverage percent
+ */
+ public function calculate_cc_percentage()
+ {
+ if ($stats = $this->calculate_cc())
+ {
+ $executable = 0;
+ $executed = 0;
+
+ foreach ($stats as $stat)
+ {
+ $executable += $stat['locExecutable'];
+ $executed += $stat['locExecuted'];
+ }
+
+ return $executable > 0 ? ($executed / $executable) * 100 : 100;
+ }
+
+ return FALSE;
+ }
+
+ /**
+ * Generate a report using the specified $temp_path
+ *
+ * @param array $groups Groups to test
+ * @param string $temp_path Temporary path to use while generating report
+ */
+ public function generate_report(array $groups, $temp_path, $create_sub_dir = TRUE)
+ {
+ if ( ! is_writable($temp_path))
+ {
+ throw new Kohana_Exception('Temp path :path does not exist or is not writable by the webserver', array(':path' => $temp_path));
+ }
+
+ $folder_path = $temp_path;
+
+ if ($create_sub_dir === TRUE)
+ {
+ // Icky, highly unlikely, but do it anyway
+ // Basically adds "(n)" to the end of the filename until there's a free file
+ $count = 0;
+ do
+ {
+ $folder_name = date('Y-m-d_H:i:s')
+ .( ! empty($groups) ? '['.implode(',', $groups).']' : '')
+ .($count > 0 ? '('.$count.')' : '');
+ ++$count;
+ }
+ while(is_dir($folder_path.$folder_name));
+
+ $folder_path .= $folder_name;
+
+ mkdir($folder_path, 0777);
+ }
+ else
+ {
+ $folder_name = basename($folder_path);
+ }
+
+ $this->run($groups, TRUE);
+
+ require_once 'PHPUnit/Runner/Version.php';
+ require_once 'PHPUnit/Util/Report.php';
+
+ PHPUnit_Util_Report::render($this->result, $folder_path);
+
+ return array($folder_path, $folder_name);
+ }
+
+ /**
+ * Runs the test suite using the result specified in the constructor
+ *
+ * @param array $groups Optional array of groups to test
+ * @param bool $collect_cc Optional, Should code coverage be collected?
+ * @return Kohana_PHPUnit Instance of $this
+ */
+ public function run(array $groups = array(), $collect_cc = FALSE)
+ {
+ if ($collect_cc AND ! extension_loaded('xdebug'))
+ {
+ throw new Kohana_Exception('Code coverage cannot be collected because the xdebug extension is not loaded');
+ }
+
+ $this->result->collectCodeCoverageInformation((bool) $collect_cc);
+
+ // Run the tests.
+ $this->suite->run($this->result, FALSE, $groups);
+
+ return $this;
+ }
+
+ public function addError(PHPUnit_Framework_Test $test, Exception $e, $time)
+ {
+ $this->totals['errors']++;
+ $this->current['result'] = 'errors';
+ $this->current['message'] = $test->getStatusMessage();
+
+ }
+
+ public function addFailure(PHPUnit_Framework_Test $test, PHPUnit_Framework_AssertionFailedError $e, $time)
+ {
+ $this->totals['failures']++;
+ $this->current['result'] = 'failures';
+ $this->current['message'] = $test->getStatusMessage();
+ }
+
+ public function addIncompleteTest(PHPUnit_Framework_Test $test, Exception $e, $time)
+ {
+ $this->totals['incomplete']++;
+ $this->current['result'] = 'incomplete';
+ $this->current['message'] = $test->getStatusMessage();
+ }
+
+ public function addSkippedTest(PHPUnit_Framework_Test $test, Exception $e, $time)
+ {
+ $this->totals['skipped']++;
+ $this->current['result'] = 'skipped';
+ $this->current['message'] = $test->getStatusMessage();
+ }
+
+ public function startTest(PHPUnit_Framework_Test $test)
+ {
+ $this->current['name'] = $test->getName(FALSE);
+ $this->current['description'] = $test->toString();
+ $this->current['result'] = 'passed';
+ }
+
+ public function endTest(PHPUnit_Framework_Test $test, $time)
+ {
+ // Add totals
+ $this->totals['tests']++;
+ $this->totals['assertions'] += $test->getNumAssertions();
+
+ // Handle passed tests
+ if ($this->current['result'] == 'passed')
+ {
+ // Add to total
+ $this->totals['passed']++;
+ }
+ else
+ {
+ // Add to results
+ $this->results[$this->current['result']][] = $this->current;
+ }
+
+ $this->current = array();
+
+ $this->time += $time;
+ }
+
+ public function startTestSuite(PHPUnit_Framework_TestSuite $suite)
+ {
+ }
+
+ public function endTestSuite(PHPUnit_Framework_TestSuite $suite)
+ {
+ // Parse test descriptions to make them look nicer
+ foreach ($this->results as $case => $testresults)
+ {
+ foreach ($testresults as $type => $result)
+ {
+ preg_match('/^(?:([a-z0-9_]+?)::)?([a-z0-9_]+)(?: with data set (#\d+ \(.*?\)))?/i', $result['description'], $m);
+
+ $this->results[$case][$type] += array(
+ 'class' => $m[1],
+ 'test' => $m[2],
+ 'data_set' => isset($m[3]) ? $m[3] : FALSE,
+ );
+ }
+ }
+ }
+}
diff --git a/includes/kohana/modules/unittest/classes/kohana/unittest/testcase.php b/includes/kohana/modules/unittest/classes/kohana/unittest/testcase.php
new file mode 100644
index 00000000..f22efdc9
--- /dev/null
+++ b/includes/kohana/modules/unittest/classes/kohana/unittest/testcase.php
@@ -0,0 +1,102 @@
+
+ * @author Paul Banks
+ * @copyright (c) 2008-2009 Kohana Team
+ * @license http://kohanaphp.com/license
+ */
+Abstract Class Kohana_Unittest_TestCase extends PHPUnit_Framework_TestCase
+{
+ /**
+ * Make sure PHPUnit backs up globals
+ * @var boolean
+ */
+ protected $backupGlobals = TRUE;
+
+ /**
+ * A set of unittest helpers that are shared between normal / database
+ * testcases
+ * @var Kohana_Unittest_Helpers
+ */
+ protected $_helpers = NULL;
+
+ /**
+ * A default set of environment to be applied before each test
+ * @var array
+ */
+ protected $environmentDefault = array();
+
+ /**
+ * Creates a predefined environment using the default environment
+ *
+ * Extending classes that have their own setUp() should call
+ * parent::setUp()
+ */
+ public function setUp()
+ {
+ $this->_helpers = new Kohana_Unittest_Helpers;
+
+ $this->setEnvironment($this->environmentDefault);
+ }
+
+ /**
+ * Restores the original environment overriden with setEnvironment()
+ *
+ * Extending classes that have their own tearDown()
+ * should call parent::tearDown()
+ */
+ public function tearDown()
+ {
+ $this->_helpers->restore_environment();
+ }
+
+ /**
+ * Removes all kohana related cache files in the cache directory
+ */
+ public function cleanCacheDir()
+ {
+ return Kohana_Unittest_Helpers::clean_cache_dir();
+ }
+
+ /**
+ * Helper function that replaces all occurences of '/' with
+ * the OS-specific directory separator
+ *
+ * @param string $path The path to act on
+ * @return string
+ */
+ public function dirSeparator($path)
+ {
+ return Kohana_Unittest_Helpers::dir_separator($path);
+ }
+
+ /**
+ * Allows easy setting & backing up of enviroment config
+ *
+ * Option types are checked in the following order:
+ *
+ * * Server Var
+ * * Static Variable
+ * * Config option
+ *
+ * @param array $environment List of environment to set
+ */
+ public function setEnvironment(array $environment)
+ {
+ return $this->_helpers->set_environment($environment);
+ }
+
+ /**
+ * Check for internet connectivity
+ *
+ * @return boolean Whether an internet connection is available
+ */
+ public function hasInternet()
+ {
+ return Kohana_Unittest_Helpers::has_internet();
+ }
+}
\ No newline at end of file
diff --git a/includes/kohana/modules/unittest/config/unittest.php b/includes/kohana/modules/unittest/config/unittest.php
new file mode 100644
index 00000000..b634d8ec
--- /dev/null
+++ b/includes/kohana/modules/unittest/config/unittest.php
@@ -0,0 +1,53 @@
+ Kohana::DEVELOPMENT,
+
+ // This is the folder where we generate and zip all the reports for downloading
+ // Needs to be readable and writable
+ 'temp_path' => Kohana::$cache_dir.'/unittest',
+
+ // Path from DOCROOT (i.e. http://yourdomain/) to the folder where HTML cc reports can be published.
+ // If you'd prefer not to allow users to do this then simply set the value to FALSE.
+ // Example value of 'cc_report_path' would allow devs to see report at http://yourdomain/report/
+ 'cc_report_path' => 'report',
+
+ // If you don't use a whitelist then only files included during the request will be counted
+ // If you do, then only whitelisted items will be counted
+ 'use_whitelist' => FALSE,
+
+ // Items to whitelist, only used in cli
+ // Web runner ui allows user to choose which items to whitelist
+ 'whitelist' => array(
+
+ // Should the app be whitelisted?
+ // Useful if you just want to test your application
+ 'app' => TRUE,
+
+ // Set to array(TRUE) to include all modules, or use an array of module names
+ // (the keys of the array passed to Kohana::modules() in the bootstrap)
+ // Or set to FALSE to exclude all modules
+ 'modules' => array(TRUE),
+
+ // If you don't want the Kohana code coverage reports to pollute your app's,
+ // then set this to FALSE
+ 'system' => TRUE,
+ ),
+
+ // Does what it says on the tin
+ // Blacklisted files won't be included in code coverage reports
+ // If you use a whitelist then the blacklist will be ignored
+ 'use_blacklist' => FALSE,
+
+ // List of individual files/folders to blacklist
+ 'blacklist' => array(
+ ),
+
+ // A database connection that can be used when testing
+ // This doesn't overwrite anything, tests will have to use this value manually
+ 'db_connection' => 'unittest',
+);
diff --git a/includes/kohana/modules/unittest/example.phpunit.xml b/includes/kohana/modules/unittest/example.phpunit.xml
new file mode 100644
index 00000000..9792d37d
--- /dev/null
+++ b/includes/kohana/modules/unittest/example.phpunit.xml
@@ -0,0 +1,16 @@
+
+
+
+
+
++ : + + , + , + , + , + . + + + + 75 ? 'excellent' : ($coverage > 35 ? 'ok' : 'terrible')) ?> + ''.num::format($coverage, 2).'%', + ':codebase' => ( ! empty($coverage_explanation) ? 'modules' : 'codebase') + ) + ); + ?>, + + or + + the report + + +
+
+
+
+
+
+
+ $tests):?>
+
+
+
diff --git a/includes/kohana/modules/userguide/README.md b/includes/kohana/modules/userguide/README.md
new file mode 100644
index 00000000..8bf319a2
--- /dev/null
+++ b/includes/kohana/modules/userguide/README.md
@@ -0,0 +1,16 @@
+Kohana user guide and live API documentation module
+
+**Note to Contributors**
+
+Just so you are aware, I am not merging forks of forks. As the owner of a translation language, I expect you to merge the downstream forks into your own. For instance:
+
+ kohana/userguide
+ -- you/userguide-xx
+ -- -- person/userguide-xx
+
+All changes from `person/userguide-xx` must be merged into your own repo, using `git merge` or the fork queue. See [github forking](http://help.github.com/forking/) for more information about how to merge remote repositories, and note that you will need to add a remote for `person/userguide-xx` using:
+
+ git remote add person git://github.com/person/userguide-xx
+ git pull person master
+
+Thanks for your help!
\ No newline at end of file
diff --git a/includes/kohana/modules/userguide/classes/controller/userguide.php b/includes/kohana/modules/userguide/classes/controller/userguide.php
new file mode 100644
index 00000000..fb7768bb
--- /dev/null
+++ b/includes/kohana/modules/userguide/classes/controller/userguide.php
@@ -0,0 +1,314 @@
+request->action === 'media')
+ {
+ // Do not template media files
+ $this->auto_render = FALSE;
+ }
+ else
+ {
+ // Grab the necessary routes
+ $this->media = Route::get('docs/media');
+ $this->guide = Route::get('docs/guide');
+
+ if (isset($_GET['lang']))
+ {
+ $lang = $_GET['lang'];
+
+ // Load the accepted language list
+ $translations = array_keys(Kohana::message('userguide', 'translations'));
+
+ if (in_array($lang, $translations))
+ {
+ // Set the language cookie
+ Cookie::set('userguide_language', $lang, Date::YEAR);
+ }
+
+ // Reload the page
+ $this->request->redirect($this->request->uri);
+ }
+
+ // Set the translation language
+ I18n::$lang = Cookie::get('userguide_language', Kohana::config('userguide')->lang);
+
+ if (defined('MARKDOWN_PARSER_CLASS'))
+ {
+ throw new Kohana_Exception('Markdown parser already registered. Live documentation will not work in your environment.');
+ }
+
+ // Use customized Markdown parser
+ define('MARKDOWN_PARSER_CLASS', 'Kodoc_Markdown');
+
+ if ( ! class_exists('Markdown', FALSE))
+ {
+ // Load Markdown support
+ require Kohana::find_file('vendor', 'markdown/markdown');
+ }
+
+ // Set the base URL for links and images
+ Kodoc_Markdown::$base_url = URL::site($this->guide->uri()).'/';
+ Kodoc_Markdown::$image_url = URL::site($this->media->uri()).'/';
+ }
+
+ parent::before();
+ }
+
+ public function action_docs()
+ {
+ $page = $this->request->param('page');
+
+ if ( ! $page)
+ {
+ // Redirect to the default page
+ $this->request->redirect($this->guide->uri(array('page' => Kohana::config('userguide')->default_page)));
+ }
+
+ $file = $this->file($page);
+
+ if ( ! $file)
+ {
+ $this->error(__('Userguide page not found'));
+ return;
+ }
+
+ // Set the page title
+ $this->template->title = $this->title($page);
+
+ // Parse the page contents into the template
+ $this->template->content = Markdown(file_get_contents($file));
+
+ // Attach the menu to the template
+ $this->template->menu = Markdown(file_get_contents($this->file('menu')));
+
+ // Bind module menu items
+ $this->template->bind('module_menus', $module_menus);
+
+ // Attach module-specific menu items
+ $module_menus = array();
+
+ foreach(Kohana::modules() as $module => $path)
+ {
+ if ($file = $this->file('menu.'.$module))
+ {
+ $module_menus[$module] = Markdown(file_get_contents($file));
+ }
+ }
+
+ // Bind the breadcrumb
+ $this->template->bind('breadcrumb', $breadcrumb);
+
+ // Add the breadcrumb
+ $breadcrumb = array();
+ $breadcrumb[$this->guide->uri()] = __('User Guide');
+ $breadcrumb[] = $this->section($page);
+ $breadcrumb[] = $this->template->title;
+ }
+
+ public function action_api()
+ {
+ // Enable the missing class autoloader
+ spl_autoload_register(array('Kodoc_Missing', 'create_class'));
+
+ // Get the class from the request
+ $class = $this->request->param('class');
+
+ if ($class)
+ {
+ try
+ {
+ $_class = Kodoc_Class::factory($class);
+
+ if ( ! Kodoc::show_class($_class))
+ throw new Exception(__('That class is hidden'));
+ }
+ catch (Exception $e)
+ {
+ return $this->error(__('API Reference: Class not found.'));
+ }
+
+ $this->template->title = $class;
+
+ $this->template->content = View::factory('userguide/api/class')
+ ->set('doc', Kodoc::factory($class))
+ ->set('route', $this->request->route);
+ }
+ else
+ {
+ $this->template->title = __('Table of Contents');
+
+ $this->template->content = View::factory('userguide/api/toc')
+ ->set('classes', Kodoc::class_methods())
+ ->set('route', $this->request->route);
+ }
+
+ // Attach the menu to the template
+ $this->template->menu = Kodoc::menu();
+
+ // Bind the breadcrumb
+ $this->template->bind('breadcrumb', $breadcrumb);
+
+ // Get the docs URI
+ $guide = Route::get('docs/guide');
+
+ // Add the breadcrumb
+ $breadcrumb = array();
+ $breadcrumb[$this->guide->uri(array('page' => NULL))] = __('User Guide');
+ $breadcrumb[$this->request->route->uri()] = $this->title('api');
+ $breadcrumb[] = $this->template->title;
+ }
+
+ public function action_media()
+ {
+ // Generate and check the ETag for this file
+ $this->request->check_cache(sha1($this->request->uri));
+
+ // Get the file path from the request
+ $file = $this->request->param('file');
+
+ // Find the file extension
+ $ext = pathinfo($file, PATHINFO_EXTENSION);
+
+ // Remove the extension from the filename
+ $file = substr($file, 0, -(strlen($ext) + 1));
+
+ if ($file = Kohana::find_file('media', $file, $ext))
+ {
+ // Send the file content as the response
+ $this->request->response = file_get_contents($file);
+ }
+ else
+ {
+ // Return a 404 status
+ $this->request->status = 404;
+ }
+
+ // Set the proper headers to allow caching
+ $this->request->headers['Content-Type'] = File::mime_by_ext($ext);
+ $this->request->headers['Content-Length'] = filesize($file);
+ $this->request->headers['Last-Modified'] = date('r', filemtime($file));
+ }
+
+ // Display an error if a page isn't found
+ public function error($message)
+ {
+ $this->request->status = 404;
+ $this->template->title = __('User Guide').' - '.__('Error');
+ $this->template->content = View::factory('userguide/error',array('message'=>$message));
+ $this->template->menu = Kodoc::menu();
+ $this->template->breadcrumb = array($this->guide->uri() => __('User Guide'), __('Error'));
+ }
+
+ public function after()
+ {
+ if ($this->auto_render)
+ {
+ // Get the media route
+ $media = Route::get('docs/media');
+
+ // Add styles
+ $this->template->styles = array(
+ $media->uri(array('file' => 'css/print.css')) => 'print',
+ $media->uri(array('file' => 'css/screen.css')) => 'screen',
+ $media->uri(array('file' => 'css/kodoc.css')) => 'screen',
+ $media->uri(array('file' => 'css/shCore.css')) => 'screen',
+ $media->uri(array('file' => 'css/shThemeKodoc.css')) => 'screen',
+ );
+
+ // Add scripts
+ $this->template->scripts = array(
+ $media->uri(array('file' => 'js/jquery.min.js')),
+ $media->uri(array('file' => 'js/kodoc.js')),
+ $media->uri(array('file' => 'js/shCore.js')),
+ $media->uri(array('file' => 'js/shBrushPhp.js')),
+ );
+
+ // Add languages
+ $this->template->translations = Kohana::message('userguide', 'translations');
+ }
+
+ return parent::after();
+ }
+
+ public function file($page)
+ {
+ if ( ! ($file = Kohana::find_file('guide', I18n::$lang.'/'.$page, 'md')))
+ {
+ // Use the default file
+ $file = Kohana::find_file('guide', $page, 'md');
+ }
+
+ return $file;
+ }
+
+ public function section($page)
+ {
+ $markdown = $this->_get_all_menu_markdown();
+
+ if (preg_match('~\*{2}(.+?)\*{2}[^*]+\[[^\]]+\]\('.preg_quote($page).'\)~mu', $markdown, $matches))
+ {
+ return $matches[1];
+ }
+
+ return $page;
+ }
+
+ public function title($page)
+ {
+ $markdown = $this->_get_all_menu_markdown();
+
+ if (preg_match('~\[([^\]]+)\]\('.preg_quote($page).'\)~mu', $markdown, $matches))
+ {
+ // Found a title for this link
+ return $matches[1];
+ }
+
+ return $page;
+ }
+
+ protected function _get_all_menu_markdown()
+ {
+ // Only do this once per request...
+ static $markdown = '';
+
+ if (empty($markdown))
+ {
+ // Get core menu items
+ $file = $this->file('menu');
+
+ if ($file AND $text = file_get_contents($file))
+ {
+ $markdown .= $text;
+ }
+
+ // Look in module specific files
+ foreach(Kohana::modules() as $module => $path)
+ {
+ if ($file = $this->file('menu.'.$module) AND $text = file_get_contents($file))
+ {
+ // Concatenate markdown to produce one string containing all menu items
+ $markdown .="\n".$text;
+ }
+ }
+ }
+
+ return $markdown;
+ }
+
+} // End Userguide
diff --git a/includes/kohana/modules/userguide/classes/kodoc.php b/includes/kohana/modules/userguide/classes/kodoc.php
new file mode 100644
index 00000000..60484b29
--- /dev/null
+++ b/includes/kohana/modules/userguide/classes/kodoc.php
@@ -0,0 +1,3 @@
+uri(array('class' => $class->class->name)), $class->class->name);
+
+ if (isset($class->tags['package']))
+ {
+ foreach ($class->tags['package'] as $package)
+ {
+ if (isset($class->tags['category']))
+ {
+ foreach ($class->tags['category'] as $category)
+ {
+ $menu[$package][$category][] = $link;
+ }
+ }
+ else
+ {
+ $menu[$package]['Base'][] = $link;
+ }
+ }
+ }
+ else
+ {
+ $menu['[Unknown]']['Base'][] = $link;
+ }
+ }
+
+ // Sort the packages
+ ksort($menu);
+
+ return View::factory('userguide/api/menu')
+ ->bind('menu', $menu);
+ }
+
+ /**
+ * Returns an array of all the classes available, built by listing all files in the classes folder and then trying to create that class.
+ *
+ * This means any empty class files (as in complety empty) will cause an exception
+ *
+ * @param array array of files, obtained using Kohana::list_files
+ * @return array an array of all the class names
+ */
+ public static function classes(array $list = NULL)
+ {
+ if ($list === NULL)
+ {
+ $list = Kohana::list_files('classes');
+ }
+
+ $classes = array();
+
+ foreach ($list as $name => $path)
+ {
+ if (is_array($path))
+ {
+ $classes += Kodoc::classes($path);
+ }
+ else
+ {
+ // Remove "classes/" and the extension
+ $class = substr($name, 8, -(strlen(EXT)));
+
+ // Convert slashes to underscores
+ $class = str_replace(DIRECTORY_SEPARATOR, '_', strtolower($class));
+
+ $classes[$class] = $class;
+ }
+ }
+
+ return $classes;
+ }
+
+ /**
+ * Get all classes and methods of files in a list.
+ *
+ * > I personally don't like this as it was used on the index page. Way too much stuff on one page. It has potential for a package index page though.
+ * > For example: class_methods( Kohana::list_files('classes/sprig') ) could make a nice index page for the sprig package in the api browser
+ * > ~bluehawk
+ *
+ */
+ public static function class_methods(array $list = NULL)
+ {
+ $list = Kodoc::classes($list);
+
+ $classes = array();
+
+ foreach ($list as $class)
+ {
+ $_class = new ReflectionClass($class);
+
+ if (stripos($_class->name, 'Kohana') === 0)
+ {
+ // Skip the extension stuff stuff
+ continue;
+ }
+
+ $methods = array();
+
+ foreach ($_class->getMethods() as $_method)
+ {
+ $declares = $_method->getDeclaringClass()->name;
+
+ if (stripos($declares, 'Kohana') === 0)
+ {
+ // Remove "Kohana_"
+ $declares = substr($declares, 7);
+ }
+
+ if ($declares === $_class->name)
+ {
+ $methods[] = $_method->name;
+ }
+ }
+
+ sort($methods);
+
+ $classes[$_class->name] = $methods;
+ }
+
+ return $classes;
+ }
+
+ /**
+ * Parse a comment to extract the description and the tags
+ *
+ * @param string the comment retreived using ReflectionClass->getDocComment()
+ * @return array array(string $description, array $tags)
+ */
+ public static function parse($comment)
+ {
+ // Normalize all new lines to \n
+ $comment = str_replace(array("\r\n", "\n"), "\n", $comment);
+
+ // Remove the phpdoc open/close tags and split
+ $comment = array_slice(explode("\n", $comment), 1, -1);
+
+ // Tag content
+ $tags = array();
+
+ foreach ($comment as $i => $line)
+ {
+ // Remove all leading whitespace
+ $line = preg_replace('/^\s*\* ?/m', '', $line);
+
+ // Search this line for a tag
+ if (preg_match('/^@(\S+)(?:\s*(.+))?$/', $line, $matches))
+ {
+ // This is a tag line
+ unset($comment[$i]);
+
+ $name = $matches[1];
+ $text = isset($matches[2]) ? $matches[2] : '';
+
+ switch ($name)
+ {
+ case 'license':
+ if (strpos($text, '://') !== FALSE)
+ {
+ // Convert the lincense into a link
+ $text = HTML::anchor($text);
+ }
+ break;
+ case 'link':
+ $text = preg_split('/\s+/', $text, 2);
+ $text = HTML::anchor($text[0], isset($text[1]) ? $text[1] : $text[0]);
+ break;
+ case 'copyright':
+ if (strpos($text, '(c)') !== FALSE)
+ {
+ // Convert the copyright sign
+ $text = str_replace('(c)', '©', $text);
+ }
+ break;
+ case 'throws':
+ if (preg_match('/^(\w+)\W(.*)$/',$text,$matches))
+ {
+ $text = HTML::anchor(Route::get('docs/api')->uri(array('class' => $matches[1])), $matches[1]).' '.$matches[2];
+ }
+ else
+ {
+ $text = HTML::anchor(Route::get('docs/api')->uri(array('class' => $text)), $text);
+ }
+ break;
+ case 'uses':
+ if (preg_match('/^([a-z_]+)::([a-z_]+)$/i', $text, $matches))
+ {
+ // Make a class#method API link
+ $text = HTML::anchor(Route::get('docs/api')->uri(array('class' => $matches[1])).'#'.$matches[2], $text);
+ }
+ break;
+ // Don't show @access lines, they are shown elsewhere
+ case 'access':
+ continue 2;
+ }
+
+ // Add the tag
+ $tags[$name][] = $text;
+ }
+ else
+ {
+ // Overwrite the comment line
+ $comment[$i] = (string) $line;
+ }
+ }
+
+ // Concat the comment lines back to a block of text
+ if ($comment = trim(implode("\n", $comment)))
+ {
+ // Parse the comment with Markdown
+ $comment = Markdown($comment);
+ }
+
+ return array($comment, $tags);
+ }
+
+ /**
+ * Get the source of a function
+ *
+ * @param string the filename
+ * @param int start line?
+ * @param int end line?
+ */
+ public static function source($file, $start, $end)
+ {
+ if ( ! $file)
+ {
+ return FALSE;
+ }
+
+ $file = file($file, FILE_IGNORE_NEW_LINES);
+
+ $file = array_slice($file, $start - 1, $end - $start + 1);
+
+ if (preg_match('/^(\s+)/', $file[0], $matches))
+ {
+ $padding = strlen($matches[1]);
+
+ foreach ($file as & $line)
+ {
+ $line = substr($line, $padding);
+ }
+ }
+
+ return implode("\n", $file);
+ }
+
+ /**
+ * Test whether a class should be shown, based on the api_packages config option
+ *
+ * @param Kodoc_Class the class to test
+ * @return bool whether this class should be shown
+ */
+ public static function show_class(Kodoc_Class $class)
+ {
+ $api_packages = Kohana::config('userguide.api_packages');
+
+ // If api_packages is true, all packages should be shown
+ if ($api_packages === TRUE)
+ return TRUE;
+
+ // Get the package tags for this class (as an array)
+ $packages = Arr::get($class->tags,'package',Array('None'));
+
+ $show_this = FALSE;
+
+ // Loop through each package tag
+ foreach ($packages as $package)
+ {
+ // If this package is in the allowed packages, set show this to true
+ if (in_array($package,explode(',',$api_packages)))
+ $show_this = TRUE;
+ }
+
+ return $show_this;
+ }
+
+
+} // End Kodoc
diff --git a/includes/kohana/modules/userguide/classes/kohana/kodoc/class.php b/includes/kohana/modules/userguide/classes/kohana/kodoc/class.php
new file mode 100644
index 00000000..1681daff
--- /dev/null
+++ b/includes/kohana/modules/userguide/classes/kohana/kodoc/class.php
@@ -0,0 +1,167 @@
+class = new ReflectionClass($class);
+
+ if ($modifiers = $this->class->getModifiers())
+ {
+ $this->modifiers = ''.implode(' ', Reflection::getModifierNames($modifiers)).' ';
+ }
+
+ if ($constants = $this->class->getConstants())
+ {
+ foreach ($constants as $name => $value)
+ {
+ $this->constants[$name] = Kohana::debug($value);
+ }
+ }
+
+ $parent = $this->class;
+
+ do
+ {
+ if ($comment = $parent->getDocComment())
+ {
+ // Found a description for this class
+ break;
+ }
+ }
+ while ($parent = $parent->getParentClass());
+
+ list($this->description, $this->tags) = Kodoc::parse($comment);
+ }
+
+ /**
+ * Gets a list of the class properties as [Kodoc_Property] objects.
+ *
+ * @return array
+ */
+ public function properties()
+ {
+ $props = $this->class->getProperties();
+
+ sort($props);
+
+ foreach ($props as $key => $property)
+ {
+ // Only show public properties, because Reflection can't get the private ones
+ if ($property->isPublic())
+ {
+ $props[$key] = new Kodoc_Property($this->class->name, $property->name);
+ }
+ else
+ {
+ unset($props[$key]);
+ }
+ }
+
+ return $props;
+ }
+
+ /**
+ * Gets a list of the class properties as [Kodoc_Method] objects.
+ *
+ * @return array
+ */
+ public function methods()
+ {
+ $methods = $this->class->getMethods();
+
+ usort($methods, array($this,'_method_sort'));
+
+ foreach ($methods as $key => $method)
+ {
+ $methods[$key] = new Kodoc_Method($this->class->name, $method->name);
+ }
+
+ return $methods;
+ }
+
+ protected function _method_sort($a,$b)
+ {
+ /*
+ echo kohana::debug('a is '.$a->class.'::'.$a->name,'b is '.$b->class.'::'.$b->name,
+ 'are the classes the same?',$a->class == $b->class,'if they are, the result is:',strcmp($a->name,$b->name),
+ 'is a this class?',$a->name == $this->class->name,-1,
+ 'is b this class?',$b->name == $this->class->name,1,
+ 'otherwise, the result is:',strcmp($a->class,$b->class)
+ );
+ */
+
+
+ // If both methods are defined in the same class, just compare the method names
+ if ($a->class == $b->class)
+ return strcmp($a->name,$b->name);
+
+ // If one of them was declared by this class, it needs to be on top
+ if ($a->name == $this->class->name)
+ return -1;
+ if ($b->name == $this->class->name)
+ return 1;
+
+ // Otherwise, get the parents of each methods declaring class, then compare which function has more "ancestors"
+ $adepth = 0;
+ $bdepth = 0;
+
+ $parent = $a->getDeclaringClass();
+ do
+ {
+ $adepth++;
+ }
+ while ($parent = $parent->getParentClass());
+
+ $parent = $b->getDeclaringClass();
+ do
+ {
+ $bdepth++;
+ }
+ while ($parent = $parent->getParentClass());
+
+ return $bdepth - $adepth;
+ }
+
+} // End Kodac_Class
diff --git a/includes/kohana/modules/userguide/classes/kohana/kodoc/markdown.php b/includes/kohana/modules/userguide/classes/kohana/kodoc/markdown.php
new file mode 100644
index 00000000..51530f65
--- /dev/null
+++ b/includes/kohana/modules/userguide/classes/kohana/kodoc/markdown.php
@@ -0,0 +1,169 @@
+span_gamut['doImageURL'] = 9;
+
+ // doLink is 20, add base url just before
+ $this->span_gamut['doBaseURL'] = 19;
+
+ // Add API links
+ $this->span_gamut['doAPI'] = 90;
+
+ // Add note spans last
+ $this->span_gamut['doNotes'] = 100;
+
+ // Parse Kohana view inclusions at the very end
+ $this->document_gamut['doIncludeViews'] = 100;
+
+ // PHP4 makes me sad.
+ parent::MarkdownExtra_Parser();
+ }
+
+ public function doIncludeViews($text)
+ {
+ if (preg_match_all('/{{([^\s{}]++)}}/', $text, $matches, PREG_SET_ORDER))
+ {
+ $replace = array();
+
+ foreach ($matches as $set)
+ {
+ list($search, $view) = $set;
+
+ try
+ {
+ $replace[$search] = View::factory($view)->render();
+ }
+ catch (Exception $e)
+ {
+ ob_start();
+
+ // Capture the exception handler output and insert it instead
+ Kohana::exception_handler($e);
+
+ $replace[$search] = ob_get_clean();
+ }
+ }
+
+ $text = strtr($text, $replace);
+ }
+
+ return $text;
+ }
+
+ /**
+ * Add the current base url to all local links.
+ *
+ * [filesystem](about.filesystem "Optional title")
+ *
+ * @param string span text
+ * @return string
+ */
+ public function doBaseURL($text)
+ {
+ // URLs containing "://" are left untouched
+ return preg_replace('~(?uri(array('class' => $class)).$method, $link);
+ }
+
+ /**
+ * Wrap notes in the applicable markup. Notes can contain single newlines.
+ *
+ * [!!] Remember the milk!
+ *
+ * @param string span text
+ * @return string
+ */
+ public function doNotes($text)
+ {
+ if ( ! preg_match('/^\[!!\]\s*+(.+?)(?=\n{2,}|$)/s', $text, $match))
+ {
+ return $text;
+ }
+
+ return $this->hashBlock('
+
+
+
++ + []
+-
+
+
- + :: + + + + + + +
'.$match[1].'
'); + } + +} // End Kodoc_Markdown diff --git a/includes/kohana/modules/userguide/classes/kohana/kodoc/method.php b/includes/kohana/modules/userguide/classes/kohana/kodoc/method.php new file mode 100644 index 00000000..d704a8c0 --- /dev/null +++ b/includes/kohana/modules/userguide/classes/kohana/kodoc/method.php @@ -0,0 +1,141 @@ +method = new ReflectionMethod($class, $method); + + $this->class = $parent = $this->method->getDeclaringClass(); + + if ($modifiers = $this->method->getModifiers()) + { + $this->modifiers = ''.implode(' ', Reflection::getModifierNames($modifiers)).' '; + } + + do + { + if ($parent->hasMethod($method) AND $comment = $parent->getMethod($method)->getDocComment()) + { + // Found a description for this method + break; + } + } + while ($parent = $parent->getParentClass()); + + list($this->description, $tags) = Kodoc::parse($comment); + + if ($file = $this->class->getFileName()) + { + $this->source = Kodoc::source($file, $this->method->getStartLine(), $this->method->getEndLine()); + } + + if (isset($tags['param'])) + { + $params = array(); + + foreach ($this->method->getParameters() as $i => $param) + { + $param = new Kodoc_Method_Param(array($this->method->class,$this->method->name),$i); + + if (isset($tags['param'][$i])) + { + preg_match('/^(\S+)(?:\s*(?:\$'.$param->name.'\s*)?(.+))?$/', $tags['param'][$i], $matches); + + $param->type = $matches[1]; + + if (isset($matches[2])) + { + $param->description = $matches[2]; + } + } + $params[] = $param; + } + + $this->params = $params; + + unset($tags['param']); + } + + if (isset($tags['return'])) + { + foreach ($tags['return'] as $return) + { + if (preg_match('/^(\S*)(?:\s*(.+?))?$/', $return, $matches)) + { + $this->return[] = array($matches[1], isset($matches[2]) ? $matches[2] : ''); + } + } + + unset($tags['return']); + } + + $this->tags = $tags; + } + + public function params_short() + { + $out = ''; + $required = TRUE; + $first = TRUE; + foreach ($this->params as $param) + { + if ($required AND $param->default AND $first) + { + $out .= '[ '.$param; + $required = FALSE; + $first = FALSE; + } + elseif ($required AND $param->default) + { + $out .= '[, '.$param; + $required = FALSE; + } + elseif ($first) + { + $out .= $param; + $first = FALSE; + } + else + { + $out .= ', '.$param; + } + } + + if ( ! $required) + { + $out .= '] '; + } + + return $out; + } + +} // End Kodoc_Method \ No newline at end of file diff --git a/includes/kohana/modules/userguide/classes/kohana/kodoc/method/param.php b/includes/kohana/modules/userguide/classes/kohana/kodoc/method/param.php new file mode 100644 index 00000000..8afa72d8 --- /dev/null +++ b/includes/kohana/modules/userguide/classes/kohana/kodoc/method/param.php @@ -0,0 +1,101 @@ +param = new ReflectionParameter($method, $param); + + $this->name = $this->param->name; + + if ($this->param->isDefaultValueAvailable()) + { + $this->default = Kohana::dump($this->param->getDefaultValue()); + } + + if ($this->param->isPassedByReference()) + { + $this->reference = TRUE; + } + + if ($this->param->isOptional()) + { + $this->optional = TRUE; + } + } + + public function __toString() + { + $display = ''; + + if ($this->type) + { + $display .= ''.$this->type.' '; + } + + if ($this->reference) + { + $display .= '& '; + } + + if ($this->description) + { + $display .= '$'.$this->name.' '; + } + else + { + $display .= '$'.$this->name.' '; + } + + if ($this->default) + { + $display .= '= '.$this->default.' '; + } + + return $display; + } + +} // End Kodoc_Method_Param diff --git a/includes/kohana/modules/userguide/classes/kohana/kodoc/missing.php b/includes/kohana/modules/userguide/classes/kohana/kodoc/missing.php new file mode 100644 index 00000000..f7256724 --- /dev/null +++ b/includes/kohana/modules/userguide/classes/kohana/kodoc/missing.php @@ -0,0 +1,36 @@ +getDocComment()); + + $this->description = $description; + + if ($modifiers = $property->getModifiers()) + { + $this->modifiers = ''.implode(' ', Reflection::getModifierNames($modifiers)).' '; + } + + if (isset($tags['var'])) + { + if (preg_match('/^(\S*)(?:\s*(.+?))?$/', $tags['var'][0], $matches)) + { + $this->type = $matches[1]; + + if (isset($matches[2])) + { + $this->description = $matches[2]; + } + } + } + + $this->property = $property; + + if ($property->isStatic()) + { + $this->value = Kohana::debug($property->getValue($class)); + } + } + +} // End Kodoc_Property diff --git a/includes/kohana/modules/userguide/config/userguide.php b/includes/kohana/modules/userguide/config/userguide.php new file mode 100644 index 00000000..aae05699 --- /dev/null +++ b/includes/kohana/modules/userguide/config/userguide.php @@ -0,0 +1,17 @@ + 'about.kohana', + + // Default the userguide language. + 'lang' => 'en-us', + + // Enable the API browser. TRUE or FALSE + 'api_browser' => TRUE, + + // Enable these packages in the API browser. TRUE for all packages, or a string of comma seperated packages, using 'None' for a class with no @package + // Example: 'api_packages' => 'Kohana,Kohana/Database,Kohana/ORM,None', + 'api_packages' => TRUE, +); diff --git a/includes/kohana/modules/userguide/guide/about.conventions.md b/includes/kohana/modules/userguide/guide/about.conventions.md new file mode 100644 index 00000000..bf0acfe1 --- /dev/null +++ b/includes/kohana/modules/userguide/guide/about.conventions.md @@ -0,0 +1,293 @@ +# Conventions + +It is encouraged to follow Kohana's [coding style](http://dev.kohanaframework.org/wiki/kohana2/CodingStyle). This uses [BSD/Allman style](http://en.wikipedia.org/wiki/Indent_style#BSD.2FAllman_style) bracing, among other things. + +## Class Names and File Location {#classes} + +Class names in Kohana follow a strict convention to facilitate [autoloading](using.autoloading). Class names should have uppercase first letters with underscores to separate words. Underscores are significant as they directly reflect the file location in the filesystem. + +The following conventions apply: + +1. CamelCased class names should not be used, except when it is undesirable to create a new directory level. +2. All class file names and directory names are lowercase. +3. All classes should be in the `classes` directory. This may be at any level in the [cascading filesystem](about.filesystem). + +[!!] Unlike Kohana v2.x, there is no separation between "controllers", "models", "libraries" and "helpers". All classes are placed in the "classes/" directory, regardless if they are static "helpers" or object "libraries". You can use whatever kind of class design you want: static, singleton, adapter, etc. + +## Examples + +Remember that in a class, an underscore means a new directory. Consider the following examples: + +Class Name | File Path +----------------------|------------------------------- +Controller_Template | classes/controller/template.php +Model_User | classes/model/user.php +Database | classes/database.php +Database_Query | classes/database/query.php +Form | classes/form.php + +## Coding Standards {#coding_standards} + +In order to produce highly consistent source code, we ask that everyone follow the coding standards as closely as possible. + +### Brackets +Please use [BSD/Allman Style](http://en.wikipedia.org/wiki/Indent_style#BSD.2FAllman_style) bracketing. + +### Naming Conventions + +Kohana uses under_score naming, not camelCase naming. + +#### Classes + + // Controller class, uses Controller_ prefix + class Controller_Apple extends Controller { + + // Model class, uses Model_ prefix + class Model_Cheese extends Model { + + // Regular class + class Peanut { + +When creating an instance of a class, don't use parentheses if you're not passing something on to the constructor: + + // Correct: + $db = new Database; + + // Incorrect: + $db = new Database(); + +#### Functions and Methods + +Functions should be all lowercase, and use under_scores to separate words: + + function drink_beverage($beverage) + { + +#### Variables + +All variables should be lowercase and use under_score, not camelCase: + + // Correct: + $foo = 'bar'; + $long_example = 'uses underscores'; + + // Incorrect: + $weDontWantThis = 'understood?'; + +### Indentation + +You must use tabs to indent your code. Using spaces for tabbing is strictly forbidden. + +Vertical spacing (for multi-line) is done with spaces. Tabs are not good for vertical alignment because different people have different tab widths. + + $text = 'this is a long text block that is wrapped. Normally, we aim for ' + . 'wrapping at 80 chars. Vertical alignment is very important for ' + . 'code readability. Remember that all indentation is done with tabs,' + . 'but vertical alignment should be completed with spaces, after ' + . 'indenting with tabs.'; + +### String concatenation + +Don't put spaces around the concatenation operator: + + // Correct: + $str = 'one'.$var.'two'; + + // Incorrect: + $str = 'one'. $var .'two'; + $str = 'one' . $var . 'two'; + +### Single Line Statements + +Single-line IF statements should only be used when breaking normal execution (e.g. return or continue): + + // Acceptable: + if ($foo == $bar) + return $foo; + + if ($foo == $bar) + continue; + + if ($foo == $bar) + break; + + if ($foo == $bar) + throw new Exception('You screwed up!'); + + // Not acceptable: + if ($baz == $bun) + $baz = $bar + 2; + +### Comparison Operations + +Please use OR and AND for comparison: + + // Correct: + if (($foo AND $bar) OR ($b AND $c)) + + // Incorrect: + if (($foo && $bar) || ($b && $c)) + +Please use elseif, not else if: + + // Correct: + elseif ($bar) + + // Incorrect: + else if($bar) + +### Switch structures + +Each case, break and default should be on a separate line. The block inside a case or default must be indented by 1 tab. + + switch ($var) + { + case 'bar': + case 'foo': + echo 'hello'; + break; + case 1: + echo 'one'; + break; + default: + echo 'bye'; + break; + } + +### Parentheses + +There should be one space after statement name, followed by a parenthesis. The ! (bang) character must have a space on either side to ensure maximum readability. Except in the case of a bang or type casting, there should be no whitespace after an opening parenthesis or before a closing parenthesis. + + // Correct: + if ($foo == $bar) + if ( ! $foo) + + // Incorrect: + if($foo == $bar) + if(!$foo) + if ((int) $foo) + if ( $foo == $bar ) + if (! $foo) + +### Ternaries + +All ternary operations should follow a standard format. Use parentheses around expressions only, not around just variables. + + $foo = ($bar == $foo) ? $foo : $bar; + $foo = $bar ? $foo : $bar; + +All comparisons and operations must be done inside of a parentheses group: + + $foo = ($bar > 5) ? ($bar + $foo) : strlen($bar); + +When separating complex ternaries (ternaries where the first part goes beyond ~80 chars) into multiple lines, spaces should be used to line up operators, which should be at the front of the successive lines: + + $foo = ($bar == $foo) + ? $foo + : $bar; + +### Type Casting + +Type casting should be done with spaces on each side of the cast: + + // Correct: + $foo = (string) $bar; + if ( (string) $bar) + + // Incorrect: + $foo = (string)$bar; + +When possible, please use type casting instead of ternary operations: + + // Correct: + $foo = (bool) $bar; + + // Incorrect: + $foo = ($bar == TRUE) ? TRUE : FALSE; + +When casting type to integer or boolean, use the short format: + + // Correct: + $foo = (int) $bar; + $foo = (bool) $bar; + + // Incorrect: + $foo = (integer) $bar; + $foo = (boolean) $bar; + +### Constants + +Always use uppercase for constants: + + // Correct: + define('MY_CONSTANT', 'my_value'); + $a = TRUE; + $b = NULL; + + // Incorrect: + define('MyConstant', 'my_value'); + $a = True; + $b = null; + +Place constant comparisons at the end of tests: + + // Correct: + if ($foo !== FALSE) + + // Incorrect: + if (FALSE !== $foo) + +This is a slightly controversial choice, so I will explain the reasoning. If we were to write the previous example in plain English, the correct example would read: + + if variable $foo is not exactly FALSE + +And the incorrect example would read: + + if FALSE is not exactly variable $foo + +Since we are reading left to right, it simply doesn't make sense to put the constant first. + +### Comments + +#### One-line comments + +Use //, preferably above the line of code you're commenting on. Leave a space after it and start with a capital. Never use #. + + // Correct + + //Incorrect + // incorrect + # Incorrect + +### Regular expressions + +When coding regular expressions please use PCRE rather than the POSIX flavor. PCRE is considered more powerful and faster. + + // Correct: + if (preg_match('/abc/i'), $str) + + // Incorrect: + if (eregi('abc', $str)) + +Use single quotes around your regular expressions rather than double quotes. Single-quoted strings are more convenient because of their simplicity. Unlike double-quoted strings they don't support variable interpolation nor integrated backslash sequences like \n or \t, etc. + + // Correct: + preg_match('/abc/', $str); + + // Incorrect: + preg_match("/abc/", $str); + +When performing a regular expression search and replace, please use the $n notation for backreferences. This is preferred over \\n. + + // Correct: + preg_replace('/(\d+) dollar/', '$1 euro', $str); + + // Incorrect: + preg_replace('/(\d+) dollar/', '\\1 euro', $str); + +Finally, please note that the $ character for matching the position at the end of the line allows for a following newline character. Use the D modifier to fix this if needed. [More info](http://blog.php-security.org/archives/76-Holes-in-most-preg_match-filters.html). + + $str = "email@example.com\n"; + + preg_match('/^.+@.+$/', $str); // TRUE + preg_match('/^.+@.+$/D', $str); // FALSE diff --git a/includes/kohana/modules/userguide/guide/about.filesystem.md b/includes/kohana/modules/userguide/guide/about.filesystem.md new file mode 100644 index 00000000..c760c3e2 --- /dev/null +++ b/includes/kohana/modules/userguide/guide/about.filesystem.md @@ -0,0 +1,86 @@ +# Cascading Filesystem + +The Kohana filesystem is a heirarchy of directory structure. When a file is +loaded by [Kohana::find_file], it is searched in the following order: + +Application Path +: Defined as `APPPATH` in `index.php`. The default value is `application`. + +Module Paths +: This is set as an associative array using [Kohana::modules] in `APPPATH/bootstrap.php`. + Each of the values of the array will be searched in the order that the modules + are added. + +System Path +: Defined as `SYSPATH` in `index.php`. The default value is `system`. All of the + main or "core" files and classes are defined here. + +Files that are in directories higher up the include path order take precedence +over files of the same name lower down the order, which makes it is possible to +overload any file by placing a file with the same name in a "higher" directory: + + + +If you have a view file called `welcome.php` in the `APPPATH/views` and +`SYSPATH/views` directories, the one in application will be returned when +`welcome.php` is loaded because it is at the top of the filesystem. + +## Types of Files + +The top level directories of the application, module, and system paths has the following +default directories: + +classes/ +: All classes that you want to [autoload](using.autoloading) should be stored here. + This includes controllers, models, and all other classes. All classes must + follow the [class naming conventions](about.conventions#classes). + +config/ +: Configuration files return an associative array of options that can be + loaded using [Kohana::config]. See [config usage](using.configuration) for + more information. + +i18n/ +: Translation files return an associative array of strings. Translation is + done using the `__()` method. To translate "Hello, world!" into Spanish, + you would call `__('Hello, world!')` with [I18n::$lang] set to "es-es". + See [translation usage](using.translation) for more information. + +messages/ +: Message files return an associative array of strings that can be loaded + using [Kohana::message]. Messages and i18n files differ in that messages + are not translated, but always written in the default language and referred + to by a single key. See [message usage](using.messages) for more information. + +views/ +: Views are plain PHP files which are used to generate HTML or other output. The view file is + loaded into a [View] object and assigned variables, which it then converts + into an HTML fragment. Multiple views can be used within each other. + See [view usage](usings.views) for more information. + +## Finding Files + +The path to any file within the filesystem can be found by calling [Kohana::find_file]: + + // Find the full path to "classes/cookie.php" + $path = Kohana::find_file('classes', 'cookie'); + + // Find the full path to "views/user/login.php" + $path = Kohana::find_file('views', 'user/login'); + + +# Vendor Extensions + +We call extensions that are not specific to Kohana "vendor" extensions. +For example, if you wanted to use [DOMPDF](http://code.google.com/p/dompdf), +you would copy it to `application/vendor/dompdf` and include the DOMPDF +autoloading class: + + require Kohana::find_file('vendor', 'dompdf/dompdf/dompdf_config.inc'); + +Now you can use DOMPDF without loading any more files: + + $pdf = new DOMPDF; + +[!!] If you want to convert views into PDFs using DOMPDF, try the +[PDFView](http://github.com/shadowhand/pdfview) module. diff --git a/includes/kohana/modules/userguide/guide/about.flow.md b/includes/kohana/modules/userguide/guide/about.flow.md new file mode 100644 index 00000000..5e7f6bc3 --- /dev/null +++ b/includes/kohana/modules/userguide/guide/about.flow.md @@ -0,0 +1,73 @@ +# Request Flow + +Every application follows the same flow: + +1. Application starts from `index.php`. +2. The application, module, and system paths are set. +3. Error reporting levels are set. +4. Install file is loaded, if it exists. +5. The [Kohana] class is loaded. +6. The bootstrap file, `APPPATH/bootstrap.php`, is included. +7. [Kohana::init] is called, which sets up error handling, caching, and logging. +8. [Kohana_Config] readers and [Kohana_Log] writers are attached. +9. [Kohana::modules] is called to enable additional modules. + * Module paths are added to the [cascading filesystem](about.filesystem). + * Includes the module `init.php` file, if it exists. + * The `init.php` file can perform additional environment setup, including adding routes. +10. [Route::set] is called multiple times to define the [application routes](using.routing). +11. [Request::instance] is called to start processing the request. + 1. Checks each route that has been set until a match is found. + 2. Creates the controller instance and passes the request to it. + 3. Calls the [Controller::before] method. + 4. Calls the controller action, which generates the request response. + 5. Calls the [Controller::after] method. + * The above 5 steps can be repeated multiple times when using [HMVC sub-requests](about.mvc). +12. The main [Request] response is displayed + +## index.php + +Kohana follows a [front controller] pattern, which means that all requests are sent to `index.php`. This allows a very clean [filesystem](about.filesystem) design. In `index.php`, there are some very basic configuration options available. You can change the `$application`, `$modules`, and `$system` paths and set the error reporting level. + +The `$application` variable lets you set the directory that contains your application files. By default, this is `application`. The `$modules` variable lets you set the directory that contains module files. The `$system` variable lets you set the directory that contains the default Kohana files. + +You can move these three directories anywhere. For instance, if your directories are set up like this: + + www/ + index.php + application/ + modules/ + system/ + +You could move the directories out of the web root: + + application/ + modules/ + system/ + www/ + index.php + +Then you would change the settings in `index.php` to be: + + $application = '../application'; + $modules = '../modules'; + $system = '../system'; + +Now none of the directories can be accessed by the web server. It is not necessary to make this change, but does make it possible to share the directories with multiple applications, among other things. + +[!!] There is a security check at the top of every Kohana file to prevent it from being accessed without using the front controller. However, it is more secure to move the application, modules, and system directories to a location that cannot be accessed via the web. + +### Error Reporting + +By default, Kohana displays all errors, including strict mode warnings. This is set using [error_reporting](http://php.net/error_reporting): + + error_reporting(E_ALL | E_STRICT); + +When you application is live and in production, a more conservative setting is recommended, such as ignoring notices: + + error_reporting(E_ALL & ~E_NOTICE); + +If you get a white screen when an error is triggered, your host probably has disabled displaying errors. You can turn it on again by adding this line just after your `error_reporting` call: + + ini_set('display_errors', TRUE); + +Errors should **always** be displayed, even in production, because it allows you to use [exception and error handling](debugging.errors) to serve a nice error page rather than a blank white screen when an error happens. diff --git a/includes/kohana/modules/userguide/guide/about.install.md b/includes/kohana/modules/userguide/guide/about.install.md new file mode 100644 index 00000000..f3ab2a98 --- /dev/null +++ b/includes/kohana/modules/userguide/guide/about.install.md @@ -0,0 +1,96 @@ +# Installation + +1. Download the latest **stable** release from the [Kohana website](http://kohanaframework.org/). +2. Unzip the downloaded package to create a `kohana` directory. +3. Upload the contents of this folder to your webserver. +4. Open `application/bootstrap.php` and make the following changes: + - Set the default [timezone](http://php.net/timezones) for your application. + - Set the `base_url` in the [Kohana::init] call to reflect the location of the kohana folder on your server. +6. Make sure the `application/cache` and `application/logs` directories are writable by the web server. +7. Test your installation by opening the URL you set as the `base_url` in your favorite browser. + +[!!] Depending on your platform, the installation's subdirs may have lost their permissions thanks to zip extraction. Chmod them all to 755 by running `find . -type d -exec chmod 0755 {} \;` from the root of your Kohana installation. + +You should see the installation page. If it reports any errors, you will need to correct them before continuing. + + + +Once your install page reports that your environment is set up correctly you need to either rename or delete `install.php` in the root directory. You should then see the Kohana welcome page: + + + +## Setting up a production environment + +There are a few things you'll want to do with your application before moving into production. + +1. See the [Configuration page](about.configuration) in the docs. + This covers most of the global settings that would change between environments. + As a general rule, you should enable caching and disable profiling ([Kohana::init] settings) for production sites. + [Route caching](api/Route#cache) can also help if you have a lot of routes. +2. Catch all exceptions in `application/bootstrap.php`, so that sensitive data is cannot be leaked by stack traces. + See the example below which was taken from Shadowhand's [wingsc.com source](http://github.com/shadowhand/wingsc). +3. Turn on APC or some kind of opcode caching. + This is the single easiest performance boost you can make to PHP itself. The more complex your application, the bigger the benefit of using opcode caching. + +[!!] Note: The default bootstrap will set Kohana::$environment = $_ENV['KOHANA_ENV'] if set. Docs on how to supply this variable are available in your web server's documentation (e.g. [Apache](http://httpd.apache.org/docs/1.3/mod/mod_env.html#setenv), [Lighttpd](http://redmine.lighttpd.net/wiki/1/Docs:ModSetEnv#Options), [Nginx](http://wiki.nginx.org/NginxHttpFcgiModule#fastcgi_param)). This is considered better practice than many alternative methods to set Kohana::$enviroment. + + /** + * Set the environment string by the domain (defaults to Kohana::DEVELOPMENT). + */ + Kohana::$environment = ($_SERVER['SERVER_NAME'] !== 'localhost') ? Kohana::PRODUCTION : Kohana::DEVELOPMENT; + /** + * Initialise Kohana based on environment + */ + Kohana::init(array( + 'base_url' => '/', + 'index_file' => FALSE, + 'profile' => Kohana::$environment !== Kohana::PRODUCTION, + 'caching' => Kohana::$environment === Kohana::PRODUCTION, + )); + + /** + * Execute the main request using PATH_INFO. If no URI source is specified, + * the URI will be automatically detected. + */ + $request = Request::instance($_SERVER['PATH_INFO']); + + try + { + // Attempt to execute the response + $request->execute(); + } + catch (Exception $e) + { + if (Kohana::$environment === Kohana::DEVELOPMENT) + { + // Just re-throw the exception + throw $e; + } + + // Log the error + Kohana::$log->add(Kohana::ERROR, Kohana::exception_text($e)); + + // Create a 404 response + $request->status = 404; + $request->response = View::factory('template') + ->set('title', '404') + ->set('content', View::factory('errors/404')); + } + + if ($request->send_headers()->response) + { + // Get the total memory and execution time + $total = array( + '{memory_usage}' => number_format((memory_get_peak_usage() - KOHANA_START_MEMORY) / 1024, 2).'KB', + '{execution_time}' => number_format(microtime(TRUE) - KOHANA_START_TIME, 5).' seconds'); + + // Insert the totals into the response + $request->response = str_replace(array_keys($total), $total, $request->response); + } + + + /** + * Display the request response. + */ + echo $request->response; + diff --git a/includes/kohana/modules/userguide/guide/about.kohana.md b/includes/kohana/modules/userguide/guide/about.kohana.md new file mode 100644 index 00000000..c1ad270f --- /dev/null +++ b/includes/kohana/modules/userguide/guide/about.kohana.md @@ -0,0 +1,18 @@ +# What is Kohana? + +Kohana is an open source, [object oriented](http://wikipedia.org/wiki/Object-Oriented_Programming) [MVC](http://wikipedia.org/wiki/Model–View–Controller "Model View Controller") [web framework](http://wikipedia.org/wiki/Web_Framework) built using [PHP5](http://php.net/manual/intro-whatis "PHP Hypertext Preprocessor") by a team of volunteers that aims to be swift, secure, and small. + +[!!] Kohana is licensed under a [BSD license](http://kohanaframework.org/license), so you can legally use it for any kind of open source, commercial, or personal project. + +## What makes Kohana great? + +Anything can be extended using the unique [filesystem](about.filesystem) design, little or no [configuration](about.configuration) is necessary, [error handling](debugging.errors) helps locate the source of errors quickly, and [debugging](debugging) and [profiling](debugging.profiling) provide insight into the application. + +To help secure your applications, tools for [XSS removal](security.xss), [input validation](security.validation), [signed cookies](security.cookies), [form](security.forms) and [HTML](security.html) generators are all included. The [database](security.database) layer provides protection against [SQL injection](http://wikipedia.org/wiki/SQL_Injection). Of course, all official code is carefully written and reviewed for security. + +## Contribute to the Documentation + +We are working very hard to provide complete documentation. To help improve the guide, please [fork the userguide](http://github.com/kohana/userguide), make your changes, and send a pull request. If you are not familiar with git, you can also submit a [feature request](http://dev.kohanaframework.org/projects/kohana3/issues) (requires registration). + +## Help, I can't find the answer? +If you are having trouble finding an answer here, have a look through the [unofficial wiki](http://kerkness.ca/wiki/doku.php). Your answer may also be found by searching the [forum](http://forum.kohanaphp.com/) or [stackoverflow](http://stackoverflow.com/questions/tagged/kohana) followed by asking your question on either. Additionally, you can chat with the community of developers on the freenode [#kohana](irc://irc.freenode.net/kohana) IRC channel. \ No newline at end of file diff --git a/includes/kohana/modules/userguide/guide/about.mvc.md b/includes/kohana/modules/userguide/guide/about.mvc.md new file mode 100644 index 00000000..4c9442d5 --- /dev/null +++ b/includes/kohana/modules/userguide/guide/about.mvc.md @@ -0,0 +1,7 @@ +# (Hierarchical) Model View Controller + +Model View Controller (Or MVC for short) is a popular design pattern that separates your data sources (Model) from the presentation/templates (View) and the request logic (Controller). + +It makes it much easier to develop applications as the system is designed to maximise the code reuse, meaning you don't have to write as much! + +[!!] Stub diff --git a/includes/kohana/modules/userguide/guide/about.translation.md b/includes/kohana/modules/userguide/guide/about.translation.md new file mode 100644 index 00000000..00c3f529 --- /dev/null +++ b/includes/kohana/modules/userguide/guide/about.translation.md @@ -0,0 +1,4 @@ +# Translation + +[!!] This article is a stub! + diff --git a/includes/kohana/modules/userguide/guide/about.upgrading.md b/includes/kohana/modules/userguide/guide/about.upgrading.md new file mode 100644 index 00000000..ce11fcf4 --- /dev/null +++ b/includes/kohana/modules/userguide/guide/about.upgrading.md @@ -0,0 +1,290 @@ +# Upgrading from 2.3.x + +Most of Kohana v3 works very differently from Kohana 2.3, here's a list of common gotchas and tips for upgrading. + +## Naming conventions + +The 2.x series differentiated between different 'types' of class (i.e. controller, model etc.) using suffixes. Folders within model / controller folders didn't have any bearing on the name of the class. + +In 3.0 this approach has been scrapped in favour of the Zend framework filesystem conventions, where the name of the class is a path to the class itself, separated by underscores instead of slashes (i.e. `/some/class/file.php` becomes `Some_Class_File`). + +See the [conventions documentation](start.conventions) for more information. + +## Input Library + +The Input Library has been removed from 3.0 in favour of just using `$_GET` and `$_POST`. + +### XSS Protection + +If you need to XSS clean some user input you can use [Security::xss_clean] to sanitise it, like so: + + $_POST['description'] = security::xss_clean($_POST['description']); + +You can also use the [Security::xss_clean] as a filter with the [Validate] library: + + $validation = new Validate($_POST); + + $validate->filter('description', 'Security::xss_clean'); + +### POST & GET + +One of the great features of the Input library was that if you tried to access the value in one of the superglobal arrays and it didn't exist the Input library would return a default value that you could specify i.e.: + + $_GET = array(); + + // $id is assigned the value 1 + $id = Input::instance()->get('id', 1); + + $_GET['id'] = 25; + + // $id is assigned the value 25 + $id = Input::instance()->get('id', 1); + +In 3.0 you can duplicate this functionality using [Arr::get]: + + $_GET = array(); + + // $id is assigned the value 1 + $id = Arr::get($_GET, 'id', 1); + + $_GET['id'] = 42; + + // $id is assigned the value 42 + $id = Arr::get($_GET, 'id', 1); + +## ORM Library + +There have been quite a few major changes in ORM since 2.3, here's a list of the more common upgrading problems. + +### Member variables + +All member variables are now prefixed with an underscore (_) and are no longer accessible via `__get()`. Instead you have to call a function with the name of the property, minus the underscore. + +For instance, what was once `loaded` in 2.3 is now `_loaded` and can be accessed from outside the class via `$model->loaded()`. + +### Relationships + +In 2.3 if you wanted to iterate a model's related objects you could do: + + foreach($model->{relation_name} as $relation) + +However, in the new system this won't work. In version 2.3 any queries generated using the Database library were generated in a global scope, meaning that you couldn't try and build two queries simultaneously. Take for example: + +# TODO: NEED A DECENT EXAMPLE!!!! + +This query would fail as the second, inner query would 'inherit' the conditions of the first one, thus causing pandemonia. +In v3.0 this has been fixed by creating each query in its own scope, however this also means that some things won't work quite as expected. Take for example: + + foreach(ORM::factory('user', 3)->where('post_date', '>', time() - (3600 * 24))->posts as $post) + { + echo $post->title; + } + +[!!] (See [the Database tutorial](tutorials.databases) for the new query syntax) + +In 2.3 you would expect this to return an iterator of all posts by user 3 where `post_date` was some time within the last 24 hours, however instead it'll apply the where condition to the user model and return a `Model_Post` with the joining conditions specified. + +To achieve the same effect as in 2.3 you need to rearrange the structure slightly: + + foreach(ORM::factory('user', 3)->posts->where('post_date', '>', time() - (36000 * 24))->find_all() as $post) + { + echo $post->title; + } + +This also applies to `has_one` relationships: + + // Incorrect + $user = ORM::factory('post', 42)->author; + // Correct + $user = ORM::factory('post', 42)->author->find(); + +### Has and belongs to many relationships + +In 2.3 you could specify `has_and_belongs_to_many` relationships. In 3.0 this functionality has been refactored into `has_many` *through*. + +In your models you define a `has_many` relationship to the other model but then you add a `'through' => 'table'` attribute, where `'table'` is the name of your through table. For example (in the context of posts<>categories): + + $_has_many = array + ( + 'categories' => array + ( + 'model' => 'category', // The foreign model + 'through' => 'post_categories' // The joining table + ), + ); + +If you've set up kohana to use a table prefix then you don't need to worry about explicitly prefixing the table. + +### Foreign keys + +If you wanted to override a foreign key in 2.x's ORM you had to specify the relationship it belonged to, and your new foreign key in the member variable `$foreign_keys`. + +In 3.0 you now define a `foreign_key` key in the relationship's definition, like so: + + Class Model_Post extends ORM + { + $_belongs_to = array + ( + 'author' => array + ( + 'model' => 'user', + 'foreign_key' => 'user_id', + ), + ); + } + +In this example we should then have a `user_id` field in our posts table. + + + +In has_many relationships the `far_key` is the field in the through table which links it to the foreign table and the foreign key is the field in the through table which links "this" model's table to the through table. + +Consider the following setup, "Posts" have and belong to many "Categories" through `posts_sections`. + +| categories | posts_sections | posts | +|------------|------------------|---------| +| id | section_id | id | +| name | post_id | title | +| | | content | + + Class Model_Post extends ORM + { + protected $_has_many = array( + 'sections' => array( + 'model' => 'category', + 'through' => 'posts_sections', + 'far_key' => 'section_id', + ), + ); + } + + Class Model_Category extends ORM + { + protected $_has_many = array ( + 'posts' => array( + 'model' => 'post', + 'through' => 'posts_sections', + 'foreign_key' => 'section_id', + ), + ); + } + + +Obviously the aliasing setup here is a little crazy, but it's a good example of how the foreign/far key system works. + +### ORM Iterator + +It's also worth noting that `ORM_Iterator` has now been refactored into `Database_Result`. + +If you need to get an array of ORM objects with their keys as the object's pk, you need to call [Database_Result::as_array], e.g. + + $objects = ORM::factory('user')->find_all()->as_array('id'); + +Where `id` is the user table's primary key. + +## Router Library + +In version 2 there was a Router library that handled the main request. It let you define basic routes in a `config/routes.php` file and it would allow you to use custom regex for the routes, however it was fairly inflexible if you wanted to do something radical. + +## Routes + +The routing system (now refered to as the request system) is a lot more flexible in 3.0. Routes are now defined in the bootstrap file (`application/bootstrap.php`) and the module init.php (`modules/module_name/init.php`). It's also worth noting that routes are evaluated in the order that they are defined. + +Instead of defining an array of routes you now create a new [Route] object for each route. Unlike in the 2.x series there is no need to map one uri to another. Instead you specify a pattern for a uri, use variables to mark the segments (i.e. controller, method, id). + +For example, in 2.x these regexes: + + $config['([a-z]+)/?(\d+)/?([a-z]*)'] = '$1/$3/$1'; + +Would map the uri `controller/id/method` to `controller/method/id`. In 3.0 you'd use: + + Route::set('reversed','({{userguide/examples/error}}
+
+## Disabling Error/Exception Handling
+
+If you do not want to use the internal error handling, you can disable it when calling [Kohana::init]:
+
+ Kohana::init(array('errors' => FALSE));
diff --git a/includes/kohana/modules/userguide/guide/debugging.profiling.md b/includes/kohana/modules/userguide/guide/debugging.profiling.md
new file mode 100644
index 00000000..493dd484
--- /dev/null
+++ b/includes/kohana/modules/userguide/guide/debugging.profiling.md
@@ -0,0 +1,20 @@
+# Profiling
+
+Kohana provides a very simple way to display statistics about your application:
+
+1. Common [Kohana] method calls
+2. Requests
+3. [Database] queries
+4. Average execution times for your application
+
+## Example
+
+You can display or collect the current [profiler] statistics at any time:
+
+
+
+
+
+## Preview
+
+{{profiler/stats}}
\ No newline at end of file
diff --git a/includes/kohana/modules/userguide/guide/es-es/debugging.errors.md b/includes/kohana/modules/userguide/guide/es-es/debugging.errors.md
new file mode 100644
index 00000000..aa124880
--- /dev/null
+++ b/includes/kohana/modules/userguide/guide/es-es/debugging.errors.md
@@ -0,0 +1,24 @@
+# Gestión de Errores/Excepciones
+
+Kohana proporciona un gestor de errores y excepciones que transforma errores en excepciones usando la clase [ErrorException](http://php.net/errorexception) de PHP. Se muestran muchos detalles del error y del estado interno de la aplicación:
+
+1. Clase de excepción
+2. Nivel del error
+3. Mensaje de error
+4. Fuente del error, con la línea del error resaltada
+5. Una [depuración hacia atrás](http://php.net/debug_backtrace) del flujo de ejecución
+6. Archivos incluídos, extensiones cargadas y variables globales
+
+## Ejemplo
+
+Haz clic en cualquiera de los enlaces para mostrar la información adicional:
+
+{{userguide/examples/error}}
+
+## Desactivando la Gestión de Errores/Excepciones
+
+Si no quieres usar la gestión de errores interna, la puedes desactivar cuando se llama a [Kohana::init]:
+
+~~~
+Kohana::init(array('errors' => FALSE));
+~~~
diff --git a/includes/kohana/modules/userguide/guide/es-es/debugging.md b/includes/kohana/modules/userguide/guide/es-es/debugging.md
new file mode 100644
index 00000000..d277e327
--- /dev/null
+++ b/includes/kohana/modules/userguide/guide/es-es/debugging.md
@@ -0,0 +1,24 @@
+# Depuración
+
+Kohana incluye varias herramientas útiles que te ayudarán en la depuración de tus aplicaciones.
+
+La más básica de ellas es [Kohana::debug]. Este método simple mostrará cualquier número de variables, similar a [var_export] o [print_r], pero usando HTML para una mejor visualización.
+
+~~~
+// Mostrar el contenido de las variables $foo y $bar
+echo Kohana::debug($foo, $bar);
+~~~
+
+Kohana también proporciona un método para mostrar el código fuente de una línea particular usando [Kohana::debug_source].
+
+~~~
+// Mostrar esta línea del código
+echo Kohana::debug_source(__FILE__, __LINE__);
+~~~
+
+Si quieres mostrar información sobre los archivos de tu aplicación sin exponer el directorio de instalación, puedes usar [Kohana::debug_path]:
+
+~~~
+// Mostrar "APPPATH/cache" en vez de la ruta real
+echo Kohana::debug_file(APPPATH.'cache');
+~~~
diff --git a/includes/kohana/modules/userguide/guide/es-es/debugging.profiling.md b/includes/kohana/modules/userguide/guide/es-es/debugging.profiling.md
new file mode 100644
index 00000000..f38b78ee
--- /dev/null
+++ b/includes/kohana/modules/userguide/guide/es-es/debugging.profiling.md
@@ -0,0 +1,22 @@
+# Análisis de Rendimiento
+
+Kohana proporciona una forma muy simple de mostrar estadísticas sobre tu aplicación:
+
+1. Los métodos de [Kohana] más usados
+2. Peticiones
+3. Consultas a la Base de Datos ([Database])
+4. Tiempo de ejecución media de tu aplicación
+
+## Ejemplo
+
+En cualquier momento puedes mostrar o recolectar las estadísticas actuales del analizador ([profiler]):
+
+~~~
+
+
+
+~~~
+
+## Vista previa
+
+{{profiler/stats}}
diff --git a/includes/kohana/modules/userguide/guide/es-es/features.md b/includes/kohana/modules/userguide/guide/es-es/features.md
new file mode 100644
index 00000000..e846d3b0
--- /dev/null
+++ b/includes/kohana/modules/userguide/guide/es-es/features.md
@@ -0,0 +1 @@
+Esta página lista las características de Kohana v3
diff --git a/includes/kohana/modules/userguide/guide/es-es/menu.md b/includes/kohana/modules/userguide/guide/es-es/menu.md
new file mode 100644
index 00000000..c6eaed2f
--- /dev/null
+++ b/includes/kohana/modules/userguide/guide/es-es/menu.md
@@ -0,0 +1,23 @@
+1. **[Cómo Empezar](start)**
+ - [Convenciones y Estilos](start.conventions)
+ - [Instalación](start.installation)
+ - [Configuración](start.configuration)
+ - [Modelo Vista Controlador](start.mvc)
+ - [Sistema de Archivos](start.filesystem)
+ - [Autocarga](start.autoloading)
+ - [Proceso de las Peticiones](start.flow)
+2. **[Tutoriales](tutorials)**
+ - [Hola, Mundo](tutorials.helloworld)
+ - [Rutas, URLs, y Enlaces](tutorials.urls)
+ - [Bases de Datos](tutorials.databases)
+3. **[Seguridad](security)**
+ - [XSS](security.xss)
+ - [Validación](security.validation)
+ - [Cookies](security.cookies)
+ - [Bases de Datos](security.database)
+4. **[Depuración](debugging)**
+ - [Gestión de Errores](debugging.errors)
+ - [Análisis de Rendimiento](debugging.profiling)
+5. **[Actualizando](upgrading)**
+ - [Desde 2.3](upgrading.23)
+6. **[Explorar API](api)**
diff --git a/includes/kohana/modules/userguide/guide/es-es/security.cookies.md b/includes/kohana/modules/userguide/guide/es-es/security.cookies.md
new file mode 100644
index 00000000..c4bc0da7
--- /dev/null
+++ b/includes/kohana/modules/userguide/guide/es-es/security.cookies.md
@@ -0,0 +1,3 @@
+# Seguridad en las Cookies
+
+[!!] inacabado
diff --git a/includes/kohana/modules/userguide/guide/es-es/security.database.md b/includes/kohana/modules/userguide/guide/es-es/security.database.md
new file mode 100644
index 00000000..2d86664b
--- /dev/null
+++ b/includes/kohana/modules/userguide/guide/es-es/security.database.md
@@ -0,0 +1,3 @@
+# Seguridad en las Bases de Datos
+
+[!!] inacabado
diff --git a/includes/kohana/modules/userguide/guide/es-es/security.md b/includes/kohana/modules/userguide/guide/es-es/security.md
new file mode 100644
index 00000000..0b1b50aa
--- /dev/null
+++ b/includes/kohana/modules/userguide/guide/es-es/security.md
@@ -0,0 +1,3 @@
+# Seguridad
+
+[!!] inacabado
diff --git a/includes/kohana/modules/userguide/guide/es-es/security.validation.md b/includes/kohana/modules/userguide/guide/es-es/security.validation.md
new file mode 100644
index 00000000..440151fe
--- /dev/null
+++ b/includes/kohana/modules/userguide/guide/es-es/security.validation.md
@@ -0,0 +1,3 @@
+# Validación
+
+[!!] inacabado
diff --git a/includes/kohana/modules/userguide/guide/es-es/security.xss.md b/includes/kohana/modules/userguide/guide/es-es/security.xss.md
new file mode 100644
index 00000000..0f16deb1
--- /dev/null
+++ b/includes/kohana/modules/userguide/guide/es-es/security.xss.md
@@ -0,0 +1,15 @@
+# Seguridad en Cross-Site Scripting (XSS)
+
+El primer paso para prevenir los ataques de [XSS](http://es.wikipedia.org/wiki/Cross-site_scripting) es saber cuando necesitas protegerte a ti mismo. El XSS sólo puede llevarse a cabo cuando se muestra dentro de contenido HTML, muchas veces vía una entrada de formulario o cuando mostramos datos de resultados de la base de datos. Cualquier variable global que contenga información desde el cliente puede ser contaminada. Esto incluye los datos de las variables $_GET, $_POST, y $_COOKIE.
+
+## Prevención
+
+Hay unas pocas reglas simples para proteger el HTML tu aplicación del XSS. La primera es usar el método [Security::xss] para limpiar cualquier dato de entrada que venga de una variable global. Si no necesitas HTML en una variable, usa [strip_tags](http://php.net/strip_tags) para remover todas las etiquetas HTML innecesarias del contenido.
+
+[!!] Si quieres permitir a los usuarios enviar HTML en tu aplicación, es altamente recomendable usar una herramienta de limpieza de HTML como [HTML Purifier](http://htmlpurifier.org/) o [HTML Tidy](http://php.net/tidy).
+
+La segunda es que siempre debemos escapar los datos cuando se insertan en el HTML. La clase [HTML] proporciona generadores para muchas de las principales etiquetas, incluyendo scripts, hojas de estilo, enlaces, imágenes, y email (mailto). Cualquier contenido no verificado debería escaparse usando [HTML::chars].
+
+## Referencias
+
+* [OWASP XSS Cheat Sheet](http://www.owasp.org/index.php/XSS_(Cross_Site_Scripting)_Prevention_Cheat_Sheet)
diff --git a/includes/kohana/modules/userguide/guide/es-es/start.autoloading.md b/includes/kohana/modules/userguide/guide/es-es/start.autoloading.md
new file mode 100644
index 00000000..b115565f
--- /dev/null
+++ b/includes/kohana/modules/userguide/guide/es-es/start.autoloading.md
@@ -0,0 +1,17 @@
+# Autocarga
+
+Kohana aprovecha la habilidad de PHP [autocarga](http://docs.php.net/manual/es/language.oop5.autoload.php). Esto elimina la necesidad de llamar a [include](http://php.net/include) o [require](http://php.net/require) antes de usar una clase.
+
+Las clases son cargadas usando el método [Kohana::auto_load], el cual hace una simple conversión del nombre de la clase al nombre del archivo:
+
+1. Las clases son colocadas en el directorio `classes/` del [sistema de archivos](start.filesystem)
+2. Cualquier caracter de barra baja es convertido a barra invertida
+2. El nombre de archivo es todo en minúsculas
+
+Cuando llamamos a una clase que no ha sido cargada (por ejemplo: `Session_Cookie`), Kohana buscará en el sistema de archivos usando [Kohana::find_file] un archivo llamado `classes/session/cookie.php`.
+
+## Autocargadores personalizados
+
+[!!] El autocargador por defecto es activado en `application/bootstrap.php`.
+
+Los cargadores de clases adicionales pueden ser añadidos usando [spl_autoload_register](http://php.net/spl_autoload_register).
diff --git a/includes/kohana/modules/userguide/guide/es-es/start.configuration.md b/includes/kohana/modules/userguide/guide/es-es/start.configuration.md
new file mode 100644
index 00000000..0413403f
--- /dev/null
+++ b/includes/kohana/modules/userguide/guide/es-es/start.configuration.md
@@ -0,0 +1,94 @@
+# Configuración General
+
+[!!] por hacer, descripción de los beneficios de las propiedades estáticas para la configuración
+
+## Configuración Principal
+
+La primera tarea de configuración de cualquier nueva instalación de Kohana es cambiar la configuración de inicio [Kohana::init] en `application/bootstrap.php`. Los datos configurables son:
+
+`boolean` errors
+: ¿Usar el gestor de errores y excepciones interno? (Por defecto `TRUE`) Establecer a `FALSE` para desactivar el gestor de errores y excepciones de Kohana.
+
+`boolean` profile
+: ¿Hacer análisis de rendimiento interno? (Por defecto `TRUE`) Establecer a `FALSE` para desactivarlo. En sitios en producción debería estar desactivado para un mejor rendimiento.
+
+`boolean` caching
+: ¿Cachear la localización de los archivos entre peticiones? (Por defecto `FALSE`) Establecer a `TRUE` para cachear la
+ ruta absoluta de los archivos. Esto aumenta dramáticamente la velocidad de [Kohana::find_file] y puede muchas veces
+ tener un impacto dramático en el desempeño. Sólo activar en sitios en producción o para su prueba.
+
+`string` charset
+: Juego de caracteres usado para todas las entradas y salidas. (Por defecto `"utf-8"`) Debería ser un juego de caracteres que sea soportado por [htmlspecialchars](http://php.net/htmlspecialchars) e [iconv](http://php.net/iconv).
+
+`string` base_url
+: URL base de la aplicación. (Por defecto `"/"`) Puede ser una URL completa o parcial. Por ejemplo "http://example.com/kohana/" o sólo "/kohana/" funcionan ambas por igual.
+
+`string` index_file
+: El archivo PHP que inicia la aplicación. (Por defecto `"index.php"`) Establecer a `FALSE` cuando elimines el archivo index con la reescritura de la URL (mod_rewrite y similares).
+
+`string` cache_dir
+: Directorio de la Cache. (Por defecto `"application/cache"`) Debe apuntar a un directorio **escribible**.
+
+## Configuración de las Cookies
+
+Hay varias propiedades estáticas en la clase [Cookie] que deberían establecerse, especialmente en sitios en producción.
+
+`string` salt
+: Cadena que es usada para crear [cookies cifradas](security.cookies)
+
+`integer` expiration
+: Tiempo de expiración en segundos
+
+`string` path
+: Ruta URL para restringir dónde pueden ser accedidas las cookies
+
+`string` domain
+: Dominio URL para restringir dónde pueden ser accedidas las cookies
+
+`boolean` secure
+: Permitir que las cookies sólo sean accedidas por HTTPS
+
+`boolean` httponly
+: Permitir que las cookies sólo sean accedidas por HTTP (también desactiva el acceso por Javascript)
+
+# Archivos de Configuración
+
+La configuración se establece en archivos PHP planos, del estilo de:
+
+~~~
+ 'value',
+ 'options' => array(
+ 'foo' => 'bar',
+ ),
+);
+~~~
+
+Si el archivo de configuración anterior se llamaba `myconf.php`, puedes acceder a él usando:
+
+~~~
+$config = Kohana::config('myconf');
+$options = $config['options'];
+~~~
+
+[Kohana::config] también proporciona una forma corta para acceder a valores individuales del array de configuración usando "rutas con puntos".
+
+Obtener el array "options":
+
+~~~
+$options = Kohana::config('myconf.options');
+~~~
+
+Obtener el valor de "foo" del array "options":
+
+~~~
+$foo = Kohana::config('myconf.options.foo');
+~~~
+
+Los arrays de configuración también pueden ser accedidos como objetos, si prefieres ese método:
+
+~~~
+$options = Kohana::config('myconf')->options;
+~~~
diff --git a/includes/kohana/modules/userguide/guide/es-es/start.conventions.md b/includes/kohana/modules/userguide/guide/es-es/start.conventions.md
new file mode 100644
index 00000000..731f1373
--- /dev/null
+++ b/includes/kohana/modules/userguide/guide/es-es/start.conventions.md
@@ -0,0 +1,26 @@
+# Convenciones
+
+## Nombre de las clases y la localización del archivo
+
+Los nombres de las clases en Kohana siguen una forma estricta para facilitar la [autocarga](start.autoloading).
+
+Los nombres de las clases deben tener la primera letra mayúscula con barra baja para separar palabras. Las barras bajas son significativas ya que directamente reflejan la localización del archivo en el sistema de archivos.
+
+ Clase Archivo
+
+ Controller_Template classes/controller/template.php
+ Model_User classes/model/user.php
+ Model_Auth_User classes/model/auth/user.php
+ Auth classes/auth.php
+
+Los nombres de las clases del estilo de PrimeraMayuscula no deberían ser usadas.
+
+Todos los nombres de los archivos de las clases y los directorios van en minúscula.
+
+Todas las clases deben ir en el directorio `classes`. Esto debe ser así en cualquier nivel del [sistema de archivos en cascada](start.filesystem).
+
+Kohana 3 no diferencia entre *tipos* de clases de la misma forma en que Kohana 2.x y otros frameworks lo hacen. No hay diferencia entre una clase tipo 'helper' o una de tipo 'library' - en Kohana 3 cualquier clase puede implementar cualquier interface que necesite o ser estática totalmente (estilo helper), o instanciable, o una mezcla (por ejemplo singleton).
+
+## Estilo de Código
+
+Se recomienda seguir el estilo de código usado en Kohana. Usamos el [estilo BSD/Allman](http://en.wikipedia.org/wiki/Indent_style#BSD.2FAllman_style). ([Descripción más pormenorizada](http://dev.kohanaphp.com/wiki/kohana2/CodingStyle) del estilo de código preferido por Kohana)
diff --git a/includes/kohana/modules/userguide/guide/es-es/start.filesystem.md b/includes/kohana/modules/userguide/guide/es-es/start.filesystem.md
new file mode 100644
index 00000000..bee39919
--- /dev/null
+++ b/includes/kohana/modules/userguide/guide/es-es/start.filesystem.md
@@ -0,0 +1,13 @@
+# Sistema de Archivos en Cascada
+
+El sistema de archivos de Kohana se compone de una única estructura de directorios que es repetida a lo largo de todos los directorios, lo que llamamos la ruta de inclusión, que sigue el orden:
+
+1. application
+2. modules, según el orden en que sean añadidos
+3. system
+
+Los archivos que se encuentran en directorios superiores en la lista de las rutas de inclusión tienen preferencia sobre los archivos del mismo nombre pero que están más abajo, lo cual hace posible sobrecargar cualquier archivo colocando otro archivo con el mismo nombre en un directorio superior:
+
+
+
+Si tiene un archivo de Vista llamado layout.php en los directorios application/views y system/views, será devuelto el que se encuentra bajo application cuando se busque por layout.php ya que se encuentra más arriba en la lista de inclusión ordenada. Si elimina ese archivo de application/views, el que se encuentra en system/views será devuelto cuando lo busquemos.
diff --git a/includes/kohana/modules/userguide/guide/es-es/start.flow.md b/includes/kohana/modules/userguide/guide/es-es/start.flow.md
new file mode 100644
index 00000000..401973aa
--- /dev/null
+++ b/includes/kohana/modules/userguide/guide/es-es/start.flow.md
@@ -0,0 +1,21 @@
+# Proceso de las Peticiones
+
+Cada aplicación sigue el siguiente proceso:
+
+1. La aplicación empieza desde el archivo `index.php`
+2. Incluye `APPPATH/bootstrap.php`
+3. bootstrap.php llama a [Kohana::modules] con la lista de módulos usados
+ 1. Genera una matriz con las rutas para el sistema de archivos en cascada
+ 2. Comprueba cada módulo para ver si tiene un init.php, y si lo tiene, lo carga
+ * Cada init.php puede definir una serie de rutas a usar, que son cargadas cuando el archivo init.php es incluido
+4. [Request::instance] es llamada para procesar la petición
+ 1. Comprueba cada ruta hasta que se encuentra una coincidencia
+ 2. Carga el controlador y le pasa la petición
+ 3. Llama al método [Controller::before]
+ 4. Llama a la acción del controlador
+ 5. Llama al método [Controller::after]
+5. Muestra la respuesta a la petición ([Request])
+
+La acción del controlador puede ser cambiada por el método [Controller::before] en base a los parámetros de la petición.
+
+[!!] inacabado
diff --git a/includes/kohana/modules/userguide/guide/es-es/start.installation.md b/includes/kohana/modules/userguide/guide/es-es/start.installation.md
new file mode 100644
index 00000000..6599326e
--- /dev/null
+++ b/includes/kohana/modules/userguide/guide/es-es/start.installation.md
@@ -0,0 +1,19 @@
+# Instalación
+
+1. Descarga la última versión **estable** de la [web de Kohana](http://kohanaphp.com/)
+2. Descomprime el archivo descargado para crear un directorio `kohana`
+3. Sube el contenido de esta carpeta a tu servidor
+4. Abre `application/bootstrap.php` y haz los cambios siguientes:
+ - Establece la [zona horaria](http://php.net/timezones) por defecto para tu aplicación
+ - Establece `base_url` en la llamada a [Kohana::init] para reflejar la localización de la carpeta de kohana en tu servidor
+6. Comprueba que los directorios `application/cache` y `application/logs` tienen permisos de escritura para todos con `chmod application/{cache,logs} 0777`
+7. Comprueba tu instalación abriendo la url que has establecido en `base_url` en tu navegador favorito
+
+[!!] Dependiendo de tu plataforma, los subdirectorios de la instalación podrían haber perdido sus permisos debido a la descompresión zip. Para cambiarle los permisos a todos ejecutar `find . -type d -exec chmod 0755 {} \;` desde la raíz de la instalación de Kohana.
+
+Deberías ver la página de instalación. Si reporta algún error, debes corregirlo antes de continuar.
+
+
+
+Una vez que la página de instalación reporta que tu entorno está correcto, debes renombrar o borrar el archivo `install.php` del directorio raíz. Entonces deberías ver la página de bienvenida de Kohana (el texto `hello, world!`).
+
diff --git a/includes/kohana/modules/userguide/guide/es-es/start.md b/includes/kohana/modules/userguide/guide/es-es/start.md
new file mode 100644
index 00000000..826102e3
--- /dev/null
+++ b/includes/kohana/modules/userguide/guide/es-es/start.md
@@ -0,0 +1,11 @@
+# ¿Qué es Kohana?
+
+Kohana es un [framework web](http://es.wikipedia.org/wiki/Framework_para_aplicaciones_web) [MVC](http://es.wikipedia.org/wiki/Modelo_Vista_Controlador "Modelo Vista Controlador") de código abierto y [orientado a objetos](http://es.wikipedia.org/wiki/Programaci%C3%B3n_orientada_a_objetos) realizado para [PHP5](http://docs.php.net/manual/es/intro-whatis.php "Preprocesador de Hipertexto PHP") por un equipo de voluntarios, y destaca por ser rápido, seguro y ligero.
+
+[!!] Kohana está licenciado bajo una [licencia BSD](http://kohanaphp.com/license), así que puede legalmente usarlo para cualquier tipo de proyecto de código abierto, comercial, o personal.
+
+## ¿Qué hace potente a Kohana?
+
+Cualquier cosa puede ser extendida usando el [sistema de archivos](start.filesystem) de diseño único, poco o nada hay que cambiar en la [configuración](start.configuration), la [gestión de errores](debugging.errors) ayuda a localizar los errores de código rápidamente, y la [depuración](debugging) y [profiling](debugging.profiling) informan sobre la aplicación en sí.
+
+Para que sus aplicaciones sean más seguras, se incluyen herramientas para [eliminar el XSS](security.xss), [validar de los datos de entrada](security.validation), [cookies](security.cookies), [formularios](security.forms) y [HTML](security.html). La capa de la [base de datos](security.database) proporciona protección de [inyección de código SQL](http://es.wikipedia.org/wiki/Inyecci%C3%B3n_SQL). Por supuesto, todo el código oficial ha sido cuidadosamente escrito y revisado pensando en la seguridad.
diff --git a/includes/kohana/modules/userguide/guide/es-es/start.mvc.md b/includes/kohana/modules/userguide/guide/es-es/start.mvc.md
new file mode 100644
index 00000000..496695b3
--- /dev/null
+++ b/includes/kohana/modules/userguide/guide/es-es/start.mvc.md
@@ -0,0 +1,5 @@
+# Modelo Vista Controlador
+
+Modelo Vista Controlador (o MVC) es un patrón de diseño popular que separa el origen de tus datos (Modelo) de la presentación/plantillas (Vista) y la lógica de la petición (Controlador).
+
+Esto hace mucho más fácil desarrollar aplicaciones y el sistema es diseñado para maximizar la reutilización de código, lo que se traduce en que ¡no tendrás que escribir mucho!
diff --git a/includes/kohana/modules/userguide/guide/es-es/tutorials.databases.md b/includes/kohana/modules/userguide/guide/es-es/tutorials.databases.md
new file mode 100644
index 00000000..14f29252
--- /dev/null
+++ b/includes/kohana/modules/userguide/guide/es-es/tutorials.databases.md
@@ -0,0 +1,3 @@
+# Bases de Datos
+
+[!!] inacabado
diff --git a/includes/kohana/modules/userguide/guide/es-es/tutorials.helloworld.md b/includes/kohana/modules/userguide/guide/es-es/tutorials.helloworld.md
new file mode 100644
index 00000000..cf451c79
--- /dev/null
+++ b/includes/kohana/modules/userguide/guide/es-es/tutorials.helloworld.md
@@ -0,0 +1,106 @@
+# Hola, Mundo
+
+Muchos frameworks proporcionan algún ejemplo de tipo hola mundo, de forma que ¡sería muy grosero por nuestra parte romper esa tradición!
+
+Empezaremos creando un hola mundo muy básico, y luego lo ampliaremos para seguir con los principios del patrón MVC.
+
+## Lo esencial
+
+En primer lugar, tenemos que crear un controlador que kohana usará para manejar la petición
+
+Crea el archivo `application/classes/controller/hello.php` en tu directorio **application** y copia dentro el siguiente código:
+
+ template->message = 'hello, world!';
+ }
+ }
+
+`extends Controller_Template`
+: Ahora estamos extendiendo el controlador de plantillas, el cual es más conveniente para usar vistas en nuestro controlador.
+
+`public $template = 'site';`
+: El controlador de plantillas necesita conocer que plantilla queremos usar. Automáticamente cargará la vista definida en esta variable y le asignará el objeto de tipo vista.
+
+`$this->template->message = 'hello, world!';`
+: `$this->template` es una referencia al objeto tipo vista de nuestra plantilla del sitio. Lo que estamos haciendo es asignar a una variable de la vista llamada "message" el valor de "hello, world!"
+
+Ahora intentamos ejecutar nuestro código...
+
+{{userguide/examples/hello_world_error}}
+
+Por alguna razón kohana lanza una excepción y no muestra nuestro sorprendente mensaje.
+
+Si miramos dentro del mensaje de error podemos ver que la librería View no es capaz de encontrar la plantilla de nuestro sitio, probablemente porque no ha sido creada todavía - ¡*ouch*!
+
+Vamos y creamos el archivo de vista `application/views/site.php` para nuestro mensaje -
+
+
+
+ We just wanted to say it! :)
+ + + +Si luego refrescamos la página podremos ver el fruto de nuestra labor - + + + +## En resumen + +En este tutorial has aprendido cómo crear un controlador y usar una vista para separar la lógica de la presentación. + +Esto es obviamente una introducción muy básica al trabajo con kohana y no entra de lleno en el potencial que tienes cuando desarrollas aplicaciones con él. diff --git a/includes/kohana/modules/userguide/guide/es-es/tutorials.md b/includes/kohana/modules/userguide/guide/es-es/tutorials.md new file mode 100644 index 00000000..a4363aec --- /dev/null +++ b/includes/kohana/modules/userguide/guide/es-es/tutorials.md @@ -0,0 +1,7 @@ +# Tutoriales + +[!!] inacabado + +- [Hola, Mundo](tutorials.helloworld) +- [Rutas, URLs, y Enlaces](tutorials.urls) +- [Bases de Datos](tutorials.databases) diff --git a/includes/kohana/modules/userguide/guide/es-es/tutorials.urls.md b/includes/kohana/modules/userguide/guide/es-es/tutorials.urls.md new file mode 100644 index 00000000..21c6912a --- /dev/null +++ b/includes/kohana/modules/userguide/guide/es-es/tutorials.urls.md @@ -0,0 +1,3 @@ +# Rutas, URLs, y Enlaces + +[!!] inacabado diff --git a/includes/kohana/modules/userguide/guide/es-es/upgrading.md b/includes/kohana/modules/userguide/guide/es-es/upgrading.md new file mode 100644 index 00000000..07fefeca --- /dev/null +++ b/includes/kohana/modules/userguide/guide/es-es/upgrading.md @@ -0,0 +1,5 @@ +# Actualizando + +Obviamente te gustaría actualizar tu código desde la versión 2 a la 3, y para hacer esta transición más fácil hemos recopilado algunos de los principales cambios desde la versión + +* [Kohana 2.3](upgrading.23) diff --git a/includes/kohana/modules/userguide/guide/features.md b/includes/kohana/modules/userguide/guide/features.md new file mode 100644 index 00000000..25cbb18e --- /dev/null +++ b/includes/kohana/modules/userguide/guide/features.md @@ -0,0 +1 @@ +This page lists the features of Kohana v3 \ No newline at end of file diff --git a/includes/kohana/modules/userguide/guide/fr-fr/about.autoloading.md b/includes/kohana/modules/userguide/guide/fr-fr/about.autoloading.md new file mode 100644 index 00000000..753bc9eb --- /dev/null +++ b/includes/kohana/modules/userguide/guide/fr-fr/about.autoloading.md @@ -0,0 +1,17 @@ +# Auto-chargement de classes + +Kohana tire partie de la fonctionnalité PHP d'[auto-chargement de classes](http://php.net/manual/fr/language.oop5.autoload.php) permettant de s'affranchir des inclusions manuelles avec [include](http://de.php.net/manual/fr/function.include.php) ou [require](http://de.php.net/manual/fr/function.require.php). + +Les classes sont chargées via la méthode [Kohana::auto_load], qui à partir du nom d'une classe, retrouve le fichier associé: + +1. Les classes sont placées dans le répertoire `classes/` de l'[arborescence de fichiers](about.filesystem) +2. Les caractères underscore '_' sont convertis en slashes '/' +2. Les noms de fichier doivent être en minuscule + +Lors de l'appel à une classe non chargée (eg: `Session_Cookie`), Kohana recherchera dans son arboresence via la méthode [Kohana::find_file] le fichier `classes/session/cookie.php`. + +## Auto-chargement tiers + +[!!] Le mécanisme par défaut d'auto-chargement de classes est défini dans le fichier `application/bootstrap.php`. + +Des mécanismes d'auto-chargement supplémentaires peuvent être ajoutés en utilisant [spl_autoload_register](http://php.net/spl_autoload_register). \ No newline at end of file diff --git a/includes/kohana/modules/userguide/guide/fr-fr/about.configuration.md b/includes/kohana/modules/userguide/guide/fr-fr/about.configuration.md new file mode 100644 index 00000000..0ac81c6f --- /dev/null +++ b/includes/kohana/modules/userguide/guide/fr-fr/about.configuration.md @@ -0,0 +1,95 @@ +# Configuration Générale + +[!!] todo, description of benefits of static properties for configuration + +## Configuration du noyau + +La toute première configuration à modifier lors d'une installation de kohana est de changer les paramètres d'initlalisation [Kohana::init] dans le fichier `application/bootstrap.php`. Ces paramètres sont: + +`boolean` errors +: Utilisation de la gestion des erreurs et des exceptions? (Défaut `TRUE`) Affecter à `FALSE` pour désactiver + la gestion des erreurs et exceptions. + +`boolean` profile +: Activer le benchmarking interne? (Défault `TRUE`) Affecter à `FALSE` pour désactiver le benchmarking interne. + A desactiver en production pour obtenir de meilleures performances. + +`boolean` caching +: Mettre en cache les chemins des fichiers entre les requêtes? (Défault `FALSE`) Affecter à `TRUE` pour mettre en cache + les chemins absolus. Ceci peut améliorer drastiquement les performances de la méthode [Kohana::find_file]. + +`string` charset +: Jeu de caractères à utiliser pour toutes les entrées et sorties. (Défault `"utf-8"`) Affecter un jeu de caractères supporté aussi bien par [htmlspecialchars](http://fr.php.net/htmlspecialchars) que [iconv](http://fr.php.net/iconv). + +`string` base_url +: URL racine de l'application. (Défault `"/"`) Peut être une URL complète ou partielle. Par exemple "http://example.com/kohana/" ou "/kohana/" fonctionneraient. + +`string` index_file +: Le fichier PHP qui démarre l'application. (Défault `"index.php"`) Affecter à `FALSE` pour enlever le fichier index de l'URL en utilisant l'URL Rewriting. + +`string` cache_dir +: Répertoire de stockage du cache. (Défault `"application/cache"`) Doit pointer vers un répertoire **inscriptible**. + +## Paramètres des Cookies + +Il y a plusieurs propriétés statiques dans la classe [Cookie] qui doivent être paramétrées, particuliérement sur les sites en production. + +`string` salt +: La chaîne d'aléa (salt) unique utilisée pour [signer les cookies](security.cookies) + +`integer` expiration +: La durée d'expiration par défaut + +`string` path +: Restreindre l'accès aux cookies par rapport au chemin spécifié + +`string` domain +: Restreindre l'accès aux cookies par rapport au domaine spécifié + +`boolean` secure +: N'autoriser les cookies qu'en HTTPS + +`boolean` httponly +: N'autorise l'accès aux cookies que via HTTP (désactive aussi l'accès javascript) + +# Fichiers de configuration + +La configuration de Kohana est faite dans des fichiers à plat PHP, qui ressemblent à l'exemple ci-dessous: + +~~~ + 'value', + 'options' => array( + 'foo' => 'bar', + ), +); +~~~ + +Supposons que le fichier ci-dessus soit appelé `myconf.php`, il est alors possible d'y accèder de la manière suivante: + +~~~ +$config = Kohana::config('myconf'); +$options = $config['options']; +~~~ + +[Kohana::config] fournit aussi un raccourci pour accèder à des clés spécifiques des tableaux de configuration en utilisant des chemins spérarés par le caractère point. + +Récupérer le tableau "options": + +~~~ +$options = Kohana::config('myconf.options'); +~~~ + +Récupérer la valeur de la clé "foo" du tableau "options": + +~~~ +$foo = Kohana::config('myconf.options.foo'); +~~~ + +Les tableaux de configuration peuvent aussi être parcourus comme des objets comme suit: + +~~~ +$options = Kohana::config('myconf')->options; +~~~ diff --git a/includes/kohana/modules/userguide/guide/fr-fr/about.conventions.md b/includes/kohana/modules/userguide/guide/fr-fr/about.conventions.md new file mode 100644 index 00000000..2ac39c69 --- /dev/null +++ b/includes/kohana/modules/userguide/guide/fr-fr/about.conventions.md @@ -0,0 +1,26 @@ +# Conventions et style de codage + +## Nom de classe et emplacement des fichiers + +Les noms de classe dans Kohana suivent des règles strictes pour faciliter l'[auto-chargement de classes](about.autoloading). + +Ils doivent avoir la première lettre en majuscule, et les mots doivent être séparés par des underscores. Les underscores sont très importants car ils déterminent le chemin d'accès au fichier. + +Nom de classe | Chemin +----------------------|------------------------------- +Controller_Template | classes/controller/template.php +Model_User | classes/model/user.php +Database | classes/database.php +Database_Query | classes/database/query.php + +Les noms de classe ne doivent pas utiliser de syntaxe CamelCase sauf si vous ne souhaitez pas créer un nouveau niveau de répertoire. + +Tous les noms de fichier et répertoire sont en minuscule. + +Toutes les classes doivent être dans le répertoire `classes`. Elles peuvent néanmoins être sur plusieurs niveaux de répertoire de l'[arborescence](about.filesystem). + +Kohana 3 ne différencie pas les *types* de classe comme le fait Kohana 2.x. Il n'y a pas de distinction entre une classe 'helper' ou une 'librairie' – avec Kohana 3 toute classe peut implémenter l'interface que vous souhaitez, qu'elle soit statique (helper), instanciable, ou mixte (e.g. singleton). + +## Style de codage + +Il est vivement conseillé de suivre les [styles de codage](http://dev.kohanaphp.com/wiki/kohana2/CodingStyle) de Kohana c'est-à-dire le [style BSD/Allman](http://en.wikipedia.org/wiki/Indent_style#BSD.2FAllman_style) pour les accolades, entre autres choses. \ No newline at end of file diff --git a/includes/kohana/modules/userguide/guide/fr-fr/about.filesystem.md b/includes/kohana/modules/userguide/guide/fr-fr/about.filesystem.md new file mode 100644 index 00000000..2a306300 --- /dev/null +++ b/includes/kohana/modules/userguide/guide/fr-fr/about.filesystem.md @@ -0,0 +1,13 @@ +# Arborescence de fichiers en cascade + +L'arborescence de fichiers de Kohana est construite autour d'une structure de répertoires unique qui est dupliquée dans tous les répertoires formant ce que l'on appelle l'"include path". Cette structure est composée des répertoires suivants et dans cet ordre: + +1. application +2. modules, dans l'ordre dans lequel ils ont été ajoutés +3. system + +Les fichiers qui sont dans les répertoires les plus haut de l'"include path" sont prioritaires par rapport aux fichiers de même noms dans des répertoires plus bas. Cela rend possible la surcharge de nimporte quel fichier en plaçant un fichier de même nom dans un répertoire de niveau supérieur: + + + +Par exemple, si vous avez un fichier appelé layout.php dans les répertoires application/views et system/views, alors celui contenu dans le répertoire application sera retourné lors de l'appel à layout.php du fait qu'il est plus haut dans l'"include path". Si vous supprimez le fichier de application/views, alors c'est celui contenu dans system/views qui sera alors retourné. \ No newline at end of file diff --git a/includes/kohana/modules/userguide/guide/fr-fr/about.flow.md b/includes/kohana/modules/userguide/guide/fr-fr/about.flow.md new file mode 100644 index 00000000..6f13cb7b --- /dev/null +++ b/includes/kohana/modules/userguide/guide/fr-fr/about.flow.md @@ -0,0 +1,21 @@ +# Processus de traitement des requêtes + +Toutes les applications suivent le même processus: + +1. L'application commence depuis `index.php` +2. Inclut `APPPATH/bootstrap.php` +3. L'initialisation (bootstrap) appelle [Kohana::modules] avec une liste de modules à utiliser + 1. Génére un tableau de chemins utilisés par l'arborescence en cascade + 2. Vérifie la présence du fichier init.php dans chaque module. Si il existe + * Chaque fichier init.php peut définir un ensemble de routes à utiliser, elles sont chargées lorsque le fichier init.php est inclut +4. [Request::instance] est appelé pour traiter la requête + 1. Vérifie toutes les routes jusqu'à ce que l'une d'entres elles concorde + 2. Charge le controleur et lui transmet la requête + 3. Appelle la méthode [Controller::before] + 4. Appelle l'action du controleur + 5. Appelle la méthode [Controller::after] +5. Affiche la réponse à la requête + +L'action du controleur peut etre changée suivant ses paramètres de la par [Controller::before]. + +[!!] Stub diff --git a/includes/kohana/modules/userguide/guide/fr-fr/about.install.md b/includes/kohana/modules/userguide/guide/fr-fr/about.install.md new file mode 100644 index 00000000..86e533c1 --- /dev/null +++ b/includes/kohana/modules/userguide/guide/fr-fr/about.install.md @@ -0,0 +1,20 @@ +# Installation + +1. Téléchargez la dernière version **stable** depuis [le site web Kohana](http://kohanaphp.com/) +2. Dézippez l'archive téléchargée pour créer le répertoire `kohana` +3. Uploadez le contenu de ce répertoire sur votre serveur web +4. Ouvrez `application/bootstrap.php` et effectuez les changements suivants: + - Affecter la [timezone](http://php.net/timezones) par défaut de votre application + - Affecter `base_url` dans l'appel à [Kohana::init] afin de faire comprendre à votre serveur ou est situé le répertoire kohana uploadé à l'étape précédente +6. Vérifiez que les répertoires `application/cache` et `application/logs` sont inscriptibles en tapant la commande `chmod application/{cache,logs} 0777` (Linux). +7. Testez votre installation en tapant l'URL que vous avez spécifiée dans `base_url` dans votre navigateur préféré + +[!!] Suivant votre plateforme, l'extraction de l'archive peut avoir changé les permissions sur les sous répertoires. Rétablissez-les avec la commande suivante: `find . -type d -exec chmod 0755 {} \;` depuis la racine de votre installation Kohana. + +Vous devriez alors voir la page d'installation contenant un rapport d'installation. Si une erreur est affichée, vous devez la corriger pour pouvoir continuer. + + + +Une fois que votre rapport d'installation vous informe que votre environnement est correctement configuré, vous devez soit renommer, soit supprimer le fichier `install.php`. Vous devriez alors voir apparaitre la page de bienvenue de Kohana: + + diff --git a/includes/kohana/modules/userguide/guide/fr-fr/about.kohana.md b/includes/kohana/modules/userguide/guide/fr-fr/about.kohana.md new file mode 100644 index 00000000..2897852b --- /dev/null +++ b/includes/kohana/modules/userguide/guide/fr-fr/about.kohana.md @@ -0,0 +1,11 @@ +# Kohana... Kesako? + +Kohana est un [framework web](http://wikipedia.org/wiki/Web_Framework) [PHP5](http://php.net/manual/intro-whatis "PHP Hypertext Preprocessor") open source, [orienté objet](http://wikipedia.org/wiki/Object-Oriented_Programming), adoptant le design pattern [MVC](http://wikipedia.org/wiki/Model–View–Controller "Model View Controller"). Il vise à être rapide, sécurisé et léger. + +[!!] Kohana est licencié sous [licence BSD](http://kohanaphp.com/license), donc vous pouvez légalement l'utiliser pour tout projet open source, commercial ou personnel. + +## Pourquoi Kohana est-il différent? + +Tout peut être surchargé et étendu grâce à son [arborescence de fichiers en cascade](about.filesystem), il y a très peu de [configuration](about.configuration) nécessaire, la [gestion des erreurs](debugging.errors) aide à la localisation rapide de la source des erreurs, et enfin le [debugging](debugging) et le [profiling](debugging.profiling) vous fournissent les statistiques et informations nécessaires sur votre application. + +Pour vous aider dans la sécurisation de votre application, Kohana fournit des protections contre les attaques [XSS](security.xss), des méthodes de [filtrage et de validation des données d'entrées](security.validation), de [signature des cookies](security.cookies), de sécurisation de vos [formulaires](security.forms) et de génération [HTML](security.html). La couche [base de données](security.database) fournit des protections contre l'[injection SQL](http://wikipedia.org/wiki/SQL_Injection). Et bien évidemment, le code officiel est écrit et revu consciencieusement. diff --git a/includes/kohana/modules/userguide/guide/fr-fr/about.mvc.md b/includes/kohana/modules/userguide/guide/fr-fr/about.mvc.md new file mode 100644 index 00000000..16df839f --- /dev/null +++ b/includes/kohana/modules/userguide/guide/fr-fr/about.mvc.md @@ -0,0 +1,5 @@ +# Modèle Vue Controleur + +Modèle Vue Controleur (ou MVC) est un design pattern populaire visant à séparer les sources de données (Modèle) de la présentation (Vue) et de l'enchainement logique de traitement de la requête (Controleur). + +Il rend plus facile le développement d'application modulaires et réutilisables. \ No newline at end of file diff --git a/includes/kohana/modules/userguide/guide/fr-fr/about.upgrading.md b/includes/kohana/modules/userguide/guide/fr-fr/about.upgrading.md new file mode 100644 index 00000000..4f0ec30b --- /dev/null +++ b/includes/kohana/modules/userguide/guide/fr-fr/about.upgrading.md @@ -0,0 +1,290 @@ +# Mise à jour depuis 2.x + +Kohana v3 fonctionne très différemment de Kohana 2.x, néanmoins vous trouverez ci-dessous une liste d'astuces qui pourront vous aider dans votre tâche de mise à jour. + +## Conventions de nommage + +La série 2.x différentie les 'types' de classes (i.e. controleur, modele etc.) en utilisant des suffixes. Dans la série 3.0, cette approche a été abandonnée au profit des conventions du framework Zend c'est-à-dire que les noms de classe sont les chemins vers les classes elles-mêmes. Les répertoires du chemin sont séparés par le caractère underscore au lieu du slashe (i.e. `/some/class/file.php` devient `Some_Class_File`). + +Pour plus d'informations consultez la documentatation sur les [conventions de nommage](start.conventions). + +## Librairie Input + +La librairie Input a été supprimée en faveur de l'utilisation directe des variables `$_GET` et `$_POST`. + +### Protection XSS + +Si vous avez besoin de nettoyer des données contre des attaques XSS, vous pouvez utiliser [Security::xss_clean] de la manière suivante: + + $_POST['description'] = security::xss_clean($_POST['description']); + +Vous pouvez aussi utiliser [Security::xss_clean] en tant que filtre via la librairie [Validate]: + + $validation = new Validate($_POST); + + $validate->filter('description', 'Security::xss_clean'); + +### POST & GET + +Une des fonctionnalités très intéressante de la librairie Input était que lors de la tentative de lecture d'une variable superglobale, si celle-ci n'existait pas, il était possible de spécifier la valeur par défaut retournée i.e.: + + $_GET = array(); + + // On assigne à $id la valeur 1 + $id = Input::instance()->get('id', 1); + + $_GET['id'] = 25; + + // On assigne à $id la valeur 25 + $id = Input::instance()->get('id', 1); + +En 3.0 cette fonctionnalité est rendue par la méthode [Arr::get]: + + $_GET = array(); + + // On assigne à $id la valeur 1 + $id = Arr::get($_GET, 'id', 1); + + $_GET['id'] = 42; + + // On assigne à $id la valeur 42 + $id = Arr::get($_GET, 'id', 1); + +## Librairie ORM + +De nombreux changements majeurs ont été faits sur la librairie ORM depuis la série 2.x, et voici quelques-uns des problèmes les plus courants que vous pourrez rencontrer: + +### Variables de classe + +Toutes les variables de classe sont désormais préfixées par un underscore (_) et ne sont plus accessibles via `__get()`. A la place, vous devez appeler une méthode portant le nom de la propriété sans le caractère underscore. + +Par exemple, la propriété `loaded` en 2.x devient désormais `_loaded` et est accessible depuis l'extérieur via `$model->loaded()`. + +### Relations + +En 2.x, l'itération sur les objets liés à un modèle se faisait comme suit: + + foreach($model->{relation_name} as $relation) + +Cependant avec la nouvelle librarie 3.0 cela ne fonctionnera pas. En effet en version 2.3, toutes les requêtes sont générées avec une portée globale, c'est-à-dire qu'il est impossible de construire 2 requêtes simultanément. Par exemple: + +# TODO: NEED A DECENT EXAMPLE!!!! + +La requête échouera car la seconde requête hérite des conditions de la première et fausse donc les filtres. + +En 3.0 ce problème a été corrigé car chaque requête à sa propre portée. Cela signifie aussi que certains de vos anciens codes ne fonctionneront plus. Prenez par exemple: + + foreach(ORM::factory('user', 3)->where('post_date', '>', time() - (3600 * 24))->posts as $post) + { + echo $post->title; + } + +[!!] (Voir [le tutorial sur la Base de Données](tutorials.databases) pour la nouvelle syntaxe des requêtes) + +En 2.3 on reçoit un itérateur sur tous les posts de l'utilisateur d'id 3 et dont la date est dans l'intervalle spécifié. Au lieu de ça, la condition 'where' sera appliquée au modèle 'user' et la requête retournera un objet `Model_Post` avec les conditions de jointure comme spécifié. + +Pour obtenir le même résultat qu'en 2.x, en 3.0 la structure de la requête doit être modifiée: + + foreach(ORM::factory('user', 3)->posts->where('post_date', '>', time() - (36000 * 24))->find_all() as $post) + { + echo $post->title; + } + +Cela s'applique aussi aux relations `has_one`: + + // Incorrect + $user = ORM::factory('post', 42)->author; + // Correct + $user = ORM::factory('post', 42)->author->find(); + +### Relations Has and belongs to many + +En 2.x vous pouvez spécifier des relations `has_and_belongs_to_many`. En 3.0 cette fonctionnalité a été renommée en `has_many` *through*. + +Dans vos modèles vous définissez une relation `has_many` avec les autres modèles et vous ajoutez un attribut `'through' => 'table'`, où `'table'` est le nom de la table de jointure. Par exemple dans la relation posts<>catégories: + + $_has_many = array + ( + 'categories' => array + ( + 'model' => 'category', // Le modèle étranger + 'through' => 'post_categories' // La table de jointure + ), + ); + +Si vous avez configuré Kohana pour utiliser une prefixe de table vous n'avez pas besoin d'explicitement préfixer la table. + +### Clés étrangères + +En 2.x, pour surcharger une clé étrangère vous deviez spécifier la relation auquelle elle appartenait et ajouter votre nouvelle clé étrangère dans la propriété `$foreign_keys`. + +En 3.0 il faut juste définir une clé `foreign_key` dans la définition de la relation comme suit: + + Class Model_Post extends ORM + { + $_belongs_to = array + ( + 'author' => array + ( + 'model' => 'user', + 'foreign_key' => 'user_id', + ), + ); + } + +Dans cet exemple on doit aussi avoir un champ `user_id` dans la table 'posts'. + + + +Dans les relations has_many le champ `far_key` est le champ de la table de jointure qui le lie à la table étrangère et la clé étrangère est le champ de la table de jointure qui lie la table du modèle courant ("this") avec la table de jointure. + +Considérez la configuration suivante où les "Posts" appartiennent à plusieurs "Categories" via `posts_sections`. + +| categories | posts_sections | posts | +|------------|------------------|---------| +| id | section_id | id | +| name | post_id | title | +| | | content | + + Class Model_Post extends ORM + { + protected $_has_many = array( + 'sections' => array( + 'model' => 'category', + 'through' => 'posts_sections', + 'far_key' => 'section_id', + ), + ); + } + + Class Model_Category extends ORM + { + protected $_has_many = array ( + 'posts' => array( + 'model' => 'post', + 'through' => 'posts_sections', + 'foreign_key' => 'section_id', + ), + ); + } + + +Bien sûr l'exemple d'aliasing présenté ci-dessus est un peu exagéré, mais c'est un bon exemple de fonctionnement des clés foreign/far. + +### Itérateur ORM + +Il est important aussi de noter que `ORM_Iterator` a été renommé en `Database_Result`. + +Si vous avez besoin de récupérer un tableau d'objets ORM dont la clé est la clé étrangère de l'objet, vous devez utiliser [Database_Result::as_array], e.g. + + $objects = ORM::factory('user')->find_all()->as_array('id'); + +où `id` est la clé primaire de la table user. + +## Librairie Router + +En version 2.x il existe une librairie Router qui se charge du traitement des requêtes. Cela permet de définir des routes basiques dans le fichier`config/routes.php` et d'utiliser des expressions régulières mais au détriment de la flexibilité. + +## Routes + +Le sytème de routage est plus flexible en 3.0. Les routes sont maintenant définies dans le fichier bootstrap (`application/bootstrap.php`) et dans le cas des modules dans init.php (`modules/module_name/init.php`). Les routes sont évaluées dans l'ordre dans lequel elles sont définies. + +Aulieu de définir un tableau de routes, désormais on crée un objet [Route] pour chacunes des routes. Contraitement à la version 2.x, il n'est pas nécessaire d'associer une URI à une autre. Au lieu de ça, il faut spécifier un pattern pour une URI en utilisation des variables pour marquer les segments (i.e. controller, method, id). + +Par exemple, en 2.x on créé une route sous forme d'expression régulière comme suit: + + $config['([a-z]+)/?(\d+)/?([a-z]*)'] = '$1/$3/$1'; + +Cette route associe l'URI `controller/id/method` à `controller/method/id`. + +En 3.0 on utilise: + + Route::set('reversed','({{userguide/examples/error}}
+
+## Désactiver le support des Exceptions
+
+Si vous ne voulez pas utiliser le mécanisme interne de gestion des exceptions et des erreurs, vous pouvez le désactiver via [Kohana::init]:
+
+~~~
+Kohana::init(array('errors' => FALSE));
+~~~
\ No newline at end of file
diff --git a/includes/kohana/modules/userguide/guide/fr-fr/debugging.profiling.md b/includes/kohana/modules/userguide/guide/fr-fr/debugging.profiling.md
new file mode 100644
index 00000000..4dea4b6e
--- /dev/null
+++ b/includes/kohana/modules/userguide/guide/fr-fr/debugging.profiling.md
@@ -0,0 +1,22 @@
+# Profiling
+
+Kohana fournit de façon très facile les statistiques de vos applications:
+
+1. Appels de méthodes [Kohana] communes
+2. Requêtes URI
+3. Requêtes de [base de données](tutorials.databases)
+4. Temps moyen d'execution de votre application
+
+## Affichage/Récupération des statistiques
+
+Vous pouvez afficher ou récupérer les statistiques courantes à tout moment en faisant:
+
+~~~
+
+
+
+~~~
+
+## Exemple
+
+{{profiler/stats}}
\ No newline at end of file
diff --git a/includes/kohana/modules/userguide/guide/fr-fr/features.md b/includes/kohana/modules/userguide/guide/fr-fr/features.md
new file mode 100644
index 00000000..068341da
--- /dev/null
+++ b/includes/kohana/modules/userguide/guide/fr-fr/features.md
@@ -0,0 +1 @@
+Cette page liste les fonctionnalités clés de Kohana v3.
\ No newline at end of file
diff --git a/includes/kohana/modules/userguide/guide/fr-fr/menu.md b/includes/kohana/modules/userguide/guide/fr-fr/menu.md
new file mode 100644
index 00000000..2c8bca8a
--- /dev/null
+++ b/includes/kohana/modules/userguide/guide/fr-fr/menu.md
@@ -0,0 +1,26 @@
+1. **Bien débuter**
+ - [Qu'est-ce que Kohana?](about.kohana)
+ - [Conventions et style](about.conventions)
+ - [Installation](about.install)
+ - [Mise à jour depuis 2.x](about.upgrading)
+ - [Configuration](about.configuration)
+ - [Modèle Vue Controleur](about.mvc)
+ - [Arborescence de fichier](about.filesystem)
+ - [Auto-chargement](about.autoloading)
+ - [Enchainement des Requetes](about.flow)
+ - [Explorateur API](api)
+2. **Tutoriaux**
+ - [Hello, World](tutorials.helloworld)
+ - [Routes, URLs, et Liens](tutorials.urls)
+ - [Base de données](tutorials.databases)
+ - [ORM](tutorials.orm)
+ - [Travailler avec Git](tutorials.git)
+3. **Securité**
+ - [XSS](security.xss)
+ - [Validation](security.validation)
+ - [Cookies](security.cookies)
+ - [Base de données](security.database)
+4. **Debugging**
+ - [Code](debugging.code)
+ - [Gestion des erreurs](debugging.errors)
+ - [Profiling](debugging.profiling)
diff --git a/includes/kohana/modules/userguide/guide/fr-fr/security.cookies.md b/includes/kohana/modules/userguide/guide/fr-fr/security.cookies.md
new file mode 100644
index 00000000..cd999df1
--- /dev/null
+++ b/includes/kohana/modules/userguide/guide/fr-fr/security.cookies.md
@@ -0,0 +1,3 @@
+# Sécurité des Cookies
+
+[!!] stub
diff --git a/includes/kohana/modules/userguide/guide/fr-fr/security.database.md b/includes/kohana/modules/userguide/guide/fr-fr/security.database.md
new file mode 100644
index 00000000..9046f266
--- /dev/null
+++ b/includes/kohana/modules/userguide/guide/fr-fr/security.database.md
@@ -0,0 +1,3 @@
+# Sécurité de la Base de données
+
+[!!] stub
diff --git a/includes/kohana/modules/userguide/guide/fr-fr/security.validation.md b/includes/kohana/modules/userguide/guide/fr-fr/security.validation.md
new file mode 100644
index 00000000..9a5b3f97
--- /dev/null
+++ b/includes/kohana/modules/userguide/guide/fr-fr/security.validation.md
@@ -0,0 +1,241 @@
+# Validation
+
+La validation peut être effectuée sur tous les tableaux en utilisant la classe [Validate]. Les labels, filtres, règles et callbacks peuvent être attachés à un objet Validate via un tableau de clé, appellées "champs" (field name).
+
+labels
+: Un label est la version lisible (par un humain) d'un nom de champ.
+
+filters
+: Un filtre modifie la valeur d'un champs avant que les règles et callbacks ne soient exécutées.
+
+rules
+: Une règle est une vérification sur un champ qui retourne `TRUE` ou `FALSE`. Si une règle retourne `FALSE`, une erreur sera ajoutée à ce champ.
+
+callbacks
+: Une callback est une méthode spécifique ayant accès à l'ensemble de l'objet Validate.
+ La valeur retournée par une callback est ignorée. A la place, en cas d'erreur une callback doit manuellement ajouter une erreur à un champ en utilisant [Validate::error].
+
+[!!] A noter que les callbacks [Validate] et les [callbacks PHP](http://php.net/manual/language.pseudo-types.php#language.types.callback) ne sont pas pareils.
+
+Utiliser `TRUE` comment nom de champ lors de l'ajout d'un filtre, règle ou callback a pour effet de l'appliquer à tous les champs.
+
+**L'objet [Validate] supprimera tous les champs du tableau qui n'ont pas explicitement été utilisés via un label, un filtre, une règle ou une callback. Ceci pour empêcher tout accès à un champ qui n'a pas été validé et ajouter ainsi une protection de sécurité supplémentaire.**
+
+La création d'un objet de validation est faite en utilsiant la méthode [Validate::factory]:
+
+ $post = Validate::factory($_POST);
+
+[!!] L'objet `$post` sera utilisé pour le reste de ce tutorial dans lequel sera illustré la validation de l'inscription d'un nouveal utilisateur.
+
+### Règles par défaut
+
+La validation supporte les règles par défaut suivantes:
+
+Nom de la règle | Description
+------------------------- |-------------------------------------------------
+[Validate::not_empty] | La valeur ne doit pas être vide
+[Validate::regex] | La valeur respecte l'expression réguliére spécifiée
+[Validate::min_length] | La valeur respecte un nombre minimum de caractères
+[Validate::max_length] | La valeur respecte un nombre maximum de caractères
+[Validate::exact_length] | La valeur fait exactement le nombre de caractéres spécifiés
+[Validate::email] | La valeur doit respecter un format d'email
+[Validate::email_domain] | Le domaine de l'email existe
+[Validate::url] | La valeur entrée doit respecter un format d'URL
+[Validate::ip] | La valeur entrée doit respecter un format d'adresse IP
+[Validate::phone] | La valeur entrée doit respecter un format d'un uméro de téléphone
+[Validate::credit_card] | La valeur entrée doit respecter un format de numéro de carte de crédit
+[Validate::date] | La valeur entrée doit respecter un format de date (et heure)
+[Validate::alpha] | Seuls les caractères alphabétiques sont autorisés
+[Validate::alpha_dash] | Seuls les caractères alphabétiques et le caractère tiret '-' sont autorisés
+[Validate::alpha_numeric] | Seuls les caractères alphabétiques et numériques sont autorisés
+[Validate::digit] | La valeur doit être un chiffre
+[Validate::decimal] | La valeur doit être décimale ou flottante
+[Validate::numeric] | Seuls les caractères numériques sont autorisés
+[Validate::range] | La valeur doit être dans l'intervalle spécifié
+[Validate::color] | La valeur entrée doit respecter un format de couleur hexadécimal
+[Validate::matches] | La valeur doit correspondre à la valeur d'un autre champ
+
+[!!] Toute méthode existante de la classe [Validate] peut être utilisée directement sans utiliser une déclaration de callback compléte. Par exemple, ajouter la règle `'not_empty'` est la même chose que `array('Validate', 'not_empty')`.
+
+## Ajouter des filtres
+
+Tous les filtres de validation sont définis par un nom de champ, une méthode ou une fonction (en utilisant la syntaxe des [callbacks PHP](http://php.net/manual/language.pseudo-types.php#language.types.callback)), ainsi q'un tableau de paramètres:
+
+ $object->filter($field, $callback, $parameter);
+
+Les filtres modifient la valeur d'un filtre avant leur vérification par les règles et callbacks définies.
+
+Par exemple pour convertir un nom d'utilisateur en minuscule, alors il suffit d'écrire:
+
+ $post->filter('username', 'strtolower');
+
+Autre exemple, si l'on souhaite enlever les caratères vides au début et en fin de chaine de tous les champs, alors il faut écrire:
+
+ $post->filter(TRUE, 'trim');
+
+## Ajouter des règles
+
+Toutes les règles de validation sont définies par un nom de champ, une méthode ou une fonction (en utilisant la syntaxe des [callbacks PHP](http://php.net/manual/language.pseudo-types.php#language.types.callback)), ainsi q'un tableau de paramètres:
+
+ $object->rule($field, $callback, $parameter);
+
+Pour commencer notre exemple, nous allons commencer par valider le tableau `$_POST` contenant des informations d'inscription d'un utilisateur.
+
+Pour cela nous avons besoin de traiter les informations POSTées en utilisant [Validate]. Commencons par ajouter quelque régles:
+
+ $post
+ ->rule('username', 'not_empty')
+ ->rule('username', 'regex', array('/^[a-z_.]++$/iD'))
+
+ ->rule('password', 'not_empty')
+ ->rule('password', 'min_length', array('6'))
+ ->rule('confirm', 'matches', array('password'))
+
+ ->rule('use_ssl', 'not_empty');
+
+Toute fonction PHP existante peut aussi être utilisée comme une règle. Par exemple si l'on souhaite vérifier que l'utilisateur a entré une valeur correcte pour une question, on peut écrire:
+
+ $post->rule('use_ssl', 'in_array', array(array('yes', 'no')));
+
+A noter que les tableaux de paramètres doivent quand même être insérés dans un tableau! Si vous ne mettez pas ce tableau, `in_array` serait appelée via `in_array($value, 'yes', 'no')`, ce qui aboutirait à une erreur PHP.
+
+Toute régle spécifique peut être ajoutée en utilisant une [callback PHP](http://php.net/manual/language.pseudo-types.php#language.types.callback):
+
+ $post->rule('username', array($model, 'unique_username'));
+
+La méthode `$model->unique_username()` ressemblerait alors à:
+
+ public function unique_username($username)
+ {
+ // Vérifie si le nom d'utilisateur existe déjà dans la base de données
+ return ! DB::select(array(DB::expr('COUNT(username)'), 'total'))
+ ->from('users')
+ ->where('username', '=', $username)
+ ->execute()
+ ->get('total');
+ }
+
+[!!] Vous pouvez définir vos propres régles pour faire des vérifications additionnelles. Ces régles peuvent être réutilisés à plusieurs fins. Ces méthodes vont presque toujours exister au sein d'un modèle mais peuvent être définies dans nimporte quelle classe.
+
+## Ajouter des callbacks
+
+Toutes les callbacks de validation sont définies par un nom de champ et une méthode ou une fonction (en utilisant la syntaxe des [callbacks PHP](http://php.net/manual/language.pseudo-types.php#language.types.callback)):
+
+ $object->callback($field, $callback);
+
+[!!] Contrairement aux filtres et aux régles, aucun paramètre n'est passé à une callback.
+
+Le mot de passe utilisateur doit être hashé parès validaiton, nous allons donc le faire avec une callback:
+
+ $post->callback('password', array($model, 'hash_password'));
+
+Cela implique la création de la méthode `$model->hash_password()` de la manière suivante:
+
+ public function hash_password(Validate $array, $field)
+ {
+ if ($array[$field])
+ {
+ // Hasher le mot de passe s'il existe
+ $array[$field] = sha1($array[$field]);
+ }
+ }
+
+# Un exemple complet
+
+TOut d'abord nous avons besoin d'une [Vue] contenant le formulaire HTML que l'on placera dans `application/views/user/register.php`:
+
+
+
+
+ -
+
+
+
+
+
+
- Le mot de passe doit contenir au moins 6 caractères. + + + + +
- 'Toujours', 'no' => 'Seulement si nécessaire'), $post['use_ssl']) ?> +
- Pour des raisons de sécurité, SSL est toujours utilisé pour les paiements. +
- Wachtwoord moet minstens 6 karakters lang zijn. + + + + +
- 'Altijd', 'no' => 'Enkel indien nodig'), $post['use_ssl']) ?> +
- Voor uw veiligheid wordt SSL altijd gebruik bij betalingen. +
- Пароль должен быть длиной как минимум в 6 знаков. + + + + +
- 'Всегда', 'no' => 'По необходимости'), $post['use_ssl']) ?> +
- В целях безопасности, при проведении платежей всегда используется протокол SSL. +
- Passwords must be at least 6 characters long. + + + + +
- 'Always', 'no' => 'Only when necessary'), $post['use_ssl']) ?> +
- For security, SSL is always used when making payments. +
- 密码必须保证至少六位字符 + + + + +
- '总是使用 SSL', 'no' => '仅当需要的时候'), $post['use_ssl']) ?> +
- 鉴于安全起见，SSL 一般用于支付时使用 +
-
+
+
+
+
+
+
{{userguide/examples/hello_world_error}}
+
+Kohana vous affiche une erreur au lieu du message fascinant qu'il devrait afficher. En regardant de plus près le message d'erreur on peut voir que la librairie View n'a pas été capable de trouver notre template, probablement parceque nous ne l'avons pas encore créé!
+
+Créons donc notre vue en créant le fichier `application/views/site.php` avec le texte suivant:
+
+
+
+ We just wanted to say it! :)
+ + + +Maintenant si vous ré-actualisez, vous devriez voir apparaitre ce qu'il faut: + + + +## A moi la gloire et l'argent! + +Dans ce tutorial on a abordé comment créer un controleur et utiliser une vue pour séparer la logique de la présentation. + +Evidemment l'exemple choisi est une introduction basique à Kohana et n'effleure même pas les possibilités infinies de Kohana ;). \ No newline at end of file diff --git a/includes/kohana/modules/userguide/guide/fr-fr/tutorials.orm.md b/includes/kohana/modules/userguide/guide/fr-fr/tutorials.orm.md new file mode 100644 index 00000000..ee7d9bbf --- /dev/null +++ b/includes/kohana/modules/userguide/guide/fr-fr/tutorials.orm.md @@ -0,0 +1,121 @@ +# ORM {#top} + +Kohana 3.0 inclus un module [ORM](http://en.wikipedia.org/wiki/Object-relational_mapping) puissant utilisant le pattern active record et l'introspection de base de données pour déterminer les informations sur les colonnes d'un modèle. + +Bien que le module ORM soit inclus par défaut dans vos installations de Kohana 3.0, il est désactivé par défaut. Pour l'activer modifiez le fichier `application/bootstrap.php` et ajoutez à l'appel [Kohana::modules] le module ORM: + + Kohana::modules(array( + ... + 'orm' => MODPATH.'orm', + ... + )); + +## Configuration {#configuration} + +Pour pouvoir utiliser l'ORM, il faut tout d'abord faire hériter vos modèles de la classe ORM comme suit: + + class Model_User extends ORM + { + ... + } + +Dans l'exemple ci-dessus, le modele cherchera une table `users` dans la base de données par défaut. + +### Propriétés d'un modèle ORM + +Les propriétés suivantes peuvent être utilisées pour configurer chacuns de vos modèles: + +Type | Option | Description | Valeur par défaut +----------|-----------------|--------------------------------------| ------------------------- +`string` | _table_name | Nom de la table | +`string` | _db | Nom de la base de données |`default` +`string` | _primary_key | Colonne contenant la clé primaire |`id` +`string` | _primary_val | Colonne contenant la valeur primaire |`name` + +## Utiliser l'ORM + +### Charger un enregistrement + +Pour créér une instance d'un modèle, il faut utiliser la méthode [ORM::factory] ou passer directement par le constructeur: + + $user = ORM::factory('user'); + // ou + $user = new Model_User(); + +Les 2 méthodes ci-dessus peuvent prendre en argument la valeur de la clé primaire de l'élément que l'on souhaite charger: + + // Charge l'utilisateur d'ID 5 + $user = ORM::factory('user', 5); + +[ORM::loaded] permet de savoir si un modèle donné a été chargé avec succès. + +### Rechercher un enregistrement + +L'ORM supporte la plupart des méthodes [Base de données](tutorials.databases) pour affiner les recherches sur les données du modèle. Pour avoir une liste complète, référez vous à la propriété `_db_methods`. Les enregistrements sont récupérés lors de l'appel à [ORM::find] ou [ORM::find_all]. + + // Le code ci-dessous récupère le premier utilisateur actif prénommé Bob + $user = ORM::factory('user') + ->where('active', '=', TRUE) + ->where('name', '=', 'Bob') + ->find(); + + // Le code ci-dessous récupère tous les utilisateur actifs Bob + $users = ORM::factory('user') + ... + ->find_all(); + +Lors de la récupération d'une liste de modèles par la méthode [ORM::find_all], le parcours des éléments se fait comme pour les résultats de base de données: + + foreach ($users as $user) + { + ... + } + +### Accès aux propriétés d'un Modèle + +Toutes les propriétés d'un modèle sont accessibles en utilisant les méthodes magiques `__get` et `__set`. + + $user = ORM::factory('user', 5); + + // Affiche le nom de l'utilisateur + echo $user->name; + + // Change le nom de l'utilisateur + $user->name = 'Bob'; + +Pour stocker des informations/propriétés qui n'ont pas de correspondances dans la table (c'est-à-dire aucune colonnes du même nom que la propriété), il faut utiliser la propriété `_ignored_columns`: + + class Model_User extends ORM + { + ... + protected $_ignored_columns = array('field1', 'field2', ...) + ... + } + +### Créér et sauvegarder des enregistrements + +La méthode [ORM::save] est utilisée aussi bien pour créer et sauvegarder de nouveaux enregistrements que pour mettre à jour des enregistrements existants. + + // Création d'un enregistrement + $user = ORM::factory('user'); + $user->name = 'New user'; + $user->save(); + + // Mise à jour d'un enregistrement + $user = ORM::factory('user', 5); + $user->name = 'User 2'; + $user->save(); + +Vous pouvez mettre à jour plusieurs enregistrements à la fois en utilisant la méthode [ORM::save_all]: + + $user = ORM::factory('user'); + $user->name = 'Bob'; + + // Change le nom de tous les utilisateurs actifs à Bob + $user->where('active', '=', TRUE)->save_all(); + +[ORM::saved] permet de vérifier si le modèle a bien été sauvegardé. + +### Supprimer des enregistrements + +La suppression d'enregistrements se fait avec [ORM::delete] et [ORM::delet_all]. Ces méthodes fonctionnement de manière similaire à celles de sauvegarde détaillées plus haut à l'exception du fait que [ORM::delete] peut prendre en argument l'`id` de l'enregistrment à supprimer. \ No newline at end of file diff --git a/includes/kohana/modules/userguide/guide/fr-fr/tutorials.urls.md b/includes/kohana/modules/userguide/guide/fr-fr/tutorials.urls.md new file mode 100644 index 00000000..911a21a4 --- /dev/null +++ b/includes/kohana/modules/userguide/guide/fr-fr/tutorials.urls.md @@ -0,0 +1,163 @@ +# Routes, URLs et Liens + +Ce chapitre fournit les bases permettant de comprendre la logique de traitement des requêtes, de la génération des URLs et des liens. + +## Routage + +Comment évoqué dans le chapitre [processus de traitement des requêtes](about.flow), une requête est traitée par la classe [Request] qui tente de trouver une [Route] correspondante et charge les méthodes appropriées du controleur qui permettront de traiter la requete. + +Si vous regardez le fichier `APPPATH/bootstrap.php` vous pouvez voir le code ci-dessous qui est exécuté juste avant que la requête ne soit traitée par [Request::instance]: + + Route::set('default', '({{userguide/examples/error}}
+
+## Disabling Error/Exception Handling - ביטול הטיפול בשגיאות וחריגים
+
+במידה וברצונך לבטל את הטיפול בשגיאות, ניתן לעשות זאת בעת הקריאה
+ [Kohana::init] בצורה הבאה:
+
+~~~
+Kohana::init(array('errors' => FALSE));
+~~~
+
+חשוב לזכור שבדרך כלל נרצה שהשגיאות המפורטות יופיעו רק בעבודה לוקאלית ולא באתר אונליין
\ No newline at end of file
diff --git a/includes/kohana/modules/userguide/guide/he-il/debugging.profiling.md b/includes/kohana/modules/userguide/guide/he-il/debugging.profiling.md
new file mode 100644
index 00000000..bd7663b1
--- /dev/null
+++ b/includes/kohana/modules/userguide/guide/he-il/debugging.profiling.md
@@ -0,0 +1,21 @@
+# Profiling - פרופיל סטטיסטי לכל דף
+
+קוהנה מאפשרת בקלות לצפות בסטטיסטיקה אודות האפליקציה:
+
+1. קריאות למטודות קוהנה
+2. בקשות
+3. שאילתות שבוצעו על מסד הנתונים
+4. ממוצע זמני פעולה של האפליקציה
+
+## דוגמא
+
+ניתן לאסוף ולהציג את הסטטיסטיקות בכל רגע נתון:
+~~~
+
+
+
+~~~
+
+## התוצאה:
+
+{{profiler/stats}}
\ No newline at end of file
diff --git a/includes/kohana/modules/userguide/guide/he-il/menu.md b/includes/kohana/modules/userguide/guide/he-il/menu.md
new file mode 100644
index 00000000..5b027976
--- /dev/null
+++ b/includes/kohana/modules/userguide/guide/he-il/menu.md
@@ -0,0 +1,26 @@
+1. **מתחילים**
+ - [ מה זה Kohana?](about.kohana)
+ - [מוסכמות וסיגנון](about.conventions)
+ - [התקנה](about.install)
+ - [שידרוג](about.upgrading)
+ - [הגדרות](about.configuration)
+ - [Model View Controller הסבר על](about.mvc)
+ - [מערכת קבצים](about.filesystem)
+ - [Autoloading - טעינה אוטומטית](about.autoloading)
+ - [Request זרימת](about.flow)
+ - [API דפדפן](api)
+2. **ערכות לימוד**
+ - [Hello, World](tutorials.helloworld)
+ - [Routes, URLs, and Links](tutorials.urls)
+ - [Databases](tutorials.databases)
+ - [ORM](tutorials.orm)
+ - [עבודה עם Git](tutorials.git)
+3. **אבטחה**
+ - [XSS](security.xss)
+ - [Validation - ואלידציה](security.validation)
+ - [Cookies - עוגיות](security.cookies)
+ - [Database - מסד נתונים](security.database)
+4. **ניפוי באגים**
+ - [קוד](debugging.code)
+ - [טיפול בשגיאות](debugging.errors)
+ - [פרופיל](debugging.profiling)
diff --git a/includes/kohana/modules/userguide/guide/menu.md b/includes/kohana/modules/userguide/guide/menu.md
new file mode 100644
index 00000000..a5aacb86
--- /dev/null
+++ b/includes/kohana/modules/userguide/guide/menu.md
@@ -0,0 +1,31 @@
+1. **Getting Started**
+ - [What is Kohana?](about.kohana)
+ - [Conventions and Style](about.conventions)
+ - [Model View Controller](about.mvc)
+ - [Cascading Filesystem](about.filesystem)
+ - [Request Flow](about.flow)
+ - [Installation](about.install)
+ - [Upgrading](about.upgrading)
+ - [API Browser](api)
+3. **Basic Usage**
+ - [Configuration](using.configuration)
+ - [Loading Classes](using.autoloading)
+ - [Views and HTML](using.views)
+ - [Sessions and Cookies](using.sessions)
+ - [Messages](using.messages)
+4. **Debugging**
+ - [Code](debugging.code)
+ - [Error Handling](debugging.errors)
+ - [Profiling](debugging.profiling)
+5. **Security**
+ - [XSS](security.xss)
+ - [Validation](security.validation)
+ - [Cookies](security.cookies)
+ - [Database](security.database)
+6. **Tutorials**
+ - [Hello, World](tutorials.helloworld)
+ - [Routes, URLs, and Links](tutorials.urls)
+ - [Clean URLs](tutorials.removeindex)
+ - [Databases](tutorials.databases)
+ - [ORM](tutorials.orm)
+ - [Working with Git](tutorials.git)
diff --git a/includes/kohana/modules/userguide/guide/nl/about.conventions.md b/includes/kohana/modules/userguide/guide/nl/about.conventions.md
new file mode 100644
index 00000000..65094928
--- /dev/null
+++ b/includes/kohana/modules/userguide/guide/nl/about.conventions.md
@@ -0,0 +1,316 @@
+# Conventies
+
+Het is aanbevolen om Kohana's [manier van coderen](http://dev.kohanaframework.org/wiki/kohana2/CodingStyle) te gebruiken. Dit gebruikt de [BSD/Allman stijl](http://en.wikipedia.org/wiki/Indent_style#BSD.2FAllman_style) van haakjes, en nog andere dingen.
+
+## Class namen en locaties van bestanden {#classes}
+
+Class namen in Kohana volgen een strikte conventie om [autoloading](using.autoloading) gemakkelijker te maken. Class namen zouden met een hoofdletter moeten beginnen en een underscore gebruiken om woorden af te scheiden van elkaar. Underscores zijn belangrijk omdat ze de locatie van het bestand weerspiegelen in de folderstructuur.
+
+De volgende conventies worden gebruikt:
+
+1. CamelCased class namen worden niet gebruikt, alleen maar als het onnodig is om een nieuw folderniveau aan te maken.
+2. Alle class bestandsnamen en foldernamen zijn met kleine letters geschreven.
+3. Alle classes zitten in de `classes` folder. Dit kan op ieder niveau in het [cascading filesystem](about.filesystem).
+
+[!!] In tegenstelling tot Kohana v2.x, is er geen afscheiding tussen "controllers", "models", "libraries" en "helpers". Alle classes worden in de folder "classes/" geplaatst, of het nu static "helpers" of object "libraries" zijn. Ieder design pattern is mogelijk voor het maken van classes: static, singleton, adapter, etc.
+
+## Voorbeelden
+
+Onthoud dat in een class, een underscore een folder betekent. Bekijk de volgende voorbeelden:
+
+Class Naam | Locatie File
+----------------------|-------------------------------
+Controller_Template | classes/controller/template.php
+Model_User | classes/model/user.php
+Database | classes/database.php
+Database_Query | classes/database/query.php
+Form | classes/form.php
+
+## Coding Standaarden {#coding_standards}
+
+Om zeer consistente broncode te schrijven, vragen we dat iedereen de coding standaarden zo nauw mogelijk probeert na te volgen.
+
+### Gekrulde Haakjes (Brackets)
+
+Gebruik aub [BSD/Allman Stijl](http://en.wikipedia.org/wiki/Indent_style#BSD.2FAllman_style) van bracketing.
+
+### Naam conventies
+
+Kohana gebruikt underscore namen, geen camelCase.
+
+#### Classes
+
+ 5) ? ($bar + $foo) : strlen($bar);
+
+Bij het scheiden van complexe ternaries (ternaries waarbij het eerste deel meer dan ~80 karakters bevat) in meerdere regels, moet je spaties gebruiken om operators op te lijnen, deze plaats je in het begin van de opeenvolgende lijnen:
+
+ $foo = ($bar == $foo)
+ ? $foo
+ : $bar;
+
+### Type Casting
+
+Type casting wordt gedaan met spatie langs elke kant van de cast:
+
+ // Correct:
+ $foo = (string) $bar;
+ if ( (string) $bar)
+
+ // Niet correct:
+ $foo = (string)$bar;
+
+Indien mogelijk, gebruik dan in plaats van type casting ternaire operators:
+
+ // Correct:
+ $foo = (bool) $bar;
+
+ // Niet correct:
+ $foo = ($bar == TRUE) ? TRUE : FALSE;
+
+Bij het casten van een integer of een boolean gebruik je het korte formaat:
+
+ // Correct:
+ $foo = (int) $bar;
+ $foo = (bool) $bar;
+
+ // Incorrect:
+ $foo = (integer) $bar;
+ $foo = (boolean) $bar;
+
+### Constanten
+
+Gebruik altijd hoofdletters voor constanten:
+
+ // Correct:
+ define('MY_CONSTANT', 'my_value');
+ $a = TRUE;
+ $b = NULL;
+
+ // Niet correct:
+ define('MyConstant', 'my_value');
+ $a = True;
+ $b = null;
+
+Plaats constant vergelijkingen aan het einde van de tests:
+
+ // Correct:
+ if ($foo !== FALSE)
+
+ // Niet correct:
+ if (FALSE !== $foo)
+
+Dit is een enigszins een controversiële keuze, dus is een uitleg op zijn plaats. Als we het vorige voorbeeld in gewoon taal schrijven, zou het goede voorbeeld als volgt te lezen zijn:
+
+ if variable $foo is not exactly FALSE
+
+En het foute voorbeeld zou als volgt te lezen zijn:
+
+ if FALSE is not exactly variable $foo
+
+En aangezien we van links naar rechts lezen, is het logischer om de constante als laatste te plaatsen.
+
+### Commentaren
+
+#### Commentaren op één lijn
+
+Gebruik //, best boven de lijn met je code waar je de commentaar voor wilt schrijven. Laat een spatie tussen en start met een hoofdletter. Gebruik nooit #
+
+ // Correct
+
+ //Niet correct
+ // niet correct
+ # Niet correct
+
+### Reguliere expressies
+
+Bij het coderen van reguliere expressies gebruik je beter PCRE in plaats van POSIX. PCRE zou krachtiger en sneller zijn.
+
+ // Correct:
+ if (preg_match('/abc/i'), $str)
+
+ // Incorrect:
+ if (eregi('abc', $str))
+
+Gebruik enkele aanhalingstekens rond uw reguliere expressies in plaats van dubbele aanhalingstekens. Enkele aanhalingstekens worden gemakkelijker door hun eenvoud in gebruik. In tegenstelling tot de dubbele aanhalingstekens ondersteunen ze niet variabele interpolatie, noch geïntegreerde backslash sequenties zoals \n of \t, enz.
+
+ // Correct:
+ preg_match('/abc/', $str);
+
+ // Incorrect:
+ preg_match("/abc/", $str);
+
+Bij het uitvoeren van een reguliere expressie zoeken en vervangen, gebruik dan de $n notatie voor terugverwijzingen. Dit verdient de voorkeur boven \\n.
+
+ // Correct:
+ preg_replace('/(\d+) dollar/', '$1 euro', $str);
+
+ // Incorrect:
+ preg_replace('/(\d+) dollar/', '\\1 euro', $str);
+
+Tot slot, let wel dat het $-teken voor de eindpositie van de lijn aan te geven toelaat om een newline-karakter als volgend karakter te gebruiken. Gebruik de D modifier om dit te verhelpen indien nodig. [Meer informatie](http://blog.php-security.org/archives/76-Holes-in-most-preg_match-filters.html).
+
+ $str = "email@example.com\n";
+
+ preg_match('/^.+@.+$/', $str); // TRUE
+ preg_match('/^.+@.+$/D', $str); // FALSE
diff --git a/includes/kohana/modules/userguide/guide/nl/about.filesystem.md b/includes/kohana/modules/userguide/guide/nl/about.filesystem.md
new file mode 100644
index 00000000..f2a1ddee
--- /dev/null
+++ b/includes/kohana/modules/userguide/guide/nl/about.filesystem.md
@@ -0,0 +1,76 @@
+# Cascading Filesystem
+
+Het Kohana filesysteem heeft hiërarchie van folder-structuur. Wanneer een bestand wordt ingeladen door [Kohana::find_file], dan wordt het gezocht in de volgend volgorde:
+
+Application pad
+: Gedefineerd als `APPPATH` in `index.php`. De standaard value hiervan is `application`.
+
+Module paden
+: Dit is ingesteld als een associatieve array met behulp van [Kohana::modules] in `APPPATH/bootstrap.php`. Elk van de waarden van de array zal worden gezocht in de volgorde waarin de modules worden toegevoegd.
+
+System pad
+: Gedefineerd als `SYSPATH` in `index.php`. De standaard value hiervan is `system`. Alle belangrijkste of "core"-bestanden en classes zijn hier gedefinieerd.
+
+Bestanden die zich hoger bevinden in de volgorde van het inladen van bestanden hebben voorrang op bestanden met dezelfde naam die zich lager bevinden in de volgorde van inladen, dit maakt het mogelijk om ieder bestand te overloaden door een bestand met dezelfde naam in een "hogere" folder te plaatsen:
+
+
+
+Als je een view bestand hebt met de naam `welcome.php` in de `APPPATH/views` en `SYSPATH/views` folders, dan zal hetgeen uit application worden gereturned als `welcome.php` wordt ingeladen omdat het "hoger" staat in de folderstructuur.
+
+## Types bestanden
+
+De top level folders van de application, module en systeem paden hebben volgende standaard folders:
+
+classes/
+: Alle classes dat je wilt [automatisch inladen](using.autoloading) moeten zich hier
+ bevinden. Dit houdt in controllers, models, en alle andere classes. Alle classes moeten
+ de [class naam conventies](about.conventions#classes) volgen.
+
+config/
+: Configuratie bestanden geven een associatieve array van opties terug die je kunt
+ inladen via [Kohana::config]. Zie [gebruik van configuratie](using.configuration) voor
+ meer informatie.
+
+i18n/
+: Vertalingsbestanden geven een associatieve array van strings terug. Vertalen wordt
+ gedaan door de `__()` methode te gebruiken. Om "Hello, world!" te vertalen in het
+ Spaans zou je de methode `__('Hello, world!')` oproepen met [I18n::$lang] ingesteld op "es-es".
+ Zie [gebruik van vertaling](using.translation) voor meer informatie.
+
+messages/
+: Berichtenbestanden geven een associatieve array van strings terug die ingeladen kunnen
+ worden via [Kohana::message]. Messages en i18n bestanden verschillen erin dat messages
+ niet worden vertaald, maar altijd geschreven worden in de standaard taal en verwezen worden
+ via een enkelvoudige key. Zie [gebruik van messages](using.messages) voor meer informatie.
+
+views/
+: Views zijn plain PHP files die worden gebruikt om HTML of een ander formaat te genereren. Het view bestand wordt
+ ingeladen in in een [View] object en toegewezen variabelen, die het dan zal omzetten naar een HTML fractie. Het is mogelijk om meerder views in elkaar te gebruiken.
+ Zie [gebruik van views](usings.views) voor meer informatie.
+
+## Vinden van betanden
+
+Het pad naar eender welk bestand in de folderstructuur kan worden gevonden door het gebruik van [Kohana::find_file]:
+
+ // Vind het volledige pad naar "classes/cookie.php"
+ $path = Kohana::find_file('classes', 'cookie');
+
+ // Vind het volledige pad naar "views/user/login.php"
+ $path = Kohana::find_file('views', 'user/login');
+
+
+# Vendor Extensions
+
+Extensies die niet specifiek zijn aan Kohana noemen we "vendor" extensions.
+Bijvoorbeeld, als je [DOMPDF](http://code.google.com/p/dompdf) wilt gebruiken,
+dan moet je het kopiëren naar `application/vendor/dompdf` en de DOMPDF
+autoloading class inladen:
+
+ require Kohana::find_file('vendor', 'dompdf/dompdf/dompdf_config.inc');
+
+Nu kan je DOMPDF gebruiken zonder inladen van andere bestanden:
+
+ $pdf = new DOMPDF;
+
+[!!] Indien je views wilt omzetten in PDFs via DOMPDF, probeer dan de
+[PDFView](http://github.com/shadowhand/pdfview) module.
diff --git a/includes/kohana/modules/userguide/guide/nl/about.flow.md b/includes/kohana/modules/userguide/guide/nl/about.flow.md
new file mode 100644
index 00000000..b9194e0d
--- /dev/null
+++ b/includes/kohana/modules/userguide/guide/nl/about.flow.md
@@ -0,0 +1,73 @@
+# Request Flow
+
+Iedere applicatie volgt de zelfde flow:
+
+1. Applicatie start vanaf `index.php`.
+2. De application, module, en system paden worden ingesteld.
+3. Error reporting niveaus worden ingesteld.
+4. Install file wordt geladen, als het bestaat.
+5. De [Kohana] class wordt ingeladen.
+6. Het bootstrap bestand, `APPPATH/bootstrap.php`, wordt geinclude.
+7. [Kohana::init] wordt aangeroepen, deze stelt error handling, caching, en logging in.
+8. [Kohana_Config] lezers en [Kohana_Log] schrijvers worden toegevoegd.
+9. [Kohana::modules] wordt aangeroepen om additionele modules te activeren.
+ * Module paden worden toegevoegd aan het [cascading filesystem](about.filesystem).
+ * Includen van `init.php` bestand, als het bestaat.
+ * Het `init.php` bestand kan een extra omgevingsinstellingen instellen, waaronder het toevoegen van routes.
+10. [Route::set] wordt verschillende keren opgeroepen om de [applicaties routes](using.routing) te definiëren.
+11. [Request::instance] wordt opgeroepen om het request-proces te starten.
+ 1. Iedere route controleren dat is ingesteld tot er een overeenkomst is gevonden.
+ 2. Conroller instantie wordt gecreeërd en het request wordt doorgeven eraan.
+ 3. De [Controller::before] methode wordt aangeroepen.
+ 4. De controller action wordt aangeroepen, deze genereerd de request response.
+ 5. De [Controller::after] methode wordt aangeroepen.
+ * De 5 bovenstaande stappen kunnen verschillende keren worden herhaald wanneer je [HMVC sub-requests](about.mvc) gebruikt.
+12. De basis [Request] response wordt getoond
+
+## index.php
+
+Kohana volgt een [front controller] pattern, dit betekent dat alle requests worden gezonden naar `index.php`. Dit laat een zeer eenvoudig [bestandsstructuur](about.filesystem) design toe. In `index.php` zijn er enkele zeer basis configuratie opties mogelijk. je kan de `$application`, `$modules`, en `$system` paden veranderen en het error reporting level instellen.
+
+De `$application` variabele laat je toe om de folder in te stellen die al je application bestanden bevat. Standaard is dit `application`. De `$modules` variabele laat je toe om de folder in te stellen die alle module bestanden bevat. De `$system` variabele laat je toe om de folder in te stellen die alle Kohana bestanden bevat.
+
+Je kan deze drie folders overal naartoe verplaatsen. Bijvoorbeeld, als je folderstructuur zo is ingesteld:
+
+ www/
+ index.php
+ application/
+ modules/
+ system/
+
+Dan kan je de folders uit de webroot verplaatsen:
+
+ application/
+ modules/
+ system/
+ www/
+ index.php
+
+Dan moet je de instellingen in `index.php` veranderen naar:
+
+ $application = '../application';
+ $modules = '../modules';
+ $system = '../system';
+
+Nu kan geen enkele van deze folders worden bereikt via de webserver. Het is niet noodzakelijk om deze verandering te maken, maar het maakt het wel mogelijk om de folders te delen met meerdere applicaties, de mogelijkheden zijn enorm.
+
+[!!] Er is een veiligheidscontrole bovenaan elke Kohana file om te voorkomen dat het wordt uitgevoerd zonder het gebruik van de front controller. Maar natuurlijk is het veiliger om de application, modules, en system folders te verplaatsen naar een locatie dat niet kan worden bereikt via het web.
+
+### Error Reporting
+
+Standaard toont Kohana alle errors, zo ook strikte warnings. Dit wordt ingesteld door [error_reporting](http://php.net/error_reporting):
+
+ error_reporting(E_ALL | E_STRICT);
+
+Als je applicatie live staat en in productie is, een meer conversatieve instelling is aangeraden, zoals het negeren van notices:
+
+ error_reporting(E_ALL & ~E_NOTICE);
+
+Als je een wit scherm krijgt wanneer een error is opgetreden, dan zal uw host waarschijnlijk het tonen van errors hebben uitgeschakeld. Je kan dit terug aanzetten door deze lijn toe te voegen juist achter je `error_reporting` call:
+
+ ini_set('display_errors', TRUE);
+
+Errors zouden **altijd** moeten worden getoond, zelf in productie, omdat het je toelaat om [exception en error handling](debugging.errors) te gebruiken om een mooie error pagina te tonen in plaats van een wit scherm als een error voorkomt.
\ No newline at end of file
diff --git a/includes/kohana/modules/userguide/guide/nl/about.install.md b/includes/kohana/modules/userguide/guide/nl/about.install.md
new file mode 100644
index 00000000..71a566d5
--- /dev/null
+++ b/includes/kohana/modules/userguide/guide/nl/about.install.md
@@ -0,0 +1,94 @@
+# Installatie
+
+1. Download de laatste **stabiele** release van de [Kohana website](http://kohanaframework.org/).
+2. Unzip het gedownloade pakket om de `kohana` folder aan te maken.
+3. Upload de inhoud van deze folder naar je webserver.
+4. Open `application/bootstrap.php` en maak de volgende aanpassingen:
+ - Stel de standaard [timezone](http://php.net/timezones) in voor je applicatie
+ - Stel de `base_url` in de [Kohana::init] methode in om te verwijzen naar de locatie van de kohana folder op je server
+6. Zorg ervoor dat de `application/cache` en `application/logs` folders schrijfrechten hebben voor de web server
+7. Test je installatie door de URL te openen in je favoriete browser dat je hebt ingesteld als `base_url`
+
+[!!] Afhankelijk van je platform is het mogelijk dat de installatie subfolders hun rechten verloren hebben tijdens de zip extractie. Chmod ze allemaal met 755 door het commando `find . -type d -exec chmod 0755 {} \;` uit te voeren in de root van je Kohana installatie.
+
+Je zou de installatie pagina moeten zien. Als het errors toont, zal je ze moeten aanpassen vooraleer je verder kunt gaan.
+
+
+
+Eens je installatie pagina zegt dat je omgeving goed is ingesteld dan moet je de `install.php` pagina hernoemen of verwijderen in de root folder. Je zou nu de de Kohana welcome pagina moeten zien:
+
+
+
+## Een productie-omgeving opzetten
+
+Er zijn enkele dingen dat je best doet met je applicatie vooraleer je deze in productie plaatst:
+
+1. Bekijk de [configuratie pagina](about.configuration) in de documentatie.
+ Dit omvat het grootste gedeelte van de globale instellingen dat zouden moeten veranderen bij andere omgevingen.
+ Als algemene regel, zet je best caching aan en zet je profiling uit ([Kohana::init] settings) voor sites in productie.
+ [Route caching](api/Route#cache) kan ook helpen als je heel wat routes hebt.
+2. Catch alle exceptions in `application/bootstrap.php`, zodat gevoelige gegevens niet kan worden gelekt door stack traces.
+ Zie onderstaand voorbeeld van Shadowhand's [wingsc.com broncode](http://github.com/shadowhand/wingsc).
+3. Zet APC of een andere soort opcode caching aan. Dit is het enige en eenvoudigste manier om de performantie te verbeteren dat je kunt doen in PHP zelf. Hoe complexer je applicatie, hoe groter het voordeel van opcode caching.
+
+[!!] Opmerking: De standaard bootstrap zal Kohana::$environment = $_ENV['KOHANA_ENV'] instellen indien ingesteld. Documentatie hoe je deze variable moet invullen kan je vinden in je webservers documentatie (e.g. [Apache](http://httpd.apache.org/docs/1.3/mod/mod_env.html#setenv), [Lighttpd](http://redmine.lighttpd.net/wiki/1/Docs:ModSetEnv#Options), [Nginx](http://wiki.nginx.org/NginxHttpFcgiModule#fastcgi_param))). Deze manier wordt als beste beschouwd in vergelijking met de alternatieve manieren om Kohana::$environment in te stellen.
+
+ /**
+ * Stel de omgeving in aan de hand van het domein (standaard Kohana::DEVELOPMENT).
+ */
+ Kohana::$environment = ($_SERVER['SERVER_NAME'] !== 'localhost') ? Kohana::PRODUCTION : Kohana::DEVELOPMENT;
+ /**
+ * Initialiseer Kohana op basis van de omgeving
+ */
+ Kohana::init(array(
+ 'base_url' => '/',
+ 'index_file' => FALSE,
+ 'profile' => Kohana::$environment !== Kohana::PRODUCTION,
+ 'caching' => Kohana::$environment === Kohana::PRODUCTION,
+ ));
+
+ /**
+ * Voer de algemene request uit met PATH_INFO. Als er geen URI is gespecifeerd,
+ * dan zal de URI automatisch worden gedetecteerd.
+ */
+ $request = Request::instance($_SERVER['PATH_INFO']);
+
+ try
+ {
+ // Propeer het request uit te voeren
+ $request->execute();
+ }
+ catch (Exception $e)
+ {
+ if (Kohana::$environment == Kohana::DEVELOPMENT)
+ {
+ // Just re-throw the exception
+ throw $e;
+ }
+
+ // De error loggen
+ Kohana::$log->add(Kohana::ERROR, Kohana::exception_text($e));
+
+ // Maak een 404 uitvoer
+ $request->status = 404;
+ $request->response = View::factory('template')
+ ->set('title', '404')
+ ->set('content', View::factory('errors/404'));
+ }
+
+ if ($request->send_headers()->response)
+ {
+ // Verkrijg totaal aantal geheugen en snelheids tijd
+ $total = array(
+ '{memory_usage}' => number_format((memory_get_peak_usage() - KOHANA_START_MEMORY) / 1024, 2).'KB',
+ '{execution_time}' => number_format(microtime(TRUE) - KOHANA_START_TIME, 5).' seconds');
+
+ // Stel de totalen in, in de uitvoer
+ $request->response = str_replace(array_keys($total), $total, $request->response);
+ }
+
+
+ /**
+ * Toon de uitvoer dan het request.
+ */
+ echo $request->response;
diff --git a/includes/kohana/modules/userguide/guide/nl/about.kohana.md b/includes/kohana/modules/userguide/guide/nl/about.kohana.md
new file mode 100644
index 00000000..1371b381
--- /dev/null
+++ b/includes/kohana/modules/userguide/guide/nl/about.kohana.md
@@ -0,0 +1,15 @@
+# Wat is Kohana?
+
+Kohana is een open source, [objectgeoriënteerd](http://nl.wikipedia.org/wiki/Objectgeori%C3%ABnteerd) [MVC](http://wikipedia.org/wiki/Model–View–Controller "Model View Controller") [web framework](http://wikipedia.org/wiki/Web_Framework) gebouwd met [PHP5](http://php.net/manual/intro-whatis "PHP Hypertext Preprocessor") door een aantal vrijwilligers die veiligheid, snelheid en een kleine voetafdruk nastreven.
+
+[!!] Kohana is gelicentieerd onder een [BSD license](http://kohanaframework.org/license), zodat je het framework legaal kunt gebruiken voor allerlei projecten: open source, commercieel of persoonlijk.
+
+## Waarom is Kohana zo goed?
+
+Alles kan worden uitgebreid door het unieke design van het [filesystem](about.filesystem), er is geen of weinig [configuratie](about.configuration) voor nodig, [error handling](debugging.errors) helpt je vlug de oorzaak te vinden van je fouten en [debuggen](debugging) en [profiling](debugging.profiling) zorgen voor een beter inzicht in je applicatie.
+
+Om je te helpen je applicatie te beveiligen zijn er tools voor [XSS te verwijderen](security.xss), [input validatie](security.validation), [gesigneerde cookies](security.cookies), [formulieren](security.forms) en [HTML](security.html) generators toegevoegd aan het systeem. De [database](security.database) layer voorkomt [SQL injectie](http://wikipedia.org/wiki/SQL_Injection). En natuurlijk, alle officiële code is met zorg geschreven en herbekeken inzake veiligheid.
+
+## Vul mee deze documentatie aan
+
+We zijn keihard en volop bezig om je van een complete documentatie te voorzien. Om deze documentatie te helpen verbeteren, gelieve dan de userguide te [forken](http://github.com/kohana/userguide), uw aanpassingen te doen en een pull request te sturen. Als je nog geen ervaring hebt met git kan je altijd een [feature request](http://dev.kohanaframework.org/projects/kohana3/issues) aanmaken (vereist registratie).
\ No newline at end of file
diff --git a/includes/kohana/modules/userguide/guide/nl/about.mvc.md b/includes/kohana/modules/userguide/guide/nl/about.mvc.md
new file mode 100644
index 00000000..2e94ba8f
--- /dev/null
+++ b/includes/kohana/modules/userguide/guide/nl/about.mvc.md
@@ -0,0 +1,7 @@
+# (Hiërarchische) Model View Controller
+
+Model View Controller (of MVC afgekort) is een populair design pattern dat de data (Model) afscheid van de presentatie/templates (View) en de request-logica (Controller).
+
+Het maakt ontwikkelen van applicaties een stuk gemakkelijker omdat het systeem zo gedesignd is om code meermaals te hergebruiken, wat wil zeggen dat je er minder moet schrijven!
+
+[!!] Stub
diff --git a/includes/kohana/modules/userguide/guide/nl/about.translation.md b/includes/kohana/modules/userguide/guide/nl/about.translation.md
new file mode 100644
index 00000000..00c3f529
--- /dev/null
+++ b/includes/kohana/modules/userguide/guide/nl/about.translation.md
@@ -0,0 +1,4 @@
+# Translation
+
+[!!] This article is a stub!
+
diff --git a/includes/kohana/modules/userguide/guide/nl/about.upgrading.md b/includes/kohana/modules/userguide/guide/nl/about.upgrading.md
new file mode 100644
index 00000000..d843e996
--- /dev/null
+++ b/includes/kohana/modules/userguide/guide/nl/about.upgrading.md
@@ -0,0 +1,288 @@
+# Upgraden vanaf 2.3.x
+
+De code van Kohana v3 werkt grotendeels anders dan Kohana 2.3, hier is een lijst van de meeste valkuilen en tips om succesvol te upgraden.
+
+## Naming conventies
+
+In 2.x versies onderscheiden de verschillende soorten van classes (zoals controller, model, ...) zich met elkaar met behulp van achtervoegsels. Mappen in de model / controller mappen hadden geen invloed op de naam van de class.
+
+In 3.0 werd aanpak geschrapt ten gunste van de Zend framework bestandssysteem conventies, waar de naam van de class het pad is naar de class zelf, gescheiden door een underscore in plaats van slashes (dus `/some/class/file.php` bekomt `Some_Class_File`).
+Zie de [conventies documentatie](start.conventions) voor meer informatie.
+
+## Input Library
+
+De Input Library is verwijderd in 3.0, er wordt nu aanbevolen om gewoon `$_GET` en `$_POST` te gebruiken.
+
+### XSS Protectie
+
+Als je invoer van gebruikers wilt filteren op XSS kan je [Security::xss_clean] gebruiken om:
+
+ $_POST['description'] = security::xss_clean($_POST['description']);
+
+Je kan ook altijd [Security::xss_clean] gebruiken als filter met de [Validate] library:
+
+ $validation = new Validate($_POST);
+
+ $validate->filter('description', 'Security::xss_clean');
+
+### POST & GET
+
+Eén van de grootste functies van de Input Library was als je probeerde een waarde uit een superglobale array te halen en deze bestond bestond niet, dan zou de Input Library een standaard waarde teruggeven dat je kon instellen:
+
+ $_GET = array();
+
+ // $id heeft de waarde 1 gekregen
+ $id = Input::instance()->get('id', 1);
+
+ $_GET['id'] = 25;
+
+ // $id heeft de waarde 25 gekregen
+ $id = Input::instance()->get('id', 1);
+
+In 3.0 kan je deze functionaliteit nabootsen door [Arr::get] te gebruiken:
+
+ $_GET = array();
+
+ // $id heeft de waarde 1 gekregen
+ $id = Arr::get($_GET, 'id', 1);
+
+ $_GET['id'] = 42;
+
+ // $id heeft de waarde 42 gekregen
+ $id = Arr::get($_GET, 'id', 1);
+
+## ORM Library
+
+Er zijn redelijk veel grote wijzingingen aangebracht in ORM sedert 2.3. Hier is een lijst met de meest voorkomende upgrade problemen.
+
+### Member variablen
+
+Alle member variablen hebben nu een voorvoegsel gekregen met een underscore (_) en zijn niet langer bereikbaar via `__get()`. Nu moet je een functie aanroepen met de naam van de property zonder de underscore.
+
+Bijvoorbeeld, in 2.3 had je `loaded` en in 3.x is dat nu `_loaded` en heb je nu toegang van buiten de class via `$model->loaded()`.
+
+### Relaties
+
+Als je in 2.3 de gerelateerde objecten van een model wilde herhalen, kon je dat zo doen:
+
+ foreach($model->{relation_name} as $relation)
+
+Maar in 3.0 zal dit niet werken. In de 2.3 serie werden alle queries die gegenereerd werden met behulp van de Database Library gegeneeerd in een globale omgeving, wat betekent dat je niet kon proberen en maken van twee queries. Bijvoorbeeld:
+
+# TODO: GOED VOORBEELD!!!!
+
+Deze query zou mislukken doordat de tweede, inner query alle voorwaarden zou overerven van de eerste, wat zou leiden tot het mislukken.
+In 3.0 is dit aangepast door iedere query te laten genereren in zijn eigen omgeving. Let wel dat sommige dingen hierdoor niet gaan werken zoals je verwacht. Bijvoorbeeld:
+
+ foreach(ORM::factory('user', 3)->where('post_date', '>', time() - (3600 * 24))->posts as $post)
+ {
+ echo $post->title;
+ }
+
+[!!] (Zie [de Database tutorial](tutorials.databases) voor de nieuwe query syntax)
+
+In 2.3 zou je verwachten dat dit iterator teruggeeft van alle berichten van een gebruiker met `id` 3 met een `post_date` binnenin de 24 uren, maar in de plaats daarvan zal de WHERE conditie toegepast worden op het user-model en een `Model_Post` worden teruggevens met de joining conditities gespecifieerd.
+
+Om hetzelfde effect te verkrijgen zoals in 2.3, moet je de structuur iets aanpassen:
+
+ foreach(ORM::factory('user', 3)->posts->where('post_date', '>', time() - (36000 * 24))->find_all() as $post)
+ {
+ echo $post->title;
+ }
+
+Dit is ook van toepassing op de `has_one` relaties:
+
+ // Niet correct
+ $user = ORM::factory('post', 42)->author;
+ // Correct
+ $user = ORM::factory('post', 42)->author->find();
+
+### Has and belongs to many relaties
+
+In 2.3 kon je `has_and_belongs_to_many` relaties specifieren. In 3.0 is deze functionaliteit herschreven naar `has_many` *through*.
+
+In het model definieer je een `has_many` relatie met een ander model maar dan voeg je nog een `'through' => 'table'` attribuut aan toe, waar `'table'` de naam is van de trough tabel. Bijvoorbeeld (in de context van posts<>categories):
+
+ $_has_many = array
+ (
+ 'categories' => array
+ (
+ 'model' => 'category', // The foreign model
+ 'through' => 'post_categories' // The joining table
+ ),
+ );
+
+Als je Kohana hebt opgezet om een tabel voorvoegsel te gebruiken, dan hoef je geen zorgen te maken om dit voorvoegsel hier te gebruiken bij de tabelnaam.
+
+### Foreign keys
+
+Als je in Kohana 2.x's ORM een foreign key wilde overschrijven moest je de relatie specificeren waaraan het toebehoorde, en de nieuwe foreign key instellen in de member variabele `$foreign_keys`.
+
+In 3.0 moet je nu een `foreign_key` definiëren in de relatie-definitie, zoals hier:
+
+ Class Model_Post extends ORM
+ {
+ $_belongs_to = array
+ (
+ 'author' => array
+ (
+ 'model' => 'user',
+ 'foreign_key' => 'user_id',
+ ),
+ );
+ }
+
+In dit voorbeeld zouden we een `user_id` veld moeten hebben in de tabel posts.
+
+
+
+In has_many relaties is de `far_key` het veld in de trough tabel die linkt naar de foreign tabel en is de `foreign key` het veld in de trough tabel die "this" model's tabel linkt naar de trough table.
+
+Stel je de volgende opstelleing voor: "Posts" hebben en behoren tot vele "Categories" via `posts_sections` ("Posts" have and belong to many "Categories" through `posts_sections`)
+
+| categories | posts_sections | posts |
+|------------|------------------|---------|
+| id | section_id | id |
+| name | post_id | title |
+| | | content |
+
+ Class Model_Post extends ORM
+ {
+ protected $_has_many = array(
+ 'sections' => array(
+ 'model' => 'category',
+ 'through' => 'posts_sections',
+ 'far_key' => 'section_id',
+ ),
+ );
+ }
+
+ Class Model_Category extends ORM
+ {
+ protected $_has_many = array (
+ 'posts' => array(
+ 'model' => 'post',
+ 'through' => 'posts_sections',
+ 'foreign_key' => 'section_id',
+ ),
+ );
+ }
+
+
+Uiteraard is de aliasing setup hier een beetje gek, onnodig, maar het is een goed voorbeeld om te tonen hoe het foreign/far key systeem werkt.
+
+### ORM Iterator
+
+Het is ook best te melden dat `ORM_Iterator` nu herschreven is naar `Database_Result`.
+
+Als je een array van ORM objecten met hun keys als index van de array wilt verkrijgen, moet je [Database_Result::as_array] gebruiken, bijvoorbeeld:
+
+
+ $objects = ORM::factory('user')->find_all()->as_array('id');
+
+Waar `id` de primary key is in de user tabel.
+
+## Router Library
+
+In versie 2 was er een Router library die de main request afhandelde. Het liet je de basisroutes instellen in het `config/routes.php` bestand en het liet je toe om zelfgeschreven regex te gebruiken voor routes, maar het was niet echt flexibel als je iets radicaal wou veranderen.
+
+## Routes
+
+Het routing systeem (nu wordt verwezen naar het request systeem) is een stuk flexibeler in 3.0. Routes zijn nu gedefinieerd in het boostrap bestand (`application/bootstrap.php`) en de de module's init.php (`modules/module_name/init.php`). Het is ook interessant te weten dat routes worden geëvalueerd in de volgorde dat ze worden gedefinieerd. In plaats daarvan specifieer je een patroon voor elke uri, je kan variabelen gebruiken om segmenten aan te duiden (zoals een controller, methode, id).
+
+Bijvoorbeeld, in 2.x zouden deze regexes:
+
+ $config['([a-z]+)/?(\d+)/?([a-z]*)'] = '$1/$3/$1';
+
+de uri `controller/id/method` linken aan `controller/method/id`. In 3.0 gebruik je dit:
+
+ Route::set('reversed','({{userguide/examples/error}}
+
+## Error/Exception Handling uitzetten
+
+Als je niet de interne error handling wilt gebruiken, kan je deze uitschakelen wanneer je [Kohana::init] aanroept:
+
+ Kohana::init(array('errors' => FALSE));
diff --git a/includes/kohana/modules/userguide/guide/nl/debugging.profiling.md b/includes/kohana/modules/userguide/guide/nl/debugging.profiling.md
new file mode 100644
index 00000000..9c82f7dc
--- /dev/null
+++ b/includes/kohana/modules/userguide/guide/nl/debugging.profiling.md
@@ -0,0 +1,20 @@
+# Profiling
+
+Kohana biedt een zeer eenvoudige manier aan om statistieken over uw aanvraag te tonen:
+
+1. Gewone [Kohana] methodes dat aangeroepen worden
+2. Requests
+3. [Database] queries
+4. Gemiddelde uitvoeringstijden voor uw applicatie
+
+## Voorbeeld
+
+Je kan op elk tijdstip de huidige [profiler] statistieken tonen of opvragen:
+
+
+
+
+
+## Voorbeeld
+
+{{profiler/stats}}
\ No newline at end of file
diff --git a/includes/kohana/modules/userguide/guide/nl/features.md b/includes/kohana/modules/userguide/guide/nl/features.md
new file mode 100644
index 00000000..25cbb18e
--- /dev/null
+++ b/includes/kohana/modules/userguide/guide/nl/features.md
@@ -0,0 +1 @@
+This page lists the features of Kohana v3
\ No newline at end of file
diff --git a/includes/kohana/modules/userguide/guide/nl/menu.md b/includes/kohana/modules/userguide/guide/nl/menu.md
new file mode 100644
index 00000000..3aa787c1
--- /dev/null
+++ b/includes/kohana/modules/userguide/guide/nl/menu.md
@@ -0,0 +1,31 @@
+1. **Ga aan de slag**
+ - [Wat is Kohana?](about.kohana)
+ - [Conventies and Codeerstijl](about.conventions)
+ - [Model View Controller](about.mvc)
+ - [Cascading Filesystem](about.filesystem)
+ - [Request Flow](about.flow)
+ - [Installatie](about.install)
+ - [Upgraden](about.upgrading)
+ - [API Browser](api)
+3. **Basis gebruik**
+ - [Configuratie](using.configuration)
+ - [Laden van classes](using.autoloading)
+ - [Views en HTML](using.views)
+ - [Sessies en Cookies](using.sessions)
+ - [Berichten (Messages)](using.messages)
+4. **Debuggen**
+ - [Code](debugging.code)
+ - [Error Handling](debugging.errors)
+ - [Profiling](debugging.profiling)
+5. **Beveiliging**
+ - [XSS](security.xss)
+ - [Validatie](security.validation)
+ - [Cookies](security.cookies)
+ - [Database](security.database)
+6. **Tutorials**
+ - [Hello, World](tutorials.helloworld)
+ - [Routes, URLs en Links](tutorials.urls)
+ - [URLs opschonen](tutorials.removeindex)
+ - [Databases](tutorials.databases)
+ - [ORM](tutorials.orm)
+ - [Werken met Git](tutorials.git)
diff --git a/includes/kohana/modules/userguide/guide/nl/security.cookies.md b/includes/kohana/modules/userguide/guide/nl/security.cookies.md
new file mode 100644
index 00000000..174800f6
--- /dev/null
+++ b/includes/kohana/modules/userguide/guide/nl/security.cookies.md
@@ -0,0 +1,3 @@
+# Cookie Veiligheid
+
+[!!] Nog niet beschikbaar
diff --git a/includes/kohana/modules/userguide/guide/nl/security.database.md b/includes/kohana/modules/userguide/guide/nl/security.database.md
new file mode 100644
index 00000000..aa5135b3
--- /dev/null
+++ b/includes/kohana/modules/userguide/guide/nl/security.database.md
@@ -0,0 +1,3 @@
+# Database Veiligheid
+
+[!!] Nog niet beschikbaar
diff --git a/includes/kohana/modules/userguide/guide/nl/security.validation.md b/includes/kohana/modules/userguide/guide/nl/security.validation.md
new file mode 100644
index 00000000..80947b94
--- /dev/null
+++ b/includes/kohana/modules/userguide/guide/nl/security.validation.md
@@ -0,0 +1,244 @@
+# Validatie
+
+Validatie kan uitgevoerd worden op elke array met behulp van de [Validate] class. Labels, filters, regels en callbacks kunnen aan het Validate object worden toegevoegd via een array key, zogenaamd een "veldnaam".
+
+labels
+: Een label is een gebruiksvriendelijke leesbare versie van de veldnaam.
+
+filters
+: Een filter wijzigt de waarde van een veld voordat de regels en callbacks worden uitgevoerd.
+
+rules
+: Een regel is een controle op een veld dat "TRUE" of "FALSE" teruggeeft. A rule is a check on a field that returns `TRUE` or `FALSE`. Als een regel `FALSE` teruggeeft, wordt er een error toegevoegd aan het veld.
+
+callbacks
+: Een callback is een zelfgeschreven methode die het gehele Validate object tot zijn beschikking heeft. De return value van een callback wordt genegeerd. In plaats daarvan moet de callback handmatig een error toevoegen aan het object met behulp van [Validate::error] wanneer een fout optreedt.
+
+[!!] Merk op dat de [Validate] callbacks en de [PHP callbacks](http://php.net/manual/language.pseudo-types.php#language.types.callback) niet hetzelfde zijn.
+
+Waneer je `TRUE` als veldnaam gebruikt bij het toevoegen van een filter, regel of callback, dan zal deze worden toegepast op alle velden met een naam.
+
+**Het [Validate] object zal alle velden verwijderen van de array wanneer deze niet specifiek een naam hebben gekregen via een label, filter, regel of callback. Dit voorkomt toegang tot velden die niet gevalideerd zijn als een veiligheidsmaatregel.**
+
+Een validatie object maken wordt gedaan door de [Validate::factory] methode:
+
+ $post = Validate::factory($_POST);
+
+[!!] Het `$post` object zal worden gebruikt voor de rest van deze tutorial. Deze tutorial zal je tonen hoe je een registratie van een nieuwe gebruiker valideert.
+
+### Standaard regels
+
+Validatie heeft standaard altijd enkele regels:
+
+Naam van de regel | Functie
+------------------------- |---------------------------------------------------
+[Validate::not_empty] | Waarde moet een niet-lege waarde zijn
+[Validate::regex] | Waarde moet voldoen aan de reguliere expressie
+[Validate::min_length] | Minimum aantal karakters voor een waarde
+[Validate::max_length] | Maximum aantal karakters voor een waarde
+[Validate::exact_length] | Waarde moet een exact aantal karakters bevatten
+[Validate::email] | Een emailadres is vereist
+[Validate::email_domain] | Controleer of het domein van het email bestaat
+[Validate::url] | Waarde moet een URL zijn
+[Validate::ip] | Waarde moet een IP address zijn
+[Validate::phone] | Waarde moet een telefoonnummer zijn
+[Validate::credit_card] | Waarde moet een credit card zijn
+[Validate::date] | Waarde moet een datum (en tijd) zijn
+[Validate::alpha] | Alleen alpha karakters toegelaten
+[Validate::alpha_dash] | Alleen alpha karakters en koppeltekens toegelaten
+[Validate::alpha_numeric] | Alleen alpha karakters en nummers toegelaten
+[Validate::digit] | Waarde moet een geheel getal zijn
+[Validate::decimal] | Waarde moet een decimaal of float getal zijn
+[Validate::numeric] | Alleen nummers toegelaten
+[Validate::range] | Waarde moet zich bevinden binnenin een range
+[Validate::color] | Waarde moet een geldige HEX kleurencode zijn
+[Validate::matches] | Waarde moet gelijk zijn aan een ander veld
+
+[!!] Iedere methode dat bestaat binnenin de [Validate] class kan gebruikt worden als validatie-regel zonder een volledige callback te definiëren. Bijvoorbeeld, `'not_empty'` toevoegen is hetzelfde als `array('Validate', 'not_empty')`.
+
+## Toevoegen van filters
+
+Alle validatie-filters worden gedefineerd als een veldnaam, een methode of een functie (gebruik makend van [PHP callback](http://php.net/manual/language.pseudo-types.php#language.types.callback) syntax) en een array van parameters:
+
+ $object->filter($field, $callback, $parameter);
+
+Filters veranderen de waarde van een veld vooraleer deze gecontoleerd zijn via regels of callbacks.
+
+Indien we het veld "username" willen omvormen naar kleine letters:
+
+ $post->filter('username', 'strtolower');
+
+Als we alle witruimtes voor en na de waarde willen verwijderen voor *alle* velden:
+
+ $post->filter(TRUE, 'trim');
+
+## Toevoegen van regels
+
+Alle validatieregels worden gedefineerd als een veldnaam, een methode of een functie (gebruik makend van [PHP callback](http://php.net/manual/language.pseudo-types.php#language.types.callback) syntax) en een array van parameters:
+
+ $object->rule($field, $callback, $parameter);
+
+Om ons voorbeeld te starten, zullen we validatie uitvoeren op een `$_POST` array die gebruikers registratie gegevens bevat:
+
+ $post = Validate::factory($_POST);
+
+Vervolgens moeten we de POST-informatie met behulp van [Validate] doorlopen. Om te beginnen moeten we een aantal regels toevoegen:
+
+ $post
+ ->rule('username', 'not_empty')
+ ->rule('username', 'regex', array('/^[a-z_.]++$/iD'))
+
+ ->rule('password', 'not_empty')
+ ->rule('password', 'min_length', array('6'))
+ ->rule('confirm', 'matches', array('password'))
+
+ ->rule('use_ssl', 'not_empty');
+
+Iedere bestaande PHP functie kan worden gebruikt als regel. Bijvoorbeeld, als we willen controleren of een gebruiker een correcte waarde heeft ingevuld als antwoord op de SSL question:
+
+ $post->rule('use_ssl', 'in_array', array(array('yes', 'no')));
+
+Merk op dat alle array parameters steeds moeten "verpakt" worden door een array! Zonder die array, `in_array` zou worden aangeroepen als `in_array($value, 'yes', 'no')`, wat een PHP error zou teruggeven.
+
+Je kan eigen regels toevoegen met behulp van een [PHP callback](http://php.net/manual/language.pseudo-types.php#language.types.callback]:
+
+ $post->rule('username', 'User_Model::unique_username');
+
+[!!] Momenteel (v3.0.7) is het niet mogelijk om een object te gebruiken als rule, enkel statische methodes en functies.
+
+De methode `User_Model::unique_username()` zal ongeveer gedefinieerd worden als:
+
+ public static function unique_username($username)
+ {
+ // Controleer of de username al bestaat in de database
+ return ! DB::select(array(DB::expr('COUNT(username)'), 'total'))
+ ->from('users')
+ ->where('username', '=', $username)
+ ->execute()
+ ->get('total');
+ }
+
+[!!] Zelfgeschreven regels laten toe om de vele extra controles te hergebruiken voor verschillende doeleinden. Deze functies zullen meestal bestaan in een model, maar kunnen gedefinieerd worden in elke class.
+
+## Toevoegen van callbacks
+
+Alle validatie-callbacks worden gedefineerd als een veldnaam en een methode of een functie (gebruik makend van [PHP callback](http://php.net/manual/language.pseudo-types.php#language.types.callback) syntax):
+
+ $object->callback($field, $callback);
+
+[!!] In tegenstelling tot filters en regels, kunnen geen parameters worden meegestuurd naar een callback.
+
+Het gebruikers wachtwoord moet gehashed worden indien het gevalideerd is, dus zulen we dit doen met een callback:
+
+ $post->callback('password', array($model, 'hash_password'));
+
+Dit in de veronderstelling dat de `$model->hash_password()` methode er gelijkaardig uitzien als:
+
+ public function hash_password(Validate $array, $field)
+ {
+ if ($array[$field])
+ {
+ // Hash het wachtwoord als het bestaat
+ $array[$field] = sha1($array[$field]);
+ }
+ }
+
+# Een volledig voorbeeld
+
+Eerst hewwen we een [View] nodig met daarin een HTML formulier, die we plaatsen in `application/views/user/register.php`:
+
+
+
+
+ -
+
+
+
+
+
+
-
+
+
+
+
+
+
{{userguide/examples/hello_world_error}}
+
+Voor de één of andere reden geeft Kohana een error en toont het niet ons cool bericht.
+
+Als we kijken naar het error-bericht kunnen we zien dat de View library onze site template niet kon vinden, waarschijnlijk omdat we er nog geen aangemaakt hebben - *doh*!
+
+Laten we het view bestand `application/views/site.php` aanmaken voor ons bericht:
+
+
+
+ We just wanted to say it! :)
+ + + +Als we de pagina vernieuwen dan kunnen we de vruchten zien van ons *zwaar" werk: + + + +## Stage 3 – Profit! + +In deze tutorial heb je geleerd hoe je een controller maakt en een view gebruikt om je logica te scheiden van het visuele. + +Dit is natuurlijk een zeer elementaire inleiding over het werken met Kohana en toont zelfs niet de sterkte van het framework voor wanneer je applicaties hiermee ontwikkelt. diff --git a/includes/kohana/modules/userguide/guide/nl/tutorials.orm.md b/includes/kohana/modules/userguide/guide/nl/tutorials.orm.md new file mode 100644 index 00000000..bc5be9f2 --- /dev/null +++ b/includes/kohana/modules/userguide/guide/nl/tutorials.orm.md @@ -0,0 +1,298 @@ +# ORM {#top} + +Kohana 3.0 bevat een krachtige ORM-module die het "active record"-patroon gebruikt en database introspectie gebruikt om kolominformatie te bepalen van een model. + +De ORM-module is opgenomen in de Kohana 3.0 installatie maar moet worden ingeschakeld vooraleer je het kunt gebruiken. In je `application/bootstrap.php` bestand moet je de oproen naar [Kohana::modules] aanpassen en de ORM-module insluiten: + + Kohana::modules(array( + ... + 'orm' => MODPATH.'orm', + ... + )); + +## Configuratie {#configuration} + +ORM vergt weinig configuratie om aan de slag te kunnen. Breid uw model classes uit met ORM om de module te kunnen gebruiken: + + class Model_User extends ORM + { + ... + } + +In het voorbeeld hierboven zal het model zoeken naar een tabel `users` in de standaard database. + +### Model Configuratie Properties + +De volgende eigenschappen worden gebruikt om ieder model te configureren: + +Type | Eigenschap | Omschrijving | Standaard waarde +----------|---------------------|--------------------------------------| ------------------------- +`string` | _table_name | Tabelnaam om te gebruiken | `singular model name` +`string` | _db | Naam van de database om te gebruiken | `default` +`string` | _primary_key | Kolom die dient als primary key | `id` +`string` | _primary_val | Kolom die dient als primary value | `name` +`bool` | _table_names_plural | Zijn de tabelnamen meervoudig? | `TRUE` +`array` | _sorting | Array met kolom => volgorde | `primary key => ASC` +`string` | _foreign_key_suffix | Achtervoegsel voor foreign keys | `_id` + +## Het gebruik van ORM + +### Een Record inladen + +Om een instantie van een model aan te maken, kan je de [ORM::factory] methode of [ORM::__construct] gebruiken: + + $user = ORM::factory('user'); + // of + $user = new Model_User(); + +De constructor en factory methodes accepteren ook een primary key waarde om het gegeven model's data in te laden: + + // Laad gebruiker met ID 5 + $user = ORM::factory('user', 5); + + // Kijk of de gebruiker succesvol werd ingeladen + if ($user->loaded()) { ... } + +Je kan optioneel een array met keys => value paren meegeven om een data object in te laden die voldoet aan de gegeven criteria: + + // Laad een gebruiker met email joe@example.com + $user = ORM::factory('user', array('email' => 'joe@example.com')); + +### Zoeken naar één of meerdere records + +ORM ondersteunt de meeste krachtige [Database] methoden voor het doorzoeken van gegevens van uw model. Zie de `_db_methods` eigenschap voor een volledige lijst van ondersteunde methode oproepen. Records worden opgehaald met behulp van de [ORM::find] en [ORM::find_all] functies. + + // Dit zal de eerste actieve gebruiker nemen met de naam Bob + $user = ORM::factory('user') + ->where('active', '=', TRUE) + ->where('name', '=', 'Bob') + ->find(); + + // Dit zal alle gebruikers nemen met de naam Bob + $users = ORM::factory('user') + ->where('name', '=', 'Bob') + ->find_all(); + +Wanneer je een lijst van modellen ontvangt met behulp van [ORM::find_all], kan je deze doorlopen zoals je doet met database resultaten: + + foreach ($users as $user) + { + ... + } + +Een zeer handige functie van ORM is de [ORM::as_array] methode die het record zal teruggeven als een array. Indien je dit gebruikt met [ORM::find_all], zal een array van alle records worden teruggegeven. Een goed voorbeeld van wanneer dit nuttig is, is voor select in het HTML formulier: + + // Toon een dropdown/select met daarin alle gebruikersnamen (id als value van de options) + echo Form::select('user', ORM::factory('user')->find_all()->as_array('id', 'username')); + +### Het aantal records tellen + +Gebruik [ORM::count_all] om het aantal records terug te geven voor een bepaalde query. + + // Aantal actieve gebruikers + $count = ORM::factory('user')->where('active', '=', TRUE)->count_all(); + +Als je het totaal aantal gebruikers wilt tellen voor een bepaalde query, terwijl je enkel een bepaalde set van deze gebruikers wilt tonen, gebruik dan de [ORM::reset] methode met `FALSE` vooraleer je `count_all` gebruikt: + + $user = ORM::factory('user'); + + // Totaal aantal gebruikers (reset FALSE zorgt ervoor dat het query object dat het query object niet geleegd wordt) + $count = $user->where('active', '=', TRUE)->reset(FALSE)->count_all(); + + // Geef enkel de eerste 10 resultaten terug van deze resultaten + $users = $user->limit(10)->find_all(); + +### Properties van een model aanspreken + +Alle model properties zijn toegankelijk via de `__get` en `__set` magic methodes. + + $user = ORM::factory('user', 5); + + // Geef de gebruikersnaam terug + echo $user->name; + + // Verander de gebruiker zijn naam + $user->name = 'Bob'; + +Voor het opslaan van gegevens/properties die niet bestaan in de tabel van het model, kan je gebruik maken van het `_ignored_columns` data member. De gegevens zullen worden opgeslagen in het interne `_object` member, maar zal worden genegeerd op database-niveau. + + class Model_User extends ORM + { + ... + protected $_ignored_columns = array('field1', 'field2', …); + ... + } + +Meerdere key => value paren kunnen worden ingesteld door gebruik te maken van de [ORM::values] methode. + + $user->values(array('username' => 'Joe', 'password' => 'bob')); + +### Aanmaken en opslaan van records + +De methode [ORM::save] wordt gebruikt om zowel nieuwe records aan te maken als het upaten van bestaande. + + // Nieuw record aanmaken + $user = ORM::factory('user'); + $user->name = 'Nieuwe gebruiker'; + $user->save(); + + // Aanpassen van een bestaand record + $user = ORM::factory('user', 5); + $user->name = 'Gebruiker 2'; + $user->save(); + + // Controleer of het record opgeslagen is + if ($user->saved()) { ... } + +Je kan meerdere records tegelijk veranderen met de [ORM::save_all] methode: + + $user = ORM::factory('user'); + $user->name = 'Bob'; + + // Verander bij alle actieve gebruikers de naam naar 'Bob' + $user->where('active', '=', TRUE)->save_all(); + +#### Gebruik `Updated` en `Created` kolommen + +De `_updated_column` en `_created_column` members staan ter beschikking om automatisch aangepast te worden wanneer een model wordt gecreëerd of aangepast. Ze worden standaard niet gebruikt. Om ze te gebruiken: + + // date_created is de kolom die wordt gebruikt om de aanmaak datum op te slaan. Gebruik format => TRUE om een timestamp op te slaan + protected $_created_column = array('date_created', 'format' => TRUE); + + // date_modified is de kolom die wordt gebruikt om de datum op te slaan wanneer het item is aangepast. In dit geval wordt een string gebruikt om een date() formaat te specificeren + protected $_updated_column = array('date_modified', 'format' => 'm/d/Y'); + +### Verwijderen van records + +Records worden verwijderd met [ORM::delete] en [ORM::delete_all]. Deze methoden werken op dezelfde manier als het opslaan van records zoals hierboven beschreven, met de uitzondering dat [ORM::delete] nog een optionele parameter heeft, het `id` van het record om te verwijderen. Anders wordt het huidig ingeladen record verwijderd. + +### Relaties + +ORM ondersteunt zeer goed relateies. Ruby heeft een [goede tutorial omtrent relaties](http://api.rubyonrails.org/classes/ActiveRecord/Associations/ClassMethods.html). + +#### Belongs-To en Has-Many + +We gaan er van uit dat we werken met een school dat veel (has many) studenten heeft. Iedere student kan enkel maar tot één school behoren (belong to). Dan zullen de relaties als volgt gedefinieerd worden: + + // In het model "school" + protected $_has_many = array('students' => array()); + + // In het model "student" + protected $_belongs_to = array('school' => array()); + +Om een student zijn school te verkrijgen gebruik je: + + $school = $student->school; + +Om een school zijn studenten te verkrijgen gebruik je: + + // Merk op dat find_all is vereist na "students" + $students = $school->students->find_all(); + + // Om resultaten te "filteren": + $students = $school->students->where('active', '=', TRUE)->find_all(); + +Standaard zal ORM willen zoeken naar een `school_id` model in de studenten tabel. Dit kan worden overschreven door gebruik te maken van het `foreign_key` attribuut: + + protected $_belongs_to = array('school' => array('foreign_key' => 'schoolID')); + +De foreign key moet overschreven worden in zowel het student als school model. + +#### Has-One + +Has-One is een speciale versie van Has-Many, het enige verschil is dat er maar één enkel record is. In het bovenstaande voorbeeld zou iedere school maar één student hebben (al is dat wel een slecht voorbeeld). + + // In het model "school" + protected $_has_one = array('student' => array()); + +Je moet niet zoals bij Belongs-To de `find` methode gebruiken wanneer je verwijst naar een het Has-One gerelateerd object, dit gebeurt automatisch. + +#### Has-Many "Through" + +De Has-Many "through" relatie (ook bekend als Has-And-Belongs-To-Many) wordt gebruikt in het geval dat één object gerelateerd is met meerdere objecten van verschillende types en omgekeerd. Bijvoorbeeld, een student kan verschillende klassen volgen en een klass kan verschillende studenten hebben. In dit geval wordt een derde tabel gebruikt en een model die dienst doet als `pivot`. In dit geval noemen we het pivot object/model `enrollment` (=inschrijving). + + // In het model "student" + protected $_has_many = array('classes' => array('through' => 'enrollment')); + + // In het model "class" + protected $_has_many = array('students' => array('through' => 'enrollment')); + +De inschrijvingstabel (`enrollment`) moet twee foreign keys hebben, een voor `class_id` en de andere voor `student_id`. Deze kunnen worden overschreven door `foreign_key` en `far_key` te gebruiken bij het definiëren van de relatie. Bijvoorbeeld: + + // In het model "student" (de foreign key verwijst naar dit model [student], terwijl de far key verwijst naar het andere model [class]) + protected $_has_many = array('classes' => array('through' => 'enrollment', 'foreign_key' => 'studentID', 'far_key' => 'classID')); + + // In het model "class" + protected $_has_many = array('students' => array('through' => 'enrollment', 'foreign_key' => 'classID', 'far_key' => 'studentID')); + +Het inschrijvings model (enrollment) zal als volgt gedefinieerd worden: + + // Het model "enrollment" hoort bij zowel "student" als "class" + protected $_belongs_to = array('student' => array(), 'class' => array()); + +Om de gerelateerde objecten te bereiken, gebruik je: + + // Om de klassen van een student te verkrijgen + $student->classes->find_all(); + + // Om studenten te verkrijven vanuit de klas + $class->students->find_all(); + +### Validatie + +ORM werkt nauw samen met de [Validate] library. ORM biedt de volgende members aan voor validatie + +* _rules +* _callbacks +* _filters +* _labels + +#### `_rules` + + protected $_rules = array + ( + 'username' => array('not_empty' => array()), + 'email' => array('not_empty' => array(), 'email' => array()), + ); + +`username` zal gecontroleerd worden om zeker niet leeg te zijn. `email` zal ook gecontroleerd worden om te verzekeren dat het een geldig emailadres is. De lege arrays die als values worden meegestuurd, kunnen worden gebruikt om optionele parameters mee te geven aan deze functie aanroepen. + +#### `_callbacks` + + protected $_callbacks = array + ( + 'username' => array('username_unique'), + ); + +`username` zal worden meegestuurd naar een callback methode `username_unique`. Als de methode bestaat in het huidige model, zal het worden gebruikt, anders zal een globale functie worden opgeroepen. Hier is een voorbeeld van z'n methode: + + public function username_unique(Validate $data, $field) + { + // Logica om te controleren of de gebruikersnaam uniek is + ... + } + +#### `_filters` + + protected $_filters = array + ( + TRUE => array('trim' => array()), + 'username' => array('stripslashes' => array()), + ); + +`TRUE` slaat erop dat de `trim` filter wordt gebruikt voor alle velden. `username` zal ook gefilterd worden door `stripslashes` vooraleer het gevalideerd wordt. De lege arrays die als values worden meegestuurd, kunnen worden gebruikt om optionele parameters mee te geven aan deze filter-functie aanroepen. + +#### Controleren of een Object Valid is + +Gebruik [ORM::check] om te kijken of het object momenteel valid is. + + // Een object zijn values instellen en dan controleren of het valid is + if ($user->values($_POST)->check()) + { + $user->save(); + } + +Je kan de `validate()` methode gebruiken om een model zijn validatie object aan te roepen. + + // Een optionele filter manueel toevoegen + $user->validate()->filter('username', 'trim'); \ No newline at end of file diff --git a/includes/kohana/modules/userguide/guide/nl/tutorials.removeindex.md b/includes/kohana/modules/userguide/guide/nl/tutorials.removeindex.md new file mode 100644 index 00000000..dc8864c5 --- /dev/null +++ b/includes/kohana/modules/userguide/guide/nl/tutorials.removeindex.md @@ -0,0 +1,88 @@ +# `index.php` verwijderen uit de URL + +Om uw URLs proper te houden, wil je hoogtswaarschijnlijk je applicatie kunnen benaderen zonder /index.php/` in uw URL te gebruiken. Er zijn twee stappen om `index.php` te verwijderen uit de URL. + +1. Het bootstrap bestand aanpassen +2. Herschrijven van URL's instellen + +# Configuratie van de Bootstrap + +Het eerste dat je moet veranderen is de `index_file` instelling van [Kohana::init]: + + Kohana::init(array( + 'base_url' => '/myapp/', + 'index_file' => FALSE, + )); + +Nu zullen alle links die gegeneerd worden met [URL::site], [URL::base] en [HTML::anchor] niet meer "index.php" gebruiken in de URL. Alle gegenereerde links zullen starten met `/myapp/` in plaats van `/myapp/index.php/`. + +# URL Herschrijven + +Het herschrijven van URL kan verschillen, naargelang je web server. + +## Apache + +Hernoem `example.htaccess` naar `.htaccess` en verander de volgende regel code: + + RewriteBase /kohana/ + +Dit moet gelijk zijn met de `base_url` instelling van [Kohana::init]: + + RewriteBase /myapp/ + +In de meeste gevallen is dit het enige dat je moet veranderen. + +### Er loopt iets fout! + +Als je een "Internal Server Error" of "No input file specified" error krijgt, probeer dan hetvolgende te veranderen: + + RewriteRule ^(?:application|modules|system)\b - [F,L] + +Door enkel een slash te gebruiken: + + RewriteRule ^(application|modules|system)/ - [F,L] + +Als het nog steeds niet werkt, probeer dan hetvolgende te veranderen: + + RewriteRule .* index.php/$0 [PT] + +Naar iets simpeler: + + RewriteRule .* index.php [PT] + +### Nog steeds niet loopt het fout! + +Als je nog steeds fouten krijgt, controleer dan zeker dat je host wel URL `mod_rewrite` ondersteund. Als je de Apache configuratie kunt aanpassen, voeg dan deze lijnen toe aan de configuratie, meestal in `httpd.conf`: + +{{userguide/examples/error}}
+
+## Отключение обработчика ошибок/исключений
+
+Если Вы не хотите использовать встроенный обработчик ошибок, отключите его с помощью [Kohana::init]:
+
+ Kohana::init(array('errors' => FALSE));
diff --git a/includes/kohana/modules/userguide/guide/ru-ru/debugging.profiling.md b/includes/kohana/modules/userguide/guide/ru-ru/debugging.profiling.md
new file mode 100644
index 00000000..020bac18
--- /dev/null
+++ b/includes/kohana/modules/userguide/guide/ru-ru/debugging.profiling.md
@@ -0,0 +1,20 @@
+# Профилирование
+
+Kohana предлагает очень простой способ для отображения статистики Вашего приложения:
+
+1. Системных вызовов [Kohana]
+2. Запросов (Requests)
+3. Запросов к [базам данных](Database)
+4. Среднего времени выполнения Вашего приложения
+
+## Пример
+
+Вы можете отобразить или собрать текущую статистику [профилировщика](profiler) в любое время:
+
+
+
+
+
+## Что получится
+
+{{profiler/stats}}
\ No newline at end of file
diff --git a/includes/kohana/modules/userguide/guide/ru-ru/features.md b/includes/kohana/modules/userguide/guide/ru-ru/features.md
new file mode 100644
index 00000000..76f3fa7c
--- /dev/null
+++ b/includes/kohana/modules/userguide/guide/ru-ru/features.md
@@ -0,0 +1 @@
+Эта страница перечисляет возможности Kohana v3
\ No newline at end of file
diff --git a/includes/kohana/modules/userguide/guide/ru-ru/menu.md b/includes/kohana/modules/userguide/guide/ru-ru/menu.md
new file mode 100644
index 00000000..d8cf8eee
--- /dev/null
+++ b/includes/kohana/modules/userguide/guide/ru-ru/menu.md
@@ -0,0 +1,32 @@
+1. **Первые шаги**
+ - [Что такое Kohana?](about.kohana)
+ - [Соглашения и стили](about.conventions)
+ - [Модель-Представление-Контроллер](about.mvc)
+ - [Файловая система](about.filesystem)
+ - [Порядок выполнения](about.flow)
+ - [Установка](about.install)
+ - [Обновление](about.upgrading)
+ - [Обзор API](api)
+2. **Основные операции**
+ - [Настройка](using.configuration)
+ - [Автозагрузка](using.autoloading)
+ - [Представление и HTML](using.views)
+ - [Сессии и Cookies](using.sessions)
+ - [Сообщения (Messages)](using.messages)
+ - [Интернационализация](using.translation)
+3. **Отладка**
+ - [Отладка кода](debugging.code)
+ - [Обработка ошибок](debugging.errors)
+ - [Профилирование](debugging.profiling)
+4. **Безопасность**
+ - [XSS](security.xss)
+ - [Валидация](security.validation)
+ - [Cookies](security.cookies)
+ - [База данных](security.database)
+5. **Обучение**
+ - [Hello, World](tutorials.helloworld)
+ - [Маршруты, URL и ссылки](tutorials.urls)
+ - [Очистка URL, ЧПУ](tutorials.removeindex)
+ - [Базы данных](tutorials.databases)
+ - [ORM](tutorials.orm)
+ - [Работа с Git](tutorials.git)
\ No newline at end of file
diff --git a/includes/kohana/modules/userguide/guide/ru-ru/security.cookies.md b/includes/kohana/modules/userguide/guide/ru-ru/security.cookies.md
new file mode 100644
index 00000000..13a8480d
--- /dev/null
+++ b/includes/kohana/modules/userguide/guide/ru-ru/security.cookies.md
@@ -0,0 +1,3 @@
+# Безопасность Cookie
+
+[!!] заглушка
diff --git a/includes/kohana/modules/userguide/guide/ru-ru/security.database.md b/includes/kohana/modules/userguide/guide/ru-ru/security.database.md
new file mode 100644
index 00000000..504a2740
--- /dev/null
+++ b/includes/kohana/modules/userguide/guide/ru-ru/security.database.md
@@ -0,0 +1,3 @@
+# Безопасность Database
+
+[!!] заглушка
diff --git a/includes/kohana/modules/userguide/guide/ru-ru/security.validation.md b/includes/kohana/modules/userguide/guide/ru-ru/security.validation.md
new file mode 100644
index 00000000..4c0d21bb
--- /dev/null
+++ b/includes/kohana/modules/userguide/guide/ru-ru/security.validation.md
@@ -0,0 +1,243 @@
+# Валидация
+
+С использованием [Validate] класса можно произвести валидацию любого массива. По ключу значения массива ("наименование поля" для валидатора), к объекту валидации можно добавить ярлыки, фильтры, правила и функции обратного вызова.
+
+labels (ярлыки)
+: Ярлык - это удобочитаемая интерпретация имени поля.
+
+filters (фильтры)
+: Фильтр видоизменяет значение поля перед применением к нему правил и функций обратного вызова.
+
+rules (правила)
+: Правило - это проверка значения поля, которая возвращает `TRUE` или `FALSE` в результате проверки. Если правило возвращает `FALSE`, то полю будет добавлена информация об ошибке.
+
+callbacks (функция обратного вызова)
+: Функция обратного вызова - это пользовательский метод, который имеет доступ до содержания объекта валидации. Возвращаемое значение функции игнорируется, ввиду этого, функция должна сама добавлять ошибку к полу объекта валидации, используя метод [Validate::error], при возникновении ошибки.
+
+[!!] Заметьте, что функции обратного вызова объекта [Validate] и функции обратного вызова PHP ([PHP callbacks](http://php.net/manual/language.pseudo-types.php#language.types.callback)) - это не одно и то же.
+
+Если вместо имени поля при добавлении фильтра, правила или функции обратного вызова использовать значение `TRUE`, то этот фильтр, правило или функция будет применена ко всем полям объекта Validate.
+
+**В мерах предосторожности, объект [Validate] удалит все поля из массива, которым не присвоен ярлык, фильтр, правило или функция обратного вызова. Это предотвращает доступ до полей, которые не участвуют в валидации.**
+
+Создание объекта валидации производится с использованием метода [Validate::factory]:
+
+ $post = Validate::factory($_POST);
+
+[!!] Далее в данном руководстве будет использован объект `$post`. Как пример, будет рассмотрена валидация регистрации нового пользователя.
+
+### Стандартные правила
+
+Класс валидации содержит следующие правила:
+
+Наименование правила | Действие
+------------------------- |-------------------------------------------------
+[Validate::not_empty] | Значение не должно быть пустым
+[Validate::regex] | Проверяется значение на совпадение с регулярным выражением
+[Validate::min_length] | Минимальная длина значения (минимальное количество знаков)
+[Validate::max_length] | Максимальная длина значения (максимальное количество знаков)
+[Validate::exact_length] | Длина значения должна быть равна указанному числу
+[Validate::email] | Значение должно представлять собой emal адрес
+[Validate::email_domain] | Проверяет существование email домена
+[Validate::url] | Значение должно представлять собой URL
+[Validate::ip] | Значение должно представлять собой IP адрес
+[Validate::phone] | Значение должно представлять собой номер телефона
+[Validate::credit_card] | Значение должно представлять собой номер кредитной карты
+[Validate::date] | Значение должно представлять собой дату (и время)
+[Validate::alpha] | Допустимы только буквенные значения
+[Validate::alpha_dash] | Допустимы значения, состоящие из букв и тире
+[Validate::alpha_numeric] | Допустимы только буквенные и числовые значения
+[Validate::digit] | Значение должно представлять собой целое число
+[Validate::decimal] | Значение должно представлять собой число десятичное число или число с плавающей точкой
+[Validate::numeric] | Допустимы только цифровые символы
+[Validate::range] | Значение должно быть в указанных пределах
+[Validate::color] | Значение должно представлять собой правильное значение цвета в HEX
+[Validate::matches] | Значение должно совпадать со значением другого поля
+
+[!!] Любой метод [Validate] класса может быть использован как правило валидации без определения полного обратного вызова (callback). Например, добавление `'not_empty'` - то же самое, что и `array('Validate', 'not_empty')`.
+
+## Добавление фильтров
+
+Фильтр валидации задаётся как имя поля, метод или функция (используя синтаксис [PHP callback](http://ru2.php.net/callback)) и массив параметров:
+
+ $object->filter($field, $callback, $parameters);
+
+Фильтры изменяют значение поля перед проверкой правилами или функциями обратного вызова.
+
+Для того, чтобы конвертировать значение поля "username" в нижний регистр:
+
+ $post->filter('username', 'strtolower');
+
+Если мы хотим удалить все пробелы до и после значения у *всех* полей:
+
+ $post->filter(TRUE, 'trim');
+
+## Добавление правил
+
+Все правила валидации задаются как имя поля, метод или функция (используя синтаксис [PHP callback](http://ru2.php.net/callback)) и массива параметров:
+
+ $object->rule($field, $callback, $parameters);
+
+Для начала, инициируем валидацию `$_POST` массива, который содержит информацию о регистрации:
+
+ $post = Validate::factory($_POST);
+
+Далее, нам необходимо обработать полученные данные, используя [Validate] класс. Во-первых, добавим несколько правил:
+
+ $post
+ ->rule('username', 'not_empty')
+ ->rule('username', 'regex', array('/^[a-z_.]++$/iD'))
+
+ ->rule('password', 'not_empty')
+ ->rule('password', 'min_length', array('6'))
+ ->rule('confirm', 'matches', array('password'))
+
+ ->rule('use_ssl', 'not_empty');
+
+В виде правила можно использовать практически все функции PHP. Например, можно проверить, верное ли значение ввёл пользователь на SSL вопрос:
+
+ $post->rule('use_ssl', 'in_array', array(array('yes', 'no')));
+
+Имейте в виду, что все параметры должны быть в виде массива! Если параметры были не в виде массива, то функция `in_array` была бы вызвана как `in_array($value, 'yes', 'no')`, что привело бы к PHP ошибке.
+
+Пользовательские правила могут быть добавлены, используя синтаксис [PHP callback](http://ru2.php.net/callback):
+
+ $post->rule('username', array($model, 'unique_username'));
+
+Метод `$model->unique_username()` определяется следующим образом:
+
+ public function unique_username($username)
+ {
+ // Проверка на то, имеется ли указанное значение username в БД
+ return ! DB::select(array(DB::expr('COUNT(username)'), 'total'))
+ ->from('users')
+ ->where('username', '=', $username)
+ ->execute()
+ ->get('total');
+ }
+
+[!!] Пользовательские правила позволяют производить большое количество дополнительных проверок и могут быть использованы для различных целей множество раз. Зачастую, они создаются как методы модели, однако, если необходимо, могут быть определены в любом классе.
+
+## Добавление функций обратного вызова (callbacks)
+
+Все функции обратного вызова (callback) определяются как имя поля, метод или функция (используя синтаксис [PHP callback](http://ru2.php.net/callback)) и массива параметров:
+
+ $object->callback($field, $callback, $parameters);
+
+[!!] До версии kohana 3.0.7, функции обратного вызова не обрабатывали входных параметров, в отличие от фильтров и правил. Если Вы используете старую версию, эти параметры будут проигнорированы.
+
+Пароль пользователя должен быть захэширован, если он прошёл валидацию, поэтому это можно сделать, используя функцию обратного вызова:
+
+ $post->callback('password', array($model, 'hash_password'));
+
+Это подразумевает, что метод `$model->hash_password()` будет работать следующим образом:
+
+ public function hash_password(Validate $array, $field)
+ {
+ if ($array[$field])
+ {
+ // Хэшировать пароль, если он присутствует
+ $array[$field] = sha1($array[$field]);
+ }
+ }
+
+# Полный пример
+
+Во-первых, нам понадобится представление ([View]), которое содержит HTML форму и которое будет располагаться в `application/views/user/register.php`:
+
+
+
+
+ -
+
+
+
+
+
+
-
+
+
+
+
+
+
{{userguide/examples/hello_world_error}}
+
+По каким-то причинам kohana генерирует ошибку и не хочет показать наше восхитительное сообщение.
+
+Если мы посмотрим на сообщение с ошибкой, то увидим, что библиотека View не смогла найти наш главный шаблон, скорее всего потому что мы его еще не создали - *черт*!
+
+Давайте добавим файл представления `application/views/site.php` для нашего сообщения:
+
+
+
+ We just wanted to say it! :)
+ + + +Если обновить страницу, то мы увидим увидим результаты наших усилий: + + + +## Этап 3 - Итого! + +В данной статье Вы изучили, как создать контроллер и использовать шаблоны для отделения логики от представления. + +Очевидно, что это было всего-навсего упрощенное вступление, и оно не отражает даже малой части всех возможностей, доступных при разработке приложений с помощью kohana. diff --git a/includes/kohana/modules/userguide/guide/ru-ru/tutorials.orm.md b/includes/kohana/modules/userguide/guide/ru-ru/tutorials.orm.md new file mode 100644 index 00000000..14d2096e --- /dev/null +++ b/includes/kohana/modules/userguide/guide/ru-ru/tutorials.orm.md @@ -0,0 +1,312 @@ +# ORM {#top} + +Kohana 3.0 включает мощный модуль ORM, который использует паттерн Active Record и автоопределение информации о списке полей БД модели. + +Модуль ORM включен в дистрибутив Kohana 3.0, но нуждается в подключении перед его использованием. В файле `application/bootstrap.php` отредактируйте вызов [Kohana::modules] и добавьте модуль ORM: + + Kohana::modules(array( + ... + 'orm' => MODPATH.'orm', + ... + )); + +## Настройка {#configuration} + +ORM требует небольшую настройку перед использованием. Наследуйте Вашу модуль от ORM: + + class Model_User extends ORM + { + ... + } + +В примере выше, модель будет искать таблицу `users` в БД по умолчанию. + +### Свойства модели, отвечающие за конфигурацию + +Следующие свойства используются для настройки каждой модели: + +Тип | Название | Описание | Значение по умолчанию +----------|---------------------|-------------------------------------|--------------------------------- +`string` | _table_name | Используемая таблица БД | `имя модели в единственном числе` +`string` | _db | Название БД | `default` +`string` | _primary_key | Поле - первичный ключ | `id` +`string` | _primary_val | Титульное поле | `name` +`bool` | _table_names_plural | Имя таблицы во множественном числе | `TRUE` +`array` | _sorting | Сортировка (столбец => направление) | `primary key => ASC` +`string` | _foreign_key_suffix | Суффикс внешнего ключа | `_id` + +## Использование ORM + +### Загрузка записи + +Для создания экземпляра модели используйте метод [ORM::factory] или конструктор [ORM::__construct]: + + $user = ORM::factory('user'); + // или + $user = new Model_User(); + +Конструктор и фабричный метод также поддерживают значение первичного ключа для загрузки конкретной записи: + + // Загружаем пользователя с ID 5 + $user = ORM::factory('user', 5); + + // Проверяем успешность загрузки объекта пользователя + if ($user->loaded()) { ... } + +Опционально, Вы можете передать массив с парами ключ => значение для загрузки данных объекта по совпадающим критериям, указанным в массиве: + + // Загрузка пользователя с email joe@example.com + $user = ORM::factory('user', array('email' => 'joe@example.com')); + +### Поиск записи + +ORM поддерживает большинство методов класса [Database] для полноценного поиска данных модели. В свойстве `_db_methods` перечислен полный список поддерживаемых методов. Записи извлекаются после вызовов [ORM::find] или [ORM::find_all]. + + // Извлекаем первого активного пользователя по имени Bob + $user = ORM::factory('user') + ->where('active', '=', TRUE) + ->where('name', '=', 'Bob') + ->find(); + + // Ищем всех активных пользователей по имени Bob + $users = ORM::factory('user') + ... + ->find_all(); + +Когда Вы запрашиваете список моделей через [ORM::find_all], перебирать его можно аналогично обычным выборкам из БД: + + foreach ($users as $user) + { + ... + } + +Мощным инструментом ORM является метод [ORM::as_array], который возвращает полученные записи в виде массива. При использовании совместно с [ORM::find_all], будет возвращён массив всех записей. Хороший пример использование этого метода - когда необходимо передать значения для выпадающего списка: + + // Отображается выпадающий список пользователей + // (используется id в качестве значения select option) + form::select('user', ORM::factory('user')->find_all()->as_array('id', 'username') ... + +### Подсчёт записей + +Для получения количества записей для данного запроса, используйте [ORM::count_all]. + + // Число активных пользователей + $count = ORM::factory('user')->where('active', '=', TRUE)->count_all(); + +Если требуется подсчитать общее количество пользователей для данного запроса при лимитировании количества возвращаемых записей, используйте метод [ORM::reset] с параметром `FALSE` перед использованием `count_all`: + + $user = ORM::factory('user'); + + // Общее число пользователей (reset FALSE предотвращает объект от очистки перез запросом) + $count = $user->where('active', '=', TRUE)->reset(FALSE)->count_all(); + + // Получаем только первые 10 результатов + $users = $user->limit(10)->find_all(); + +### Доступ к свойствам модели + +Все свойства модели доступны через "магические" методы `__get` и `__set`. + + $user = ORM::factory('user', 5); + + // Выводит имя пользователя + echo $user->name; + + // Изменяет имя пользователя + $user->name = 'Bob'; + +Для хранения данных/свойств, которые отсутствуют в таблице модели, надо использовать атрибут `_ignored_columns`. + + class Model_User extends ORM + { + ... + protected $_ignored_columns = array('field1', 'field2', ...) + ... + } + +Множественные пары ключ => значение могут быть заданы с использованием метода [ORM::values]: + + $user->values(array('username' => 'Joe', 'password' => 'bob')); + +### Создаем и сохраняем записи + +Метод [ORM::save] используется как для создания новых записей, так и для обновления существующих. + + // Создаем запись + $user = ORM::factory('user'); + $user->name = 'New user'; + $user->save(); + + // Редактируем запись + $user = ORM::factory('user', 5); + $user->name = 'User 2'; + $user->save(); + + // Проверяем, сохранена ли запись + if ($user->saved()) { ... } + +Вы можете обновить множество записей с помощью метода [ORM::save_all]: + + $user = ORM::factory('user'); + $user->name = 'Bob'; + + // Все активные пользователи получат имя 'Bob' + $user->where('active', '=', TRUE)->save_all(); + +#### Использование `Updated` и `Created` для столбцов БД + +Свойства `_updated_column` и `_created_column` позволяют производить автоматическое обновление модели при её обновлении и сохранении. Это используется не по-умолчанию. Чтобы использовать эти свойства, следует их указать: + + // date_created является столбцом таблицы, в котором хранится дата создания. + // Для сохранения метки времени, используем TRUE + protected $_created_column = array('date_created' => TRUE); + + // date_modified является столбцом таблицы, в котором хранится дата изменения. + // В этом случае используется строка, определяющая формат для функции date() + protected $_updated_column = array('date_modified' => 'm/d/Y'); + +### Удаление записей + +Записи удаляются методами [ORM::delete] и [ORM::delete_all]. Эти методы работают аналогично описанному выше сохранению, за исключением того, что [ORM::delete] принимает необязательный параметр `id` для удаляемой записи. + +### Отношения + +ORM предоставляет мощную поддержку отношений таблиц. Прочитать про отношения можно в [справочнике по Ruby](http://api.rubyonrails.org/classes/ActiveRecord/Associations/ClassMethods.html) + +#### Belongs-To и Has-Many + +Допустим, мы работаем со школой, которая имеет много учеников (has many). Каждый студент приписан к одной школе (принадлежит - belongs to). Необходимо определить отношения моделей следующим образом: + + // В модели school + protected $_has_many = array('students' => array()); + + // В модели student + protected $_belongs_to = array('school' => array()); + +Получаем информацию о школе студента: + + $school = $student->school; + +Ищем всех студентов школы: + + // Учтите, что после students следует вызвать метод find_all + $students = $school->students->find_all(); + + // Чтобы сузить результаты поиска: + $students = $school->students->where('active', '=', TRUE)->find_all(); + +По-умолчанию, ORM будет искать поле `school_id` в таблице модели student. Это можно изменить, используя аттрибут `foreign_key`: + + protected $_belongs_to = array('school' => array('foreign_key' => 'schoolID')); + +Внешний ключ будет перегружен как в модели student, так и в school. + +#### Has-One + +Has-One - это частный случай Has-Many, единственным отличаем которого является то, что в отношении участвует только одна запись. В дополнении к приведённому выше примеру школы, каждая школа будет иметь (has-one) только одного директора, который принадлежит (belongs-to) школе. + + // Inside the school model + protected $_has_one = array('principal' => array()); + +Как и для Belongs-To, Вам не нужно использовать метод `find` для получение объекта, ссылающегося на Has-One объект - это будет сделано автоматически. + +#### Has-Many "через" (through) + +Отношение Has-Many "through" (так же известное как Has-And-Belongs-To-Many) оспользуется в случае если объект связан с несколькими объектами другого типа и наоборот. Например, студент записан на многие занятия и на занятие ходит много студентов. В этом случаеи используется `промежуточная` таблица. Используем для нашего примера промежуточную таблицу и модель - журнал (`enrollment`). + + // В модели student + protected $_has_many = array('classes' => array('through' => 'enrollment')); + + // В модели class + protected $_has_many = array('students' => array('through' => 'enrollment')); + +Таблица enrollment должна содержать 2 внешних ключа: для занятий `class_id` и для студентов `student_id`. Наименование внешних и дальних ключей (`foreign_key` и `far_key`) могут быть переопределены при определении отношений. Например: + + // В модели student (внешний ключ ссылается на модель student, + // в то время, как дальний ключ - на class) + protected $_has_many = array( + 'classes' => array( + 'through' => 'enrollment', + 'foreign_key' => 'studentID', + 'far_key' => 'classID' + )); + + // В модели class + protected $_has_many = array( + 'students' => array( + 'through' => 'enrollment', + 'foreign_key' => 'classID', + 'far_key' => 'studentID' + )); + +Определяем в модели enrollment: + + // Журнал принадлежит как студенту, так и занятию + protected $_belongs_to = array('student' => array(), 'class' => array()); + +Для доступа к связанным объектам: + + // Для получение занятий студента + $student->classes->find_all(); + + // Для получения студентов, записанных на занятие + $class->students->find_all(); + +### Валидация + +ORM тесно взимодействует с [Validate] библиотекой, позволяя использовать возможности этого класса в следующих свойствах: + +* _rules +* _callbacks +* _filters +* _labels + +#### `_rules` + + protected $_rules = array + ( + 'username' => array('not_empty' => array()), + 'email' => array('not_empty' => array(), 'email' => array()), + ); + +`username` будет проверяться на то, что значение этого поля не является пустым. `email` поле будет проверено на соответствие значения валидному email адресу. Ввиду возможности передачи дополнительных опций для правил, значения правил задаются как пустые массивы. + +#### `_callbacks` + + protected $_callbacks = array + ( + 'username' => array('username_unique'), + ); + +Значение поля `username` будет передано методы `username_unique`. Если метод не существует в текущей модели, то будет вызвана глобальная функция. Вот пример описания этого метода: + + public function username_unique(Validate $data, $field) + { + // Логика, проверяющая уникальность имени пользователя + ... + } + +#### `_filters` + + protected $_filters = array + ( + TRUE => array('trim' => array()), + 'username' => array('stripslashes' => array()), + ); + +`TRUE` Указывает на то, что фильтр `trim` будет применён ко всем полям. Значение поля `username` будет отфильтровано с помощью функции `stripslashes` перед процессом валидации. Ввиду возможности передачи дополнительных опций для фильтров, значения фильтра задаются как пустые массивы. + +#### Проверка объекта + +Для проверки объекта, используйте [ORM::check]: + + // Задание значений объекта и дальнейшая их валидация + if ($user->values($_POST)->check()) + { + $user->save(); + } + +Для доступа к объекту валидации данной модели, можно использовать метод `validate()`: + + // Ручное добавление дополнительного фильтра + $user->validate()->filter('username', 'trim'); \ No newline at end of file diff --git a/includes/kohana/modules/userguide/guide/ru-ru/tutorials.removeindex.md b/includes/kohana/modules/userguide/guide/ru-ru/tutorials.removeindex.md new file mode 100644 index 00000000..96789c90 --- /dev/null +++ b/includes/kohana/modules/userguide/guide/ru-ru/tutorials.removeindex.md @@ -0,0 +1,88 @@ +# Удаление из URL `index.php` + +Для чистоты URL, Вам наверняка захочется иметь доступ до разделов Вашего приложения без `/index.php/` в адресной строке. Для этого необходимо выполнить 2 действия. + +1. Откорректировать bootstrap файл +2. Установить возможности rewriting'а на Вашем веб-сервере + +# Конфигурирование Bootstrap + +Первое, что следует сделать - это изменить значение `index_file` в [Kohana::init]: + + Kohana::init(array( + 'base_url' => '/myapp/', + 'index_file' => FALSE, + )); + +Теперь все ссылки, генерируемые методами [URL::site], [URL::base], и [HTML::anchor] не будут использовать "index.php" при построении URL. Все генерируемые ссылки будут начинаться с `/myapp/` вместо `/myapp/index.php/`. + +# URL Rewriting + +В зависимости от Вашего сервера, rewriting активируется по разному. + +## Apache + +Переименуйте `example.htaccess` в `.htaccess` и измените следующую строчку кода: + + RewriteBase /kohana/ + +RewriteBase должен совпадать со значением, указанным у Вас в `base_url` свойстве [Kohana::init]: + + RewriteBase /myapp/ + +В большинстве случаев - это всё, что необходимо сделать. + +### Ошибка! + +Если вдруг Вы стали получать ошибки в виде "Internal Server Error" или "No input file specified", попытайтесь изменить `.htaccess` следующее: + + RewriteRule ^(?:application|modules|system)\b - [F,L] + +Вместо параметра `\b` попробуйте использовать слеш: + + RewriteRule ^(application|modules|system)/ - [F,L] + +Если это не поможет, попробуйте изменить следующее: + + RewriteRule .* index.php/$0 [PT] + +На что-то более простое: + + RewriteRule .* index.php [PT] + +### Всё равно ошибка! + +Если всё ещё получаете ошибки, убедитесь, что Ваш хостинг предоставляет поддержку Apache `mod_rewrite`. Если у Вас есть доступ до изменения настроек Apache, то добавьте следующие строки в конфигурационный файл (зачастую это `httpd.conf`): + +-
+
+
+
+
+
+
-
+
+
+
+
+
+
{{userguide/examples/hello_world_error}}
+
+For some reason Kohana's thrown a wobbly and isn't showing our amazing message.
+
+If we look at the error message we can see that the View library wasn't able to find our site template, probably because we haven't made it yet – *doh*!
+
+Let's go and make the view file `application/views/site.php` for our message:
+
+
+
+ We just wanted to say it! :)
+ + + +If we refresh the page then we can see the fruits of our labour: + + + +## Stage 3 – Profit! + +In this tutorial you've learnt how to create a controller and use a view to separate your logic from your display. + +This is obviously a very basic introduction to working with Kohana and doesn't even scrape the potential you have when developing applications with it. diff --git a/includes/kohana/modules/userguide/guide/tutorials.orm.md b/includes/kohana/modules/userguide/guide/tutorials.orm.md new file mode 100644 index 00000000..3fef93f4 --- /dev/null +++ b/includes/kohana/modules/userguide/guide/tutorials.orm.md @@ -0,0 +1,298 @@ +# ORM {#top} + +Kohana 3.0 includes a powerful ORM module that uses the active record pattern and database introspection to determine a model's column information. + +The ORM module is included with the Kohana 3.0 install but needs to be enabled before you can use it. In your `application/bootstrap.php` file modify the call to [Kohana::modules] and include the ORM module: + + Kohana::modules(array( + ... + 'orm' => MODPATH.'orm', + ... + )); + +## Configuration {#configuration} + +ORM requires little configuration to get started. Extend your model classes with ORM to begin using the module: + + class Model_User extends ORM + { + ... + } + +In the example above, the model will look for a `users` table in the default database. + +### Model Configuration Properties + +The following properties are used to configure each model: + +Type | Option | Description | Default value +----------|---------------------|----------------------------------| ------------------------- +`string` | _table_name | Table name to use | `singular model name` +`string` | _db | Name of the database to use | `default` +`string` | _primary_key | Column to use as primary key | `id` +`string` | _primary_val | Column to use as primary value | `name` +`bool` | _table_names_plural | Whether tables names are plural | `TRUE` +`array` | _sorting | Array of column => direction | `primary key => ASC` +`string` | _foreign_key_suffix | Suffix to use for foreign keys | `_id` + +## Using ORM + +### Loading a Record + +To create an instance of a model, you can use the [ORM::factory] method or the [ORM::__construct]: + + $user = ORM::factory('user'); + // or + $user = new Model_User(); + +The constructor and factory methods also accept a primary key value to load the given model data: + + // Load user ID 5 + $user = ORM::factory('user', 5); + + // See if the user was loaded successfully + if ($user->loaded()) { ... } + +You can optionally pass an array of key => value pairs to load a data object matching the given criteria: + + // Load user with email joe@example.com + $user = ORM::factory('user', array('email' => 'joe@example.com')); + +### Searching for a Record or Records + +ORM supports most of the [Database] methods for powerful searching of your model's data. See the `_db_methods` property for a full list of supported method calls. Records are retrieved using the [ORM::find] and [ORM::find_all] method calls. + + // This will grab the first active user with the name Bob + $user = ORM::factory('user') + ->where('active', '=', TRUE) + ->where('name', '=', 'Bob') + ->find(); + + // This will grab all users with the name Bob + $users = ORM::factory('user') + ->where('name', '=', 'Bob') + ->find_all(); + +When you are retrieving a list of models using [ORM::find_all], you can iterate through them as you do with database results: + + foreach ($users as $user) + { + ... + } + +A powerful feature of ORM is the [ORM::as_array] method which will return the given record as an array. If used with [ORM::find_all], an array of all records will be returned. A good example of when this is useful is for a select list: + + // Display a select field of usernames (using the id as values) + echo Form::select('user', ORM::factory('user')->find_all()->as_array('id', 'username')); + +### Counting Records + +Use [ORM::count_all] to return the number of records for a given query. + + // Number of users + $count = ORM::factory('user')->where('active', '=', TRUE)->count_all(); + +If you wish to count the total number of users for a given query, while only returning a certain subset of these users, call the [ORM::reset] method with `FALSE` before using `count_all`: + + $user = ORM::factory('user'); + + // Total number of users (reset FALSE prevents the query object from being cleared) + $count = $user->where('active', '=', TRUE)->reset(FALSE)->count_all(); + + // Return only the first 10 of these results + $users = $user->limit(10)->find_all(); + +### Accessing Model Properties + +All model properties are accessible using the `__get` and `__set` magic methods. + + $user = ORM::factory('user', 5); + + // Output user name + echo $user->name; + + // Change user name + $user->name = 'Bob'; + +To store information/properties that don't exist in the model's table, you can use the `_ignored_columns` data member. Data will be stored in the internal `_object` member, but ignored at the database level. + + class Model_User extends ORM + { + ... + protected $_ignored_columns = array('field1', 'field2', ...); + ... + } + +Multiple key => value pairs can be set by using the [ORM::values] method. + + $user->values(array('username' => 'Joe', 'password' => 'bob')); + +### Creating and Saving Records + +The [ORM::save] method is used to both create new records and update existing records. + + // Creating a record + $user = ORM::factory('user'); + $user->name = 'New user'; + $user->save(); + + // Updating a record + $user = ORM::factory('user', 5); + $user->name = 'User 2'; + $user->save(); + + // Check to see if the record has been saved + if ($user->saved()) { ... } + +You can update multiple records by using the [ORM::save_all] method: + + $user = ORM::factory('user'); + $user->name = 'Bob'; + + // Change all active records to name 'Bob' + $user->where('active', '=', TRUE)->save_all(); + +#### Using `Updated` and `Created` Columns + +The `_updated_column` and `_created_column` members are provided to automatically be updated when a model is updated and created. These are not used by default. To use them: + + // date_created is the column used for storing the creation date. Use format => TRUE to store a timestamp. + protected $_created_column = array('column' => 'date_created', 'format' => TRUE); + + // date_modified is the column used for storing the modified date. In this case, a string specifying a date() format is used. + protected $_updated_column = array('column' => 'date_modified', 'format' => 'm/d/Y'); + +### Deleting Records + +Records are deleted with [ORM::delete] and [ORM::delete_all]. These methods operate in the same fashion as saving described above with the exception that [ORM::delete] takes one optional parameter, the `id` of the record to delete. Otherwise, the currently loaded record is deleted. + +### Relationships + +ORM provides for powerful relationship support. Ruby has [a great tutorial on relationships](http://api.rubyonrails.org/classes/ActiveRecord/Associations/ClassMethods.html). + +#### Belongs-To and Has-Many + +We'll assume we're working with a school that has many students. Each student can belong to only one school. You would define the relationships in this manner: + + // Inside the school model + protected $_has_many = array('students' => array()); + + // Inside the student model + protected $_belongs_to = array('school' => array()); + +To access a student's school you use: + + $school = $student->school; + +To access a school's students, you would use: + + // Note that find_all is required after students + $students = $school->students->find_all(); + + // To narrow results: + $students = $school->students->where('active', '=', TRUE)->find_all(); + +By default, ORM will look for a `school_id` model in the student table. This can be overriden by using the `foreign_key` attribute: + + protected $_belongs_to = array('school' => array('foreign_key' => 'schoolID')); + +The foreign key should be overridden in both the student and school models. + +#### Has-One + +Has-One is a special case of Has-Many, the only difference being that there is one and only one record. In the above example, each school would have one and only one student (although this is a poor example). + + // Inside the school model + protected $_has_one = array('student' => array()); + +Like Belongs-To, you do not need to use the `find` method when referencing the Has-One related object - it is done automatically. + +#### Has-Many "Through" + +The Has-Many "through" relationship (also known as Has-And-Belongs-To-Many) is used in the case of one object being related to multiple objects of another type, and visa-versa. For instance, a student may have multiple classes and a class may have multiple students. In this case, a third table and model known as a `pivot` is used. In this case, we will call the pivot object/model `enrollment`. + + // Inside the student model + protected $_has_many = array('classes' => array('through' => 'enrollment')); + + // Inside the class model + protected $_has_many = array('students' => array('through' => 'enrollment')); + +The enrollment table should contain two foreign keys, one for `class_id` and the other for `student_id`. These can be overriden using `foreign_key` and `far_key` when defining the relationship. For example: + + // Inside the student model (the foreign key refers to this model [student], while the far key refers to the other model [class]) + protected $_has_many = array('classes' => array('through' => 'enrollment', 'foreign_key' => 'studentID', 'far_key' => 'classID')); + + // Inside the class model + protected $_has_many = array('students' => array('through' => 'enrollment', 'foreign_key' => 'classID', 'far_key' => 'studentID')); + +The enrollment model should be defined as such: + + // Enrollment model belongs to both a student and a class + protected $_belongs_to = array('student' => array(), 'class' => array()); + +To access the related objects, use: + + // To access classes from a student + $student->classes->find_all(); + + // To access students from a class + $class->students->find_all(); + +### Validation + +ORM is integrated tightly with the [Validate] library. The ORM provides the following members for validation: + +* _rules +* _callbacks +* _filters +* _labels + +#### `_rules` + + protected $_rules = array + ( + 'username' => array('not_empty' => array()), + 'email' => array('not_empty' => array(), 'email' => array()), + ); + +`username` will be checked to make sure it's not empty. `email` will be checked to also ensure it is a valid email address. The empty arrays passed as values can be used to provide optional additional parameters to these validate method calls. + +#### `_callbacks` + + protected $_callbacks = array + ( + 'username' => array('username_unique'), + ); + +`username` will be passed to a callback method `username_unique`. If the method exists in the current model, it will be used, otherwise a global function will be called. Here is an example of the definition of this method: + + public function username_unique(Validate $data, $field) + { + // Logic to make sure a username is unique + ... + } + +#### `_filters` + + protected $_filters = array + ( + TRUE => array('trim' => array()), + 'username' => array('stripslashes' => array()), + ); + +`TRUE` indicates that the `trim` filter is to be used on all fields. `username` will be filtered through `stripslashes` before it is validated. The empty arrays passed as values can be used to provide additional parameters to these filter method calls. + +#### Checking if the Object is Valid + +Use [ORM::check] to see if the object is currently valid. + + // Setting an object's values, then checking to see if it's valid + if ($user->values($_POST)->check()) + { + $user->save(); + } + +You can use the `validate()` method to access the model's validation object. + + // Add an additional filter manually + $user->validate()->filter('username', 'trim'); diff --git a/includes/kohana/modules/userguide/guide/tutorials.removeindex.md b/includes/kohana/modules/userguide/guide/tutorials.removeindex.md new file mode 100644 index 00000000..9c88f0a2 --- /dev/null +++ b/includes/kohana/modules/userguide/guide/tutorials.removeindex.md @@ -0,0 +1,88 @@ +# Removing `index.php` From the URL + +To keep your URLs clean, you will probably want to be able to access your app without having `/index.php/` in the URL. There are two steps to remove `index.php` from the URL. + +1. Edit the bootstrap file +2. Set up rewriting + +# Configure Bootstrap + +The first thing you will need to change is the `index_file` setting of [Kohana::init]: + + Kohana::init(array( + 'base_url' => '/myapp/', + 'index_file' => FALSE, + )); + +Now all of the links generated using [URL::site], [URL::base], and [HTML::anchor] will no longer include "index.php" in the URL. All generated links will start with `/myapp/` instead of `/myapp/index.php/`. + +# URL Rewriting + +Enabling rewriting is done differently, depending on your web server. + +## Apache + +Rename `example.htaccess` to only `.htaccess` and alter the following line of code: + + RewriteBase /kohana/ + +This needs to match the `base_url` setting of [Kohana::init]: + + RewriteBase /myapp/ + +In most cases, this is all you will need to change. + +### Failed! + +If you get a "Internal Server Error" or "No input file specified" error, try changing: + + RewriteRule ^(?:application|modules|system)\b - [F,L] + +Instead, we can try a slash: + + RewriteRule ^(application|modules|system)/ - [F,L] + +If that doesn't work, try changing: + + RewriteRule .* index.php/$0 [PT] + +To something more simple: + + RewriteRule .* index.php [PT] + +### Still Failed! + +If you are still getting errors, check to make sure that your host supports URL `mod_rewrite`. If you can change the Apache configuration, add these lines to the the configuration, usually `httpd.conf`: + +{{userguide/examples/error}}
+
+## 显示错误/异常句柄
+
+如果您不希望使用内部错误句柄，您可以调用 [Kohana::init] 时禁用它:
+
+ Kohana::init(array('errors' => FALSE));
diff --git a/includes/kohana/modules/userguide/guide/zh-cn/debugging.profiling.md b/includes/kohana/modules/userguide/guide/zh-cn/debugging.profiling.md
new file mode 100644
index 00000000..95ebe61a
--- /dev/null
+++ b/includes/kohana/modules/userguide/guide/zh-cn/debugging.profiling.md
@@ -0,0 +1,20 @@
+# 分析器
+
+Kohana 提供一种非常简单的方法来显示你的程序的统计信息
+
+1. 普通 [Kohana] 方法调用
+2. 请求
+3. [Database] 查询
+4. 程序的平均运行时间
+
+## 实例
+
+你可以在任何时候显示或收集当前 [profiler] 统计:
+
+
+
+
+
+## 预览
+
+{{profiler/stats}}
\ No newline at end of file
diff --git a/includes/kohana/modules/userguide/guide/zh-cn/features.md b/includes/kohana/modules/userguide/guide/zh-cn/features.md
new file mode 100644
index 00000000..4f7e05e5
--- /dev/null
+++ b/includes/kohana/modules/userguide/guide/zh-cn/features.md
@@ -0,0 +1 @@
+本页面将会列举 Kohana v3 的特性。
\ No newline at end of file
diff --git a/includes/kohana/modules/userguide/guide/zh-cn/menu.md b/includes/kohana/modules/userguide/guide/zh-cn/menu.md
new file mode 100644
index 00000000..7de47433
--- /dev/null
+++ b/includes/kohana/modules/userguide/guide/zh-cn/menu.md
@@ -0,0 +1,31 @@
+1. **入门指南**
+ - [什么是 Kohana?](about.kohana)
+ - [约定和样式](about.conventions)
+ - [模型-视图-控制器](about.mvc)
+ - [级联文件系统](about.filesystem)
+ - [请求流程](about.flow)
+ - [安装](about.install)
+ - [升级](about.upgrading)
+ - [API 浏览器](api)
+3. **基本使用**
+ - [配置](using.configuration)
+ - [类的加载](using.autoloading)
+ - [视图和 HTML](using.views)
+ - [Sessions 和 Cookies](using.sessions)
+ - [消息](using.messages)
+6. **调试**
+ - [代码](debugging.code)
+ - [错误句柄](debugging.errors)
+ - [分析器](debugging.profiling)
+5. **安全**
+ - [XSS](security.xss)
+ - [校验](security.validation)
+ - [Cookies](security.cookies)
+ - [数据库](security.database)
+4. **教程**
+ - [Hello, World](tutorials.helloworld)
+ - [路由，URLs 和链接](tutorials.urls)
+ - [清理 URLs](tutorials.removeindex)
+ - [数据库](tutorials.databases)
+ - [ORM](tutorials.orm)
+ - [使用 Git 开发](tutorials.git)
diff --git a/includes/kohana/modules/userguide/guide/zh-cn/security.validation.md b/includes/kohana/modules/userguide/guide/zh-cn/security.validation.md
new file mode 100644
index 00000000..796e956d
--- /dev/null
+++ b/includes/kohana/modules/userguide/guide/zh-cn/security.validation.md
@@ -0,0 +1,244 @@
+# 效验
+
+使用 [Validate] 类可以对任意的数组进行校验。标签，过滤器，规则和回调函数都以数组的键（称之为 "字段名"）附属于 Validate 对象。
+
+标签(labels)
+: 标签是人们可读取的字段名。
+
+过滤器(filters)
+: 过滤器必须在规则和回调函数之前调用执行做预处理。
+
+规则(rules)
+: 规则是用于检测字段并返回结果 `TRUE` 或 `FALSE`。
+ 如果返回 `FALSE`，其对于的错误会添加到字段中。
+
+回调函数(callbacks)
+: 回调函数是自定义函数，它可以访问整个校验对象。
+ 回调函数的返回值会被忽略，因此，当校验错误时回调函数必须手动的使用 [Validate::error] 添加错误到对象中。
+
+[!!] 注意 [Validate] 的 callbacks 和 [PHP callbacks](http://php.net/manual/language.pseudo-types.php#language.types.callback) 是完全不同的两个方法。
+
+如果想把添加的过滤器，规则或回调函数应用到所有的定义的字段需要设置字段名为 `TRUE` 。
+
+**[Validate] 对象会移除所有未设置标签，过滤器，规则或回调函数的字段。以此防止未被验证的字段发生校验错误。**
+
+使用 [Validate::factory] 方法创建校验对象:
+
+ $post = Validate::factory($_POST);
+
+[!!] 提示 `$post` 对象将会被用于本教程的其他实例中。
+
+### 默认规则
+
+校验默认提供的规则:
+
+规则名称 | 函数
+------------------------- |-------------------------------------------------
+[Validate::not_empty] | 值不能为空值
+[Validate::regex] | 值使用正则表达式匹配
+[Validate::min_length] | 值的最小长度
+[Validate::max_length] | 值的最大长度
+[Validate::exact_length] | 值的长度必须是这里指定的长度
+[Validate::email] | 值必须是 Email 地址
+[Validate::email_domain] | 检查 Email 的域是否存在
+[Validate::url] | 值必须是 URL
+[Validate::ip] | 值必须是 IP 地址
+[Validate::phone] | 值必须是电话号码
+[Validate::credit_card] | 值必须是信用卡号
+[Validate::date] | 值必须是日期(时间)
+[Validate::alpha] | 仅允许英文字母
+[Validate::alpha_dash] | 仅允许英文字母和连词符号(-)
+[Validate::alpha_numeric] | 仅允许英文字母和数字
+[Validate::digit] | 仅允许整数
+[Validate::decimal] | 值必须是小数或浮点数
+[Validate::numeric] | 仅允许数字
+[Validate::range] | 值必须是某一范围内的值
+[Validate::color] | 值必须是有效的 HEX 颜色
+[Validate::matches] | 值必须匹配其他字段的值
+
+[!!] 任何存在于 [Validate] 类中的方法都可以在不指定完整回调的情况下用于校验规则。
+比如，添加 `'not_empty'` 和 `array('Validate', 'not_empty')` 是等同的。
+
+## 添加过滤器
+
+所有的校验规则被定义为字段名，方法或函数(使用 [PHP callback](http://php.net/callback) 语法)以及数组形式的参数:
+
+ $object->filter($field, $callback, $parameter);
+
+过滤器修改字段值之前请仔细检查规则或回调函数。
+
+如果要转换 "username" 字段的值为全小写:
+
+ $post->filter('username', 'strtolower');
+
+如果要对所有字段移除左右*所有*空格:
+
+ $post->filter(TRUE, 'trim');
+
+## 添加规则
+
+所有的校验规则被定义为字段名，方法或函数(使用 [PHP callback](http://php.net/callback) 语法)以及数组形式的参数:
+
+ $object->rule($field, $callback, $parameter);
+
+### 实例
+
+任何函数添加到 `Validate` 类都可以通过调用一个规则而不必指定 `Validate` 类:
+
+ $post
+ ->rule('username', 'not_empty')
+ ->rule('username', 'regex', array('/^[a-z_.]++$/iD'))
+
+ ->rule('password', 'not_empty')
+ ->rule('password', 'min_length', array('6'))
+ ->rule('confirm', 'matches', array('password'))
+
+ ->rule('use_ssl', 'not_empty');
+
+任何 PHP 可用的函数也可以当作规则。比如，如果我们要检测用户是否使用 SSL:
+
+ $post->rule('use_ssl', 'in_array', array(array('yes', 'no')));
+
+[!!] 注意：所有的参数类数组都必须在一个数组内！
+
+所有其他自定义的规则也可以作为回调函数添加进来:
+
+ $post->rule('username', array($model, 'unique_username'));
+
+回调方法 `$model->unique_username()` 的代码如下：
+
+ public function unique_username($username)
+ {
+ // 检测用户名是否存在于数据库
+ return ! DB::select(array(DB::expr('COUNT(username)'), 'total'))
+ ->from('users')
+ ->where('username', '=', $username)
+ ->execute()
+ ->get('total');
+ }
+
+[!!] 自定义规则可以设置许多额外的检测以可用于多种用途。这些方法运行存在于一个模型(model)中，或者是定义在任意一个类中。
+
+## 添加回调函数
+
+所有的校验规则被定义为字段名，方法或函数(使用 [PHP callback](http://php.net/callback) 语法)以及数组形式的参数:
+
+ $object->callback($field, $callback);
+
+[!!] 不同的过滤器和规则，没有参数也可以传递到回调函数之中。
+
+如果用户的密码必须是哈希值，我们可以使用回调函数哈希其值：
+
+ $post->callback('password', array($model, 'hash_password'));
+
+假设 `$model->hash_password()` 方法是类似这样定义的：
+
+ public function hash_password(Validate $array, $field)
+ {
+ if ($array[$field])
+ {
+ // 如果存在此字段进行哈希操作
+ $array[$field] = sha1($array[$field]);
+ }
+ }
+
+# 一个完整的例子
+
+首先，我们使用 [View] 创建一个 HTML 表单。假设文件存放于 `application/views/user/register.php`:
+
+
+
+
+ -
+
+
+
+
+
+
-
+
+
+
+
+
+
{{userguide/examples/hello_world_error}}
+
+出于某种原因 Kohana 会抛出一个不稳定的而没有正常显示我们期望的信息。
+
+如果我们仔细查看错误信息，我们可以发现 View 库无法找到我们设定的模板文件，这可能是我们还没有创建它 – *doh*！（译注：doh 表达当发现事情朝坏的、不随人意的方向发展或某人说了傻话、做了蠢事时的情绪低落）
+
+马上开始创建视图文件 `application/views/site.php`:
+
+
+
+ We just wanted to say it! :)
+ + + +再次刷新刚才的错误页面，怎么样看到正确的结果了吧: + + + +## 第三阶段 – 成果！ + +在本教程中你已经学会如何创建和使用控制器，以及使用视图分离逻辑来显示视图。 + +这绝对是一个非常基本教程来介绍如何使用 Kohana 工作，且它根本就不会影响你的潜力使用它来开发应用。 diff --git a/includes/kohana/modules/userguide/guide/zh-cn/tutorials.orm.md b/includes/kohana/modules/userguide/guide/zh-cn/tutorials.orm.md new file mode 100644 index 00000000..2c418dcb --- /dev/null +++ b/includes/kohana/modules/userguide/guide/zh-cn/tutorials.orm.md @@ -0,0 +1,299 @@ +# ORM {#top} + +Kohana 3.0 包含一个强劲的 ORM 扩展，作用于记录模式，数据库内省来确定模型的列表。 + +ORM 扩展默认包含在 Kohana 3.0 之中，但是如要使用它则需要先开启它。修改 `application/bootstrap.php` 文件中的 [Kohana::modules] 方法并加载 ORM 扩展： + + Kohana::modules(array( + ... + 'orm' => MODPATH.'orm', + ... + )); + +## 配置 {#configuration} + +通过一些配置 ORM 才能工作。通过在模型类继承 ORM： + + class Model_User extends ORM + { + ... + } + +上面的例子中，模型会寻找默认数据库的 `users` 表。 + +### 模型配置属性 + +下面的属性是用于配置每个模型的： + +类型 | 属性 | 描述 | 默认值 +----------|---------------------|----------------------------------| ------------------------- +`string` | _table_name | 表名 | `singular model name` +`string` | _db | 数据库配置名 | `default` +`string` | _primary_key | 主键 | `id` +`string` | _primary_val | 主键值 | `name` +`bool` | _table_names_plural | 表名是否是复数形式 | `TRUE` +`array` | _sorting | 列名 => 排序方向的数组 | `primary key => ASC` +`string` | _foreign_key_suffix | 外键的后缀 | `_id` + +## 使用 ORM + +### 加载一条记录 + +通过调用 [ORM::factory] 或 [ORM::__construct] 方法创建模型的实例化： + + $user = ORM::factory('user'); + // 或者 + $user = new Model_User(); + +构造函数和 factory 方法也接受一个主键值来加载模型数据： + + // 加载 ID 为 5 的用户 + $user = ORM::factory('user', 5); + + // 检查用户是否加载成功 + if ($user->loaded()) { ... } + +你同样可以使用传递键-值型数组的数据对象去加载记录: + + // 加载 email 为 oe@example.com 的用 + $user = ORM::factory('user', array('email' => 'joe@example.com')); + +### 搜索记录 + +ORM 支持大多数的 [Database] 方法来强劲驱动搜索模型中的数据。ORM 类的 `_db_methods` 属性列出了所有支持调用的方法列表。记录的搜索可以通过 [ORM::find] 和 [ORM::find_all] 方法调用获得。 + + // 搜索活跃用户中名为 Bob 的第一条记录 + $user = ORM::factory('user') + ->where('active', '=', TRUE) + ->where('name', '=', 'Bob') + ->find(); + + // 搜索名为 Bob 的所有用户 + $users = ORM::factory('user') + ... + ->find_all(); + +当你使用 [ORM::find_all] 搜索一批记录模型，你可以使用迭代从数据库结果中获取每条记录模型： + + foreach ($users as $user) + { + ... + } + +ORM 一个强大的特性是 [ORM::as_array] 方法，它把返回的记录集转为为一个数组。如果使用了 [ORM::find_all] 所有的记录都会以数组的形式返回。 +对于选择列的时候是非常好用的: + + // 显示选择列的用户名 (使用 id 作为其值) + form::select('user', ORM::factory('user')->find_all()->as_array('id', 'username') ... + +### 记录数 + +使用 [ORM::count_all] 方法返回查询返回记录集的记录数。 + + // 用户的记录数 + $count = ORM::factory('user')->where('active', '=', TRUE)->count_all(); + +如果你想在特定子集的查询语句中统计所有用户的记录数，在调用 `count_all` 方法之前先调用 [ORM::reset] 方法并赋值 `FALSE`: + + $user = ORM::factory('user'); + + // 用户的总数 (reset FALSE prevents the query object from being cleared) + $count = $user->where('active', '=', TRUE)->reset(FALSE)->count_all(); + + // 仅返回前 10 条记录的记录数 + $users = $user->limit(10)->find_all(); + +### 取出模型属性 + +所有的模型属性都可以通过 PHP 的魔法方法 `__get` 和 `__set` 得到读写权。 + + $user = ORM::factory('user', 5); + + // 输出用户名 + echo $user->name; + + // 更改用户名 + $user->name = 'Bob'; + +假如保存的信息/属性并不存在于模型表中，使用 `_ignored_columns` 来忽略数据成员。 + + class Model_User extends ORM + { + ... + protected $_ignored_columns = array('field1', 'field2', ...) + ... + } + +使用 [ORM::values] 方法设置键-值型数组: + + $user->values(array('username' => 'Joe', 'password' => 'bob')); + +### 创建并存储记录 + +[ORM::save] 方法既可以用于创建新记录也可作用于更新现有记录。 + + // 创建新记录 + $user = ORM::factory('user'); + $user->name = 'New user'; + $user->save(); + + // 更新现有记录 + $user = ORM::factory('user', 5); + $user->name = 'User 2'; + $user->save(); + + // 检查记录是否保存成功 + if ($user->saved()) { ... } + +你也可以使用 [ORM::save_all] 方法来更新多条记录： + + $user = ORM::factory('user'); + $user->name = 'Bob'; + + // 更新所有结果记录的名字为 'Bob' + $user->where('active', '=', TRUE)->save_all(); + +#### 使用 `Updated` 和 `Created` 列 + +`_updated_column` 和 `_created_column` 变量是用于当模型更新或插入新纪录的时候自动更新设置的字段值。默认没有使用。如果你想使用: + + // date_created 列用于储存创建的时间，使用 TRUE 保存的是时间戳(timestamp) + protected $_created_column = array('date_created' => TRUE); + + // date_modified 列用于储存最后修改时间。这里的时间设置为使用 date() 格式后的字符串 + protected $_updated_column = array('date_modified' => 'm/d/Y'); + +### 删除记录 + +删除记录可以使用 [ORM::delete] 和 [ORM::delet_all] 方法。这两个方法的使用和上面 存储记录 方法类似，但有一点不同的是 [ORM::delete] 方法带有一个删除记录 'id' 的可选参数。 + +### 关系 + +ORM 提供强大的关系模型。Ruby 有一篇介绍关系模型的文章: [http://api.rubyonrails.org/classes/ActiveRecord/Associations/ClassMethods.html](http://api.rubyonrails.org/classes/ActiveRecord/Associations/ClassMethods.html) + +#### Belongs-To 和 Has-Many + +假设我们在一所学校工作，当然学校有很多学生，而每个学生都只属于一个学校。这样的关系模型可以这样定义: + + // school 模型文件 + protected $_has_many = array('students' => array()); + + // student 模型文件 + protected $_belongs_to = array('school' => array()); + +获取学生的学校: + + $school = $student->school; + +获取学校的学生: + + // 注意在 studends 后必须调用 find_all 方法 + $students = $school->students->find_all(); + + // 缩小范围查询: + $students = $school->students->where('active', '=', TRUE)->find_all(); + +默认情况下，在 student 表定义的模型文件中 ORM 会寻找 `school_id` 当作外键。这个可以通过 `foreign_key` 属性更改: + + protected $_belongs_to = array('school' => array('foreign_key' => 'schoolID')); + +外键应该同时覆写 student 和 school 模型文件。 + +#### Has-One + +Has-One 是 Has-Many 的一个特别情况，唯一不同的这是一对一关系。还以上面的例子说明就是，每个学校有且只有一个学生（当然这是一个很牵强呃例子）。 + + // school 模型文件 + protected $_has_one = array('student' => array()); + +类似于 Belongs-To，当你引用 Has-One 关系对象的时候无需调用 `find` 方法 - 它是自动完成的。 + +#### Has-Many "Through" + +Has-Many "through" 关系(也可以称之为 Has-And-Belongs-To-Many) is used in the case of one object being related to multiple objects of another type, and visa-versa. For instance, a student may have multiple classes and a class may have multiple students. In this case, a third table and model known as a `pivot` is used. In this case, we will call the pivot object/model `enrollment`. + + // student (学生)模型文件 + protected $_has_many = array('classes' => array('through' => 'enrollment')); + + // class (班级)模型文件 + protected $_has_many = array('students' => array('through' => 'enrollment')); + +其中 enrollment 表包含两个外键: `class_id` 和 `student_id`。在定义关系时，使用 `foreign_key` 和 `far_key` 覆写了默认值。例如: + + // student (学生)模型文件() (the foreign key refers to this model [student], while the far key refers to the other model [class]) + protected $_has_many = array('classes' => array('through' => 'enrollment', 'foreign_key' => 'studentID', 'far_key' => 'classID')); + + // class (班级)模型文件 + protected $_has_many = array('students' => array('through' => 'enrollment', 'foreign_key' => 'classID', 'far_key' => 'studentID')); + +enrollment 模型文件应该这样定义: + + // Enrollment 模型同时属于一个 student 和 class + protected $_belongs_to = array('student' => array(), 'class' => array()); + +获取相关对象: + + // 从 student 中获取 classes + $student->classes->find_all(); + + // 从 class 中获取 students + $class->students->find_all(); + +### 校验 + +ORM 和 [Validate] 类是紧密结合使用的。ORM 提供以下几种校验方式: + +* _rules +* _callbacks +* _filters +* _labels + +#### `_rules` + + protected $_rules = array + ( + 'username' => array('not_empty' => array()), + 'email' => array('not_empty' => array(), 'email' => array()), + ); + +检测并确保 `username` 字段不为空。检测 `email` 字段不为空且是有效的 Email 地址格式。那些传递空值数组用于提供可选的额外参数到校验方法中使用。 + +#### `_callbacks` + + protected $_callbacks = array + ( + 'username' => array('username_unique'), + ); + +`username` 字段被传递到了 `username_unique` 回调函数。如果方法存在于当前模型它就会被调用，否则调用全局函数。下面有个小例子: + + public function username_unique(Validate $data, $field) + { + // 确保 username 是唯一的 + ... + } + +#### `_filters` + + protected $_filters = array + ( + TRUE => array('trim' => array()), + 'username' => array('stripslashes' => array()), + ); + +`TRUE` 值代表 `trim` 过滤器应用到所有字段。而 `username` 字段则在校验前使用 `stripslashes` 过滤。那些传递空值数组用于提供可选的额外参数到校验方法中使用。 + +#### 检测对象是否通过校验 + +使用 [ORM::check] 检测当前对象是否通过校验: + + // 设置完对象的值，接下来检测是否通过校验 + if ($user->values($_POST)->check()) + { + $user->save(); + } + +你也可是使用 `validate()` 方法直接访问模型的校验对象: + + // 手动添加额外的过滤器 + $user->validate()->filter('username', 'trim'); \ No newline at end of file diff --git a/includes/kohana/modules/userguide/guide/zh-cn/tutorials.removeindex.md b/includes/kohana/modules/userguide/guide/zh-cn/tutorials.removeindex.md new file mode 100644 index 00000000..b38119f5 --- /dev/null +++ b/includes/kohana/modules/userguide/guide/zh-cn/tutorials.removeindex.md @@ -0,0 +1,89 @@ +# 从 URL 移除 `index.php` + +为了保持 URLs 的干净，你可能希望 URL 在访问的时候不包含 `/index.php/`。下面有两步可以实现: + +1. 编辑 bootstrap 文件 +2. 设置重写规则 + +# 配置 Bootstrap + +首先你需要在 [Kohana::init] 方法中更改 `index_file` 设置: + + Kohana::init(array( + 'base_url' => '/myapp/', + 'index_file' => FALSE, + )); + +现在所有使用 [URL::site]，[URL::base] 和 [HTML::anchor] 生成的 URL均不会包含 "index.php" 了。 + +# URL 重写 + +开启重写配置的方法根据服务器的不同而不同，下面仅供参考: + +## Apache + +改名 `example.htaccess` 为 `.htaccess` 后修改下面的参数代码: + + RewriteBase /kohana/ + +这里需要和 [Kohana::init] 方法中的 `base_url` 选项匹配: + + RewriteBase /myapp/ + +完成了，就这点事！ + +### 失败了! + +如果提示 "Internal Server Error" 或 "No input file specified" 错误，请尝试下面的修改: + + RewriteRule ^(?:application|modules|system)\b - [F,L] + +相反，我们可以尝试反斜杠: + + RewriteRule ^(application|modules|system)/ - [F,L] + +如果这样还不工作，再试着修改: + + RewriteRule .* index.php/$0 [PT] + +再简单点: + + RewriteRule .* index.php [PT] + +### 仍然失败! + +如果还是提示失败的话，请确保你的服务器支持 URL 的 `mod_rewrite`。 +加入你可以修改 Apache 的配置，你可以复制下面的配置到 `httpd.conf`: + +","
"];c.fn.extend({text:function(a){if(c.isFunction(a))return this.each(function(b){var d=
+c(this);d.text(a.call(this,b,d.text()))});if(typeof a!=="object"&&a!==w)return this.empty().append((this[0]&&this[0].ownerDocument||s).createTextNode(a));return c.text(this)},wrapAll:function(a){if(c.isFunction(a))return this.each(function(d){c(this).wrapAll(a.call(this,d))});if(this[0]){var b=c(a,this[0].ownerDocument).eq(0).clone(true);this[0].parentNode&&b.insertBefore(this[0]);b.map(function(){for(var d=this;d.firstChild&&d.firstChild.nodeType===1;)d=d.firstChild;return d}).append(this)}return this},
+wrapInner:function(a){if(c.isFunction(a))return this.each(function(b){c(this).wrapInner(a.call(this,b))});return this.each(function(){var b=c(this),d=b.contents();d.length?d.wrapAll(a):b.append(a)})},wrap:function(a){return this.each(function(){c(this).wrapAll(a)})},unwrap:function(){return this.parent().each(function(){c.nodeName(this,"body")||c(this).replaceWith(this.childNodes)}).end()},append:function(){return this.domManip(arguments,true,function(a){this.nodeType===1&&this.appendChild(a)})},
+prepend:function(){return this.domManip(arguments,true,function(a){this.nodeType===1&&this.insertBefore(a,this.firstChild)})},before:function(){if(this[0]&&this[0].parentNode)return this.domManip(arguments,false,function(b){this.parentNode.insertBefore(b,this)});else if(arguments.length){var a=c(arguments[0]);a.push.apply(a,this.toArray());return this.pushStack(a,"before",arguments)}},after:function(){if(this[0]&&this[0].parentNode)return this.domManip(arguments,false,function(b){this.parentNode.insertBefore(b,
+this.nextSibling)});else if(arguments.length){var a=this.pushStack(this,"after",arguments);a.push.apply(a,c(arguments[0]).toArray());return a}},remove:function(a,b){for(var d=0,f;(f=this[d])!=null;d++)if(!a||c.filter(a,[f]).length){if(!b&&f.nodeType===1){c.cleanData(f.getElementsByTagName("*"));c.cleanData([f])}f.parentNode&&f.parentNode.removeChild(f)}return this},empty:function(){for(var a=0,b;(b=this[a])!=null;a++)for(b.nodeType===1&&c.cleanData(b.getElementsByTagName("*"));b.firstChild;)b.removeChild(b.firstChild);
+return this},clone:function(a){var b=this.map(function(){if(!c.support.noCloneEvent&&!c.isXMLDoc(this)){var d=this.outerHTML,f=this.ownerDocument;if(!d){d=f.createElement("div");d.appendChild(this.cloneNode(true));d=d.innerHTML}return c.clean([d.replace(Ja,"").replace(/=([^="'>\s]+\/)>/g,'="$1">').replace(V,"")],f)[0]}else return this.cloneNode(true)});if(a===true){ra(this,b);ra(this.find("*"),b.find("*"))}return b},html:function(a){if(a===w)return this[0]&&this[0].nodeType===1?this[0].innerHTML.replace(Ja,
+""):null;else if(typeof a==="string"&&!ta.test(a)&&(c.support.leadingWhitespace||!V.test(a))&&!F[(La.exec(a)||["",""])[1].toLowerCase()]){a=a.replace(Ka,Ma);try{for(var b=0,d=this.length;b