Configuring unresolved PHP class references

Before you begin

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

Procedure

  1. Click Configure Unresolved Class References to open the Configure Unresolved Class References dialog box.
  2. The upper portion of the dialog box lists the unresolved class references (all class references that were not resolved during the last scan). Information provided about the class references includes:
    OptionDescription
    Class Name / Generated File Name This column displays the class name that was referenced in the source code. This column can be expanded by clicking +, which will then show the generated file name that was used during the last scan to try and find the class. There may be multiple file names when it is expanded - one for each place in the source code where this class was used.
    Status This column will contain an X for classes that are unresolved or a check mark for classes that were successfully resolved.
    Resolved By This column indicates how the generated filename was created. Values include:
    • AutoResolver: The application used internal heuristics to find the file.
    • SearchReplace: One or more search and replace rules were applied to the class name to create the generated file name.
    Source File, Line, Column These columns show the location in the source code in which the class 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 class names can have multiple generated file name lines when expanded. These columns will have appropriate text for each of these generated file name lines.
  3. In the lower portion of the dialog box, the Class Include Path tab contains the same class 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 class references).
  4. In the lower portion of the dialog box, the Search and Replace tab is used for adding rules for modifying an unresolved class name to a full or partial file path containing the definition of that class. 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:
    • Match Text: This command is used for text search and replace. The * character is allowed in the search text and will match 0 or more characters. The results of a match text will not affect any other search and replace rules. This is usually used to try adding an extension to the class name or to filter out prefixes and suffixes from the class name when generating a file name.
    • 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 class name, it is replaced with the Replacement Text. This is used to modify the class name for use in the following rules.
    • 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 class reference. You can select text within a class name 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 a file containing the definition of the class. 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 reference to the class.
    • %MATCH_N%: This variable only applies when the command is Match Text. The N in the variable should be replaced with an integer (for example, %MATCH_1% or %MATCH_2%). This variable will then be replaced by the text that matches the Nth * in the search text.

    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, except if the command is Match Text.

    Every PHP Project starts with two simple Search/Replace rules that try to add some common file extensions onto the class name.

  5. In the lower portion of the dialog box, the Found Classes tab lists all classes that were found during the last scan. This can be used to update the class include path and search and replace rules. You can select an unresolved class reference in the Unresolved Class References section of the dialog and click Find Declaration. If the declaration is found, it will display in the Found Classes tab list.

Example: Configuring unresolved class references

Before you begin

Unresolved class references are configured in the Project Dependencies tabbed page of the project properties. Once in the page, click Configure Unresolved Class References to open the Configure Unresolved Class References dialog box.

This example assumes that you have added a class 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 Class References dialog box to see the Unresolved Class References list.

In these examples, you are providing replacement text values. Note that these can have multiple variables in the text - for example, %ROOT_DIR%/modules/%MATCH_1%/classes/%MATCH_1%.class.inc.

Procedure

  1. To add another file extension that is used by include files:
    1. Select the Search and Replace tab.
    2. 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.
    3. In the new rule, select the Replacement Text, %MATCH_1%.php. In this string, delete .php and type .class.inc in its place. The Replacement Text should now be %MATCH_1%.class.inc.
    You now have a new rule that will try to add the suffix .class.inc to a class name when resolving the class.
  2. To remove a prefix from a class name:
    1. Select the Search and Replace tab.
    2. 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.
    3. In the new rule, select the string in the Search Text column (*) and type Abc* in its place.
    4. Do not alter the %MATCH_1%.php replacement text.
    You now have a new rule that will map class names like AbcHello to Hello.php.
  3. To remove a suffix from a class name:
    1. Select the Search and Replace tab.
    2. 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.
    3. In the new rule, select the string in the Search Text column (*) and type *Xyz in its place.
    4. Do not alter the %MATCH_1%.php replacement text.
    You now have a new rule that will map class names like ByeByeXyz to ByeBye.php.
  4. You may want to map class names like Abc_Def_Ghi_class so that their prefixes are used as relative paths into the file system (for example Abc/Def/Ghi/class.php). To modify class name text for use in other rules:
    1. Select the Search and Replace tab.
    2. 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.
    3. In the new rule, select Match Text in the first column and then select Replace Text from the menu.
    4. In the rule, select the string in the Search Text column (*) and type _ in its place.
    5. Select the string in the Replacement Text column and type / in its place.
    6. While the rule is selected, click Move Up to move this rule to the top of the list.
    You now have a new rule that will replace underscores (_) with slashes (/) and the updated text will be used by all subsequent rules. This rule will change Abc_Def_Ghi_class to Abc/Def/Ghi/class and then the remaining Match Text rules will try to add extensions such as .php and .inc.