Change Signature

Basics

The Change Signature refactoring combines several different modifications that can be applied to a function signature. You can use this refactoring for the following purposes:

To change the function name.
To change the function return type.
To add new parameters and remove the existing ones.
To assign default values to the parameters.
To reorder parameters.
To change parameter names.
To propagate new parameters through the function call hierarchy.

When changing a function signature, PhpStorm searches for all usages of the function and updates all the calls, implementations, and override replacements of the function that can be safely modified to reflect the change.

Default value and propagation of new parameters

For each new parameter added to a function, you can specify:

A default value (or an expression) (the Default value field).

You can also propagate the parameters you have introduced to the functions that call the function whose signature you are changing.

The refactoring result depends on whether you specify the default value and whether you use propagation.

Propagation. New parameters can be propagated to any function that calls the function whose signature you are changing. In such case, generally, the signatures of the calling functions change accordingly.
These changes, however, also depend on the default values set for the new parameters.

Default value. Generally, this is the value to be added to the function calls.

If the new parameter is not propagated to a calling function, the calls within such function will also use this value.

If propagation is used, this value won't affect the function calls within the calling functions.

Examples

The following table shows 3 different ways of performing the same Change Signature refactoring.

In all the cases, the result() function is renamed to generateResult() and a new $b parameter is added to this function.

The examples show how the function call, the calling function (showResult()) and other code fragments may be affected depending on the refactoring settings.

Before	After
`// This is the function whose signature will be changed: function result($a) { // some code here } function showResult($a) { // Here is the function call: $this->result($a); } // Now we'll rename the function and // add one parameter.`	`// The function has been renamed to generateResult. // The new parameter $b has been added. function generateResult($a,$b) { // some code here } function showResult($a,$b) { // The function call has been changed accordingly: $this->generateResult($a,$b); }`
`// This is the function whose signature will be changed: function result($a) { // some code here } function showResult($a) { // Here is the function call: $this->result($a); } // Now we'll rename the function and add one parameter. //We will also specify the default value 'new_param' //for this new parameter`	`// The function has been renamed to generateResult. // The new parameter $b has been added. function generateResult($a,$b) { // some code here } function showResult($a) { // The function call has been changed accordingly: $this->generateResult($a,'new_param'); } // When performing the refactoring, 'new_param' was specified as // the default parameter value.`
`// This is the function whose signature will be changed: function result($a) { // some code here } function showResult($a) { // Here is the function call: $this->result($a); } // Now we'll rename the function and add one parameter. //We will also propagate this new parameter //through the showResult() calling function to the function call.`	`// The function has been renamed to generateResult. // The new parameter $b has been added. function generateResult($a,$b) { // some code here } // Note the new function parameter: function showResult($a,$b) { // The function call has been changed accordingly: $this->generateResult($a,$b); }`

Changing a function signature

In the editor, place the cursor within the name of the function whose signature you want to change.
Do one of the following:
- Press Ctrl+F6.
- Choose Refactor | Change Signature on the main menu or
- Choose Refactor | Change Signature on the context menu.
In the Change Signature dialog, make the necessary changes to the function signature and specify what other, related, changes are required.
You can:
- Change the function name. To do that, edit the text in the Name field.
- Change the function return type by editing the contents of the Return type field.
  Setting the function return type is only possible in PHP language version 7.1 and later. You can specify the PHP language level on the PHP page (File | Settings | Languages and Frameworks | PHP for Windows and Linux or PhpStorm | Preferences | Languages and Frameworks | PHP for macOS).
- Manage the function parameters using the table and the buttons in the Parameters area:
  - To add a new parameter, click and specify the properties of the new parameter in the corresponding table row.
    When adding parameters, you may want to propagate these parameters to the functions that call the current function.
    
    In the PHP context, when the Change signature refactoring is invoked from the constructor of a class, the new parameter can be initialized as a class field. To do that, use the Create and initialize class properties check box:
    - When this checkbox is selected, the newly added parameter is initialized as a field. PhpStorm creates a protected field with the same name as this parameter and adds a line with the following assignment:
      $this-><parameter_name> = $<parameter_name>;
    - When the checkbox is cleared, a parameter is added without initialization.
    For example, you have the following constructor:
    class ChangeSignatureNewParam { function __construct() { $a = "Constructor in ChangeSignatureNewParam"; print $a; } }
    If you invoke the Change signature refactoring from the __construct() method and add a new $q parameter, the result will depend on whether you select or clear the Create and initialize class properties checkbox:
    - The Create and initialize class properties checkbox is selected:
      
      class ChangeSignatureNewParam { private $q; function __construct($q) { $a = "Constructor in ChangeSignatureNewParam"; print $a; $this->q = $q; } }
    - The Create and initialize class properties checkbox is cleared:
      
      class ChangeSignatureNewParam { function __construct($q) { $a = "Constructor in ChangeSignatureNewParam"; print $a; } }
  - To remove a parameter, click any of the cells in the corresponding row, and then click .
  - To reorder the parameters, use the and buttons. For example, if you want to put a certain parameter first in the list, click any of the cells in the row corresponding to that parameter, and then click the required number of times.
  - To change the name or the default value of a parameter, make the necessary updates in the table of parameters (in the fields Name and Default value respectively).
- Propagate new method parameters (if any) along the hierarchy of the functions that call the current function.
  (There may be functions that call the function whose signature you are changing. These functions, in their turn, may be called by other functions, and so on. You can propagate the changes you are making to the parameters of the current function through the hierarchy of calling functions and also specify which calling functions should be affected and which shouldn't.)
  
  To propagate a new parameter:
  1. Click the Propagate Parameters button .
  2. In the left-hand pane of the Select Methods to Propagate New Parameters dialog, expand the necessary nodes and select the checkboxes next to the functions you want the new parameters to be propagated to.
    To help you select the necessary functions, the code for the calling function and the function being called is shown in the right-hand part of the dialog (in the Caller Method and Callee Method panes respectively).
    
    As you switch between the functions in the left-hand pane, the code in the right-hand pane changes accordingly.
  3. Click OK.
To perform the refactoring right away, click Refactor.
To see the expected changes and make the necessary adjustments prior to actually performing the refactoring, click Preview.

PhpStorm 2017.3 Help