Permalink
Browse files

Merging in 3.0.x branch

  • Loading branch information...
1 parent c5471e3 commit 928c6ff96556c1d550f89d528afc3b8cc7f7a6a8 @isaiahdw isaiahdw committed Dec 31, 2010
Showing with 3,724 additions and 78 deletions.
  1. +6 −2 classes/kohana/config.php
  2. +6 −2 classes/kohana/config/file.php
  3. +3 −1 classes/kohana/config/reader.php
  4. +2 −2 classes/kohana/controller.php
  5. +6 −0 classes/kohana/controller/rest.php
  6. +1 −1 classes/kohana/controller/template.php
  7. +86 −47 classes/kohana/core.php
  8. +4 −2 classes/kohana/encrypt.php
  9. +3 −1 classes/kohana/fragment.php
  10. +6 −0 classes/kohana/html.php
  11. +3 −1 classes/kohana/i18n.php
  12. +10 −2 classes/kohana/inflector.php
  13. +9 −5 classes/kohana/log.php
  14. +3 −1 classes/kohana/log/file.php
  15. +3 −1 classes/kohana/log/syslog.php
  16. +3 −1 classes/kohana/profiler.php
  17. +18 −6 classes/kohana/session.php
  18. +13 −0 classes/kohana/session/cookie.php
  19. +16 −0 classes/kohana/session/native.php
  20. +2 −2 classes/kohana/utf8.php
  21. +23 −0 config/userguide.php
  22. +69 −0 guide/kohana/autoloading.md
  23. +164 −0 guide/kohana/bootstrap.md
  24. +1 −0 guide/kohana/controllers.md
  25. +306 −0 guide/kohana/conventions.md
  26. +89 −0 guide/kohana/cookies.md
  27. +20 −0 guide/kohana/debugging.md
  28. +85 −0 guide/kohana/errors.md
  29. +101 −0 guide/kohana/extension.md
  30. +83 −0 guide/kohana/files.md
  31. +41 −0 guide/kohana/files/classes.md
  32. +95 −0 guide/kohana/files/config.md
  33. +1 −0 guide/kohana/files/i18n.md
  34. +5 −0 guide/kohana/files/messages.md
  35. +26 −0 guide/kohana/flow.md
  36. +135 −0 guide/kohana/fragments.md
  37. +53 −0 guide/kohana/helpers.md
  38. +19 −0 guide/kohana/index.md
  39. +33 −0 guide/kohana/install.md
  40. +48 −0 guide/kohana/menu.md
  41. +1 −0 guide/kohana/models.md
  42. +38 −0 guide/kohana/modules.md
  43. +3 −0 guide/kohana/mvc.md
  44. +189 −0 guide/kohana/mvc/controllers.md
  45. +1 −0 guide/kohana/mvc/models.md
  46. +161 −0 guide/kohana/mvc/views.md
  47. +54 −0 guide/kohana/profiling.md
  48. +15 −0 guide/kohana/requests.md
  49. +240 −0 guide/kohana/routing.md
  50. +1 −0 guide/kohana/security.md
  51. +3 −0 guide/kohana/security/cookies.md
  52. +5 −0 guide/kohana/security/database.md
  53. +81 −0 guide/kohana/security/deploying.md
  54. +1 −0 guide/kohana/security/encryption.md
  55. +247 −0 guide/kohana/security/validation.md
  56. +17 −0 guide/kohana/security/xss.md
  57. +167 −0 guide/kohana/sessions.md
  58. +33 −0 guide/kohana/tips.md
  59. +17 −0 guide/kohana/tutorials.md
  60. +80 −0 guide/kohana/tutorials/clean-urls.md
  61. +168 −0 guide/kohana/tutorials/error-pages.md
  62. +129 −0 guide/kohana/tutorials/git.md
  63. +106 −0 guide/kohana/tutorials/hello-world.md
  64. +3 −0 guide/kohana/tutorials/routes-and-links.md
  65. +54 −0 guide/kohana/tutorials/sharing-kohana.md
  66. +1 −0 guide/kohana/tutorials/simple-mvc.md
  67. +7 −0 guide/kohana/tutorials/templates.md
  68. +5 −0 guide/kohana/tutorials/translation.md
  69. +292 −0 guide/kohana/upgrading.md
  70. BIN media/guide/kohana/cascading_filesystem.png
  71. BIN media/guide/kohana/hello_world_1.png
  72. BIN media/guide/kohana/hello_world_2.png
  73. BIN media/guide/kohana/hello_world_2_error.png
  74. BIN media/guide/kohana/install.png
  75. BIN media/guide/kohana/welcome.png
  76. +5 −1 tests/kohana/HTMLTest.php
