月度归档:2015年03月

【PHP开发】国外程序员收集整理的 PHP 资源大全

依赖管理

依赖和包管理库

 

其他的依赖管理

其他的相关依赖管理

 

框架

Web开发框架

其他框架

其他Web开发框架

框架组件

来自web开发框架的独立组件

微型框架

微型框架和路由

  • Silex – 基于Symfony2组件的微型框架
  • Slim – 另一个简单的微型框架
  • Bullet PHP -用于构建REST APIs的微型框架
  • Fast Route – 快速路由库
  • Pux -另一个快速路由库

其他微型框架

其他相关的微型框架和路由

模板

模板化和词法分析的库和工具

  • Twig -一个全面的模板语言
  • Twig Cache Extension -一个用于Twig的模板片段缓存库
  • Mustache -一个Mustache模板语言的PHP实现
  • Phly Mustache -另一个Mustache模板语言的PHP实现
  • MtHaml – 一个HAML 模板语言的PHP实现
  • PHPTAL -一个 TAL 模板语言的PHP实现
  • Plates -一个原生PHP模板库
  • Lex -一个轻量级模板解析器

静态站点生成器

预处理工具来生成web页面的内容。

  • Sculpin -转换Markdown和Twig为静态HTML的工具
  • Phrozn – 另一个转换Textile,Markdown和Twig为HTML的工具

HTTP

用于HTTP和网站爬取的库

  • Guzzle -一个全面的HTTP客户端
  • Buzz -另一个HTTP客户端
  • Requests -一个简单的HTTP库
  • HTTPFul -一个链式HTTP库
  • Goutte -一个简单的web爬取器
  • PHP VCR -录制和重放HTTP请求的库

 

URL

解析URL的库

 

Email

发送和解析邮件的库

文件

文件处理和MIME类型检测库

 

Streams 流

处理流的库

  • Streamer – 一个面向对象的流包装库

 

Dependency Injection依赖注入

实现依赖注入设计模式的库

  • Pimple – 一个小的依赖注入容器
  • Auryn – 另一个依赖注入容器
  • Orno Di -另一个可伸缩的依赖注入容器
  • PHP DI -一个使用注释实现的依赖注入
  • Acclimate -一个依赖注入容器和服务定位的通用接口

 

Imagery 图像

处理图像的库

 

Testing 测试

测试代码和生成测试数据的库

  • PHPUnit -一个单元测试框架
  • DBUnit -PHPUnit的数据库测试库
  • ParaTest – PHPUnit的并行测试库
  • PHPSpec -基于功能点设计的单元测试库
  • Codeception -一个全栈测试框架
  • AspectMock –  PHPUnit/ Codeception 模拟框架。
  • Atoum -一个简单的测试库
  • Mockery -一个用测试的模拟对象库
  • Phake -另一个用测试的模拟对象库
  • Prophecy -一个可选度很高的模拟框架
  • Faker -一个伪数据生成库
  • Samsui – 另一个伪数据生成库
  • Alice -富有表现力的一代库
  • Behat -一个行为驱动开发(BDD)测试框架
  • Pho -一个行为驱动开发测试框架
  • Mink -Web验收测试
  • HTTP Mock – 一个在单元测试模拟HTTP请求的库
  • VFS Stream -一个用于测试的虚拟文件系统流的包装器
  • VFS -另一个用于测试虚拟文件系统
  • Locust -一个用Python编写的现代加载测试库

 

Continuous Integration 持续集成

持续集成的库和应用

  • Travis CI – 一个持续集成平台
  • PHPCI -一个PHP的开源持续集成平台
  • Sismo – 一个持续测试服务库
  • Jenkins一个 PHP 支持的持续集成平台
  • JoliCi – 一个用PHP编写的由Docker支持的持续集成客户端

 

Documentation 文档

