Expert PHP 5 Tools phần 3 doc

* Simplified client code might look like this: The differences from the standard @example tag is that the referenced source code will be displayed inline and that it is possible to limit

Trang 1

[ 77 ]

@method

@method return_type method_name(type $arg1[

= val1], type $arg2[ = val2], …) [description] [x]

methods provided by the class Any method documented this way will be listed on the class-level documentation

Comments:

Creates an alias for a global variable for documentation purposes (also see @global tag)

Download from Wow! eBook

www.WoweBook.com

Trang 2

This tag defines a logical grouping of elements within the documentation A file-level

@package tag will apply to all elements within that file; however, package membership

of classes will be default unless explicitly set for the class itself This is true even if the

file-level package tag has been set! The only exception is that sub-classes inherit their parent class's package membership

@property

@property data_type $var_name [description]

@property-read datatype $varname [description]

@property-write datatype $varname [description]

private $greeting = 'Hello, Stranger!';

public function get($property)

Trang 3

Usage 1: @see [ClassName::]methodName()

Usage 2: @see [ClassName::]$property_name

Usage 3: @see php_function_name

or {@link} for creating hyperlinks to external resources

www.WoweBook.com

Trang 6

@link, or inline {@link} tags instead.

@uses

@uses [ClassName::]methodName() description [x] [x] [x] [x]

@var

Example(s):

