PHP代码文档规范及phpDoc指南-共享版
php代码规范说明文档
@亲爱的php/计算机语言爱好者，开发者好，希望在这里你能收获到你需要的，祝你工作顺利，生活愉快！@姜祖斌，web爱好者，开发者@喜欢和业界的普一起交流，分享，关注互联网，关注媒体，关注开发，关注产品，关注技术@感兴趣的朋友可以和我一起交流技术的精华@weibo:/yangpage@mail/gtalk:jiangzubin1989@@msn:jiangzubin1989@@qq:757576387@honepage：/@facebook:https:///zubin.jiangphp代码规范说明文档命名规则：采用驼峰标识，尽量做到见名知义PHP编码规范与原则：//命名：类，方法，函数，变量，注释：开发中难免留下一些临时代码和调试代码，此类代码必须添加注释，以免日后遗忘。
所有临时性、调试性、试验性的代码，必须添加统一的注释标记“//debug”并后跟完整的注释信息，这样可以方便在程序发布和最终调试前批量检查程序中是否还存在有疑问的代码。
如：$flag = TRUE; //debug 这里不能确定是否需要对$flag进行赋值缩进/空格：使用四个空格为每层次缩进。
对于最大缩进层数，并没有一个固定的规矩，假如缩进层数大于五层的时候，考虑着将代码因数分解。
运算符、小括号、关键词和函数：不要把小括号和关键词紧贴在一起，要用空格隔开它们；不要把小括号和函数名紧贴在一起；除非必要，不要在Return返回语句中使用小括号。
如：if (condition) {}大括号{}、if和switch：首括号与关键词同行，尾括号与关键字同列；if结构中，if和elseif与前后两个圆括号同行，左右各一个空格，所有大括号都单独另起一行。
另外，即便if后只有一行语句，仍然需要加入大括号，以保证结构清晰；总是将恒量放在等号/不等号的左边。
switch结构中，通常当一个case块处理后，将跳过之后的case块处理，因此大多数情况下需要添加break。
PHP文档规范及phpDoc指南-共享版
PHP文档规范及phpDoc指南-共享版1 概述对于一个开发人员，文档总是最感到头疼的事情之一。
而且，很可能你对待文档会采取截然不同的2 种态度：当你使用别人的代码库的时候，最希望得到的是它的技术文档，尤其是当时间很紧，而你又不得不硬着头皮去读那些生涩的代码的时候。
当写你自己的程序的时候，最不希望做的事情却是给它编写专门的技术文档，你会以种种理由给自己开脱：我的代码已经足够清晰了，完全不用再为它重新编写文档了�6�7�6�7 为了解决这个问题，文档工具由此产生。
按照规范格式编写代码注释，当代码写完了，技术文档也就完成了。
良好的代码注释不仅能够帮助开发人员在编写代码时缕清思路，尽可能避免逻辑 bug，而且规范的代码注释还能够使用文档工具直接生成API 手册。
下面是一个规范的代码注释：/** * Common base class of all phpdoc classes （简述，用在索引列表中)* * As a kind of common base class PhpdocObject holds * configuration values (e.g. error handling)and debugging * methods (e.g. introspection()). It does not have a constructor, * so you can always inheritig Phpdoc classes from this * class without any trouble. （详细的功能描述)* * @author Ulf Wendel * @version $Id：PhpdocObject.php,v 1.3 2001/02/18 15:29:29 uw Exp $ * @package PHPDoc （文档标记)*/ class PhpdocObject { ..... ｝2 PHPDoc/ phpDocumentor 2.1 什么是PHPDoc/phpDocumentor PHPDoc（现在项目名改为了phpDocumentor）是PEAR 下面的一个非常优秀的模块，它的目标是实现类似 javadoc 的功能，可以为你的代码快速生成具有相互参照，索引等功能的API 文档。
PHPWord使用指南By_Stone
PHPWord使用指南(PHPWord Beta 0.6.2)By--Stone 首先我们要了解文档最基本的信息和设置：因为是国外编辑的类库，存在对中文支持的问题，使用前，我们需要进行一些修正：1、解决编码问题，PHPword会对输入的文字进行utf8_encode 编码转化，如果你使用GBK、GB2312或者utf8编码的话就会出现乱码，如果你用utf8编码，就查找类库中所有方法中的utf8_encode转码将其删除，如果你采用GBK或者GB2312编码，使用iconv进行编码转换。
2、解决中文字体支持，在writer/word2007/base.php中312行添加$objWriter->writeAttribute('w:eastAsia',$font)3、启动php zip支持，windows环境下在php配置文件php.ini 中，将extension=php_zip.dll前面的分号“;”去除；(如果没有，请添加extension=php_zip.dll此行并确保php_zip.dll文件存在相应的目录)，然后同样在php.ini文件中，将zlib.output_compression = Off改为zlib.output_compression = On；计量单位：缇（twips）首先解释一下PHPWord最基本的计量单位：“缇”（twips），我们常常在文件中看到或使用计量单位“缇”，它是开源办公软件中最基本的计量单位，“缇”是"TWentieth of an Inch Point"的简写，意思 1/20磅，与其他常用剂量单位的换算是1缇=1/1,440英寸，1缇=1/567厘米，1缇=1/15像素新建文档添加页面添加默认页面（默认页面方向和页边距）：页面样式创建样式数组:文本添加文本向文档添加文本使用方法函数： addText.（注意PHPword会对输入的文字进行utf8_encode编码转化，如果你使用GBK、GB2312或者utf8编码的话就会出现乱码，如果你用utf8编码，就查找类库中所有方法中的utf8_encode转码将其删除，如果你采用GBK或者GB2312编码，使用iconv进行编码转换。
PHP代码规范
请在条件陈述中使用&&和||，不要使用 and 和 or。
例如：
/* These are all wrong. */ if (($i < 7) and ($j > 8)) ... /* These are all right. */ if (($i < 7) && ($j > 8)) ...
PHP 代码范
一 编辑器设置
1．使用 Tab 缩进，不要使用空格
鉴于很多编辑器在保存文件时会自动清除用于缩进的空格，所以我们一律使 用 Tab 键进行缩进。
2．UNIX 文件格式
请将编辑器设置对所有程序使用 UNIX 格式保存，不要使用 Win32 或者 Mac 的格式。例如，EditPlus 里面 Document->File Format(CR/LF)->Unix 。
例如:
/* These are all wrong. */ if (condition) {
while (condition2) { ...
} } else {
... }
/* These are right. */ if (condition)
{ while (condition2) { ... }
例如:
/* These are all wrong. */ $i=0; /* These are all right. */ $i = 0;
/* These are all wrong. */ if($i<7) ... /* These are all right. */ if ($i < 7) ...
case: 1 ...
default: ...
PHP代码规范
PHP代码规范命名约定1. 类：(1) 使用大写字母作为词的分割，其他的字母均使用小写；（2）名字的首字母使用大写;(3) 不要使用下划线('_')；(4) 如：Name、SuperMan、BigClassObject。
2. 函数：(1) 函数名只包含字母数字的字符，数字是允许的但大多数情况下不鼓励；(2) 函数名总是以小写开头，当函数名包含多个单词，在首单词后的所有单词首字母大写，以“驼峰”格式来处理；(3) 函数名应当说明函数的意图和行为。
例子：3. 变量：(1) 变量名只包含字母数字的字符，数字是允许的但大多数情况下不鼓励；(2) 变量名总是以小写开头，当变量名包含多个单词，在首单词后的所有单词首字母大写，以“驼峰”格式来处理；例子：4. 常量：(1)常量包含数字字母字符和下划线，数字允许作为常量名;(2) 常量名的所有字母必须大写;(3) 常量中的单词必须以下划线分隔，例如可以这样 :EMBED_SUPPRESS_EMBED_EXCEPTION字符串变量替换变量替换有下面这些形式：字符串连接字符串必需用 "." 操作符连接，在它的前后加上空格以提高可读性：数组索引不能为负数，建议数组索引从 0 开始。
当用array函数声明有索引的数组，在每个逗号的后面间隔空格以提高可读性：当用声明关联数组，array我们鼓励把代码分成多行，在每个连续行的开头用空格填补来对齐键和值：类的声明花括号应当从类名下一行开始。
每个类必须有一个符合PHPDocumentor标准的文档块。
类中所有代码必需用四个空格的缩进。
例子：类成员变量变量的声明必须在类的顶部，在方法的上方声明。
不允许使用var，要用private、protected或public。
直接访问 public 变量是允许的但不鼓励，最好使用访问器（set/get）。
函数和方法声明在类中的函数必须用private、protected或public声明它们的可见性。
PHP代码规范
PHP代码规范PSR-0命名标准,官⽅已基本废弃PSR-1 基本代码规范本篇规范制定了代码基本元素的相关标准，以确保共享的PHP代码间具有较⾼程度的技术互通性。
关键词 “必须”("MUST")、“⼀定不可/⼀定不能”("MUST NOT")、“需要”("REQUIRED")、“将会”("SHALL")、“不会”("SHALL NOT")、“应该”("SHOULD")、“不该”("SHOULD NOT")、“推荐”("RECOMMENDED")、“可以”("MAY")和”可选“("OPTIONAL")的详细描述可参见 RFC 2119 。
1. 概览PHP代码⽂件必须以PHP代码⽂件必须以不带BOM的 UTF-8 编码；PHP代码中应该只定义类、函数、常量等声明，或其他会产⽣从属效应的操作（如：⽣成⽂件输出以及修改.ini配置⽂件等），⼆者只能选其⼀；命名空间以及类必须符合 PSR 的⾃动加载规范：PSR-0 或 PSR-4 中的⼀个；类的命名必须遵循 StudlyCaps ⼤写开头的驼峰命名规范；类中的常量所有字母都必须⼤写，单词间⽤下划线分隔；⽅法名称必须符合 camelCase 式的⼩写开头驼峰命名规范。
2. ⽂件2.1. PHP标签PHP代码必须使⽤长标签或短输出标签；⼀定不可使⽤其它⾃定义标签。
2.2. 字符编码PHP代码必须且只可使⽤不带BOM的UTF-8编码。
2.3. 从属效应（副作⽤）⼀份PHP⽂件中应该要不就只定义新的声明，如类、函数或常量等不产⽣从属效应的操作，要不就只有会产⽣从属效应的逻辑操作，但不该同时具有两者。
“从属效应”(side effects)⼀词的意思是，仅仅通过包含⽂件，不直接声明类、函数和常量等，⽽执⾏的逻辑操作。
PHP编码规范
PHP 编码规范一、文件格式1. 对于只含有 php 代码的文件，我们将在文件结尾处忽略掉 "?>" 。
这是为了防止多余的空格或者其它字符影响到代码。
例如：<?php$foo = 'foo';2. 缩进应该能够反映出代码的逻辑结果，尽量使用四个空格，禁止使用制表符TAB，因为这样能够保证有跨客户端编程器软件的灵活性。
例如：if (1 == $x) {$indented_code = 1;if (1 == $new_line) {$more_indented_code = 1;}}3. 变量赋值必须保持相等间距和排列。
例如：$variable = 'demo';$var = 'demo2';4. 每行代码长度应控制在80个字符以内，最长不超过120个字符。
因为 linux 读入文件一般以80列为单位，就是说如果一行代码超过80个字符，那么系统将为此付出额外操作指令。
这个虽然看起来是小问题，但是对于追求完美的程序员来说也是值得注意并遵守的规范。
5. 每行结尾不允许有多余的空格。
二、命名约定1. 类文件都是以“.class.php“为后缀，且类文件名只允许字母，使用驼峰法命名，并且首字母大写，例如：DbMysql.class.php 。
2. 配置和函数等其他类库文件之外的文件一般是分别以“.inc.php“和”.php“为后缀，且文件名命名使用小写字母和下划线的方式，多个单词之间以下划线分隔，例如config.inc.php ， common.php，install_function.php 。
3. 确保文件的命名和调用大小写一致，是由于在类Unix系统上面，对大小写是敏感的。
4. 类名和文件名一致（包括上面说的大小写一致），且类名只允许字母，例如 UserAction类的文件命名是UserAction.class.php， InfoModel类的文件名是InfoModel.class.php 。
PHP项目开发规范文档
PHP项目开发规范文档1.简介PHP是一种开源的脚本语言，广泛用于Web开发。
本文档旨在提供PHP项目开发的规范，以保证代码的可读性、可维护性和可扩展性。
2.代码风格-缩进：使用4个空格进行缩进。
- 命名规范：使用驼峰命名法（camel case）命名变量、函数和类。
-常量命名规范：使用全大写字母和下划线命名。
-注释：用注释来解释复杂的代码逻辑和关键性的功能。
-换行：每行代码长度不应超过80个字符。
当一个表达式太长无法放在一行时，可以分成多行，并使用括号或者点操作符连接。
3.文件和目录结构- 将不同类别的文件分别放在不同的目录中，例如将数据库相关的文件放在一个名为"database"的目录中。
- 使用适当的文件命名来描述文件的功能，例如"UserController.php"。
4.安全性考虑-永远不要相信用户的输入，始终进行数据有效性验证和过滤。
- 使用准备好的语句（prepared statements）和参数绑定（parameter binding）来防止SQL注入攻击。
- 对于敏感数据，如密码或社会安全号码，至少应进行哈希（hash）加密。
5.性能优化-减少数据库查询次数：使用适当的索引、缓存查询结果或使用批量操作来减少数据库查询次数。
-尽量使用更高效的函数和算法来提高代码的性能。
-避免在循环中执行过多的数据库查询或文件读写操作。
6.异常处理- 使用try-catch语句来捕获并处理异常。
- 使用异常层次结构来处理不同类型的异常，例如自定义异常类继承自PHP的Exception类。
7.文档注释-使用文档注释来说明函数和类的使用方法、输入参数、返回值和异常情况。
- 使用标准的文档注释格式，例如PHPDoc。
8.版本控制- 使用版本控制系统（如Git）来管理代码，确保代码的版本可追踪和可恢复。
- 尽量使用分支来开发新功能或修复bug，并在合并到主分支之前进行代码审查和测试。
- 1、下载文档前请自行甄别文档内容的完整性，平台不提供额外的编辑、内容补充、找答案等附加服务。
- 2、"仅部分预览"的文档,不可在线预览部分如存在完整性等问题,可反馈申请退款(可完整预览的文档不适用该条件!)。
- 3、如文档侵犯您的权益，请联系客服反馈,我们会尽快为您处理(人工客服工作时间：9:00-18:30)。
PHP文档规范及phpDoc指南目录1概述 (3)2PHPDoc/ phpDocumentor (3)2.1什么是PHPDoc/phpDocumentor (3)2.2phpDocumentor1和phpDocumentor2 (5)2.3phpDocumentor安装 (5)2.3.1pear安装 (5)2.3.2phpDocumentor安装 (6)3使用phpDocumentor生成文档 (6)3.1phpDocumentor使用说明 (6)3.2生成指定目录下的文档 (6)3.3生成指定文件的文档 (6)3.4指定文档标题 (7)4PHP注释规范 (7)4.1需要特别注意的地方 (7)4.2文件、类注释 (8)4.3方法注释 (8)4.4常用tag标签 (9)4.4.1常用tag列表 (9)4.4.2@param变量类型列表 (9)4.5常用的嵌入式{@tag }用法 (10)4.5.1{@link}用法 (10)4.5.2{@source}用法 (10)4.5.3其他inline tag (11)4.6<code></code>用法 (11)5参考资料 (12)1概述对于一个开发人员，文档总是最感到头疼的事情之一。
而且，很可能你对待文档会采取截然不同的2种态度：●当你使用别人的代码库的时候，最希望得到的是它的技术文档，尤其是当时间很紧，而你又不得不硬着头皮去读那些生涩的代码的时候。
●当写你自己的程序的时候，最不希望做的事情却是给它编写专门的技术文档，你会以种种理由给自己开脱：我的代码已经足够清晰了，完全不用再为它重新编写文档了……为了解决这个问题，文档工具由此产生。
按照规范格式编写代码注释，当代码写完了，技术文档也就完成了。
良好的代码注释不仅能够帮助开发人员在编写代码时缕清思路，尽可能避免逻辑bug，而且规范的代码注释还能够使用文档工具直接生成API手册。
2PHPDoc/ phpDocumentor2.1什么是PHPDoc/phpDocumentorPHPDoc（现在项目名改为了phpDocumentor）是PEAR下面的一个非常优秀的模块，它的目标是实现类似javadoc的功能，可以为你的代码快速生成具有相互参照，索引等功能的API文档。
目前PHPDoc有3个主要的版本：●PHPDoc：此版本最高到 1.0beta，已经停止维护，升级为phpDocumentor，PHPDoc的官网是http://www.phpdoc.de/，有兴趣的话可以看看。
此版本生成的文档格式如下图：●phpDocumentor1：此版本最高到1.4.4，已经升级到phpDocumentor2，目前网上大部分的PHP开源项目都是由此版本工具生成的API手册。
官网：/，此版本生成的文档格式如下图：●phpDocumentor2：此版本还在升级维护中，目前最高版本是2.0.0alpha1。
官网：/，此版本生成的文档格式如下图：2.2phpDocumentor1和phpDocumentor2因为最初的版本PHPDoc早已停止维护和升级，本文不再介绍和使用。
phpDocumentor从1.4.4直接升到了phpDocumentor2，2比较于1做了如下改变：●High performance：更高的性能。
优化后的phpDocumentor生成同一个项目的文档，比前一版本最高节省90秒。
●Template System：提供了非常灵活的模板系统，用户可以订制自己的API手册样式。
而且也修正了1.4.4非常讨厌的默认iso-8859-1编码，改成了默认utf-8。
●Reports & Charts：可以生成开发人员可能感兴趣的图标和报告，如类的继承关系、接口实现拓扑图，TODO就列表等。
●Plugins：增加了以AoP模式实现的的插件功能，开发人员可以开发或重写自己的tag解释方法。
在安装和使用上，phpDocumentor1和phpDocumentor2基本一样，所以下文就统一以phpDocumentor说明。
（因为phpDocumentor2的默认responsive模板生成的文档实在不太好看和不习惯，而且phpDocumentor2的新特性大多都用不上，所以笔者现在用的是能够生成上PHP手册样式的phpDocumentor1.4.4）2.3phpDocumentor安装2.3.1pear安装因为phpDocumentor是PEAR的一个模块，虽然phpDocumentor也支持单独下载使用，但最后以PEAR模块安装。
所以如果PHP没有安装PEAR，需要先安装PEAR：Mac OS X：2.3.2phpDocumentor安装●phpDocumentor1.4.4安装要求：PHP version 4.1.0或以上说明：phpDocumentor1.4.4比较讨厌的地方是文档的tpl模板默认编码是iso-8859-1，而不是常用的utf-8，如果不修改的话可能会产生中文乱码的问题。
修改默认编码方法如下：找到PEAR的安装目录，以笔者的电脑为例，PEAR的安装目录是：/opt/local/lib/php/pear●phpDocumentor2安装要求：PHP 5.2.6或以上，最好安装有XSL和Graphviz扩展。
如果需要生成PDF格式的文档，还需要安装wkhtmltopdf扩展。
3使用phpDocumentor生成文档3.1phpDocumentor使用说明使用phpdoc –h命令可以产看帮助手册，本文不再详述。
3.2生成指定目录下的文档3.3生成指定文件的文档3.4指定文档标题4PHP注释规范4.1需要特别注意的地方●需要生成文档的注释必须是以“/**”开头，以“*/”结尾。
主流的IDE开发工具（如Eclipse，Zend）会用不同的颜色来区分下面的几种注释。
●●一般以“/*”开头，而public方法以“/**”开头。
4.2文件、类注释4.3方法注释4.4常用tag标签4.4.1常用tag列表特别说明；●@version：如果代码版本控制工具使用的是CVS，可以设置成“@version$Id: Exp $”，CVS在提交代码时会自动填充文件的版本信息●@see：当某些注释说明已经写过不想再重复写，或有关联的方法或类需要参见，此时用到@see4.4.2@param变量类型列表@param 标签需要指定参数类型，可以使用的类型如下：●string 该参数是一个字符型变量。
●array 该参数是一个数组。
●int该参数是一个数值型，同integer●integer 该参数是一个数值型。
●integer (octal) 该参数是一个数值型，并且是按照八进制方式存放。
●integer (hexadecimal) 该参数是一个数值型，并且是按照十六进制方式存放。
●boolean 该参数是一个布尔型。
●mixed 该参数的类型是可变的，可以上面几种类型的组合。
不过，在随后的说明中一般要说明可以接受的变量的类型。
●void 无返回值，只用于@return标签，如@return void以上类型同样适用于@property和@return4.5常用的嵌入式{@tag }用法嵌入式{@tag }（即inline tag）是在写注释文字段时，需要在文字段中加入链接或锚点，此时用到嵌入式tag。
4.5.1{@link}用法在写注释文字段时需要加一些URL链接或是锚点，在生成的文档中用户可以通过鼠标点击进入这个链接或锚点，或是有关联的方法或类需要参见，此时用到{@link}。
格式如下：{@link URL [description]}{@link element [description]}举例：4.5.2{@source}用法当需要在文档中显示具体的实现代码时，可以使用此标签。
格式如下：●显示该方法或类的所有代码：{@source}●显示从指定行开始到方法或类的结尾代码：{@source startline}●显示从指定行开始，到指定的行数结束的代码：{@source startline number_of_lines}* {@source }* displays without a break in the flow*/function element($pages){if (empty($pages)){die("<b>ERROR</b>: nothing parsed");}}相当于===》/*** Text with an inline source tag:** <code>* function element($pages)* {* if (empty($pages))* {* die("<b>ERROR</b>: nothing parsed");* }* }* </code>* displays without a break in the flow*/当然，如果不用此标签也可以直接使用<code></code>标记，具体说明见下文。
4.5.3其他inline tag其他的不太常用，具体参见官方文档：/docs/latest/index.html4.6<code></code>用法<code></code>标签的主要作用是为了显示代码段示例。
当然，如果有大段的注释文本，而又懒得去加<br/>等HTML标签进行换行美化，也可以使用此标签。
5参考资料1、/developerworks/cn/linux/sdk/php/pear3/index.html2、/。