生成项目文档的库

  • Sami -一个API文档生成器
  • APIGen -另一个API文档生成器
  • PHP Documentor 2 -一个API文档生成器
  • phpDox – 一个PHP项目的文档生成器(不限于API文档)

 

Security 安全

生成安全的随机数,加密数据,扫描漏洞的库

 

Passwords 密码

处理和存储密码的库和工具

 

Code Analysis 代码分析

分析,解析和处理代码库的库的工具

  • PHP Parser -一个PHP编写的PHP解析器
  • PHPPHP – 一个PHP实现的PHP虚拟机
  • PHPSandbox -一个PHP沙盒环境
  • Dissect -一个词法和语法分析的工具集合
  • PHP Mess Detector -一个扫描代码缺陷,次优代码,未使用的参数等等的库。
  • PHP Code Sniffer -一个检测PHP、CSS和JS代码标准冲突的库
  • PHPCPD – 一个检测复制和粘贴代码的库
  • PHP Analyser -一个分析PHP代码查找缺陷和错误的库
  • PHP CS Fixer – 一个编码标准库
  • PHP Manipulator -一个分析和修改PHP源代码的库
  • PHP Metrics -一个静态测量库
  • PHP Refactoring Browser -一个重构PHP代码的命令行工具集
  • UBench – 一个简单的微型基准检测库
  • Athletic -一个基于注释的基准检测库
  • Mondrian – 使用使用图论的代码分析工具
  • Scrutinizer -一个审查PHP代码的web工具
  • PHPLOC -一个快速测量PHP项目大小的工具
  • xHprof -另一个PHP分析工具
  • PHPCheckstyle -一个帮助遵守特定的编码惯例的工具。

Debugging 调试

调试代码的库和工具

 

Build Tools 构建工具

项目构建和自动化工具

  • Go -一个简单的PHP构建工具
  • Bob – 一个简单的项目自动化工具
  • Phake -一个PHP克隆库
  • Box – 一个构建PHAR文件的工具
  • Phing -一个灵感来自于Apache Ant的PHP项目构建系统

 

Task Runners 任务运行器

自动运行任务的库

  • Task -一个灵感来源于Grunt和Gulp的纯PHP任务运行器
  • Robo -一个面向对象配置的PHP任务运行器
  • Bldr -一个构建在Symfony组件上的PHP任务运行器

 

Navigation导航

构建导航结构的工具

 

Asset Management 资源管理

管理,压缩和最小化web站点资源的工具

  • Assetic – 一个资源管理的管道库
  • Pipe -另一个资源管理的管道库
  • Munee -一个资源优化库
  • JShrink -一个JavaScript最小化库
  • Puli – 一个检测资源绝对路径的库

 

Geolocation 地理位置

为地理编码地址和使用纬度经度的库。

  • GeoCoder -一个地理编码库
  • GeoTools -一个地理工具相关的库
  • PHPGeo -一个简单的地理库
  • GeoJSON -一个地理JSON的实现

 

Date and Time 日期和时间

处理日期和时间的库

  • Carbon – 一个简单的日期时间API扩展
  • ExpressiveDate -另一个日期时间API扩展
  • CalendR – 一个日历管理库

 

Event 事件

时间驱动或非阻塞事件循环实现的库

 

Logging 日志

生成和处理日志文件的库

  • Monolog – 一个全面的日志工具
  • KLogger -一个易用的PSR-3兼容的日志类

 

E-commerce 电子商务

处理支付和构建在线电子商务商店的库和应用

  • OmniPay -一个框架混合了多网关支付处理的库
  • Payum – 一个支付抽象库
  • Sylius – 一个开源的电子商务解决方案
  • Thelia -另一个开源的电子商务解决方案
  • Money – 一个Fowler金钱模式的PHP实现
  • Sebastian Money -另一个处理货币值的库
  • Swap -一个汇率库

 

PDF

处理PDF文件的库和软件

  • Snappy -一个PDF和图像生成器库
  • WKHTMLToPDF -一个将HTML转换为PDF的工具

 

