// 
//     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[]


. 将自动选择占位符类名 ( ``*class_name*`` )。按 Tab 键可在占位符之间移动。您可以立即键入所需的类名，该名称将覆盖占位符。在完成后，按 Enter 键，IDE 将选择第一个函数的名称，此处为构造函数。

NOTE: <<placeholder,占位符名称>>部分详细讲述了占位符名称。

image::images/select-constructor-name.png[]


. 编辑函数名称或接受默认值。再次按 Enter 键，光标将移到函数主体内部。在实际情况下，您现在将开始对函数和类的其余部分进行编码。

最终的光标位置是由  ``${cursor}``  参数决定的。<<reserved-name,保留的名称>>部分中介绍了该参数。


=== 使用代码完成插入代码模板

要使用代码完成插入代码模板，请键入展开的代码片段的开头（而_不是_模板缩写）。此时将打开 "code completion"（代码完成）对话框，其中显示了代码片段。

*使用代码完成插入新类代码模板：*

1. 在 PHP 文件的 PHP 块中，键入  ``cla`` 。
2. 等待 "code completion"（代码完成）对话框打开。
3. 找到新类模板，将列出该模板的缩写 ( ``cls`` )。PHPDoc 框架显示了展开的模板。

image::images/insert-template-with-cc.png[]


. 选择新的类模板并按 Enter 键。IDE 将在代码中插入该模板。


. 将自动选择占位符类名 ( ``*class_name*`` )。按 Tab 键可在占位符之间移动。您可以立即键入所需的类名，该名称将覆盖占位符。在完成后，按 Enter 键，IDE 将选择第一个函数的名称，此处为构造函数。

image::images/select-constructor-name.png[]


. 编辑函数名称或接受默认值。再次按 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;?>
----


. 选择行  ``$b = 10;`` 

image::images/selected-variable.png[]


. 单击 "Hint"（提示）image:images/hint-icon.png[] 图标或按 Alt-Enter 组合键。此时将打开 "Surround with..."（包含方式...）对话框。

image::images/surround-hint.png[]


. 单击  ``Surround with if{*true*){...`` （包含在 if{true){... 中）

image::images/surround-if-true.png[]


. 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[]


. 迭代将以下两个变量作为参数： ``$index``  和  ``$array`` 。将自动选择  ``$index``  以进行编辑。（按 Tab 键可在参数之间移动。）

image::images/iteration1.png[]

键入  ``i`` 。 ``$index``  的所有三个实例将变为  ``$i`` 。

image::images/iteration2.png[]


. 按 Enter 或 Tab 键。将选择  ``$array``  参数。


. 按 Enter 键。光标将进入迭代的方法主体。

通过使用 NetBeans 中的变量名称重构功能，您只需编辑变量名称的一个实例即可更改它的所有实例。由此看出，在应用于模板参数时，该功能是多么有用！

NetBeans IDE PHP 编辑器也可以帮助确定变量的正确方法。

*将模板中的变量与正确的方法相关联：*

1. 在一个空 PHP 块中，键入以下代码：

[source,php]
----

<?php$arr = array(new ArrayIterator($array()), new ArrayObject($array()));?>
----


. 在声明  ``$arr``  数组的行后面，键入  ``fore`` ，然后使用代码完成插入  ``foreach``  模板（缩写为  ``fore`` ）。

image::images/cc-foreach.png[]


. 将光标放在  ``foreach``  函数主体中（可以按两次 Enter 键以将光标移到此处）并键入  ``$value`` ，或者仅键入  ``$``  并从代码完成中选择  ``$value`` 。

[source,php]
----

<?php$arr = array(new ArrayIterator($array()), new ArrayObject($array()));foreach ($arr as $value) {$value}?>
----


. 在  ``$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[]


. 单击 "New"（新建）以打开 "New Code Template"（新建代码模板）对话框。键入所需的模板缩写，然后单击 "OK"（确定）。 

image::images/new-abb.png[]


. 将在代码模板表中添加一个新行。该行仅包含您提供的缩写。光标位于 "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 邮件列表+]。