Planning a Better "Hello, World" for Drupal

I’ve spent a lot of time thinking about why learning Drupal is hard over the past 10 years and how we can lower the barrier by providing the right types of resources at the right time. This has led to the creation of things like the first-time contributor workshops at DrupalCon, the Drupal User Guide, and, of course, the library of content at Drupalize.Me.

What Drupal really needs right now is a curated, well-organized, and highly polished “Hello world” guide for developers. Something like React’s Quick Start, or Django’s writing your first Django app. A guide that you can work through in order, and by the end, you’ve created a real application with custom code you wrote, like the to-do list app so many of us created to learn PHP in the first place.

Image generated by OpenAI's DALL-E, a deep learning model specializing in image creation, 2023. Depicts a storybook-style illustration representing the programming concept 'Hello, World!' with the Drupal logo.

Creating more hands-on learning resources

For a long time, one of our goals at Drupalize.Me has been to create a deep library of reference-quality documentation. Tutorials we could point someone to and say, “If you want to know more about how X works, go here.” And “here” should be thorough, complete, and up-to-date.

Some of this is new content we create on Drupalize.Me, and some is content we help curate on Drupal.org. The idea is that once that is in place, we can create more hands-on guides, or recipes, for real-world scenarios. In those guides we could focus on the task at hand without having to get too deep into the weeds because we could point you to another page that has the nitty-gritty details – if that’s what you want.

For example, I want to be able to say things like; “Next, create a block plugin that outputs the content ‘Hello @name’ to the page” and then show some example code that does that. You can copy/paste the code and it’ll work, but that example code is making a whole lot of assumptions:

• You know what blocks are.
• You know what plugins are.
• You know what services are.
• You can use dependency injection to insert a service into a plugin class.
• You know what cache context and tags are and how to set them on a renderable array.
• You know what a render array is.
• ...and probably more.

Or to be able to do things like create a link to a route without explaining routing and rendering.

Sometimes all those prerequisites can get in the way of learning. Maybe it’s okay to just copy/paste the part of the code that deals with caching for now because that’s not the part we’re focused on. But, if you want to know more you should be able to click-through and dig in.

And while there’s always more reference documentation we can add, we feel like our current content is sufficiently deep to start creating some more high-level guided walk-throughs.

A quick-start guide for developers new to Drupal

Years ago I was involved with authoring the Drupal User Guide, and I’m still the maintainer today. The User Guide offers this kind of a learning path for Drupal site builders.

Now, we want to pick up where the Drupal User Guide left off, and create a Drupal Module Developer Guide. This hands-on module developer guide will build on the site and the guiding scenario used for the User Guide. We’ll walk through the process of authoring a couple of custom modules to meet your client’s needs and in the process, learn the basics of Drupal module development through writing “real-world” code.

The Drupal Module Developer Guide is going to make a bunch of assumptions like familiarity with PHP and Drupal site building. Maybe you’ve had some experience building sites with other frameworks. You’re comfortable with the command line, and the features of your IDE. Basically, this guide isn’t for someone new to development. It’s for a developer who is new to Drupal.

It’s still very much a work in progress, but it’s what I’ve been spending most of my time on this past month. And I’m supposed to blog about what I’ve been working on. 🙂

Below is the current working outline for the guide, and over the next few months we’ll be writing example code, drafting tutorials, and recording videos to fill out this outline.

If you’ve got any thoughts on this outline I would love to hear them. Leave a comment, or send me an email: [email protected].

1. Preface
   1. Audience & Goal
   2. Organization
   3. Guiding Scenario
   4. Prerequisites - e.g. OOP PHP / CLI / etc.
   5. Recommended prereq: Drupal User Guide Chapters 1-9 (You should be familiar with Drupal as a site building tool before you attempt to build a module.)
2. Chapter: Introduction to Drupal Module Development
   1. Concept: What are modules? - Extend, Alter, and Enhance Drupal
   2. Concept: How Drupal Handles a Page Request (request → routing → controller → view → response)
   3. Concept: Documentation for developers (api.drupal.org, drupal.org/project/examples, etc.)
   4. Concept: Development environment - use DDEV - link to quickstart guide?
   5. Concept: Tools for module developers (drush, devel, phpstan, xdebug, etc.)
   6. Task: Setup DDEV and Build the Initial Site - link to user guide content
   7. Task: Install Drush & Devel (assume people are starting from a complete version of the user guide site)