Database 数据库

使用对象关系映射(ORM)或数据映射技术的数据库交互库

  • Doctrine -一个全面的DBAL和ORM
  • Doctrine Extensions -一个Doctrine行为扩展的集合
  • Propel – 一个快速的ORM,迁移库和查询构架器
  • Eloquent -Laravel 4 ORM
  • Baum -一个Eloquent的嵌套集实现
  • Spot2 -一个MySQL的ORM映射器
  • RedBean -一个轻量级,低配置的ORM
  • Pomm -一个PostgreSQL对象模型管理器
  • ProxyManager -一个为数据映射生成代理对象的工具集

 

Migrations 迁移

帮助管理数据库模式和迁移的库

 

NoSQL

处理NoSQL后端的库

  • MongoQB -一个MongoDB查询构建库
  • Monga -一个MongoDB抽象库
  • Predis – 一个功能完整的Redis库

 

Queue 队列

处理事件和任务队列的库

 

Search 搜索

在数据上索引和执行查询的库和软件

 

Command Line 命令行

构建命令行工具的库

  • Boris – 一个微型PHP REPL
  • PsySH – 另一个微型PHP REPL
  • Pecan -一个事件驱动和非阻塞内核
  • GetOpt – 一个命令行选择解析器
  • OptParse -另一个命令行选择解析器
  • Commando -另一个简单的命令行选择解析器
  • GetOptionKit -另一个命令行选择解析器
  • Cron Expression -计算cron运行日期的库
  • ShellWrap -一个简单的命令行包装库
  • Hoa Console -另一个命令行库
  • Shunt – 一个在多台远程机器上并行运行命令行的库
  • Cilex -一个构建命令行工具的微型框架

 

Authentication 身份验证

实现身份验证的库

  • Sentry -一个混合的身份验证和授权的框架库
  • Sentry Social -一个社交网络身份验证库
  • Opauth -一个多渠道的身份验证框架
  • OAuth2 -一个OAuth2身份验证服务,资源服务器和客户端库
  • OAuth2 Server -另一个OAuth2服务器实现
  • PHP oAuthLib -另一个OAuth库
  • TwitterOAuth -一个Twitter OAuth库
  • TwitterSDK -一个完全测试的Twitter SDK
  • Hawk -一个Hawk HTTP身份认证库
  • HybridAuth -一个开源的社交登陆库

 

Markup 标记

处理标记的库

 

Strings 字符串

解析和处理字符串的库

 

Numbers 数字

处理数字的库

 

Filtering and Validation 过滤和验证

过滤和验证数据的库

  • Filterus – 一个简单的PHP过滤库
  • Respect Validate -一个简单的验证库
  • Valitron -另一个验证库
  • Upload – 一个处理文件上传和验证的库
  • DMS Filter – 一个注释过滤库
  • MetaYaml -一个支持YAML,JSON和XML的模式验证库
  • ISO-codes -验证各种ISO和ZIP编码的库(IBAN, SWIFT/BIC, BBAN, VAT, SSN, UKNIN)

 

 REST和API

开发REST-ful API的库和web工具

  • Apigility -一个使用Zend Framework 2构建的API构建器
  • Hateoas -一个HOATEOAS REST web服务库
  • HAL -一个超文本应用语言(HAL)构建库
  • Negotiation -一个内容协商库
  • Drest -一个将Doctrine实体暴露为REST资源节点的库
  • Restler -一个将PHP方法暴露为RESTful web API的轻量级框架

 

Caching 缓存

缓存数据的库

 

数据结构和存储

实现数据结构和存储技术的库

  • Ardent -一个数据结构库
  • PHP Collections – 一个简单的集合库
  • Serializer -一个序列化和反序列化数据的库
  • PHP Object Storage -一个对象存储库
  • Fractal -一个转换复杂数据结构到JSON输出的库
  • Totem -一个管理和穿件数据交换集的库
  • PINQ -一个PHP实时Linq库
  • JsonMapper -一个将内嵌JSON结构映射为PHP类的库

 

