Difeye框架开发手册.doc

Difeye 框架开发手册 作者：周胜军 前言 Difeye 是一款超轻量级 PHP 框架，对 Kohana 框架做了精简和部分修改，主要 特点有： 数据库连接做自动主从读写分离配置，适合单机和分布式站点部署； 引入成熟的 Smarty 模板机制； 改进了 Kohana 的路由风格，完全分离页面和动作，仿 C#页面加载自动执行 Page_Load 入口函数； 摒弃了 Kohana 的部分功能和扩展模块，包括 DB 类和 view 视图等。 保留了 Kohana 的 session，Profiler，Request，Route 等基础类。 如果您在使用过程中，有任何问题反馈请联系我们： Http:/ M mathcn 2011 年 1 月 1 日 目录 目录.3 第一章第一章 DIFEYE 1.0 入门入门.5 1.1. 命名规则约定5 1.2 文件系统结构.13 1.3 SYSTEM目录14 1.4 MODULE目录15 1.5 DO目录 .16 1.6 请求流程.18 第二章第二章 DIFEYE 1.0 配置开发配置开发.20 2.1. 基础配置20 2.2. COOKIE 及 SESSION 使用.21 2.3. DIFEYE数据库连接配置23 2.4. 配置并使用 SMARTY模板 26 2.5. 配置并使用多语言28 第三章第三章 DIFEYE 1.0 API 参数手册参数手册 29 3.1. API 参数29 周胜军： 2008 年，毕业于大连理工计算数学系，硕士。 曾任香港理工短期 RA 助理、信产部 CSIP 微软 dynamics 产品技术顾问； 擅长 windows,linux 平台 web 架构开发。 联系方式: Email: QQ 418806107 第一章 Difeye 1.0 入门 1.1. 命名规则约定 约定 鼓励大家遵循 BSD/Allman style 的编码样式。 类名和文件位置 在 Difeye 系统中类名严格遵循命名约定才能够自动加载。类名的首字母必须大写，且使用下划线连接单词， 千万要注意下划线的重要性，因为它直接关系到文件在文件系统中所存放的位置。 请遵循以下约定： 1.类名不允许使用骆驼命名法，除非需要创建新一级的目录文件。 2.所有的类文件的文件名和目录名都必须是小写。 3.所有的类文件都应该存放在 classes 目录下面，它可以是在级联文件系统的任何一级。 所有的类都存放在 “classes/“ 目录，既可以是完全静态的 辅助函数(“helpers“)或对象形式的类库 (“libraries“)。你可以使用任意形式的设计模式的类库：静态，单例，适配器等。 实例 请大家记着一点在类文件中，类名到下划线意味着是一个新的目录，参考下面例子: 类名文件路径 Controller_Templateclasses/controller/template.php Model_Userclasses/model/user.php Databaseclasses/database.php Database_Queryclasses/database/query.php 命名约定 Difeye 使用下划线连接命名，而不是驼峰命名。 类 / 控制器类，使用 Controller_ 作前缀 class Controller_Apple extends Controller / 模型类，使用 _Model 作前缀 class Model_Cheese extends Model / 普通类 class Peanut 当你实例化一个不需要附带参数的类时不需要使用圆括号: / 正确: $db = new Database; / 错误: $db = new Database(); 函数和方法 函数尽量全小写，并使用下划线分割单词: function drink_beverage($beverage) 变量 所有变量尽量全小写，并使用下划线分割单词而不是驼峰: / 正确: $foo = bar; $long_example = uses underscores; / 错误: $weDontWantThis = understood?; 缩进 代码在逻辑上缩进使用制表符(TAB)代替空格。 垂直间距(即多行)使用空格。制表符并不适用于垂直间距主要是因为不同的人可能设置类不同的制表符宽度。 $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.; 字符串连接 不要在连接符左右使用空格: / 正确: $str = one.$var.two; / 错误: $str = one. $var .two; $str = one . $var . two; 单行表达式 单行 IF 表达式仅用于破坏正常执行的情况(比如，return 或 continue): / 可接受: if ($foo = $bar) return $foo; if ($foo = $bar) continue; if ($foo = $bar) break; if ($foo = $bar) throw new Exception(You screwed up!); / 不可接受: if ($baz = $bun) $baz = $bar + 2; 比较操作 使用 OR 和 AND 作为比较符: / 正确: if ($foo AND $bar) OR ($b AND $c) / 错误: if ($foo break; case 1: echo one; break; default: echo bye; break; 括号 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. / 正确: if ($foo = $bar) if ( ! $foo) / 错误: if($foo = $bar) if(!$foo) if (int) $foo) if ( $foo = $bar ) if (! $foo) 三元操作 所有的三元操作都应该遵循一种标准格式。表达式左右使用括号，而变量则不需要。 $foo = ($bar = $foo) ? $foo : $bar; $foo = $bar ? $foo : $bar; 所有的比较和操作都必须使用括号括起来作为一个组: $foo = ($bar 5) ? ($bar + $foo) : strlen($bar); 分离复杂的三元操作（三元的第一部分超过了 80 个字符）为多行形式。spaces should be used to line up operators, which should be at the front of the successive lines: $foo = ($bar = $foo) ? $foo : $bar; 强制类型转换 强制类型转换需要在两边使用空格: / 正确: $foo = (string) $bar; if ( (string) $bar) / 错误: $foo = (string)$bar; 如果可能，请使用强制类型转换，而不是三元操作: / 正确: $foo = (bool) $bar; / 错误: $foo = ($bar = TRUE) ? TRUE : FALSE; 如果强制类型转换整形(int)或布尔型(boolean)，请使用短格式: / 正确: $foo = (int) $bar; $foo = (bool) $bar; / 错误: $foo = (integer) $bar; $foo = (boolean) $bar; 常量 常量尽量使用全大写: / 正确: define(MY_CONSTANT, my_value); $a = TRUE; $b = NULL; / 错误: define(MyConstant, my_value); $a = True; $b = null; 请把常量放在比较符号的末端: / 正确: if ($foo != FALSE) / 错误: if (FALSE != $foo) 这是一个略有争议的选择，所以我会解释其理由。如果我们用简单的英语写前面的例子中，正确的例子如下: if variable $foo is not exactly FALSE 但是错误的例子可以理解为: if FALSE is not exactly variable $foo 由于我们是从左向右读，因此把常量放在第一位根本没有意义。 注解 单行注解 单行注解使用 /，或许你在使用下面几种注解方式。请在注解符后面保留一个空格在添加注解。坚决不能 使用 #。 / 正确(Correct) /错误(Incorrect) / 错误(incorrect) /二级控制流程，页面 controller 是第一级流程，在页面 controller/下发生的动作 action 行为，被转移到第二级控制流程目录 action/下发生。同时 action 继承了 对应 controller 下的父页面类，并重载了入口函数 Page_Load。 如上图，当访问 http:/localhost/user/ 时，请求被路由到 controller/user.php 文件，加载控制类， 并寻找对应 action 类，如果存在则重载动作类 Page_Load 函数，如果不存在自动执行当前控制类的入口函 数； 当访问 http:/localhost/user/login 时，此时是二级流程，请求首先被路由到 controller/user/login.php 文件，加载控制类，然后按照优先级寻找 action/user/login.php 下的对应 controller/ action/ action 类。 如果找不到 controller/user/login.php,控制器会重新定位到 controller/user.php ，然后加载 action/user/login.php 动作类。 如果该动作类不存在，则继续寻找加载 action/userlogin.php 动作类。 Controller/下面的文件可以放入第二级文件夹（如上图 controller/test/） ，action/下面的文件也可以 按建立对应文件夹放入.php 分解的动作细分文件。 Difeye 的控制器和动作只支持二级文件目录分类，对于模块化的开发已经足够。 Classes/module/ 此文件夹，存放 webapp 开发时需要的公用类库； I18n/ 存放对应的语言文件； temp/ 存放 smarty 缓存文件夹； Views/ 存放 smarty 模板文件； 1.6 请求流程 每个应用都遵循同样的流程： 1.程序从 index.php 文件加载 2.设置 do，module 和 system 目录到路径 3.设置错误报告的级别 4.加载 Difeye 类 5.加载 APPPATH/booter.php 引导文件 6.调用 Difeye:init 方法初始化错误句柄 7.设置 Difeye _Config 8.调用 Difeye:modules 方法加载激活的模块 o模块路径附加到文件级联系统. o加载模块的 init.php 文件（如果存在的话） oinit.php 文件可以增强系统环境设置，同时也包括路由 9.Route:set 会被多次调用来定义程序路由 10. 调用 Request:instance 方法来处理请求 1.检测每个路由直到发现匹配的 2.加载控制器实例化并传递请求 11. 显示 Request 响应 index.php Difeye 遵循前端控制器模式，因此所有的请求都要发送到 index.php 文件。这样就可以允许保持一个非 常整洁的文件系统设计。在 index.php 文件中有一些非常重要而又基础的配置变量。你可以改变 $application，$modules 和 $system 的路径以及设置错误报告级别。 $application 变量让目录包含着你的程序文件。默认情况下，就是 application 目录。$modules 变量让 目录包含着你的扩展文件。默认情况下。$system 变量让目录包含着默认的 Difeye 文件。默认情况下。 你可以移动下面三个目录到任意路径。假如你的目录结构是: www/ index.php do/ modules/ system/ 应该转移这些目录到 web 目录以外的地方: do/ modules/ system/ www/ index.php 那么你应该在 index.php 文件改变下面变量的配置: $application = /do; $modules = /modules; $system = /system; 第二章 Difeye 1.0 配置开发 2.1. 基础配置 如果你的 Difeye 做为 lib 文件放在 webapp 目录之外，如下图所示： 那么您需要将 Difeye 下的 index.php 和 example.htaccess 移动到 webapp 下，并将 example.htaccess 修改为.htaccess，index.php 内容修改为如下： /* * 根据网站根目录获取 Difeye 的绝对路径 * Make the difeye directory relative to the wwwroot */ define(DIFEYE_PATH,WWWROOT./difeye.DIRECTORY_SEPARATOR); 此时访问 http:/localhost/user/login?lang=zh_cn http:/localhost/user/ http:/localhost/ 会出现 hello world 如果服务器使用的是 nginx，在 nginx.conf 文件内添加： server listen 80; server_name 0; index index.php index.html index.htm ; root /data0/htdocs/www/admin; #全部路由到 index.php if (!-e $request_filename) rewrite (.*)$ /index.php?$1 break; 如果服务器使用的是 apache，配置支持.htaccess 即可。 2.2. COOKIE 及 SESSION 使用 Session 和 cookie 演示 Session:instance(“database“)-set(“sessionname“,“sessionvalue“); echo session:instance(“database“)-get(“sessionname“,“default value“); Session:instance()-set(“sessionname2“,“sessionvalue2“); echo session:instance()-get(“sessionname2“,“default value“); Session:instance(“cookie“)-set(“abc“,“abcd“); echo Session:instance(“cookie“)-get(“abc“); Cookie:set(key_name, value); echo Cookie:get(key_name,“default“); Cookie 使用: session_id, last_active = last_active, contents = contents ); 建立数据表:(和你配置的数据库配置有关系,下面描述) CREATE TABLE sessions ( session_id VARCHAR( 24 ) NOT NULL, last_active INT UNSIGNED NOT NULL, contents TEXT NOT NULL, PRIMARY KEY ( session_id ), INDEX ( last_active ) ) ENGINE = MYISAM ; 如果使用 native 就最方便,不用配置 以下是使用方式 set(“abc“,“abcd“); echo Session:instance(“cookie“)-get(“abc“); Session:instance(“cookie“)-delete(“abc“); Session:instance(“cookie“)-destroy();/清除 SESSION 你可以把 COOKIE 去掉或者使用 database 试试,用 database 你会发现数据的 sessions 表会多一条记录 本地方式的话可以留空 即为:Session:instance(); 2.3. Difeye 数据库连接配置 Database 配置文件，default 为主数据库服务器，对于 slave 的数据源都要以 slave 为开头，后面 可以随意，比如: slave, slave1, slave2. 需要配置的参数： hostname = :5306, database = difeye, username = root, password = *, table_prefix = sys_, 修改 difeyemodulesdatabaseconfig 下的 database.php 配置: array ( type = mysql, connection = array( /* * The following options are available for MySQL: * * string hostname server hostname, or socket * string database database name * string username database username * string password database password * boolean persistent use persistent connections? * * Ports and sockets may be appended to the hostname. */ hostname = :5306, database = difeye, username = root, password = *, persistent = FALSE, ), table_prefix = sys_, charset = utf8, caching = FALSE, profiling = TRUE, ), /以下为从数据库服务器（读） slave = array ( type = mysql, connection = array( /* * The following options are available for MySQL: * * string hostname server hostname, or socket * string database database name * string username database username * string password database password * boolean persistent use persistent connections? * * Ports and sockets may be appended to the hostname. */ hostname = :5306, database = car_sysuser, username = root, password = allen123hjmHJM, persistent = FALSE, ), table_prefix = sys_, charset = utf8, caching = FALSE, profiling = TRUE, ), slave1 = array ( type = mysql, connection = array( /* * The following options are available for MySQL: * * string hostname server hostname, or socket * string database database name * string username database username * string password database password * boolean persistent use persistent connections? * * Ports and sockets may be appended to the hostname. */ hostname = :5306, database = difeye, username = root, password = *, persistent = FALSE, ), table_prefix = sys_, charset = utf8, caching = FALSE, profiling = TRUE, ), slave2 = array( type = mysql, connection = array( /* * The following options are available for MySQL: * * string hostname server hostname, or socket * string database database name * string username database username * string password database password * boolean persistent use persistent connections? * * Ports and sockets may be appended to the hostname. */ hostname = :5306, database = difeye, username = root, password = *, persistent = FALSE, ), table_prefix = sys_, charset = utf8, caching = FALSE, profiling = TRUE, ), ); 2.4. 配置并使用 Smarty 模板 difeyemodulessmartyinit.php 修改 smarty 的配置参数（如果需要） /* * 实例化 smarty 类, 调用示例 * Difeye:$smarty- * - Auto-loading smarty class */ if (!defined(INIT_NO_SMARTY) /= /* 创建 Smarty 对象。*/ require(MODPATH . smarty/smarty/Smarty.class.php); $smarty = new Smarty; $smarty-template_dir =APPPATH. views/template/; $smarty-compile_dir =APPPATH. temp/templates_c/; $smarty-cache_dir = APPPATH.temp/cache/; $smarty-compile_check = true; $smarty-debugging = true; $smarty-force_compile = true; $smarty-caching = true; $smarty-cache_lifetime = 1200; $smarty-assign(lang, setlang(); Difeye:$smarty = $smarty; 页面内使用 Smarty 示例： /演示如何使用 Smarty 模板 Difeye:$smarty-assign(“Name“,“Fred Irving Johnathan Bradley Peppergill“,true); Difeye:$smarty-assign(“FirstName“,array(“John“,“Mary“,“Jam