编辑“Kohana安装教程”

==系统安装==
从[http://down.zzbaike.com/download/kohana-2993.html 下载地址1]下载最新稳定版本的[[框架]]

创建一个名为 'kohana' 的目录并解压缩到这个目录

上传到这个目录的所有文件到你的[[服务器]]上

编辑 application/bootstrap.php 文件并按实际情况修改下面配置：
*为你的程序设置默认时区
*在 Kohana::init 方法中设置 base_url 的值为 kohana 目录的路径（或域名地址）

确保 application/cache 目录和 application/logs 目录为可写属性，命令为 
  chmod application/{cache,logs} 0777

在你喜欢的浏览器地址栏中输入 base_url 来测试 Kohana 是否安装成功
*根据系统平台的不同，安装的目录可能会随着解压缩而失去原先的权限属性。如果有错误发生请在 Kohana 根目录设定所有文件属性为 755。命令为：
  find . -type d -exec chmod 0755 {} \;

如果你可以看到安装页面（install.php）则说明已经安装成功（一片绿色），如果它报告有任何的错误（红色显示），你应该在立刻修复。
[[Image:Kohana_Install1.png|center]]

一旦安装页面报告你的环境确认无误，并且可以改名或删除install.php（Your environment is set up correctly you need to either rename or delete install.php）。安装刚才的说明操作之后就能看到 Kohana 的欢迎界面了(?? 目前 KO3 版本只有一个 'Hello World!' ??)
[[Image:Kohana_Install2.png|center]]

==系统升级==
===从 2.3.x 升级===
Kohana v3 大部分功能都不同于 Kohana 2.3 版本，下面列出了一系列的升级建议：
===命名公约===
在 2.x 体系中不同的类的类型（比如 controller，model 等）使用后缀来加以区分。文件夹在模型/控制器目录下没有任何类名的关系。

在 3.0 版本中废弃了上面的形式转而使用 Zend framework 的文件体系的公约，也就是类名包含类名和其路径，之间是有下划线分割而不是斜杠符（比如 /some/class/file.php 变为了 Some_Class_File） 

===Input 库===
Input 库已经从 3.0 版本中移除，请使用 $_GET 和 $_POST 获取。

===XSS 保护===
假如你需要使用 XSS 清除用户输入数据，你可以使用 Security::xss_clean 处理输入数据，比如：
 $_POST['description'] = security::xss_clean($_POST['description']);
你也可以把 Security::xss_clean 当作 Validate 类的过滤器使用：
 $validation = new Validate($_POST);
 $validate->filter('description', 'Security::xss_clean');

===POST & GET===
Input 库有一个最大的方便之处在于如果你试图从一个超全域阵列（superglobal arrays）访问它的值，假若其值不存在 Input 库则会返回一个指定的默认值，比如：
 $_GET = array();
 // $id 获得的值是 1
 $id = Input::instance()->get('id', 1);
 $_GET['id'] = 25;
 // $id 现在获得的值是 25
 $id = Input::instance()->get('id', 1);

在 3.0 版本你可以使用 Arr::get 方法实现同样的效果：
 $_GET = array();
 // $id 获得的值是 1
 $id = Arr::get($_GET, 'id', 1);
 $_GET['id'] = 42;
 // $id 现在获得的值是 42
 $id = Arr::get($_GET, 'id', 1);

===ORM 库===

自 2.3 版本到现在已经有一些主要的改动，下面是常见的通用升级问题：

====成员变量====
现在所有的成员变量都添加了 下划线(_) 作为前缀而且无法再通过 __get() 方法获得访问权利。相反的你可以把属性名并去掉下划线当作函数去调用。

例如，在 2.3 版本中有一个 loaded 属性，现在改名为 _loaded 并且如果需要在外边类库中访问此属性只需要 $model->loaded()。

====关系====
在 2.3 版本中如果你想要迭代一个模型相关对象的话，你需要：
 foreach($model->{relation_name} as $relation)
然而，在新的系统中这已经失效。在 2.3 版本中任何使用 Databate 库生成的查询都是在全局作用域生成，这就意味着你不能同时尝试和构建两个查询语句。这里有个例子：

===TODO: 需要一个具体的实例!!!!===
第二此查询则会失效而不能查询，内部查询将 '继承' 作为第一条件，从而造成混乱。在 3.0 版本中此问题得到了有效的解决，创建每条查询都是其自身的作用域之中，尽管如此，这也意味着有些东西没法按实际的预期正常工作。这里有个例子：
 foreach(ORM::factory('user', 3)->where('post_date', '>', time() - (3600 * 24))->posts as $post)
 {
    echo $post->title;
 }

在 2.3 版本中你希望它可以返回用户为 3 且 post_date 在最近 24 小时内发布的所有 posts 的迭代器，然而相反的，它将适用 where 语句到 user 模型中并返回带有指定加入语句的 'Model_Post' 对象。

为了达到 2.3 版本的同样效果，你只需要略微修改结构即可：
 foreach(ORM::factory('user', 3)->posts->where('post_date', '>', time() - (36000 * 24))->find_all() as $post)
 {
    echo $post->title;
 }
这同样也应用到 has_one 关系中：
 // 错误
 $user = ORM::factory('post', 42)->author;
 // 正确
 $user = ORM::factory('post', 42)->author->find();

===Has and belongs to many relationships===
在 2.3 版本中你可以设置 has_and_belongs_to_many 关系。但是在 3.0 版本此功能已经融合到了 has_many through。

在你的模型中定义一个 has_many 关系到其他模型中，并且添加一个 'through' => 'table' 属性，其中 'table' 是连接表的名称。比如（posts<>categories）：
<pre>
$_has_many = array
(
    'categories' =>     array
                        (
                            'model'     => 'category', // 外部模型
                            'through'   => 'post_categories' // 连接表
                        ),
);
</pre>
如果你的数据库配置设置了表前缀，这也不用担心去添加表前缀。

===外键===
如果你想在 2.x 版本的 ORM 中覆写一个外键，你必须指定关系属于谁，并且你的新外键在成员变量 $foreign_keys 之中。

在 3.0 版本中你只需要在关系数组中定义一个 foreign_key 键即可，比如：
<pre>
Class Model_Post extends ORM
{
    $_belongs_to =  array
                    (
                        'author' => array
                                    (
                                        'model'         => 'user',
                                        'foreign_key'   => 'user_id',
                                    ),
                    );
}
</pre>
在上面的实例中我们应该在 posts 表中存在一个 'user_id' 字段。

In has_many relationships the far_key is the field in the through table which links it to the foreign table & the foreign key is the field in the through table which links "this" model's table to the through table.

考虑以下设定，"Posts" have and belong to many "Categories" through posts_sections.

{|border="1" cellspacing="0"
 !categories||posts_sections||posts 
 |-
 |id||section_id||id
 |-
 |name||post_id||title
 |-
 | || ||name	post_id	title
 |-
|}

<pre>

    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',
                                                    ),
                                );
    }
