如何文档化你的PHP类(一)
作者:stefano Locati 翻译:limodou
你已经阅读过关于:面向对象编程可以帮助你管理你的大型web项目,并且你已经开始使用PHP来进行面向对象编程了吗?如果你已经编写了几个类应用在网站上并且你是一个有条理的人的话,那么你应该已经编写了关于它们的一些文档。但是如果你是一个象我一样的不拘小节的人,你只是会在类的源代码中加一些注释而没有别的文档。没有文档就很难记住方法的名字和它们的使用方法(参数和含义)。解决这种情况最典型的办法就是打开源代码文件,从成百上千的语句中查找。
类似Javadoc的文档
应该有一种好的方法----如果你曾经使用过Java语言,你将知道Javadoc文档系统。这个工具允许你在源代码文件注释中插入一些标记,这些标记可以被Javadoc工具进行分析以便生成一系列的HTML页面把你的类文档化。那样在编程的同时你可以开着浏览器并且可以得到类列表和带有说明的类方法的列表。在你开发web应用时,这个可以成为你的参考,提高工作效率和加快开发速度。
我的意见是维护一个作为源代码内的引用文档要比维护一个独立的文档要容易和更实用,因为这个方法更容易保持更新。否则就非常容易变得懒惰从而将对文档的更新推后到无限期(如果一定要给它加个期限,我想是一万年)。相反使用象这样的一个工具,只有一点工作量就是在你正在修改的源代码附近更新一个标记,接着运行工具再一次生成更新过的HTML页面。
一些php文档工具的预览
在对上面了解了之后,我搜索了一下哪些是可用的,并且我发现了如下一些有趣的工具:
phpSearchdoc是enzyme项目的一部分。因为enzyme 是一个巨大的项目,所以需要将其文档化。那里的开发人员已经编写了他们自已的文档系统并且他们非常慷慨地将其作为一个独立的包进行发布。得到的文档首先被写入数据库,然后可以被一些PHP脚本查看,象一个动态的web站点。
从现存的信息中将用于分析的逻辑分离出来的想法相当好,然而phpSearchdoc(版本 1.01)不具有一个真正的分析器,而是从源文件,甚至包括注释中搜索关键字。事实上,对我来说碰巧发生过在我的注释中存在'function'单词,结果分析器愚蠢地认为在这个单词后面的词就是函数的名字。更不幸的是,我不巧在同一行放了一个单引号('),接着我试图将数据写到数据库中,mysql作出了抱怨(出错了,因为单引号在 mysql中被用于分割字符串)。
而且它的安装及运行相当困难,因为它还是一个alpha测试版。毕竟比起文档系统来说它更象是一个交叉引用生成器,正如我知道的,你不能在函数和方法中加入自已的注释。
phpxref,就象名字所指的比起一个真正 的文档系统来似乎更象是面向交叉引用的生成处理。更进一步说它更适合于正常的过程化编程而不是面向对象编程。
phpautodoc的目标是实现象Javadoc 应用于Java那样用于PHP。它看上去是满足我的文档需求的完美解决。为了试验它我不得不编译了PHP的CGI版本(我通常使用模块版本),因为生成器是用PHP编的。我可能容易地在一个Linux系统下编译和安装静态的执行程序,可以使用这些命令:
rm config.chche
make clean
./configure
make
cp php /usr/local/bin
我决定对它自已的PHP源码进行测试,并且我发现它只有部分可以工作:它只能够生成类的文档(生成整齐的格式),但是不能生成小结。我不知道是否这个只是碰巧发生在我的机器上,但是在试图生成小结时却因为core dump(内核崩溃)而停止(PHP 4.0 pl2,RedHat 6.2环境)。假如在你的机器/usr/local/bin下安装了PHP执行版本,调用它的语法是(为了得到结果我不得不给出php文件和输出目录的全路径)
./phpautodoc -o
phpdoc是一个用来维护在Web站点上的php 文件,并且它非常适合分布式开发方式。文档是从数据库中生成;在安装之后,你可以使用web界面来增加你的类将其文档化。这个的确有意思,但是它是一种低级的从源代码中分离文档的维护方法,这一点就我来说不是非常方便。
通用工具
在经受了试验所有这些工具但却得不到怎么成功的挫折之后,直到Pear Project提出了一种标准的解决方法,我发现了一个与PHP完全无关的可工作的工具在Open Source Projects at Apple站点。项目的名字是 HeaderDoc。就象站点所说的" HeaderDoc是一种从C或C++头文件的注释中生成HTML的引用文档的工具。它是用Perl编写的以便于移植。与JavaDoc 相似,它允许开发者容易地文档化他们的接口,并且将接口信息输出到HTML。"
是的,你看的没错,HeaderDoc只支持C和C++。没有其它的语言,但是它不象JavaDoc,它大部分依赖写在注释中的标记,所以只要做些小改动(我会在后面解释)就可以很好的用在PHP上。这些标记同JavaDoc很象,HeaderDoc标记的一些例子是@class,@function和@var。
文档化一个类
OK,让我们现在进入细节吧。首先让我们看一下一个类如何被文档化。
--------------------------------------------------------------------------------
/*! @class BagItem
@abstract An item in the shopping bag - it is a shopitem with quantity
@discussion A BagItem object may be constructed without previous
instantiation of neither ShopItem nor Product
*/
--------------------------------------------------------------------------------
文档化一个类。可以在左边的帧选择类的方法。
第一件需要注意的事情是用在打开注释上的风格不完全象JavaDoc注释/**(一个斜线和两个星号),而是换成/*!(一个斜线,一个星号和一个感叹号) 。标记使用也不一样,但是它们以相似的方式工作。例如,第一个标记是@class标记,它用于文档化一个类,这个标记跟着类的名字。下一个标记是@abstract 标记,它
是一个可选的标记,用少量词语来描述一个类的含义,同时@discussion 标记是另一个可选的标记,用于进一步的讨论。当然由你来决定是在@discussion标记中描述所有的事情还是使用@abstract来处理,但是要记住,一般来说,你使用的标记越精确,结果就越好。
原作者:limodou
来源:PHPX

PHP tetap penting dalam pembangunan web moden, terutamanya dalam pengurusan kandungan dan platform e-dagang. 1) PHP mempunyai ekosistem yang kaya dan sokongan rangka kerja yang kuat, seperti Laravel dan Symfony. 2) Pengoptimuman prestasi boleh dicapai melalui OPCACHE dan NGINX. 3) Php8.0 memperkenalkan pengkompil JIT untuk meningkatkan prestasi. 4) Aplikasi awan asli dikerahkan melalui Docker dan Kubernet untuk meningkatkan fleksibiliti dan skalabiliti.

PHP sesuai untuk pembangunan web, terutamanya dalam pembangunan pesat dan memproses kandungan dinamik, tetapi tidak baik pada sains data dan aplikasi peringkat perusahaan. Berbanding dengan Python, PHP mempunyai lebih banyak kelebihan dalam pembangunan web, tetapi tidak sebaik python dalam bidang sains data; Berbanding dengan Java, PHP melakukan lebih buruk dalam aplikasi peringkat perusahaan, tetapi lebih fleksibel dalam pembangunan web; Berbanding dengan JavaScript, PHP lebih ringkas dalam pembangunan back-end, tetapi tidak sebaik JavaScript dalam pembangunan front-end.

PHP dan Python masing -masing mempunyai kelebihan sendiri dan sesuai untuk senario yang berbeza. 1.PHP sesuai untuk pembangunan web dan menyediakan pelayan web terbina dalam dan perpustakaan fungsi yang kaya. 2. Python sesuai untuk sains data dan pembelajaran mesin, dengan sintaks ringkas dan perpustakaan standard yang kuat. Apabila memilih, ia harus diputuskan berdasarkan keperluan projek.

PHP adalah bahasa skrip yang digunakan secara meluas di sisi pelayan, terutamanya sesuai untuk pembangunan web. 1.PHP boleh membenamkan HTML, memproses permintaan dan respons HTTP, dan menyokong pelbagai pangkalan data. 2.PHP digunakan untuk menjana kandungan web dinamik, data borang proses, pangkalan data akses, dan lain -lain, dengan sokongan komuniti yang kuat dan sumber sumber terbuka. 3. PHP adalah bahasa yang ditafsirkan, dan proses pelaksanaan termasuk analisis leksikal, analisis tatabahasa, penyusunan dan pelaksanaan. 4.Php boleh digabungkan dengan MySQL untuk aplikasi lanjutan seperti sistem pendaftaran pengguna. 5. Apabila debugging php, anda boleh menggunakan fungsi seperti error_reporting () dan var_dump (). 6. Mengoptimumkan kod PHP untuk menggunakan mekanisme caching, mengoptimumkan pertanyaan pangkalan data dan menggunakan fungsi terbina dalam. 7

Sebab mengapa PHP adalah timbunan teknologi pilihan untuk banyak laman web termasuk kemudahan penggunaannya, sokongan komuniti yang kuat, dan penggunaan yang meluas. 1) Mudah dipelajari dan digunakan, sesuai untuk pemula. 2) Mempunyai komuniti pemaju yang besar dan sumber yang kaya. 3) Digunakan secara meluas dalam platform WordPress, Drupal dan lain -lain. 4) Mengintegrasikan dengan ketat dengan pelayan web untuk memudahkan penggunaan pembangunan.

PHP kekal sebagai alat yang kuat dan digunakan secara meluas dalam pengaturcaraan moden, terutamanya dalam bidang pembangunan web. 1) PHP mudah digunakan dan diintegrasikan dengan lancar dengan pangkalan data, dan merupakan pilihan pertama bagi banyak pemaju. 2) Ia menyokong penjanaan kandungan dinamik dan pengaturcaraan berorientasikan objek, sesuai untuk membuat dan mengekalkan laman web dengan cepat. 3) Prestasi PHP dapat ditingkatkan dengan caching dan mengoptimumkan pertanyaan pangkalan data, dan komuniti yang luas dan ekosistem yang kaya menjadikannya masih penting dalam timbunan teknologi hari ini.

Dalam PHP, rujukan lemah dilaksanakan melalui kelas lemah dan tidak akan menghalang pemungut sampah daripada menebus objek. Rujukan lemah sesuai untuk senario seperti sistem caching dan pendengar acara. Harus diingat bahawa ia tidak dapat menjamin kelangsungan hidup objek dan pengumpulan sampah mungkin ditangguhkan.

Kaedah \ _ \ _ membolehkan objek dipanggil seperti fungsi. 1. Tentukan kaedah \ _ \ _ supaya objek boleh dipanggil. 2. Apabila menggunakan sintaks $ OBJ (...), PHP akan melaksanakan kaedah \ _ \ _ invoke. 3. Sesuai untuk senario seperti pembalakan dan kalkulator, meningkatkan fleksibiliti kod dan kebolehbacaan.


Alat AI Hot

Undresser.AI Undress
Apl berkuasa AI untuk mencipta foto bogel yang realistik

AI Clothes Remover
Alat AI dalam talian untuk mengeluarkan pakaian daripada foto.

Undress AI Tool
Gambar buka pakaian secara percuma

Clothoff.io
Penyingkiran pakaian AI

AI Hentai Generator
Menjana ai hentai secara percuma.

Artikel Panas

Alat panas

MinGW - GNU Minimalis untuk Windows
Projek ini dalam proses untuk dipindahkan ke osdn.net/projects/mingw, anda boleh terus mengikuti kami di sana. MinGW: Port Windows asli bagi GNU Compiler Collection (GCC), perpustakaan import yang boleh diedarkan secara bebas dan fail pengepala untuk membina aplikasi Windows asli termasuk sambungan kepada masa jalan MSVC untuk menyokong fungsi C99. Semua perisian MinGW boleh dijalankan pada platform Windows 64-bit.

Versi Mac WebStorm
Alat pembangunan JavaScript yang berguna

SecLists
SecLists ialah rakan penguji keselamatan muktamad. Ia ialah koleksi pelbagai jenis senarai yang kerap digunakan semasa penilaian keselamatan, semuanya di satu tempat. SecLists membantu menjadikan ujian keselamatan lebih cekap dan produktif dengan menyediakan semua senarai yang mungkin diperlukan oleh penguji keselamatan dengan mudah. Jenis senarai termasuk nama pengguna, kata laluan, URL, muatan kabur, corak data sensitif, cangkerang web dan banyak lagi. Penguji hanya boleh menarik repositori ini ke mesin ujian baharu dan dia akan mempunyai akses kepada setiap jenis senarai yang dia perlukan.

Dreamweaver Mac版
Alat pembangunan web visual

Pelayar Peperiksaan Selamat
Pelayar Peperiksaan Selamat ialah persekitaran pelayar selamat untuk mengambil peperiksaan dalam talian dengan selamat. Perisian ini menukar mana-mana komputer menjadi stesen kerja yang selamat. Ia mengawal akses kepada mana-mana utiliti dan menghalang pelajar daripada menggunakan sumber yang tidak dibenarkan.