Notifications 通知

处理通知软件的库

 

Deployment 部署

项目部署库

  • Pomander -一个PHP应用部署工具
  • Rocketeer -PHP世界里的一个快速简单的部署器
  • Envoy -一个用PHP运行SSH任务的工具
  • Plum – 一个部署库

 

国际化和本地化

国际化(I18n)和本地化(L10n)

 

第三方API

访问第三方API的库

 

Extensions 扩展

帮组构建PHP扩展的库

  • Zephir -用于开发PHP扩展,且介于PHP和C++之间的编译语言
  • PHP CPP -一个开发PHP扩展的C++库

 

Miscellaneous 杂项

不在上面分类中的有用库和工具

 

Software 软件

创建一个开发环境的软件

PHP安装

在你的电脑上帮助安装和管理PHP的工具

  • HomeBrew -一个OSX包管理器
  • HomeBrew PHP -一个HomeBrew的PHP通道
  • PHP OSX – 一个OSX下的PHP安装器
  • PHP Brew -一个PHP版本管理和安装器
  • PHP Env – 另一个PHP版本管理器
  • PHP Switch – 另一个PHP版本管理器
  • PHP Build – 另一个PHP版本安装器
  • VirtPHP – 一个创建和管理独立PHP环境的工具

 

Development Environment 开发环境

创建沙盒开发环境的软件和工具

  • Vagrant -一个便携的开发环境工具
  • Ansible – 一个非常简单的编制框架
  • Puppet -一个服务器自动化框架和应用
  • PuPHPet -一个构建PHP开发虚拟机的web工具
  • Protobox -另一个构建PHP开发虚拟机的web工具
  • Phansible – 一个用Ansible构建PHP开发虚拟机的web工具

 

Virtual Machines 虚拟机

相关的PHP虚拟机

  • HipHop PHP -Facebook出品的PHP虚拟机,运行时和JIT
  • HippyVM -另一个PHP虚拟机
  • Hack – 一个PHP进行无缝操作的 HHVM编程语言

IDE 集成开发环境

支持PHP的集成开发环境

 

Web Applications Web应用

基于Web的应用和工具

  • 3V4L一个在线的PHP shell
  • DBV -一个数据库版本控制应用
  • PHP Queue -一个管理后端队列的应用
  • Composer as a Service – 作为一个zip文件下载Composer包的工具
  • MailCatcher – 一个抓取和查看邮件的web工具

 

Resources 资源

各种提高你的PHP开发技能和知识的资源,比如书籍,网站,文章

PHP网站

PHP相关的有用网站

 

Other Websites 其他网站

web开发相关的有用网站

 

PHP 书籍

PHP相关的非常好的书籍

 

其他书籍

与一般计算和web开发相关的书

 

PHP视频

PHP相关的非常不错的视频

 

PHP阅读

PHP相关的阅读资料

 

PHP Internals Reading PHP内核阅读

阅读PHP内核或性能相关的资料

使用git和github进行协同开发流程(转载)

目录

  • 前言
  • 仓库(Repository)
    • 源仓库
    • 开发者仓库
  • 分支(Branch)
    • 永久性分支
    • 暂时性分支
  • 工作流(workflow)
  • 总结
  • 参考资料

前言

(本文假设各位已经对基本git的基本概念、操作有一定的理解,如无相关git知识,可以参考Pro Git这本书进行相关的学习和练习)

很多项目开发都会采用git这一优秀的分布式版本管理工具进行项目版本管理,使用github开源平台作为代码仓库托管平台。由于git的使用非常灵活,在实践当中衍生了很多种不同的工作流程,不同的项目、不同的团队会有不同的协作方式。