</pre>
显然，这里的别名设定是有点疯狂，但它是如何让 foreign/far 键很好工作的绝佳范例。

===ORM 迭代器===
ORM_Iterator 也是值得注意的改动，它已经融合到了 Database_Result 之中。

如果你想要获得带有对象主键的 ORM 对象数组，你只需要调用 Database_Result::as_array，比如：
    $objects = ORM::factory('user')->find_all()->as_array('id');
其中的 id 就是 user 表的主键。

===Router 库===
在 2.x 版本中有一个 Router 库用于处理主要的请求工作。它允许你在 config/routes.php 配置文件中定义基本的路由，而且它还允许支持自定义的正则表达式路由，尽管如此，如果你想做极端的话它就显得相当呆板。

===路由===
在 3.0 版本中路由系统（现在成为请求系统）有了更多的灵活度。路由现在全部定义在 bootstrap 文件中（application/bootstrap.php）以及模块（Module）的 init.php 文件之中（modules/module/init.php）。（另外值得一提的是，现在的路由是按照他们定义的顺序评估）

替换定义的路由数组，你现在为每个路由创建一个新的 Route 对象。不像在 2.x 体系一样没有必要映射一个 uri 到另一个。相反的你使用标记段（比如，controller，method，id）的变量来指定 uri 模式。