/**

* @var string full user name for logging purposes

Trang 7

You can use this tag to record your own versioning A common use if this tag is to put

a placeholder that will automatically be replaced by the version control system's revision

or version number upon committing the change (see the chapter on source code control for more detail)

Inline tags

Inline tags differ from standard text in that they can occur anywhere within the text

of the short or long description of a DocBlock To properly differentiate inline tags from the description, their syntax differs a bit from standard tags in that they are enclosed by curly brackets When parsed by phpDocumentor and rendered by the desired converter, these tags are replaced by content that is being placed inline with the rest of the text

In addition to DocBlock descriptions, inline tags can be used in tutorials There are a total of six inline tags, four of which can be used in DocBlocks and a different set of four can be used in tutorials

www.WoweBook.com

Trang 8

* Before being able to access the web services API,

* a client has to authenticate via this login method.

* Simplified client code might look like this:

The differences from the standard @example tag is that the referenced source code will

be displayed inline and that it is possible to limit the listing by start and end line number within the file

Trang 9

Comments:

When using a @tutorial tag to link to a particular tutorial, it is possible to directly link to specific sections within the referenced document The {@id} tag allows one to assign the desired section an identifier that can be used in the link The general structure of building a link to a sub-section of a tutorial looks like this:

package.package_name[.sub-package_name].file[.section_name]

[sub-section_name]

www.WoweBook.com

Trang 10

* Use this class and its methods to obtain an authentication

* token that will be used during the session {@internal This

* must be discussed with the architectural committee See

* our {@link http://massivecorp.com/gl.html Massive Corp

Note: This tag ends in two closing curly brackets, which is necessary because itself can contain inline tags

Trang 11

* {@inheritdoc} Specifically, the user will have to supply

* a SecureID token during login.

www.WoweBook.com

Trang 12

Example(s):

/**

* This class handles authentication using Secured tokens.

* For more details on SecureID, you can consult

* the {@link http://en.wikipedia.org/wiki/SecurID the SecureID

{@source [start_line] [end_line]} [x] [x] [x]

* This method is to be called from the client before

* it can make any other API call All the heavy lifting

* is being done by this try-catch block: {@source 10 17}

* This is where we're calling the internal authentication

Trang 13

$success = true;

} } catch (Exception $e) {

www.WoweBook.com

Trang 14

Comments:

In a tutorial, inline {@id} tags can be used as anchors for links (see {@id} tag) The inline {@toc} tag creates a table of contents from all {@id} tags The {@toc} tag typically occurs within the opening and closing refentry DocBook tag

Trang 15

* Use this class to authenticate.

* For more details take a look at this

* tutorial: {@tutorial MyApp/Authenticate/Authenticate.cls}

be final, but you cannot actually declare it final because the keyword and the

corresponding concept do not exist in PHP4

Although you should be aware that these two tags exist, I recommend against

using them

www.WoweBook.com

Trang 16

Custom tags

Custom tags are surprisingly easy to implement There is no need to extend or overwrite any classes As a matter of fact, unless you have somewhat unusual requirements, all it takes is a command-line option Say you find a need to add a tag to indicate the date on which the last peer review of the source occurred and the name of person that performed it You could start using a @sourcereviewdate tag:

/**

* This class is absolutely critical to the survival

* and success or our application.

Summary

If the example in this chapter did not sell you on the benefits of documenting

your code using the phpDoc syntax, you only need to take a look at the API

documentation of some of the biggest PHP projects out there, such as Zend

Framework and Pear There is a reason that this method of documenting source code has been around for over ten years Programmers quickly get the big picture of how the various components come together Moreover, it also allows them to drill down

to the granular level of parameters, return values, and so on

If you are not in the habit of commenting your code, I suggest you start slowly Rather than documenting every single element, start with file and class-level

DocBlocks I suspect that you will quickly get used to creating documentation at the same time as code – especially when you see the results in the form of detailed and useful documentation Hopefully, you will feel encouraged enough to start documenting more elements and produce documentation that any programmer that might come across your code can benefit from

Trang 17

TTThhheee E EEcccllliiipppssseee IIInnnttteeegggrrraaattteeeddd

D Deeevvveeelllooopppm m meeennnttt E EEnnnvvviiirrrooonnnm m meeennnttt

wiiittthhh iiittt fffooorrr aaa lllooonnnggg tttiiimmmeee IIInnn mmmyyy cccaaassseee,,, vvviii eeedddiiitttiiinnnggg cccooommmmmmaaannndddsss hhhaaavvveee bbbeeecccooommmeee ssseeecccooonnnddd nnnaaatttuuurrreee tttooo mmmeee aaa lllooonnnggg tttiiimmmeee aaagggooo (((IIIfff yyyooouuu dddooonnn'''ttt kkknnnooowww,,, vvviii iiisss aaa cccooonnnsssooollleee -bbbaaassseeeddd ttteeexxxttt eeedddiiitttooorrr yyyooouuu wwwiiillllll fififinnnddd ooonnn mmmooosssttt UUUnnniiixxx///LLLiiinnnuuuxxx ooopppeeerrraaatttiiinnnggg sssyyysssttteeemmmsss))) WWWhhheeennn iiinnn aaa bbbiiinnnddd,,, III'''mmm aaalllwwwaaayyysss llliiikkkeeelllyyy tttooo aaacccccceeessssss aaa ssseeerrrvvveeerrr dddiiirrreeeccctttlllyyy tttooo qqquuuiiiccckkklllyyy cccooorrrrrreeecccttt aaa cccrrriiitttiiicccaaalll bbbuuuggg iiinnn vvviii HHHooowwweeevvveeerrr,,, III wwwooouuulllddd bbbeee aaa fffoooooolll nnnooottt tttooo eeexxxpppaaannnddd mmmyyy hhhooorrriiizzzooonnnsss aaannnddd llleeevvveeerrraaagggeee sssooommmeee ooofff ttthhheee aaammmaaazzziiinnnggg tttoooooolllsss ttthhhaaattt aaarrreee aaavvvaaaiiilllaaabbbllleee nnnooowww

Trang 18

In this chapter, I want to take a close look at one of those IDEs, namely Eclipse with the PDT plugin We haven't even gotten beyond the first page of this chapter and

I can already hear the objections: "… but what about <insert_favorite_ide_here>?

I know many developers that swear by it!"

I realize that Eclipse isn't the only game in town, but there are some compelling reasons to take a close look at what it has to offer, not the least of which is the fact that we cannot look at all the offerings After all, PHP has become a pretty popular language and there are quite a few options when assembling your tool chest Also, you should keep in mind that many of the concepts covered in this chapter translate across development environments For example, any IDE that supports debugging

is likely to give you a way of manipulating breakpoints, inspecting variables, and viewing stack traces Even if you decide not to use Eclipse, you can probably benefit from knowing about its benefits At the very least, it might help to convince you to invest the time to learn an IDE if you haven't done so already Here is a list of the topics we will be covering in this chapter:

• Introducing and installing Eclipse with PDT

• Basic Eclipse concepts, such as workspaces, views, and perspectives

• Creating a sample project

• Understanding and using features of the editor, including syntax lighting, code assist, code folding, marking occurrences, overriding

high-indicators, and navigating types, methods, and resources

• Inspecting projects, files, and libraries

• Interactive visual debugging

• Setting of preferences to customize the Eclipse

• Eclipse's plugin architecture and useful plugins environment

• Additional features offered by Zend's commercial Zend Studio for Eclipse

Why Eclipse?

Eclipse grew out of technology and concepts at IBM Prior to being announced as

an open source project in 2001, it already had several years of development and evolution under its belt Since then, thousands of developers have contributed and continue to contribute to the project This means that many of the core concepts and implementations of Eclipse are quite mature Moreover, the project was put into the hands of a newly formed not-for-profit foundation in 2004 In other words, Eclipse

is here to stay and is unlikely to disappear overnight like some software projects

Trang 19

Eclipse is not so much a development environment itself as it is the foundation for building such tools It provides all the basic tools that are common across the various offerings to leverage this strong underpinning For example, Eclipse provides a framework for accessing and manipulating data called the "Data Tools Platform" but it makes few assumptions on the underlying storage and provides no specific support for particular vendors Other developers can use that framework to build more specific tools The real benefit here is extensibility and reusability Since Eclipse depends on additional software to really shine, it comes as no surprise that it has a strong and easy to use plugin architecture It is very straightforward to locate and install plugins that add completely new functionality to your installation of Eclipse

In addition, the mechanism for keeping all those plugins up-to-date is also built right into Eclipse itself

Last, but not least, on our list of reasons to consider Eclipse as an IDE for PHP

development is that it is open source This point is certainly debatable There is nothing wrong with commercial software After all, I would expect that the audience for this book, including myself, is looking to get paid for PHP development on some level Nevertheless, I put a lot of faith in the open source movement Most of the tools I use are open source even though most of the development I get paid for

is sold under some kind of commercial license However, I still make an effort to contribute to open source projects and often release code from my personal projects under free licenses

In order to present a balanced view, I think it would be only fair to also consider some of the criticisms that have been leveraged against the Eclipse project Some of these apply to Eclipse in general; others only apply when viewing Eclipse as a tool for PHP development

It is no secret that Eclipse's resource requirements are quite high It is a huge

application and gets only bigger as you continue to add plugins Also, you might get frustrated with its slow response times if you don't give Eclipse plenty of RAM

to do its thing This is no lightweight text editor that you can launch in the blink of

an eye Eclipse is a serious application and there is a lot going on behind the scenes

at any given time In other words, if you've been eyeing that cute little net book with the seven-inch screen that is oh-so-portable, you might want to consider that it is not the right vehicle for PHP development using Eclipse It is akin to a high-performance engine requiring premium fuel You can drive it with standard gas, but it won't be the same

www.WoweBook.com

Trang 20

Another issue to consider is the learning curve you will have to conquer to really become productive in Eclipse Yes, it has a graphical user interface, but that doesn't mean that you will automatically know how to do what you want or even everything that is possible There is no way around investing some time in learning Eclipse Luckily, you don't have to do it all at once I believe that reading this chapter will give you a solid head start on knowing how to develop PHP applications in Eclipse The rest you will pick up automatically as you continue to explore Eclipse and the world of PHP in general.

Introducing PDT

PDT is an acronym for PHP Development Tool In accordance with Eclipse's

approach to extensibility, PDT is installed and updated as a plugin PDT provides basic functionality for developing PHP applications in an integrated environment Primarily, PDT provides the developer with tools to perform the three tasks of editing, inspecting, and debugging source code We will explore each of these high-level features throughout this chapter

Installing Eclipse

When it comes to installing Eclipse, you basically have two options First, you can download one of the standard Eclipse packages and install PDT along with several other plugins Second, you can download a PHP all-in-one and then use that as a starting point for installing the remaining plugins Either way, you will be installing several plugins to extend the functionality of Eclipse

The right approach for you depends on whether you will be using Eclipse for

development in other languages If so, my recommendation is to start with a

standard Eclipse package and to install PDT and other plugins via Eclipse's built-in software installation and update feature It will be a good exercise in configuring Eclipse and keeping it up-to-date Otherwise, assuming that you will be using

Eclipse for PHP only, you are best served by download the all-in-one package for PHP devlopers

Trang 21

[ 97 ]

a requirement Eclipse is known to be many things, but speedy is not one of them Even if you ignore the debatable issue of performance of UI-based Java applications, Eclipse is a behemoth of an application It requires significant RAM, CPU, and disk space The latter is not much of an issue anymore these days But, your development machine should have plenty of RAM and extra processing cycles so as not to leave you frustrated when using Eclipse

Another recommendation I would like to make is to use at least a 20-inch display The PHP development and debugging perspectives divide the main window into

up to six or seven panes that all hold different information Take as an example the screenshot, which shows Eclipse while editing the code for this chapter The code editor in the center of the window is surrounded by panes, such as a hierarchical directory and file listing or your project(s) ("PHP Explorer"), a hierarchical outline

of the resources defined by your project, such as constants, functions, and classes ("PHP Project Outline"), a structural outline of the currently viewed file ("Outline"),

a pane for looking up PHP built-in functions ("PHP Functions"), and a pane

displaying the syntactical errors Eclipse has detected ("Problems"), and so on You get the picture

www.WoweBook.com

Trang 22

Again, since Eclipse is so customizable, you can change the layout and get rid of some panes and tabs to accommodate a smaller screen But, in my opinion, you would be compromising away some of the features that make Eclipse so powerful You will be hard-pressed to run Eclipse effectively on a 7-inch netbook, but that doesn't mean you might have to sometimes The answer is to design your own perspective that only contains the absolute essentials you can fit on a small screen When you are back to using a bigger display, you can switch back to the more full-featured perspective.

Choosing a package

Eclipse is incredibly extensible Aside from adding numerous plugins to enable tionality in Eclipse, you can start out with a pre-configured Eclipse package There are several packages available from the Eclipse download page For the version that

func-is current as of thfunc-is writing, which func-is 3.5.1, these are the available options:

• Eclipse IDE for Java EE Developers (188 MB)

• Eclipse IDE for Java Developers (91 MB)

• Eclipse for PHP Developers (137 MB)

• Eclipse IDE for C/C++ Developers (78 MB)

• Eclipse for RCP/Plugin Developers (182 MB)

• Eclipse Modeling Tools (includes Incubating components) (366 MB)

• Eclipse IDE for Java and Report Developers (218 MB)

• Pulsar for Mobile Java Developers (112 MB)

• Eclipse SOA Platform for Java and SOA Developers (136 MB)

• Eclipse Classic 3.5.1 (161 MB)

If you are going to be doing Java development in Eclipse as well, you should load one of the two Java-centric packages at the beginning of the list However, if you are going to be focusing on the much more enjoyable world of PHP, you should start with the "Eclipse for PHP Developers" package Since none of the packages available from the eclipse.org site come with all the PHP goodies, you will have

down-to add those no matter which package you download

Eclipse IDE download page: http://www.eclipse.org/downloads/

Trang 23

[ 99 ]

After downloading the chosen package, simply uncompress the archive and move the resulting folder to its final destination Eclipse is pretty self-contained and does not require an installer or a lot of external preferences files

Adding the PDT plugin

If you have chosen to start with the "Eclipse for PHP Developers" package, you can skip this section because you already have everything you need to get started exploring Eclipse and PDT However, keep reading if you started with one of the non PHP-centric packages or you already have Eclipse installed from working with another programming language

Similar to Eclipse itself, you have two installation options for adding the PHP

Development Tools (PDT) plugin to your Eclipse installation First, you can

download an archive of the plugin, extract it and put it into the "plugins"

directory inside your Eclipse folder

However, I recommend the second way of installing PDT, which is via Eclipse's

built-in built-installer After startbuilt-ing up Eclipse, select the Help | Software Updates menu option If not already selected, switch to the Available Software tab You should see

a list of all sites from which Eclipse knows to get new software or updates to installed components Assuming that they are the sites that we need to install PDT, you should

go ahead and click the Add Site … button to add each of these sites in turn:

Định dạng
Số trang	46
Dung lượng	1,51 MB