Figuring out what Drupal core code to patch

The code base for Drupal core is large, which can be overwhelming for new contributors trying to create their first few software fixes (refer to the step-by-step task writeups for making patches and merge requests). This page provides some suggestions for how to find the code that you need to edit to fix various types of issues, assuming you have already found a Drupal core issue to work on.

Search tools

There are several tools you can use to search the codebase.

Integrated Development Environments

If you use an integrated development environment (IDE), such as PHPStorm, you can use the tools in the IDE to:

• Search the codebase
• Jump to class/method definitions
• Debug code

See the section on IDEs on the Development tools page for more information about IDEs and how to configure them to work with Drupal.

Command-line grep

The grep command-line tool is quite useful for searching the codebase, especially when multiple grep commands are chained together, starting with a grep -R (recursive) command and potentially including a grep -v (exclude) or grep -i (case insensitive) command. For example, if you wanted to find where the user intrerface text "revisions for" was found, outside of test code, you could use the following command from the /core directory:

grep -R "revisions for" . | grep -v -i test

User interface text issues

Many new patch contributors start with issues where a small change needs to be made in some text on an administrative page. To find the code that generates the page, consider the following:

• Which core module generates the page? For instance, pages for listing and editing views are generated by the Views UI module, which can be found in the /core/modules/views_ui/ directory, and pages for user management come from the User module, which can be found in the /core/modules/user/ directory.
• Is the text embedded in PHP, JavaScript, or Twig/HTML code? The answer may not be easy to detect without doing a codebase search (see section above), but here are some pointers:
  • Most of the code base is PHP code; finding PHP code is described throughout this page.
  • PHP code for user interfaces generally returns a render array, which you can read about in the Render API topic on api.drupal.org. If a render array has a #theme element, the data will be passed to a Twig template of the same name for rendering. If it has a #type element, the data will be passed to an Element class for rendering (see the listing of elements by machine name on api.drupal.org).
  • JavaScript code is found in many core modules and themes (either in the main directory or a js subdirectory).
  • Twig templates contain most of the HTML markup and some UI text in Drupal core. Templates are found in modules and themes in templates subdirectories.
  • Help topics are also contained in special Twig templates (including their full text). Topics are located in help_topics subdirectories in modules and perhaps a few themes.
• Is it the Help block or the main page content?
  • The Help block (if you have the core Help module turned on) is located at the top of administrative pages (by default), and gives an overview of the function of the page.
  • Help block text is generated from functions called modulename_help() in the modulename.module file for each core module.
• For main page content, check for routing files. Modules that generate administrative pages usually have modulename.routing.yml files. Each entry in the file gives the path (the URL for the page) and provides a clue to finding the code that generates the page, which could be:
  • Controller -- in this example from user.routing.yml, the page at /user/logout is generated from the method logout() in the class \Drupal\user\Controller\UserController (see the Classes and Namespaces section below).
    

    user.logout:
      path: '/user/logout'
      defaults:
        _controller: '\Drupal\user\Controller\UserController::logout'
      requirements:
        _access: 'TRUE'
    

  • Form -- in this example from user.routing.yml, the page at /admin/config/people/accounts is generated from the form class \Drupal\user\AccountSettingsForm (see the Finding Drupal classes and namespaces section below).
    

    entity.user.admin_form:
      path: '/admin/config/people/accounts'
      defaults:
        _form: '\Drupal\user\AccountSettingsForm'
        _title: 'Account settings'
      requirements:
        _permission: 'administer account settings'
    