例如，在老系统的正则：
 $config['([a-z]+)/?(\d+)/?([a-z]*)'] = '$1/$3/$1';
需要映射 uri 的 controller/id/method 为 controller/method/id，在 3.0 版本中这样修改：
 Route::set('reversed','(<controller>(/<id>(/<action>)))')
        ->defaults(array('controller' => 'posts', 'action' => 'index'));

每个 uri 都必须指定一个独一无二的名称（这里定义的是 reversed），其背后的原因是解释在 URL 教程 之中。

尖括号的内容会当作动态解析部分。圆括号的内容则会当作是可选或不必要的字段。如果你只是想匹配 uris 的开头是 admin，你只需要：
 Rouse::set('admin', 'admin(/<controller>(/<id>(/<action>)))');
但，如果你想用户必须指定一个控制器：
 Route::set('admin', 'admin/<controller>(/<id>(/<action>))');
同样，Kohana 不使用任何的 '默认的默认项'。如果你想让 Kohana 去设置默认 action 为 'index'，你只需要使用 Route::defaults 设置即可！如果你需要为 uri 字段自定义正则表达式，你只需要以 segment => regex 传递数组，比如：
 Route::set('reversed', '(<controller>(/<id>(/<action>)))', array('id' => '[a-z_]+'))
         ->defaults(array('controller' => 'posts', 'action' => 'index'))
这会迫使 id 的值必须全部是小写字母或者是数字，下划线。

===Actions===
还有一点我们必须要提到的，如果控制器中的方法可以通过网址访问，现在被称为 "actions"，且其前缀为 'action_'。比如，在上面的例中，如果用户访问 admin/posts/1/edit，那么 "actions" 就是 'edit' 而且方法在控制器将会是 action_edit。详情请参见 URL 教程

===Sessions===

以下方法不再存在：Session::set_flash()，Session::keep_flash() 和 Session::expire_flash() 方法，替代这些废弃方法的函数你可以使用 Session::get_once。

===URL 辅助函数===

URL 辅助函数仅做了略微的改动 - url::redirect() 方法转移到了 $this->request->redirect() 之中（包含控制器）/ Request::instance()->redirect()

url::current 现在替换为了 $this->request->uri()

===Valid / Validation===
这恋歌类现在已经合并为一个类并命名为 Validate.

对于校验数组的语法也有些改动：
<pre>
$validate = new Validate($_POST);

// 应用一个过滤器到所有数组项中
$validate->filter(TRUE, 'trim');

// 定义规则使用 rule() 方法
$validate
    ->rule('field', 'not_empty')
    ->rule('field', 'matches', array('another_field'));

// 为单字段设置多个规则也使用 rules() 方法，以 rules => params 的数组方式作为第二参数
$validate->rules('field',   array(
                                'not_empty' => NULL,
                                'matches'   => array('another_field')
                            ));
为保证定义明确，其中 'required' 规则现已经改名为 'not_empty'。
</pre>
===View 库===
对于 View 库也有一些值得注意的主要改动。

在 2.3 版本中视图在其处理的控制器中调用呈现，并允许你使用 $this 作为视图应用引用到控制器中。这一点在 3.0 版本改变了。视图现在呈现在一个空白的作用域，如果你需要在视图中使用 $this，你可以使用 View::bind 绑定一个引用 - $view->bind('this', $this)

