Configuring unresolved PHP include expressions

Before you begin

In the project properties, go to the Project Dependencies page.

Procedure

  1. Click Configure Unresolved Include Expressions to open the Configure Unresolved Include Expressions dialog box.
  2. The upper portion of the dialog box lists the unresolved include expressions (all include expressions that were not resolved or that required extra processing to resolve). Information provided about the expressions includes:
    OptionDescription
    Included Text / Updated Text This column displays the expression text as it exists in the source code. This column can be expanded by clicking +, which will then show the updated text that was used during the last scan. It will display <empty> if there was no updated text available during the last scan. There may be multiple updated text lines displayed when expanded - one for each place in the source code where this expression was used.
    Status This column will contain an X for expressions that are unresolved or a check mark for expressions that were successfully resolved.
    Resolved By This column indicates how the updated text was generated. Values include:
    • AutoResolver: The application used internal heuristics to find the file.
    • SearchReplace: One or more search and replace rules were applied to the included text to generate the updated text.
    • SearchReplace+AutoResolver: One or more search and replace rules were applied to the included text to generate the updated text and then internal heuristics were applied to find the file.
    • SearchReplace+IncludePath: One or more search and replace rules were applied to the included text to generate the updated text and then was combined with a directory on the include path to find the file.
    • SearchReplace+RelativeDir: One or more search and replace rules were applied to the included text to generate the updated text and then was found relative to the source directory of the file containing the include expression.
    Source File, Line, Column These columns show the location in the source code in which the expression is used. You may want to look at these locations in an editor to see how they should be resolved.
    Note: Some of the columns may be blank. This is because included text can have multiple updated text lines when expanded. These columns will have appropriate text for each of these updated text lines.
  3. In the lower portion of the dialog box, the Include Path tab contains the same include path information that was entered in the PHP Project Dependencies page. You can update this information in this dialog box (while viewing the unresolved include expressions).
  4. In the lower portion of the dialog box, the Search and Replace tab is used for adding rules for replacing dynamic text in an include expression with static text that is a full or partial file path to an include file. There are three columns in the Search and Replace table:
    OptionDescription
    Command The value in this column determines how the Search Text and Replacement Text columns are used. The choices are:
    • Replace Text: This command is used for simple text search and replace. The Search Text is used as is and, if it is found anywhere in the included text, it is replaced with the Replacement Text.
    • Replace Function: This command is used when a function call is to be replaced. The Search Text should be the name of the function without parentheses. The search text will be augmented to look for a function call with the specified name followed by parentheses and will match anything within the parentheses.
    • Replace RegEx: This is an advanced feature that allows a regular expression to be specified for the search text.
    Search Text This is the text to search for in the include expression. You can select text within an include expression and copy it to the clipboard and then paste it here. See the above description of the Command column for the variations in specifying the search text.
    Replacement Text This is the text used to replace the search text. This is static text that is a full or partial file path to an include file. There are also a few variables that can be placed in the replacement text. They can be typed directly into the Replacement Text cell or selected from the Replacement Text Variables menu above the table (this will copy the selected variable to the clipboard). The variables that can be selected from the Replacement Text Variables menu list are:
    • %ROOT_DIR%: This variable will be replaced by the PHP document root directory specified for the project.
    • %SRC_DIR%: This variable will be replaced by the directory of the file that contains the include expression.
    • %ARG_N%: This variable only applies when the command is Replace Function. The N in the variable should be replaced with an integer (for example, %ARG_1% or %ARG_2%). This variable will then be replaced by the text that is passed into the function call's Nth parameter.

    The rules are applied in order. After each successful search and replace operation, the new text is checked to see if the file can be found. If the file is not found then the next rule is tried against the updated text.

    Every PHP project starts with three search and replace rules that try to replace some standard PHP constants and functions that are commonly used in include expressions.

Example: Configuring unresolved include expressions

Before you begin

Unresolved include expressions are configured in the Project Dependencies tabbed page of the project properties. Once in the page, click Configure Unresolved Include Expressions to open the Configure Unresolved Include Expressions dialog box.

This example assumes that you have added an include path to your project (this can be done while creating the project or while in the Project Dependencies page) and that you have run a scan. After the scan has completed, open the Configure Unresolved Include Expressions dialog box to see the Unresolved Include Expressions list. In this example, MYPROJECT_ROOT_PATH.'/a/b/filename.php', MYPROJECT_ROOT_PATH.'/language/'.$configInfo['language'].'/mypage.php', and configGet('database_inc','./includes/database.inc') are expressions in that list.

Procedure

  1. Replace a leading PHP constant or variable with a directory by following these steps:
    1. Select MYPROJECT_ROOT_PATH.'/a/b/filename.php' - this causes the text in the expression to be selected. You can then use the mouse or cursor keys to select a portion of the expression. Select MYPROJECT_ROOT_PATH and then right-click and choose Copy.
    2. Select the Search and Replace tab.
    3. Click the Add Rule for Selected Unresolved Item button (decorated with a green plus symbol). This adds a new search and replace rule to the list.
    4. In the new rule, select NewSearchText and then right-click and choose Paste from the menu. This causes NewSearchText to be replaced with MYPROJECT_ROOT_PATH.
    5. From the Replacement Text Variables menu, select %ROOT_DIR%. This causes the %ROOT_DIR% text string to be copied to the clipboard.
    6. In the rule, select NewReplacementText and then right-click and choose Paste from the menu. This causes NewReplacementText to be replaced with %ROOT_DIR%.
    You now have a new rule that will replace a constant with the path to the PHP document root directory. The PHP concatenation operator (.) and the text string that follows it will be combined with the replacement text to generate a single path expression. The next time the project is scanned, the include expressions that use this constant should succeed.
  2. To replace a dynamic expression with a single value:
    1. Select MYPROJECT_ROOT_PATH.'/language/'.$configInfo['language'].'/mypage.php' - this causes the text in the expression to be selected. You can then use the mouse or cursor keys to select a portion of the expression. Select $configInfo['language'] and then right-click and choose Copy.
    2. Select the Search and Replace tab.
    3. Click the Add Rule for Selected Unresolved Item button (decorated with a green plus symbol). This adds a new search and replace rule to the list.
    4. In the new rule, select NewSearchText and then right-click and choose Paste from the menu. This causes NewSearchText to be replaced with $configInfo['language'].
    5. In the rule, select NewReplacementText and replace it with new text by typing english.
    You now have a new rule that will replace the expression with the specified value. The PHP concatenation operator (.) will be applied to generate a single path expression. The next time the project is scanned, the include expressions that use this expression should succeed.
  3. To replace a PHP function call with one of its arguments:
    1. Select configGet('database_inc','./includes/database.inc') - this causes the text in the expression to be selected. You can then use the mouse or cursor keys to select a portion of the expression. Select configGet and then right-click and choose Copy.
    2. Select the Search and Replace tab.
    3. In the new rule, select Replace Text in the first column and then select Replace Function from the menu.
    4. In the rule, select NewSearchText and then right-click and choose Paste from the menu. This causes NewSearchText to be replaced with configGet.
    5. From the Replacement Text Variables menu, select %ARG_1%. This causes the variable to be copied to the clipboard.
    6. In the rule, select NewReplacementText and then right-click and choose Paste from the menu. Edit the pasted text to be %ARG_2% instead of %ARG_1%.
    You now have a new rule that will replace a function call with the value of its second parameter. The next time the project is scanned, the include expressions that use this function call should succeed.