Drupal’s entity relationship system is incredibly robust and powerful, but there is a messy dark side to this power. Countless times I’ve struggled to find a field because I assumed it was just in Content Type X when in reality it was in Taxonomy B, which is referenced on paragraph C, which is referenced in field D, which is on container paragraph E, which is FINALLY on content type X.
If that last sentence was hard to understand, that's the point. Tracking and explaining nested references is cumbersome and time consuming, and eventually I got tired of doing it the hard way. For that reason, I created Entity Tracer, a module that contextualizes the sprawling nest of entity references in a Drupal site and makes finding the right field a whole lot easier.
Setup
First the Entity Tracer has to be configured at “/admin/config/development/entity-tracer-settings”, where you’ll see a UI that looks like this:
Any content entities selected in the Entities section are thus available in the Entity Tracer UI, and the list of available entity types vary depending on which ones are in use on your site. The max depth value is mainly there to prevent an endless loop and likely won’t have to be adjusted. (See the “How it Works” section for more information.)
What does it do?
Once it's properly configured, this is what the Entity Tracer UI looks like:
First, you tell it which type of entity you want to examine, which auto-populates the bundle dropdown with all of the bundles of that type. Then you select that bundle and indicate which direction you want to search. First we’ll look at the Basic page node type going “down”.
This shows every entity reference that branches out from the Basic page, including the nested ones. It goes even further by providing a link to each field edit page for each referenced entity. It also deliberately lists both the human-readable and machine names just in case there was some chicanery with naming conventions. (See the field “Slide type” whose machine name is “field_tag”.)
Now, let's say you want to change something about the Tags taxonomy being referenced in “Slide Type”. You know that taxonomy is referenced on the Basic page, but you worry that it might be referenced in other places and that changing it might have unintended consequences. That is what the “Up” direction in the UI is for.
Now the results show that the Tags taxonomy is also in use on the Article node type in two different places, one buried in an paragraph called Article Section and again in a regular field called Tags. Note that this “up” selection also backtraces and links the fields just like “down” does.
Now all this information that is normally locked behind a dozen different clicks and windows is easily accessible on one page.
How does it work?
The backbone of this module is an enormous nested array of fields and references, which is constructed from the information found in the Entity Tracer settings page. This array is built by recursively stitching referenced fields and entities together, and that recursion is limited by the max depth value set in the settings. If your site has more than ten layers of nested references then you can set the depth higher (and you should really consider some refactoring to get that nesting under control).
The array is also cached to help with performance, and that cache breaks whenever the Entity Tracer settings are updated and when any entity fields are changed. The final custom piece is a Twig function that reads values off of the array and converts them into the correct field or entity representation.
What We Do
At Chapter Three, we believe every problem has a solution. Entity Tracer is just one of many contributions that we’ve made to Drupal over the years. Our M.O. is straightforward: if we run into a problem continuously, we take the time to develop and implement a creative solution. That’s what I did here and that’s what all my Chapter Three colleagues do when they get frustrated. It makes our own lives easier and helps the Drupal community at large.
Whether you’re working on theming, migration, or just plain bug fixes and you're stuck in the weeds trying to find a field, the Entity Tracer module can save you a lot of clicks and a lot of headache. Give it a try yourself and please let me know if you have any questions or suggestions for future improvements. Feel free to reach out to me on the official Drupal Slack or on Linkedin.