It's worth noting, though, that this is very bad practice as it couples your view to the controller, preventing reuse. 推荐的方法是像下面这样去传递必备的变量到视图中：
<pre>
$view = View::factory('my/view');

$view->variable = $this->property;

// 或者如果你想使用连接方式

$view
    ->set('variable', $this->property)
    ->set('another_variable', 42);

// 不推荐
$view->bind('this', $this);
</pre>
因为视图在一个空的作用域呈现，而 Controller::_kohana_load_view 现在是多余的了。如果你想在它呈现之前修改视图（比如，添加一个站点的菜单），你可以使用 Controller::after
<pre>
<?php

Class Controller_Hello extends Controller_Template
{
    function after()
    {
        $this->template->menu = '...';

        return parent::after();
    }
}
</pre>

==系统配置==
===通用配置===
TODO：静态配置属性的说明
===核心配置===
任何一个新的 [[Kohana]] 安装之后第一件事情就是需要修改位于 application/bootstrap.php 配置文件的 Kohana::init 设置：

*boolean errors

使用内部错误和异常句柄？（默认为 TRUE）设置为 FALSE 则在 Kohana 中关闭错误和异常句柄显示。

*boolean profile

使用内部基准测试？（默认为 TRUE）设置为 FALSE 则为关闭内部分析器。 禁用它可以获得最佳性能。

*boolean caching

高速[[缓存]]之间的请求文件的位置？（默认是 FALSE）设置为 TRUE 开缓存在[[绝对路径]]的文件。 这大大加速了 Kohana::find_file 方法，它有时会对性能产生重大影响。仅在产品环境开启做测试使用。

*string charset

设置所有输入和输出的字符编码。（默认是 "[[utf-8]]"`）允许设置 htmlspecialchars 和 iconv 允许的编码格式。

*string base_url

程序的 [[URL]]（默认为 "/"）可以是一个完整或部分网址。比如 <nowiki>"http://example.com/kohana/</nowiki>" 或仅有 "/kohana/" 两者都工作。string cache_dir

*string index_file

程序开始的 PHP 文件入口。（默认是 "index.php"）设置为 FALSE 时，Kohana 利用 URL 重写从 URL 地址移除 index.php 字段。

缓存文件目录。（默认是 "application/cache" 目录）且必须是可写属性。

===Cookie 设置===
[[Cookie]]类中有几个静态的属性可以设置，特别是上线中的产品。

*string salt

Unique salt string that is used to used to enable signed cookies
*integer expiration

默认的生命期限（单位以 秒 为单位）
*string path

Cookie 可以写入的一个有效 URL 路径。
*string domain

限制只有配置的[[域名]]地址才能访问 cookies

*boolean secure

仅能通过[[HTTPS]]访问允许的 cookies

*boolean httponly

仅能通过 [[HTTP]] 访问允许的 cookies（同时也禁用 [[Javascript]] 访问）

===配置文件===
配置文件是纯[[PHP]] 文件，这类似于：
<pre>

<?php defined('SYSPATH') or die('No direct script access.');

return array(
    'setting' => 'value',
    'options' => array(
        'foo' => 'bar',
    ),
);
</pre>
如果上面的配置文件名为 myconf.php，你可以通过下面代码调用：
 $config = Kohana::config('myconf');
 $options = $config['options'];
Kohana::config 也提供了一钟使用“逗号格式”访问配置数组中的键：

获得 "options" 数组：
 $options = Kohana::config('myconf.options');
从 "options" 数组获得 "foo" 键：
 $foo = Kohana::config('myconf.options.foo');
配置数组也可以当作对象访问，如果你喜欢下面的方法：
 $options = Kohana::config('myconf')->options;

==相关条目==
*[[CakePHP]]
*[[ThinkPHP]]
*[[Yii]]

==参考来源==
*[http://kohanaphp.cn/guide/about.install 参考来源]

[[category:Kohana|A]]