blob: 4a25ac82860e2a43de78c9083ca0e974d61ef3d5 [file] [log] [blame]
//
// Licensed to the Apache Software Foundation (ASF) under one
// or more contributor license agreements. See the NOTICE file
// distributed with this work for additional information
// regarding copyright ownership. The ASF licenses this file
// to you under the Apache License, Version 2.0 (the
// "License"); you may not use this file except in compliance
// with the License. You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing,
// software distributed under the License is distributed on an
// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
// KIND, either express or implied. See the License for the
// specific language governing permissions and limitations
// under the License.
//
= 适用于 PHP NetBeans IDE 中的代码模板
:jbake-type: tutorial
:jbake-tags: tutorials
:jbake-status: published
:icons: font
:syntax: true
:source-highlighter: pygments
:toc: left
:toc-title:
:description: 适用于 PHP NetBeans IDE 中的代码模板 - Apache NetBeans
:keywords: Apache NetBeans, Tutorials, 适用于 PHP NetBeans IDE 中的代码模板
代码模板是 NetBeans IDE 提供的预先编写的代码片段。可以使用代码完成或使用模板缩写并按 Tab 键,将代码片段粘贴到您的代码中。也可以将您的代码包含在相应的 PHP 代码片段中。最后,您可以定义自己的代码模板。本教程介绍了如何使用代码模板,并建议了定义您自己的代码模板的用例。
*要学完本教程,您需要具备以下软件和资源。*
|===
|软件或资源 |要求的版本
|link:https://netbeans.org/downloads/index.html[+NetBeans IDE+] |PHP 下载包
|link:http://www.oracle.com/technetwork/java/javase/downloads/index.html[+Java 开发工具包 (JDK)+] |7 或 8
|===
 
