Difeye框架开发手册.doc

Difeye 框架开发手册 作者 周胜军 前言 Difeye 是一款超轻量级 PHP 框架 对 Kohana 框架做了精简和部分修改 主要 特点有 数据库连接做自动主从读写分离配置 适合单机和分布式站点部署 引入成熟的 Smarty 模板机制 改进了 Kohana 的路由风格 完全分离页面和动作 仿 C 页面加载自动执行 Page Load 入口函数 摒弃了 Kohana 的部分功能和扩展模块 包括 DB 类和 view 视图等 保留了 Kohana 的 session Profiler Request Route 等基础类 如果您在使用过程中 有任何问题反馈请联系我们 Http Mathcn 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 mathcn 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 译者注 开头小写 错误 Incorrect 正则表达式 如果编码中使用到正则表达式 请尽量使用 PCRE 风格而不是 POSIX 风格 相比较而言 PCRE 风格更为 强大 速度更快 正确 if preg match abc i str 错误 if eregi abc str 正则表达式使用单引号括起来而不是双引号 单引号的字符串简单而且解析起来更快 Unlike double quoted strings they don t support variable interpolation nor integrated backslash sequences like n or t etc 正确 preg match abc str 错误 preg match abc str 当需要使用正则搜索活替换时 请使用 n 符号作反向引用 它的效率优于 n 正确 preg replace d dollar 1 euro str 错误 preg replace d dollar 1 euro str 最后 请注意如果使用 符号匹配字符串末尾是否允许后换行符的话 如果需要可以附加 D 修饰符解决 此问题 更多详情 str email n preg match str TRUE preg match D str FALSE 1 2 文件系统结构 当使用 Difeye find file 加载一个文件时 系统会以下顺序搜索 Do 路径 在 index php 文件中常量被定义为 APPPATH 默认值是 do Module 路径 这是在 APPPATH bootstrap php 文件中使用 Difeye modules 设置的一组数组 数组的每个值都 会按照顺序搜索并添加进来 System 路径 在 index php 文件中常量被定义为 SYSPATH 默认值是 system 所有 core 核心文件和类文 件都在这里定义 目录中的文件包含了优先顺序建立的从高到低的优先级 这就有可能使得具有 高等级 目录的同名文件的会 重载任何可以低于它的文件内容 查找文件 使用 Difeye find file 方法可以找到在文件系统中任意路径下的文件 查询的路径 classes cookie php path Difeye find file classes cookie 查询的路径 views user login php path Difeye find file views user login 1 3 System 目录 system 目录如下 Base php 包含基础函数类库 并加载对应语言文件 系统文件 包含基本的 Request Route Profilter 等基础类 classes 所有你想要 autoload 的 Difeye 系统类库均保存在这里 本目录包含了基础类库 所有的库文件都必 须遵循类的命名规则 views System views 是 Difeye 开发时报错和分析调用的标准模板 1 4 Module 目录 Module 目录是第三方扩展模块目录 其中 Smarty 是 Difeye 的核心模块之一 Smarty Smarty 文件夹为 Smarty 官方发布版本文件 Init php 对 Smarty 类初始化配置 包括 smarty 缓存等 Database Config 下为主从数据库帐号密码 IP 配置文件 Classes 下包含数据库 query exception 等类 如何使用第三方扩展 调用扩展并非限定在 Difeye 比如 如果你想使用 DOMPDF 只需把他复制到 module dompdf 并加 载 DOMPDF 的自动加载类 require Difeye find file vendor dompdf dompdf dompdf config inc 现在无需再加载任何文件就可以使用 DOMPDF pdf new DOMPDF 1 5 Do 目录 Do 目录是用户 webapp 开发程序目录 Booter php 为引导程序 用来定制加载 Difeye Classes 用户行为使用 二级控制流程 页面 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 192 168 1 10 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 192 168 2 5 5306 database difeye username root password table prefix sys 修改 difeye modules database config 下的 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 192 168 2 5 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 192 168 2 5 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 192 168 2 5 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 192 168 2 5 5306 database difeye username root password persistent FALSE table prefix sys charset utf8 caching FALSE profiling TRUE 2 4 配置并使用 Smarty 模板 difeye modules smarty init 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 sma