本文将介绍一种前人已经在各种大小项目中经过千锤百炼总结出来的一种比较成功的git工作流,这种工作流已经被成功用于许多团队开发当中。掌握git,掌握这种工作流,对大家以后的学习、开发工作大有好处。

先上一张图吓大家一下:

workflow

上面一张图展示了一种使用git进行项目协同开发的模式,接下来会进行详细介绍。

仓库(Repository)

在项目的开始到结束,我们会有两种仓库。一种是源仓库(origin),一种是开发者仓库。上图中的每个矩形都表示一个仓库,正中间的是我们的源仓库,而其他围绕着源仓库的则是开发者仓库。

源仓库

在项目的开始,项目的发起者构建起一个项目的最原始的仓库,我们把它称为origin,例如我们的PingHackers网站,origin就是这个PingHackers/blog了。源仓库的有两个作用:

  1. 汇总参与该项目的各个开发者的代码
  2. 存放趋于稳定和可发布的代码

源仓库应该是受保护的,开发者不应该直接对其进行开发工作。只有项目管理者(通常是项目发起人)能对其进行较高权限的操作。

开发者仓库

上面说过,任何开发者都不会对源仓库进行直接的操作,源仓库建立以后,每个开发者需要做的事情就是把源仓库的“复制”一份,作为自己日常开发的仓库。这个复制,也就是github上面的fork

每个开发者所fork的仓库是完全独立的,互不干扰,甚至与源仓库都无关。每个开发者仓库相当于一个源仓库实体的影像,开发者在这个影像中进行编码,提交到自己的仓库中,这样就可以轻易地实现团队成员之间的并行开发工作。而开发工作完成以后,开发者可以向源仓库发送pull request,请求管理员把自己的代码合并到源仓库中,这样就实现了分布式开发工作,和最后的集中式的管理。

分支(Branch)

分支是git中非常重要的一个概念,也是git这一个工具中的大杀器,必杀技。在其他集中式版本管理工具(SVN/CVS)把分支定位为高级技巧,而在git中,分支操作则是每个开发人员日常工作流。利用git的分支,可以非常方便地进行开发和测试,如果使用git没有让你感到轻松和愉悦,那是因为你还没有学会使用分支。不把分支用出一点翔来,不要轻易跟别人说你用过git。

在文章开头的那张图中,每一个矩形内部纷繁的枝蔓便是git的分支模型。可以看出,每个开发者的仓库都有自己的分支路线,而这些分支路线会通过代码汇总映射到源仓库中去。

我们为git定下一种分支模型,在这种模型中,分支有两类,五种

  • 永久性分支
    • master branch:主分支
    • develop branch:开发分支
  • 临时性分支
    • feature branch:功能分支
    • release branch:预发布分支
    • hotfix branch:bug修复分支

永久性分支

永久性分支是寿命无限的分支,存在于整个项目的开始、开发、迭代、终止过程中。永久性分支只有两个masterdevelop

master:主分支从项目一开始便存在,它用于存放经过测试,已经完全稳定代码;在项目开发以后的任何时刻当中,master存放的代码应该是可作为产品供用户使用的代码。所以,应该随时保持master仓库代码的清洁和稳定,确保入库之前是通过完全测试和代码reivew的。master分支是所有分支中最不活跃的,大概每个月或每两个月更新一次,每一次master更新的时候都应该用git打上tag,说明你的产品有新版本发布了。

develop:开发分支,一开始从master分支中分离出来,用于开发者存放基本稳定代码。之前说过,每个开发者的仓库相当于源仓库的一个镜像,每个开发者自己的仓库上也有masterdevelop。开发者把功能做好以后,是存放到自己的develop中,当测试完以后,可以向管理者发起一个pull request,请求把自己仓库的develop分支合并到源仓库的develop中。

所有开发者开发好的功能会在源仓库的develop分支中进行汇总,当develop中的代码经过不断的测试,已经逐渐趋于稳定了,接近产品目标了。这时候,我们就可以把develop分支合并到master分支中,发布一个新版本。所以,一个产品不断完善和发布过程就正如下图:

master & develop

注意,任何人不应该向master直接进行无意义的合并、提交操作。正常情况下,master只应该接受develop的合并,也就是说,master所有代码更新应该源于合并develop的代码。

暂时性分支

暂时性分支和永久性分支不同,暂时性分支在开发过程中是一定会被删除的。所有暂时性分支,一般源于develop,最终也一定会回归合并到develop

feature:功能性分支,是用于开发项目的功能的分支,是开发者主要战斗阵地。开发者在本地仓库从develop分支分出功能分支,在该分支上进行功能的开发,开发完成以后再合并到develop分支上,这时候功能性分支已经完成任务,可以删除。功能性分支的命名一般为feature-*,*为需要开发的功能的名称。

feature branch

举一个例子,假设我是一名PingHackers网站的开发者,已经把源仓库fork了,并且clone到了本地。现在要开发PingHackers网站的“讨论”功能。我在本地仓库中可以这样做:

step 1: 切换到develop分支

    >>> git checkout develop

step 2: 分出一个功能性分支

    >>> git checkout -b feature-discuss

step 3: 在功能性分支上进行开发工作,多次commit,测试以后…

step 4: 把做好的功能合并到develop

    >>> git checkout develop

    # 回到develop分支

    >>> git merge --no-ff feature-discuss
    # 把做好的功能合并到develop中

    >>> git branch -d feature-discuss
    # 删除功能性分支

    >>> git push origin develop
    # 把develop提交到自己的远程仓库中

这样,就完成一次功能的开发和提交。

release:预发布分支,当产品即将发布的时候,要进行最后的调整和测试,这时候就可以分出一个预发布分支,进行最后的bug fix。测试完全以后,发布新版本,就可以把预发布分支删除。预发布分支一般命名为release-*

hotfix:修复bug分支,当产品已经发布了,突然出现了重大的bug。这时候就要新建一个hotfix分支,继续紧急的bug修复工作,当bug修复完以后,把该分支合并到masterdevelop以后,就可以把该分支删除。修复bug分支命名一般为hotfix-*

releasehotfix分支离我们还比较遥远。。就不详述,有兴趣的同学可以参考本文最后的参考资料进行学习。

工作流(Workflow)

啰嗦讲了这么多,概念永远是抽象的。对于新手来说,都喜欢一步一步的步骤傻瓜教程,接下来,我们就一步一步来操作上面所说的工作流程,大家感受一下:

Step 1:源仓库的构建

这一步通常由项目发起人来操作,我们这里把管理员设为PingHackers,假设PingHackers已经为我们建立起了一个源仓库PingHackers/git-demo,并且已经初始化了两个永久性分支masterdevelop,如图:

origin

Step 2:开发者fork源仓库

源仓库建立以后,每个开发就可以去复制一份源仓库到自己的github账号中,然后作为自己开发所用的仓库。假设我是一个项目中的开发者,我就到PingHackers/git-demo项目主页上去fork

fork

fork完以后,我就可以在我自己的仓库列表中看到一个和源仓库一模一样的复制品。这时就应该感叹,你以后要和它相依为命了:

fork-origin

Step 3:把自己开发者仓库clone到本地

这一步应该不用教,git clone

Step 4:构建功能分支进行开发

进入仓库中,按照前面说所的构建功能分支的步骤,构建功能分支进行开发、合并,假设我现在要开发一个“讨论”功能:

    >>> git checkout develop
    # 切换到`develop`分支

    >>> git checkout -b feature-discuss
    # 分出一个功能性分支

    >> touch discuss.js
    # 假装discuss.js就是我们要开发的功能

    >> git add .
    >> git commit -m 'finish discuss feature'
    # 提交更改

    >>> git checkout develop
    # 回到develop分支

    >>> git merge --no-ff feature-discuss
    # 把做好的功能合并到develop中

    >>> git branch -d feature-discuss
    # 删除功能性分支

    >>> git push origin develop
    # 把develop提交到自己的远程仓库中