== 定义的 PHP 代码模板
要查看在 NetBeans 中定义的代码模板,请打开 "Tools"(工具)> "Options"(选项)(在 Mac 上为 "NetBeans" > "Preferences"(首选项)),选择 "Editor"(编辑器)功能,然后选择 "Code Templates"(代码模板)标签。要查看 PHP 代码模板,请在 "Languages"(语言)下拉列表中选择 "PHP"。将显示一个表,其中包含代码模板缩写和展开的文本。如果在该表中选择一个代码模板,将在 "Expanded Text"(展开的文本)标签中显示它的展开文本。
image::images/code-template-options.png[]
在该图中,选择了新类 ( ``cls)`` 代码模板,您可以在 "Expanded Text"(展开的文本)标签中看到该模板展开后的内容。在下一节中,将使用 Tab 功能在代码中展开该模板。
NOTE: <<syntax,PHP 代码模板语法>>部分讲述了新类 ( ``cls`` ) 代码模板的语法。
== 使用 PHP 代码模板
可以使用三种方法在 PHP 代码中插入代码模板。每种插入代码模板的方法适用于不同的情况。插入代码模板的三种方法是:
* 使用模板缩写并按 Tab 键(或您定义的不同键或组合键)<<expand-with-abb,展开模板>>。
* 使用代码完成<<expand-with-cc,插入展开的模板>>。
* 使用旁注提示或按 Alt-Enter 组合键,<<surround-code,将代码包含在模板中>>。
在插入模板后,IDE 可帮助您在展开的模板代码中<<edit-parameters,编辑参数>>。
=== 使用缩写 + Tab 键展开代码模板
再次查看 "Options"(选项)对话框中的 "Code Templates"(代码模板)标签。底部有一个下拉字段,用于选择 "Expand Template On"(展开模板)组合键。这是在键入代码模板缩写后按下的组合键,以便展开代码模板。默认情况下,将选择 Tab 键,但您可以选择其他组合键。
image::images/expand-template-on.png[]
本节的其余部分假定在 "Expand Template on:"(展开模板:)字段中选择了默认 Tab 键。
如果模板缩写也是代码完成关键字的一部分,则可能很难展开该缩写。在这种情况下,使用<<expand-with-cc,代码完成>>插入模板会更容易一些。
*要使用缩写 + Tab 键展开新类代码模板,请执行以下操作:*
1. 创建一个空 PHP 文件。
2. 在该文件的 PHP 块中,键入 ``cls`` ,然后按 Tab 键。将展开 ``cls`` 代码模板。
NOTE: 应正确拼写缩写!如果拼错缩写,将无法展开缩写。
image::images/expanding-template-with-abb.png[]
[start=3]
. 将自动选择占位符类名 ( ``*class_name*`` )。按 Tab 键可在占位符之间移动。您可以立即键入所需的类名,该名称将覆盖占位符。在完成后,按 Enter 键,IDE 将选择第一个函数的名称,此处为构造函数。
NOTE: <<placeholder,占位符名称>>部分详细讲述了占位符名称。
image::images/select-constructor-name.png[]
[start=4]
. 编辑函数名称或接受默认值。再次按 Enter 键,光标将移到函数主体内部。在实际情况下,您现在将开始对函数和类的其余部分进行编码。
最终的光标位置是由 ``${cursor}`` 参数决定的。<<reserved-name,保留的名称>>部分中介绍了该参数。
=== 使用代码完成插入代码模板
要使用代码完成插入代码模板,请键入展开的代码片段的开头(而_不是_模板缩写)。此时将打开 "code completion"(代码完成)对话框,其中显示了代码片段。
*使用代码完成插入新类代码模板:*
1. PHP 文件的 PHP 块中,键入 ``cla``
2. 等待 "code completion"(代码完成)对话框打开。
3. 找到新类模板,将列出该模板的缩写 ( ``cls`` )。PHPDoc 框架显示了展开的模板。
image::images/insert-template-with-cc.png[]
[start=4]
. 选择新的类模板并按 Enter 键。IDE 将在代码中插入该模板。
[start=5]
. 将自动选择占位符类名 ( ``*class_name*`` )。按 Tab 键可在占位符之间移动。您可以立即键入所需的类名,该名称将覆盖占位符。在完成后,按 Enter 键,IDE 将选择第一个函数的名称,此处为构造函数。
image::images/select-constructor-name.png[]
[start=6]
. 编辑函数名称或接受默认值。再次按 Enter 键,光标将移到函数主体内部。在实际情况下,您现在将开始对函数和类的其余部分进行编码。
=== 将代码包含在模板中
您可以将代码包含在以下 PHP 模板中:
* ``while``
* ``do``
* ``switch``
* ``if`` / ``elseif``
* ``try`` &amp; ``catch``
* ``foreach``
* ``for``
* ``ob_start`` &amp; ``ob_end_clean``
此外,您也可以<<create,创建新模板>>,如果该模板包括 `allowSurround` <<complex,参数提示>>,则可以包含代码。(感谢link:http://www.mybelovedphp.com/2012/05/14/tips-for-using-the-netbeans-editor-for-kohana-and-kostache-mustache-templates-using-surround-with/[+“我喜爱的 PHP”博客+]。)
要将代码包含在模板中,请选择代码,然后打开 "Surround with..."(包含方式...)对话框。要打开 "Surround with..."(包含方式...)对话框,请按 Alt-Enter 组合键或者单击 "Hint"(提示)image:images/hint-icon.png[] 图标。
*将代码包含在 if(true) 模板中:*
1. 使用变量 ``$a = true`` ``$b = 10`` 创建一个 PHP 块。
[source,php]
----
<?php$a = false;$b = 10;?>
----
[start=2]
. 选择行 ``$b = 10;``
image::images/selected-variable.png[]
[start=3]
. 单击 "Hint"(提示)image::images/hint-icon.png[] 图标或按 Alt-Enter 组合键。此时将打开 "Surround with..."(包含方式...)对话框。
image::images/surround-hint.png[]
[start=4]
. 单击 ``Surround with if{*true*){...`` (包含在 if{true){... 中)
image::images/surround-if-true.png[]
[start=5]
. IDE ``$b = 10;`` 行包含在 ``if(*true*){...`` 模板中。
image::images/inserted-if-true.png[]
IDE 自动插入前面最近的适合变量作为 ``if`` 语句的条件。此处,该变量是 ``$a`` ,这是因为 ``$a`` 是布尔型变量,并且 ``if(*true*){}`` 语句将布尔型变量作为其条件。再者,如果 IDE 插入到条件中的变量不是正确的变量,则会自动选择该条件以进行编辑。这意味着,您可以在插入模板后立即开始键入正确的变量。在这种情况下,代码完成可以帮助您选择正确的变量。
NOTE: <<complex,提示定义的参数>>部分详细介绍了 ``if(*true*){}`` 模板。
image::images/change-condition.png[]
Enter 键以退出语句的条件。光标将移到相应的位置,此处为 ``$b = 10;`` 行的末尾。您可以编辑条件并按 Enter 键,或者接受自动插入的条件并按 Enter 键。对于这两种情况,光标将退出条件并移到相应的位置。
image::images/cursor-after-not-editing.png[]
image::images/cursor-after-editing.png[]
下一节包含在展开的模板中编辑参数的详细信息。
=== 在展开的模板中编辑参数
在介绍将模板插入到代码的部分中,您了解了在展开新类模板时 IDE 如何自动选择类名以进行编辑,以及在展开 ``if(*true*)`` 模板时 IDE 如何自动选择条件名称以进行编辑。现在,您将了解 IDE 帮助您在展开的模板中编辑参数的一些其他方法。
*同时编辑参数的多个实例:*
1. 在一个空 PHP 块中,键入 ``for`` ,然后按 Ctrl-空格键以打开代码完成。选择迭代模板(缩写为 ``iter`` ),然后按 Enter 键。将在代码中插入一个新迭代。
image::images/iter-cc.png[]
[start=2]
. 迭代将以下两个变量作为参数: ``$index`` ``$array`` 。将自动选择 ``$index`` 以进行编辑。(按 Tab 键可在参数之间移动。)
image::images/iteration1.png[]
键入 ``i`` ``$index`` 的所有三个实例将变为 ``$i``
image::images/iteration2.png[]
[start=3]
. Enter Tab 键。将选择 ``$array`` 参数。
[start=4]
. Enter 键。光标将进入迭代的方法主体。
通过使用 NetBeans 中的变量名称重构功能,您只需编辑变量名称的一个实例即可更改它的所有实例。由此看出,在应用于模板参数时,该功能是多么有用!
NetBeans IDE PHP 编辑器也可以帮助确定变量的正确方法。
*将模板中的变量与正确的方法相关联:*
1. 在一个空 PHP 块中,键入以下代码:
[source,php]
----
<?php$arr = array(new ArrayIterator($array()), new ArrayObject($array()));?>
----
[start=2]
. 在声明 ``$arr`` 数组的行后面,键入 ``fore`` ,然后使用代码完成插入 ``foreach`` 模板(缩写为 ``fore`` )。
image::images/cc-foreach.png[]
[start=3]
. 将光标放在 ``foreach`` 函数主体中(可以按两次 Enter 键以将光标移到此处)并键入 ``$value`` ,或者仅键入 ``$`` 并从代码完成中选择 ``$value``
[source,php]
----
<?php$arr = array(new ArrayIterator($array()), new ArrayObject($array()));foreach ($arr as $value) {$value}?>
----
[start=4]
. ``$value`` 后面,键入 ``->`` 。代码完成为您提供了 ``$value`` 变量的正确方法,该变量是从 ``$arr`` 数组派生的。
image::images/value-method-cc.png[]
== PHP 代码模板语法
NetBeans IDE 为支持的所有语言提供了代码模板。某些语法适用于所有语言。其他语法是某种语言特有的。在本节中,您将了解最相关的通用模板语法以及 PHP 模板特有的语法。
PHP 代码模板可以包含 PHP 代码和模板参数。PHP 模板可以仅包含 PHP 代码,仅包含参数或同时包含代码和参数。
代码模板参数语法是美元符号 ``$`` ,后跟用花括号 ``{...}`` 括起来的参数定义。在该语法中,模板参数采用以下四种形式之一:
* 任意<<placeholder,占位符名称>>,例如, ``${SomeName}``
* IDE 提供处理指令的<<reserved-name,保留名称>>
* 描述性参数名称和一组<<complex,定义参数的提示>>
* <<pre-defined,预定义的参数>>。
以下几节讲述了每种形式的代码模板参数。
NOTE: ``$$${VARIABLE...} `` 有时,您会在 PHP 代码模板中看到语法似乎为三个美元符号,后跟花括号 ``$$${...}`` 。在这种情况下,代码模板包含变量及其名称。此处的语法是转义的美元符号,记为两个美元符号 ``$$`` ,后跟变量名称参数 ``${VARIABLE...}`` 。例如, ``catch ${Exception} $$${exc}`` 代码模板展开为 [examplecode]# ``catch Exception $exc`` #。
=== 占位符名称
在最简单的情况下,代码模板参数是一个任意占位符值。在展开模板时,IDE 选择该占位符名称以进行编辑。
例如,请考虑本教程的<<define,定义的 PHP 模板>>和<<expand-with-abb,使用缩写 + Tab 键展开代码模板>>部分中介绍的新类模板 ``(cls)`` 。新类模板的展开文本以 ``class ${className}`` 开头。此处, ``class`` 一词是 PHP 代码, ``${className}`` 是一个参数。该参数只是类名的任意占位符值。当 IDE 展开模板时, ``${className}`` 将变为 ``*class_name*`` IDE 知道 ``*class_name*`` 只是一个占位符值,因此,自动选择该值以进行编辑。
image::images/expanding-template-with-abb.png[]
=== 保留的名称
IDE 保留两个参数名称以作为操作指令。
* ``${cursor}`` 定义在展开的模板中编辑完所有自动选择的值后的光标位置。
* ``${selection}`` 定义编辑器选择内容的粘贴位置。只要用户在编辑器中选择文本,所谓的“选择模板”(显示为提示)就会使用该参数。如果模板包含 ``${selection}`` ,它通常指与 ``${cursor}`` 相同的位置。
例如,请再次考虑本教程的<<define,定义的 PHP 模板>>和<<expand-with-abb,使用缩写 + Tab 键展开代码模板>>部分中介绍的新类模板 ``(cls)`` 。它包含 ``${ClassName}`` ``$__construct`` 这两个占位符名称参数。在函数体中,它具有参数 ``${cursor}`` ``${selection}``
[source,php]
----
class ${ClassName} {function ${__construct} {${selection}${cursor}}}
----
在展开模板后,将自动选择 ``*class_name*`` 占位符 (1)。按 Enter 键,将自动选择 ``*__construct*`` 占位符 (2)。没有要编辑的其他值。再次按 Enter 键,光标将移到模板文本中的 ``${cursor}`` 指示的位置 (3)。
image::images/cursor-position-changes.png[]
=== 提示定义的参数
参数可以包含一个全部大写的任意描述性名称以及一个或多个提示。
[source,php]
----
${PARAMETER_NAME hint1[=value] [hint2...hint n]}
----
名称不会显示在代码中的任意位置。不过,如果要在代码模板中多次使用参数,这是非常有用的。您只需第一次定义参数,以后按名称引用该参数即可。例如,在下面的代码模板中,仅第一次定义了 ``${CONLINK}`` 参数,以后两次按名称引用该参数。
[source,php]
----
$$${CONLINK newVarName default="link"} = mysql_connect('localhost''mysql_user''mysql_password'); if (!$$${CONLINK}) {    die('Could not connect: ' mysql_error()); } echo 'Connected successfully'; mysql_close($$${CONLINK}); ${cursor}
----
IDE 展代码模板时,提示可帮助 IDE 计算模板参数的值。例如,请查看 ``if(*true*)`` 模板,本教程的<<surround-code,将代码包含在模板中>>部分中使用了该模板。该模板的展开文本是
[source,php]
----
if (${CONDITION variableFromPreviousAssignment instanceof="boolean" default="true"}) {${selection}${cursor}}
----
查看 ``${CONDITION variableFromPreviousAssignment instanceof="boolean" default="true"}`` 参数。该参数设置 ``if`` 语句的条件。因此,该参数命名为 CONDITION。第一个提示是 ``variableFromPreviousAssignment`` ,第二个提示是 ``instanceof="boolean"`` 。这两个提示共同指示 IDE 在代码模板前面的代码中查找指定的最接近布尔型变量。请添加第三个提示 ``default="true"`` ,该参数将条件设置为“如果前面的最接近布尔型变量值为 true”。
例如,如果将以下代码片段中的 ``$b = 10`` 行包含在 ``if(*true*)`` 代码模板中...
image::images/selected-variable.png[]
...IDE 将查找以前指定的最接近布尔型变量,结果找到了 ``$a`` ,并使用 ``$a`` [=true] 条件生成一个 ``if`` 语句。将自动选择该条件以进行编辑,因此,PHP 程序员可以将 ``$a`` 更改为其他变量或 ``!$a``
image::images/inserted-if-true.png[]
下表列出了 PHP 代码模板中使用的提示以及提示说明。
|===
|提示 |描述
| ``newVarName`` |参数值应该为全新的未使用变量名称。通常与 ``default`` 一起使用。
| ``default=""`` |参数的默认值。
| ``instanceof=""`` |参数中定义的 PHP 变量类型。
| ``variableFromPreviousAssignment`` |参数值是以前指定的最接近变量。通常与 ``instanceof`` ``default`` 一起使用。
| ``variableFromNextAssignmentName`` |参数值是在代码模板后面指定的最接近变量的名称。通常与 ``default`` 一起使用。
| ``variableFromNextAssignmentType`` |参数值是在代码模板后面指定的最接近变量的类型。通常与 ``default`` 一起使用。
| ``editable=false`` |在展开模板后,无法编辑参数值。
| ``allowSurround`` |允许使用模板<<surround-code,包含代码>>。
|===
== 创建您自己的代码模板
可以在 NetBeans IDE 中创建您自己的代码模板。本节介绍了如何创建代码模板,讲述了其语法并建议了一些可创建的有用模板。
*创建代码模板:*
1. 打开 "Tools"(工具)> "Options"(选项)(在 Mac 上为 "NetBeans" > "Preferences"(首选项)),选择 "Editor"(编辑器)功能,然后选择 "Code Templates"(代码模板)标签。
image::images/code-template-options.png[]
[start=2]
. 单击 "New"(新建)以打开 "New Code Template"(新建代码模板)对话框。键入所需的模板缩写,然后单击 "OK"(确定)。
image::images/new-abb.png[]
[start=3]
. 将在代码模板表中添加一个新行。该行仅包含您提供的缩写。光标位于 "Expanded Text"(展开的文本)标签中,IDE 自动将光标放在该位置。您可以立即开始键入模板的代码。
NOTE: 要了解代码模板的展开文本的语法,请参见 <<syntax,PHP 代码模板语法>>部分。
image::images/new-abb-text.png[]
以下几节介绍了创建您自己的 PHP 代码模板的一些用例。如果您要建议任何其他用例,请在 link:http://forums.netbeans.org/php-users.html[+PHP 用户论坛+]中与社区用户进行分享。
=== 用例:将 PHP 插入到 HTML
如果经常将 PHP 代码片段插入到 HTML 块中,您可以创建一个 HTML 代码模板以插入 PHP,而无需反复键入 ``<?php ?>``
以下代码模板将 PHP ``echo`` 语句插入到 HTML 中。
|===
|语言: |HTML
|缩写: |php
|展开的文本: |
[source,php]
----
<?php echo ${cursor ?>
----
|===
image::images/uc-php.png[]
=== 用例:Joomla
代码模板可帮助您在 NetBeans IDE 中使用 PHP 框架,尤其是没有内置支持的框架。下面是一个用户开发的代码模板,以便与 Joomla 一起使用。
|===
|语言: |PHP
|缩写: |joomdef
|展开的文本: |
[source,php]
----
defined('_JEXEC')or die('Restricted access');${cursor}
----
|===
image::images/uc-joomdef.png[]
=== 用例:MySQL 连接
PHP 开发者经常需要创建到 MySQL 数据库的连接。该代码模板将为您创建一个连接。指定给 MySQL 连接的变量具有占位符名称 ``link`` 。请注意使用了三个美元符号 ``$$$`` -- 实际上是两个美元符号(在展开时生成单个美元符号),后跟变量名称的参数。
|===
|语言: |PHP
|缩写: |my_con
|展开的文本: |
[source,php]
----
$$${CONLINK newVarName default="link"} = mysql_connect('localhost''mysql_user''mysql_password'); if (!$$${CONLINK}) {    die('Could not connect: ' mysql_error()); } echo 'Connected successfully'; mysql_close($$${CONLINK}); ${cursor}
----
|===
image::images/uc-mycon.png[]
=== 用例:Zend 控制器中的操作
您可以使用代码模板在 Zend 框架控制器中插入操作(如 ``indexController{}`` ),而不是使用 NetBeans 向导创建操作。
|===
|语言: |PHP
|缩写: |zf_act
|展开的文本: |
[source,php]
----
public function ${functionName}Action () {${selection}${cursor} }
----
|===
image::images/uc-zfact.png[]
=== 用例:Zend 窗体元素
该模板在 Zend 窗体中插入元素。在调用 Zend ``create form <name>`` 命令以生成窗体后,请使用该模板。
|===
|语言: |PHP
|缩写: |zf_element
|展开的文本: |
[source,php]
----
$$${ELEMENT newVarName default="element"} = new Zend_Form_Element_Submit('submit', array('label' => 'Send data to server')); $$this->addElement($$${ELEMENT}); ${cursor}
----
|===
image::images/uc-zelement.png[]
 
link:/about/contact_form.html?to=3&subject=Feedback:%20PHP%20Code%20Templates[+发送有关此教程的反馈意见+]
== 另请参见
有关 link:https://netbeans.org/[+netbeans.org+] 上 PHP 技术的更多信息,请参见下面的资源:
* link:../java/editor-codereference.html[+NetBeans IDE Java 编辑器中的代码帮助+]。这是 NetBeans IDE 代码帮助的参考指南,其中包括代码模板和宏录制。
* link:http://forums.netbeans.org/php-users.html[+NetBeans PHP 用户论坛+]
* link:http://blogs.oracle.com/netbeansphp/[+"NetBeans for PHP" 博客+]。这是 NetBeans PHP 编辑器开发人员撰写的博客。这是查找最新功能和改进功能的最佳位置。
要发送意见和建议、获得支持以及随时了解 NetBeans IDE PHP 开发功能的最新开发情况,请link:../../../community/lists/top.html[+加入 users@php.netbeans.org 邮件列表+]。