Structural search and replace

Search for a target structurally

1. From the main menu, select Edit | Find | Search Structurally to open the Structural Search dialog.

2. In the Structural Search dialog, do one of the following:

   • Create your own template from scratch.

     In the editor area, enter the code template ($variable$ that represent your code), click , and select Save Template to save it for future use.

     

     PhpStorm adds the created template to the existing template list (User Defined node) in the Existing Templates dialog.

   • Use one of the existing templates to act as a prototype.

     Click , select Existing Templates to open the list of predefined templates, and select the appropriate one.

     Consider the following example class:

     class ExampleClass { public function WRONG() { } public function right() { } }

     Let's find a certain method in the class.

     In the list of existing templates, select the All public methods of the class template under PHP | General.

     

     Click OK to return to the Structural Search dialog to work with the selected template.

     PhpStorm instantly highlights the found code occurrences in the editor.

3. The Structural Search dialog displays the selected template and values of the filters used in the template. You can edit the existing filters or add new conditions,. Place the caret at the code variable and use the filter area to manage filters.

   

4. In the filter area, click to add a new condition. If, for example, you need to add a regular expression, select Text. You can also add other conditions depending on your variable.

5. In the field that opens, type your condition.

   For example, let's type the following regular expression:

   \b[a-z]\w+\b

   

   In this case when you select the Match case checkbox in the Structural Search dialog, PhpStorm will only search for the fields with uppercase characters.

   Also note that by default, the Recursive checkbox is selected. That means that PhpStorm performs the recursive search and all nested items will be included in the results. For example, when you search for a method call, with the Recursive option enabled, PhpStorm will find nested method calls in foo(foo(foo())). With the Recursive option disabled, only the outer method call will be found.

6. Specify the following options to further narrow the search:

   • File type- use the list to select, which file types should be a part of the search. In our case, it is PHP.

   • Scope- specify where to search: in a project, module, directory, or within a custom scope.

   • Search target- you can select Complete match to match the exact template or other available code elements (in our case it is b).

     

7. Click Find.

PhpStorm displays the results in the Find tool window.

You can add the newly created search template to structural search inspections as a custom template and use it later to inspect your code.

Using Search for a target structurally

1. From the main menu, select Edit | Find | Search Structurally to open the Structural Search dialog.

2. In the Structural Search dialog, do one of the following:

   • Create your own template from scratch.

     In the editor area, enter the code pattern ($variable$ that represent your code), click , and select Save Template to save it for future use.

     

     PhpStorm adds the created template to the existing template list (User Defined node) in the Existing Templates dialog.

   • Use one of the existing templates to act as a prototype.

     Click , select Existing Templates to open the list of predefined templates, and select the appropriate one.

     Consider the following example class:

     class ExampleClass { public function WRONG() { } public function right() { } }

     Let's find a certain method in the class.

     In the list of existing templates, select the All public methods of the class template under PHP | General.

     

     Click OK to return to the Structural Search dialog to work with the selected template.

     PhpStorm instantly highlights the found code occurrences in the editor.

3. The Structural Search dialog displays the selected template and values of the filters used in the template. You can edit the existing filters or add new conditions,. Place the caret at the code variable and use the filter area to manage filters.

   

4. In the filter area, click to add a new condition. If, for example, you need to add a regular expression, select Text. You can also add other conditions depending on your variable.

5. In the field that opens, type your condition.

   For example, let's type the following regular expression:

   \b[a-z]\w+\b

   

   In this case when you select the Match case checkbox in the Structural Search dialog, PhpStorm will only search for the upper case words.

   Also note that by default, the Recursive checkbox is selected. That means that PhpStorm performs the recursive search and all nested items will be included in the results. For example, when you search for a method call, with the Recursive option enabled, PhpStorm will find nested method calls in foo(foo(foo())). With the Recursive option disabled, only the outer method call will be found.

6. Specify the following options to further narrow the search:

   • File type- use the list to select which file types should be a part of the search. In our case, it is PHP.

   • Scope- specify where to search: in a project, module, directory, or within a custom scope.

   • Search target- you can select Complete match to match the exact template or other available code elements (in our case it is b).

     

7. Click Find.

PhpStorm displays the results in the Find tool window.

You can add the newly created search template to structural search inspections as a custom template and use it later to inspect your code.

Replace a target structurally

1. From the main menu, select Edit | Find | Replace Structurally.

2. In the Replace Structurally dialog, add new or existing templates to the search and replace template areas. You can save the replace template the same way as the search one.

3. If you need to add a filter for the variable in the replace template, place a caret at the variable of interest and use the filter area to manage filters.

   

4. In the filter area, depending on what your chose as a filter, specify the condition.

   Let's call our variable $Field2$ and add the following filter script which basically is a Groovy script: Field.name.toLowerCase().

5. To narrow down your replace results, select the following options:

   • Shorten fully-qualified names- replaces fully qualified class names with short names and imports.

   • Reformat- automatically formats the replaced code.

   • Use static import- uses static import in replacement when possible.

   After specifying the necessary options, click Find. PhpStorm displays the results in the Find tool window.

6. In the Find tool window, you can work with the results further, replacing found items one by one, all of them at once, or previewing your potential changes.

Consider the following example that converts uppercase values of the class attribute in p tags to lowercase. In the Search template field, we create a template that searches for all p tags with uppercase values ([A-Z].* and Match case) in class attributes. We narrow our search only to these to class values (Search target = b). In the Replace template field, we create a new variable $d$ and assign a Groovy script to it (b.getText().toLowerCase()). After the search, we select Replace All to perform the replacing.

Share search templates

You can share a search template with your peers by exporting or importing it.

1. In the Structural Search dialog (Edit | Find | Search Structurally), create a new search template or use the existing one.

2. To export a template, click and select Export Template to Clipboard. PhpStorm adds the XML representation of the template to a clipboard (press Ctrl+Shift+V to see the clipboard's content). You can share this representation with other developers in chat, email, or a forum.

   To import a template, copy (Ctrl+C) the shared XML code from anywhere (email, chat, or a forum) and in the Structural Search dialog, click and select Import Template from Clipboard. PhpStorm takes the XML code representation and converts it into a template including variables and a scope if it is present.