这时候,你上自己github的项目主页中develop分支中看看,已经有discuss.js这个文件了:

push

Step 5:向管理员提交pull request

假设我完成了“讨论”功能(当然,你还可能对自己的develop进行了多次合并,完成了多个功能),经过测试以后,觉得没问题,就可以请求管理员把自己仓库的develop分支合并到源仓库的develop分支中,这就是传说中的pull request

pull-request

点击上图的绿色按钮,开发者就可以就可以静静地等待管理员对你的提交的评审了。

pull-finished

Step 6 管理员测试、合并

接下来就是管理员的操作了,作为管理员的PingHackers登陆github,便看到了我对源仓库发起的pull request

pull-request-origin

这时候PingHackers需要做的事情就是:

  1. 对我的代码进行review。github提供非常强大的代码review功能: reivew
  2. 在他的本地测试新建一个测试分支,测试我的代码:
    >> git checkout develop
    # 进入他本地的develop分支

    >> git checkout -b livoras-develop
    # 从develop分支中分出一个叫livoras-develop的测试分支测试我的代码

    >> git pull https://github.com/livoras/git-demo.git develop
    # 把我的代码pull到测试分支中,进行测试
  1. 判断是否同意合并到源仓库的develop,如果经过测试没问题,可以把我的代码合并到源仓库的develop中:
    >> git checkout develop
    >> git merge --no-ff livoras-develop
    >> git push origin develop

注意,PingHakers一直在操作的仓库是源仓库。所以我们经过上面一系列操作以后,就可以在源仓库主页中看到:

merge

经过辗转曲折的路程,我们的discuss.js终于从我的开发仓库的功能分支到达了源仓库的develop分支中。以上,就是一个git & github协同工作流的基本步骤。

总结

git这一个工具博大精深,使用如此恶心而又如此灵活和优雅的工具;此又为一神器,大家还是多动手,多查资料,让git成为自己的一项基本技能,帮助自己处理各种项目团队协同工作的问题,成为一个高效的开发者、优秀的项目的管理者。送大家一张神图,好好领悟:

Overview

最后给出一些参考资料,供参考学习。

参考资料

PHP经验——PHPDoc PHP注释的标准文档(翻译自Wiki)

文档注释,无非“//”和“/**/”两种 ,自己写代码,就那么点,适当写几句就好了;但是一个人总有融入团队的一天,团队的交流不是那几句注释和一张嘴能解决的,还需要通用的注释标准。

PHPDoc是PHP文档注释的一个标准,可以帮助我们在注释文档时有规范,查看别人的代码时更方便。下面的表格是我翻译的WIKI上的PHPDoc,个人英文水平有限,可以参照原文。

文档翻译自:http://en.wikipedia.org/wiki/Phpdoc

 

标记 用途 描述
@abstract 抽象类的变量和方法
@access public, private or protected 文档的访问、使用权限. @access private 表明这个文档是被保护的。
@author 张三 <zhangsan@163.com> 文档作者
@copyright 名称 时间 文档版权信息
@deprecated version 文档中被废除的方法
@deprec 同 @deprecated
@example /path/to/example 文档的外部保存的示例文件的位置。
@exception   文档中方法抛出的异常,也可参照 @throws.
@global 类型:$globalvarname 文档中的全局变量及有关的方法和函数
@ignore 忽略文档中指定的关键字
@internal 开发团队内部信息
@link URL 类似于license 但还可以通过link找到文档中的更多个详细的信息
@name 变量别名 为某个变量指定别名
@magic phpdoc.de compatibility
@package 封装包的名称 一组相关类、函数封装的包名称
@param 如 [$username] 用户名 变量含义注释
@return 如 返回bool 函数返回结果描述,一般不用在void(空返回结果的)的函数中
@see 如 Class Login() 文件关联的任何元素(全局变量,包括,页面,类,函数,定义,方法,变量)。
@since version 记录什么时候对文档的哪些部分进行了更改
@static   记录静态类、方法
@staticvar 在类、函数中使用的静态变量
@subpackage 子版本
@throws 某一方法抛出的异常
@todo   表示文件未完成或者要完善的地方
@var type 文档中的变量及其类型
@version   文档、类、函数的版本信息