@@ -11,7 +11,9 @@
*/
class Kohana_Config {
- // Singleton static instance
+ /**
+ * @var Kohana_Config Singleton static instance
+ */
protected static $_instance;
/**
@@ -32,7 +34,9 @@ public static function instance()
return Config::$_instance;
}
- // Configuration readers
+ /**
+ * @var array Configuration readers
+ */
protected $_readers = array();
/**
@@ -11,10 +11,14 @@
*/
class Kohana_Config_File extends Config_Reader {
- // Configuration group name
+ /**
+ * @var string Configuration group name
+ */
protected $_configuration_group;
- // Has the config group changed?
+ /**
+ * @var bool Has the config group changed?
+ */
protected $_configuration_modified = FALSE;
public function __construct($directory = 'config')
@@ -11,7 +11,9 @@
*/
abstract class Kohana_Config_Reader extends ArrayObject {
- // Configuration group name
+ /**
+ * @var string Configuration group name
+ */
protected $_configuration_group;
/**
@@ -23,7 +23,7 @@
abstract class Kohana_Controller {
/**
- * @var object Request that created the controller
+ * @var Request Request that created the controller
*/
public $request;
@@ -36,7 +36,7 @@
* Creates a new controller instance. Each controller must be constructed
* with the request object that created it.
*
- * @param object Request that created the controller
+ * @param Request Request that created the controller
* @return void
*/
public function __construct(Kohana_Request $request, Kohana_Response $response)
@@ -30,6 +30,9 @@
*/
abstract class Kohana_Controller_REST extends Controller {
+ /**
+ * @var array REST types
+ */
protected $_action_map = array
(
Http_Request::GET => 'index',
@@ -38,6 +41,9 @@
Http_Request::DELETE => 'delete',
);
+ /**
+ * @var string requested action
+ */
protected $_action_requested = '';
/**
@@ -11,7 +11,7 @@
abstract class Kohana_Controller_Template extends Controller {
/**
- * @var string page template
+ * @var View page template
*/
public $template = 'template';
View
@@ -32,32 +32,32 @@ class Kohana_Core {
const FILE_CACHE = ":header \n\n// :name\n\n:data\n";
/**
- * @var string current environment name
+ * @var string Current environment name
*/
public static $environment = Kohana::DEVELOPMENT;
/**
- * @var boolean command line environment?
+ * @var boolean True if Kohana is running from the command line
*/
public static $is_cli = FALSE;
/**
- * @var boolean Windows environment?
+ * @var boolean True if Kohana is running on windows
*/
public static $is_windows = FALSE;
/**
- * @var boolean magic quotes enabled?
+ * @var boolean True if [magic quotes](http://php.net/manual/en/security.magicquotes.php) is enabled.
*/
public static $magic_quotes = FALSE;
/**
- * @var boolean log errors and exceptions?
+ * @var boolean Should errors and exceptions be logged
*/
public static $log_errors = FALSE;
/**
- * @var boolean safe mode enabled?
+ * @var boolean TRUE if PHP safe mode is on
*/
public static $safe_mode = FALSE;
@@ -87,37 +87,37 @@ class Kohana_Core {
public static $base_url = '/';
/**
- * @var string application index file
+ * @var string Application index file, added to links generated by Kohana. Set by [Kohana::init]
*/
public static $index_file = 'index.php';
/**
- * @var string cache directory
+ * @var string Cache directory, used by [Kohana::cache]. Set by [Kohana::init]
*/
public static $cache_dir;
/**
- * @var integer default lifetime for caching, in seconds
+ * @var integer Default lifetime for caching, in seconds, used by [Kohana::cache]. Set by [Kohana::init]
*/
public static $cache_life = 60;
/**
- * @var boolean enabling internal caching?
+ * @var boolean Whether to use internal caching for [Kohana::find_file], does not apply to [Kohana::cache]. Set by [Kohana::init]
*/
public static $caching = FALSE;
/**
- * @var boolean enable core profiling?
+ * @var boolean Whether to enable [profiling](kohana/profiling). Set by [Kohana::init]
*/
public static $profiling = TRUE;
/**
- * @var boolean enable error handling?
+ * @var boolean Enable Kohana catching and displaying PHP errors and exceptions. Set by [Kohana::init]
*/
public static $errors = TRUE;
/**
- * @var array types of errors to display at shutdown
+ * @var array Types of errors to display at shutdown
*/
public static $shutdown_errors = array(E_PARSE, E_ERROR, E_USER_ERROR);
@@ -136,19 +136,29 @@ class Kohana_Core {
*/
public static $config;
- // Is the environment initialized?
+ /**
+ * @var boolean Has [Kohana::init] been called?
+ */
protected static $_init = FALSE;
- // Currently active modules
+ /**
+ * @var array Currently active modules
+ */
protected static $_modules = array();
- // Include paths that are used to find files
+ /**
+ * @var array Include paths that are used to find files
+ */
protected static $_paths = array(APPPATH, SYSPATH);
- // File path cache
+ /**
+ * @var array File path cache, used when caching is true in [Kohana::init]
+ */
protected static $_files = array();
- // Has the file cache changed?
+ /**
+ * @var boolean Has the file path cache changed during this execution? Used internally when when caching is true in [Kohana::init]
+ */
protected static $_files_changed = FALSE;
/**
@@ -160,21 +170,20 @@ class Kohana_Core {
* - Sanitizes GET, POST, and COOKIE variables
* - Converts GET, POST, and COOKIE variables to the global character set
*
- * Any of the global settings can be set here:
+ * The following settings can be set:
*
* Type | Setting | Description | Default Value
* ----------|------------|------------------------------------------------|---------------
- * `boolean` | errors | use internal error and exception handling? | `TRUE`
- * `boolean` | profile | do internal benchmarking? | `TRUE`
- * `boolean` | caching | cache the location of files between requests? | `FALSE`
- * `string` | charset | character set used for all input and output | `"utf-8"`
- * `string` | base_url | set the base URL for the application | `"/"`
- * `string` | index_file | set the index.php file name | `"index.php"`
- * `string` | cache_dir | set the cache directory path | `APPPATH."cache"`
- * `integer` | cache_life | set the default cache lifetime | `60`
+ * `string` | base_url | The base URL for your application. This should be the *relative* path from your DOCROOT to your `index.php` file, in other words, if Kohana is in a subfolder, set this to the subfolder name, otherwise leave it as the default. **The leading slash is required**, trailing slash is optional. | `"/"`
+ * `string` | index_file | The name of the [front controller](http://en.wikipedia.org/wiki/Front_Controller_pattern). This is used by Kohana to generate relative urls like [HTML::anchor()] and [URL::base()]. This is usually `index.php`. To [remove index.php from your urls](tutorials/clean-urls), set this to `FALSE`. | `"index.php"`
+ * `string` | charset | Character set used for all input and output | `"utf-8"`
+ * `string` | cache_dir | Kohana's cache directory. Used by [Kohana::cache] for simple internal caching, like [Fragments](kohana/fragments) and **\[caching database queries](this should link somewhere)**. This has nothing to do with the [Cache module](cache). | `APPPATH."cache"`
+ * `integer` | cache_life | Lifetime, in seconds, of items cached by [Kohana::cache] | `60`
+ * `boolean` | errors | Should Kohana catch PHP errors and uncaught Exceptions and show the `error_view`. See [Error Handling](kohana/errors) for more info. <br /> <br /> Recommended setting: `TRUE` while developing, `FALSE` on production servers. | `TRUE`
+ * `boolean` | profile | Whether to enable the [Profiler](kohana/profiling). <br /> <br />Recommended setting: `TRUE` while developing, `FALSE` on production servers. | `TRUE` * `boolean` | caching | Cache file locations to speed up [Kohana::find_file]. This has nothing to do with [Kohana::cache], [Fragments](kohana/fragments) or the [Cache module](cache). <br /> <br /> Recommended setting: `FALSE` while developing, `TRUE` on production servers. | `FALSE`
*
* @throws Kohana_Exception
- * @param array global settings
+ * @param array Array of settings. See above.
* @return void
* @uses Kohana::globals
* @uses Kohana::sanitize
@@ -371,12 +380,14 @@ public static function deinit()
/**
* Reverts the effects of the `register_globals` PHP setting by unsetting
- * all global varibles except for the default super globals (GPCS, etc).
+ * all global varibles except for the default super globals (GPCS, etc),
+ * which is a [potential security hole.][ref-wikibooks]
*
- * if (ini_get('register_globals'))
- * {
- * Kohana::globals();
- * }
+ * This is called automatically by [Kohana::init] if `register_globals` is
+ * on.
+ *
+ *
+ * [ref-wikibooks]: http://en.wikibooks.org/wiki/PHP_Programming/Register_Globals
*
* @return void
*/
@@ -452,15 +463,23 @@ public static function sanitize($value)
}
/**
- * Provides auto-loading support of Kohana classes, as well as transparent
- * extension of classes that have a _Core suffix.
+ * Provides auto-loading support of classes that follow Kohana's [class
+ * naming conventions](kohana/conventions#class-names-and-file-location).
+ * See [Loading Classes](kohana/autoloading) for more information.
*
* Class names are converted to file names by making the class name
* lowercase and converting underscores to slashes:
*
* // Loads classes/my/class/name.php
* Kohana::auto_load('My_Class_Name');
*
+ * You should never have to call this function, as simply calling a class
+ * will cause it to be called.
+ *
+ * This function must be enabled as an autoloader in the bootstrap:
+ *
+ * spl_autoload_register(array('Kohana', 'auto_load'));
+ *
* @param string class name
* @return boolean
*/
@@ -549,7 +568,7 @@ public static function modules(array $modules = NULL)
/**
* Returns the the currently active include paths, including the
- * application and system paths.
+ * application, system, and each module's path.
*
* @return array
*/
@@ -559,21 +578,25 @@ public static function include_paths()
}
/**
- * Finds the path of a file by directory, filename, and extension.
- * If no extension is given, the default EXT extension will be used.
+ * Searches for a file in the [Cascading Filesystem](kohana/files), and
+ * returns the path to the file that has the highest precedence, so that it
+ * can be included.
*
- * When searching the "config" or "i18n" directories, or when the
- * $array flag is set to true, an array of files
- * will be returned. These files will return arrays which must be
- * merged together.
+ * When searching the "config", "messages", or "i18n" directories, or when
+ * the `$array` flag is set to true, an array of all the files that match
+ * that path in the [Cascading Filesystem](kohana/files) will be returned.
+ * These files will return arrays which must be merged together.
+ *
+ * If no extension is given, the default extension (`EXT` set in
+ * `index.php`) will be used.
*
* // Returns an absolute path to views/template.php
* Kohana::find_file('views', 'template');
*
* // Returns an absolute path to media/css/style.css
* Kohana::find_file('media', 'css/style', 'css');
*
- * // Returns an array of all the "mimes" configuration file
+ * // Returns an array of all the "mimes" configuration files
* Kohana::find_file('config', 'mimes');
*
* @param string directory name (views, i18n, classes, extensions, etc.)
@@ -670,8 +693,11 @@ public static function find_file($dir, $file, $ext = NULL, $array = FALSE)
}
/**
- * Recursively finds all of the files in the specified directory.
+ * Recursively finds all of the files in the specified directory at any
+ * location in the [Cascading Filesystem](kohana/files), and returns an
+ * array of all the files found, sorted alphabetically.
*
+ * // Find all view files.
* $views = Kohana::list_files('views');
*
* @param string directory name
@@ -764,7 +790,17 @@ public static function load($file)
}
/**
- * Creates a new configuration object for the requested group.
+ * Returns the configuration array for the requested group. See
+ * [configuration files](kohana/files/config) for more information.
+ *
+ * // Get all the configuration in config/database.php
+ * $config = Kohana::config('database');
+ *
+ * // Get only the default connection configuration
+ * $default = Kohana::config('database.default')
+ *
+ * // Get only the hostname of the default connection
+ * $host = Kohana::config('database.default.connection.hostname')
*
* @param string group name
* @return Config
@@ -808,6 +844,8 @@ public static function config($group)
* Caching objects may not work as expected. Storing references or an
* object or array that has recursion will cause an E_FATAL.
*
+ * The cache directory and default cache lifetime is set by [Kohana::init]
+ *
* [ref-var]: http://php.net/var_export
*
* @throws Kohana_Exception
@@ -885,8 +923,9 @@ public static function cache($name, $data = NULL, $lifetime = NULL)
/**
* Get a message from a file. Messages are arbitary strings that are stored
- * in the messages/ directory and reference by a key. Translation is not
- * performed on the returned values.
+ * in the `messages/` directory and reference by a key. Translation is not
+ * performed on the returned values. See [message files](kohana/files/messages)
+ * for more information.
*
* // Get "username" from messages/text.php
* $username = Kohana::message('text', 'username');
Oops, something went wrong.

0 comments on commit 928c6ff

Please sign in to comment.