Understand your project's site structure and data with Xray Audit

Light on the path 

The main challenge of complex projects is to calibrate their level of complexity. Not having the resources to carry out a prior audit can lead to blind decision-making. In fact, having accurate and up-to-date information increases efficiency both in management and development. Hence, it allows to:

• Objectively quantifying the complexity of the project and properly planning its execution by establishing the necessary resources and the most suitable strategy.
• Making informed decisions during development. For example, in a migration where 20 different paragraphs have been identified, we can know if some of them are hardly being used and are susceptible of being excluded from the migration.
• Evaluating the progress of a project and detecting in time if it is acquiring excessive complexity.
• Detecting possible improvements.
• Additionally, it facilitates onboarding for new developers.

So far, the advantages of audits are clear, but at Metadrop we have encountered some difficulties in their execution:

• The need for technical profiles to carry out the audit.
• The investment of time that these profiles require.
• The low maintainability and growth of the process. It is difficult to incorporate new reports into semi-manual audits.

In summary, it is impossible to audit in an agile way.

The Xray Audit module was created to overcome these limitations.

Xray Audit, or auditing at the click of a button

The Xray Audit module overcomes the drawbacks of semi-manual audits: it allows instant report generation by any profile, whether developers, project managers or administrators.

In order to facilitate the evolution of the module and simplify the process of implementing new reports, we have developed the module on Drupal's plugin system. This way, the developer can focus on the code that generates the report rather than on its integration with the module.

At the moment, while we expand the module, let's see the different types of reports that Xray Audit currently offers.

Content entitiy reports

Since Drupal 8, the Entity system is central, in fact, the community often compares site building through configuration to playing with LEGO, where we build an entity type (node), which can have different bundles (page, article), to which we can add fields and configure different ways to display the entity (displays).

What it can be useful for:

• Calibrate project complexity and identify risks.
• Know the number of components that need to be refactored.
• Identify underused or duplicate content types that can be eliminated.
• Detect custom entities that may not be immediately apparent.

Types of content entities

This report shows a list of all existing content entities, including those that belong to contrib and custom modules.

Entities of content: types and number

They provide information about the number of entities existing in the database grouped by language. For example, the number of article type nodes that have been created so far.

Available reports 

• Number of elements grouped by per type and per type and language
  • Nodes
  • Paragraphs
  • Taxonomies
• Number of Medias grouped by type
• Users and roles
  • Number of users per roles
  • Roles
  • Permissions assigned to each role.
  • User activity. It shows the number of users who have accessed in the last 3 months, from 3 to 6 months, and beyond 6 months.
    
     

Display reports

What it can be useful for:

• Establish strategies to increase performance. 
• Identification and categorization of components in refactoring work. 
• Understanding relationships between content entities. 
• Determining the use of field formatters and image styles.

Displays

These types of reports generate information about the configuration of displays for content entities: the fields that are shown and the formatter applied to each field.

In this image we see the different displays configured for a type of node called "recipe" (we generated these reports on a Drupal with the installed Umami profile).

• In the first column (fields), all recipe fields that exist at the database level are listed, and in the following columns, the fields configured for each display, as well as computed fields, are shown. These last ones are fields that do not exist as such in the database, but are calculated "on the fly", for example, the links field.
• Media image is a reference field of entity type, associated with media entities of type image. In the card display, we can see that it is configured to be displayed using the responsive_3x2 display.
• We can consult the media entity report to find out how the entity is displayed. On the other hand, in the teaser display, which usually shows the basic data of a content, this field is not displayed.

Report on Drupal modules

This section contains a report on the installed Drupal modules, the projects they belong to, and whether they are being used, that is, enabled.

This is done by reviewing the exported configuration files, not exclusively whether they are enabled in the environment and site where we are running the Xray Audit. 

This especially interesting in complex projects that use Configuration Split  as a tool for managing different configuration contexts. For example, a multisite where there is a config split for each site type (profile), as well as for each environment and site.

The report allows us to know which modules are enabled globally (through the core.extension file) or those that are enabled by a specific config split. For example, in the image, we can see how the Xray Audit module is only enabled in the local environment and not globally.

What it's useful for

• Identifying installed modules that can be removed because they are not enabled in any context. The "Project" column warns us of those modules that are submodules of other modules.
• Detecting inconsistencies in config split configuration.
• Of course, knowing which modules are being used at a glance.

How to extend it

The development of the module has been based on Drupal's plugin system to facilitate the integration of new reports. Developers can find instructions on how to do this in the README.

XrayAuditTaskPlugin is the main plugin that will integrate the code that generates the report with the module.

/** 
 * 
 * @XrayAuditTaskPlugin ( 
 *   id = "queries_data_media", 
 *   label = @Translation("Data about medias"), 
 *   description = @Translation("Queries execute on database to get reports about medias."), 
 *   group = "queries_data", 
 *   sort = 3, 
 *   operations = { 
 *  	"media_types" = { 
 *      	"label" = "Media types", 
 *      	"description" = "Media types.", 
 *      	"dependencies" = {"media"} 
 *   	}, 
 *	}, 
 *   dependencies = {"media"} 
 * ) 
 */ 

Parameters:

• id: unique identifier.
• label: name.
• description: a brief description of the reports generated by this plugin.
• group: the type of report to which it belongs.
• sort: position it occupies on the page where the list of available reports is displayed.
• operations: each operation generates a specific report, so a plugin can generate one or several reports. The parameters are:
  • index: unique identifier of the operation. This element is used to construct the URL of the report.
  • label: name of the operation.
  • description: brief description of the report.
  • dependencies: a list of modules that the report depends on. For example, if the report is going to extract data on the Paragraph entity, the Paragraphs module must be enabled. If the dependency is not met, this operation simply is not displayed to the user.
• dependencies: it is also possible to define dependencies at the XrayAuditTaskPlugin level and not just at the operation level.

Finally, you will need to override at least these two methods:

• getDataResultOperation: is responsible for executing the code that returns the data that will be used to generate the report. This data must be returned in an array.
• buildDataRenderArray: receives the data generated by the previous method and returns a render array.

Conclusion

Having a radiography of the project you are working on is fundamental during planning and development. But for it to be truly efficient, it must be possible to perform this radiograph at any point in the project, by non-technical profiles, without requiring additional time investment, and the information must be displayed in a centralized manner. With the Xray Audit module, we cover these needs.

At the moment, the module has the reports we have discussed in this article. In the not too distant future, we want to implement the following functionalities:

• Ability to preview the displays of different entities.
• List of blocks (block_content).
• List and use of Crops and image styles.
• List of active views, displays, and places where they are used.
• List of active modules used for page construction and site navigability, such as Paragraphs, Layout Builder, and Page Manager. The goal would be to quickly identify which site building strategy or strategies are being applied.
• Core status.
• List of active and inactive Webforms and places where they are displayed.

Your suggestions, proposals, and contributions are welcome ;)