• Pages related to entities are not always found in routing files. Instead, you'll need to look at classes that define entities, which can be found in /core/modules/modulename/src/Entity directories. For instance, the Node entity (defined in /core/modules/node/src/Entity/Node.php) has this links section in its class documentation header, which defines the URLs for various node-related operations:
  

   *   links = {
   *     "canonical" = "/node/{node}",
   *     "delete-form" = "/node/{node}/delete",
   *     "delete-multiple-form" = "/admin/content/node/delete",
   *     "edit-form" = "/node/{node}/edit",
   *     "version-history" = "/node/{node}/revisions",
   *     "revision" = "/node/{node}/revisions/{node_revision}/view",
   *     "create" = "/node",
   *   }

  The classes that provide these operations pages are given above in the handlers section (again, see the Finding Drupal classes and namespaces section below):

   *   handlers = {
   *     "storage" = "Drupal\node\NodeStorage",
   *     "storage_schema" = "Drupal\node\NodeStorageSchema",
   *     "view_builder" = "Drupal\node\NodeViewBuilder",
   *     "access" = "Drupal\node\NodeAccessControlHandler",
   *     "views_data" = "Drupal\node\NodeViewsData",
   *     "form" = {
   *       "default" = "Drupal\node\NodeForm",
   *       "delete" = "Drupal\node\Form\NodeDeleteForm",
   *       "edit" = "Drupal\node\NodeForm",
   *       "delete-multiple-confirm" = "Drupal\node\Form\DeleteMultiple"
   *     },
  

API documentation issues

Many new patch contributors start with issues in Component "documentation", and specifically, issues that are requests to fix specially-formatted comments that document classes, functions, files, etc. In order to fix the issue, you will first need to locate the file containing the documentation that needs to be fixed.

Finding the file from an api.drupal.org link

The documentation on http://api.drupal.org is built from the PHP source code in selected projects (Drupal core and a few others currently; there are plans eventually to have all contributed projects on api.drupal.org). If your issue contains a link to api.drupal.org documentation:

1. Click the link.
2. Check the version of Drupal core you are looking at (top of the page). You always want to fix documentation in the latest development branch of the project, so if you are not looking at the latest version, find a link to the latest version by expanding the Same name and namespace in other branches section near the top of the page, and click the link to go to that version of the documentation.
3. Somewhere on the page, there will be a File heading, containing the full path of the file that contains the documentation you need to edit. Example: https://api.drupal.org/api/drupal/core%21core.api.php/group/best_practices/9.1.x contains this File section:

   This indicates that the documentation on that page is generated from file core.api.php starting at line 1543.

Finding the file from a class or function name

If the issue does not contain a link to api.drupal.org, you can search the http://api.drupal.org site for the class, function, or topic whose documentation needs to be updated. Once you find the class on the site, follow the steps in the previous section to locate the file that the class is in.

Alternatively, see the Finding Drupal classes and namespaces section below.

Finding Drupal classes and namespaces

If you determine that code for a certain class needs to be edited, how do you find it? In Drupal 8 and beyond, every PHP class in Drupal core has a namespace, and each namespace corresponds to a particular location:

• Each PHP class is in a file by itself, whose name is the name of the class with a .php extension.
• All Drupal PHP namespaces start with \Drupal. (If the class doesn't start with Drupal, see the note about third-party code below.)
• If the second component of the namespace is Core or Component, then the code is in a subdirectory of /core/lib/Drupal corresponding to the rest of the namespace. For example, class \Drupal\Core\Field\BaseFieldDefinition is in file /core/lib/Drupal/Core/Field/BaseFieldDefinition.php
• If the second component of the namespace is the lower-case machine name of a module, theme, or distribution, then the code is in the module, theme, or distribution's src subdirectory. For example, the class \Drupal\node\Form\NodeDeleteForm is in /core/modules/node/src/Form/NodeDeleteForm.php.
• If the second component of the namespace is Tests, followed by the machine name of a module, theme, or distribution, then the code is in the module, theme, or distribution's tests/src subdirectory. For example, the class \Drupal\Tests\node\Functional\Views\NodeViewsAnalyzeTest is in /core/modules/node/tests/src/Functional/Views/NodeViewsAnalyzeTest.php.
• There are a few base classes for tests located under the /core/tests directory whose namespace corresponds to the directory name.

A note about third-party (vendor) libraries

If you determine that the issue pertains to code under the /vendor or /core/assets/vendor directory, then it is code provided by an outside open-source project, and fixing it is generally out of scope for the Drupal project. Look in the code directory, or directories above, to find a README file that gives the web site for the project, or do a web search. Most likely their web site will have a developer guide that provides information about contributing, or a URL for GitHub or another source code hosting platform where you can create issues and submit patches or merge requests for consideration.