原文截图:

<code>

<?php
/**
* start page for webaccess
*
* PHP version 5
*
* @category PHP
* @package PSI_Web
* @author Michael Cramer <BigMichi1@users.sourceforge.net>
* @copyright 2009 phpSysInfo
* @license http://opensource.org/licenses/gpl-2.0.php GNU General Public License
* @version SVN: $Id: class.Webpage.inc.php 412 2010-12-29 09:45:53Z Jacky672 $
* @link http://phpsysinfo.sourceforge.net
*/
/**
* generate the dynamic webpage
*
* @category PHP
* @package PSI_Web
* @author Michael Cramer <BigMichi1@users.sourceforge.net>
* @copyright 2009 phpSysInfo
* @license http://opensource.org/licenses/gpl-2.0.php GNU General Public License
* @version Release: 3.0
* @link http://phpsysinfo.sourceforge.net
*/
class Webpage extends Output implements PSI_Interface_Output
{
/**
* configured language
*
* @var String
*/
private $_language;

/**
* configured template
*
* @var String
*/
private $_template;

/**
* all available templates
*
* @var Array
*/
private $_templates = array();

/**
* all available languages
*
* @var Array
*/
private $_languages = array();

/**
* check for all extensions that are needed, initialize needed vars and read config.php
*/
public function __construct()
{
parent::__construct();
$this->_getTemplateList();
$this->_getLanguageList();
}

/**
* checking config.php setting for template, if not supportet set phpsysinfo.css as default
* checking config.php setting for language, if not supported set en as default
*
* @return void
*/
private function _checkTemplateLanguage()
{
$this->_template = trim(PSI_DEFAULT_TEMPLATE);
if (!file_exists(APP_ROOT.’/templates/’.$this->_template.”.css”)) {
$this->_template = ‘phpsysinfo’;
}

$this->_language = trim(PSI_DEFAULT_LANG);
if (!file_exists(APP_ROOT.’/language/’.$this->_language.”.xml”)) {
$this->_language = ‘en’;
}
}

/**
* get all available tamplates and store them in internal array
*
* @return void
*/
private function _getTemplateList()
{
$dirlist = CommonFunctions::gdc(APP_ROOT.’/templates/’);
sort($dirlist);
foreach ($dirlist as $file) {
$tpl_ext = substr($file, strlen($file) – 4);
$tpl_name = substr($file, 0, strlen($file) – 4);
if ($tpl_ext === “.css”) {
array_push($this->_templates, $tpl_name);
}
}
}

/**
* get all available translations and store them in internal array
*
* @return void
*/
private function _getLanguageList()
{
$dirlist = CommonFunctions::gdc(APP_ROOT.’/language/’);
sort($dirlist);
foreach ($dirlist as $file) {
$lang_ext = substr($file, strlen($file) – 4);
$lang_name = substr($file, 0, strlen($file) – 4);
if ($lang_ext == “.xml”) {
array_push($this->_languages, $lang_name);
}
}
}

/**
* render the page
*
* @return void
*/
public function run()
{
$this->_checkTemplateLanguage();

$tpl = new Template(“/templates/html/index_dynamic.html”);

$tpl->set(“template”, $this->_template);
$tpl->set(“templates”, $this->_templates);
$tpl->set(“language”, $this->_language);
$tpl->set(“languages”, $this->_languages);

echo $tpl->fetch();
}
}
?>

</code>