Recently, I shared a guide for auditing, reviewing, and improving a Drupal module. In this guide, I suggested that developers experiment with the `drush generate` command, which uses the Drupal Code Generator to help gain an overall understanding of the potential architecture of a Drupal module. I decided to put my recommendation to the test by generating an example module using the Drupal Code Generator library. I've shared the results in a sandbox module on Drupal.org, called Drupal Code Generator Example.
Using code generators is new to me. Generally, my approach to module development is to find some example/template code, cut-n-paste the code into my project, and then customize the code as needed. I rely on my existing code, core, and the Examples for Developers module for my example/template code. When learning and reviewing a "Drupalism," an API or concept, I also google for documentation and blog posts. I’m hoping the Drupal Code Generator library (aka the `drush generate` command) will become another tool in my toolbox when building a Drupal module.
Feel free to browse my Drupal Code Generator Example module to gauge your level of understanding of a Drupal module's architecture. Now, I want to share some of my notes, recommendations, tips, and conclusions.
Some essential notes
Below are a few quick but essential notes about the output of the Drupal Code Generator.
First, generated examples are not always working code. There is a reasonable assumption that developers will review and customize the generated code.
Second, the generated namespaces can be tricky to work with, and plugins and services have varying namespaces. Occasionally, the generated namespaces are not specific enough, or conversely, a namespace can be too specific and may include duplicate names or labels. These nuances around the generated code led me to make some general recommendations.
Below are some recommendations when using the Drupal Code Generator.
- Always double-check the generated service name patterns against core and contrib modules.
- If you are an experienced Drupal developer, you should clean up file names and namespaces as needed.
- If you are an in-experienced Drupal developer, be careful when tweaking file names and namespaces. It is easy to break something unexpectedly.
- When cleaning up a namespace, it helps to use a professional IDE with refactoring tools like PhpStorm.
- Be aware of deprecated code warnings within some of the generated code.
- Deprecations should be fixed as needed.
- For really advanced concepts, including custom entities and plugins, start with a working example either from the Examples for Developers module or the Drupal Code Generator, which already has the intricate wiring working as expected.
The above recommendations and past observations made me want to share some specific tips around naming conventions with you.
Some tips about naming conventions
Naming things can be difficult. In Drupal, it can be challenging because the APIs and implementation patterns provided by the Symfony framework, Drupal core, and contributed modules are complex. A Drupal module can quickly become a web of services, interfaces, plugins, templates, and hooks which can be challenging to follow.
- Follow Drupal's naming conventions because dozens of smart people have contributed to them.
- As previously stated, when in doubt, look at other people's code.
- Don't use abbreviations and be as specific as needed to ensure things make sense to other developers.
- If a class, service, or plugin extends a base class, use the base class name within the child class. For example, all custom block class names should end with "Block."
Routes and links
- Prefix routes with the module's namespace.
- Links and tasks should mirror route names.
- Look at related code in Drupal core for additional guidance on route naming.
- Prefix most plugins with the module's class namespace. For example, if you have a module called 'foo,' the module's blocks should always start with foo_*.
- Plugin instances do not need to include the plugin's namespace. For example, If you are creating a block in code, the block's id does not need to end with *_block.
- If a plugin is module-specific and only one instance is expected, the plugin's id and name can be the same as the module's namespace. If the 'foo' module has one block, you can set the block's id to 'foo.''
- When in doubt, look for examples of plugin naming conventions in Drupal core.
- All services should include a module's namespace.
- Some plugins and services should begin with the plugin namespace, and others should be suffixed with the module's namespace.
Some final conclusions
There are many ways to learn Drupal, but the reality is Drupal can be difficult to learn and challenging to master. Besides using books and training videos, it helps to understand what developer-centric resources are available, and how to learn new concepts or reinforce existing knowledge.
With a trifecta of developer-centric tools, including the API documentation, examples, and code generation, new developers can discover how best to learn Drupal, and experienced developers can reinforce their existing knowledge.
The Drupal Code Generator library via the `drush generate` command is becoming another tool in my Drupal toolbox for building new modules and teaching people how to build modules.
I hope this post helps you think about your understanding of a Drupal module and make you
want to share some of your favorite tools in your individual Drupal toolbox.
Some references and resources
Below are some of the resources, articles, and posts I used to better understand a Drupal module's architecture and the code generators available for Drupal.
- Drupal Code Generator
Ivan Chi-teck maintains the Drupal Code Generator. Drupal Code Generator integrated into the Drush via the `drush generate` command.
- Examples for Developers
The Examples for Developer module is a community-maintained module that provides high-quality, well-documented API examples for a broad range of Drupal core functionality.
- Drupal API Reference
An API reference for Drupal, generated from comments embedded in the source code.
- Drupal API Documentation
Community-created documentation focused on an overview and details on all of Drupal's APIs.
- Using Code Generators in Drupal 8
In this blog post and video, Ivan Zugec walks-thru three code generators available for Drupal.