3. Chapter: Hello world
   1. Focus more on copy/paste this code and you’ll get something that works, come back and explain the details later.
   2. Concept: Where does your custom code go and what should you name it?
   3. Concept: Info files
   4. Task: Create a .info.yml file
   5. Task: Create a custom block (Just get something simple on the page - Block plugin - “Hello world block”)
   6. Task: Enable your custom module
4. Chapter: Routes and Controllers
   1. Concept: Routing
   2. Concept: PHP Namespaces and PSR-4
   3. Concept: Controllers
   4. Task: Create a new route
   5. Task: Create a controller
   6. Task: Add a parameter to the route
   7. Concept: Menu Items and Links
   8. Task: Define a Menu Item
   9. Concept: Permissions
   10. Task: Define a new permission
5. Chapter: Services & Dependency Injection
   1. Concept: What are services?
   2. Concept: Dependency Injection
   3. Task: Locate Existing Services and their Documentation
   4. Task: Use a Service In a Controller
   5. Task: Define a Service - ¯\*(ツ)*/¯ - make sure the new service depends on another service to show how to chain them in services.yml
   6. (maybe) Concept: Custom Services
   7. (maybe) Concept: Third Party Libraries via Composer
   8. (maybe) Task: Add A composer.json File — Maybe something with a 3rd party composer library?
6. Chapter: Outputting Themable Content from a Module
   1. Concept: Themable output
   2. Concept: Render API
   3. Task: Define Content Using Render API
   4. Concept: Template Files
   5. Task: Add a template file (for our page)
   6. Task: Add a preprocess function
   7. Concept: Asset Libraries
   8. Task: Add CSS/JavaScript to the page
   9. Concept: Localization (i18n)
   10. Task: Use t() to output strings
7. Chapter: Hooks and Events
   1. Concept: What are Hooks?
   2. Concept: What are Events?
   3. Task: Locate hooks and their documentation (see what hooks are invoked when)
   4. Task: Implement hook_help()
   5. Task: Invoke a Custom Hook
8. Chapter: Plugins
   1. Concept: What are Plugins?
   2. Task: Implement a Plugin (Revisit the block example from hello world and explain it from the lens of plugins?)
   3. Task: Use a Service in a Plugin
9. Chapter: Forms
   1. Concept: Form API
   2. Concept: Form Controllers
   3. Task: Create a Settings Form (location to use for looking up weather)
   4. Task: Validate User Input
   5. Task: Handle Submitted Data (save as config)
   6. Concept: Alter Existing Forms
   7. Task: Add a terms of service checkbox to user reg form and require it gets checked
10. Chapter: Working with Data
    1. Concept: Types of Data - Config vs. Content vs. State
    2. Concept: Configuration Management
    3. Task: Use Custom Configuration Data (pull location setting into weather checker service)
    4. Task: Define a Configuration Schema & Defaults
    5. Concept: Entities for Data Storage
    6. Concept: Fieldable Entities
    7. Task: Setup required … set up the new field(s) on vendor content type, and create a new module skeleton.
    8. Task: Create a Form For Editing An Entity (dynamic routing like vendor/{node.id}/status)
    9. Task: Read an Entity’s Field Values
    10. Task: Update An Entity
    11. Task: Use parameter upcasting for entities in routes
    12. Task: Entity Validation - Validate Username
    13. Concept: Query Entities with EntityTypeManager
    14. Task: Create a Page Showing Summary of Vendor Statuses
    15. Task: Implement a cron task to reset vendor attending status
    16. Concept: Custom Entity Types (why, when, link to how)
11. Chapter: Caching
    1. Concept: Caching
    2. Task: Cache Data Retrieved from Weather API
    3. Task: Add Cache Context and Tags to Render Arrays
12. Chapter: Testing
    1. Concept: Types of Tests in Drupal
    2. Task: Run a Test Suite
    3. Task: (Write a unit or kernel test)
    4. Task: (Write a functional test)
13. Chapter: Additional considerations
    1. Concept: Security
    2. Concept: Coding Standards
    3. Task: Lint Your Code with phpcs
    4. Concept: Update Hooks
    5. Task: Implement hook_update_N() to modify existing data
14. Chapter: Collaborate with the community
    1. There’s a module that does most of what I need but it needs some updates, or tweaks, how can we help with that instead of writing a custom one?
    2. Concept: Contribution and Collaboration
    3. Task: Publish Your Custom Module on Drupal.org
    4. Task: Fix a Bug in an Existing Contributed Module
15. Chapter: Final Thoughts
    1. Learning More
       • drupal.org/project/examples
    2. Getting Support
16. Index