webjoke.de

Step debugging is one of the first things every developer should master in any language or environment, and it's my opinion that it's just as fundamental as version control. With DDEV, getting Xdebug working with PhpStorm takes less than five minutes and no php.ini fiddling. This screencast shows the whole thing on a TYPO3 project, start to finish.

Watch the Video What You'll See

• Installing the DDEV Integration Plugin for PhpStorm
• Setting a breakpoint at the entry point of a TYPO3 project
• Telling PhpStorm to listen for PHP debug connections
• Enabling Xdebug with ddev xdebug on
• Stepping over (F8) and stepping into (F7) code as a page loads

The Steps

1. Install the DDEV Integration plugin from the PhpStorm marketplace (not required, but it handles most of the setup for you)
2. Set a breakpoint
3. Tell PhpStorm to listen for PHP debug connections
4. ddev xdebug on
5. Visit the page — PhpStorm stops at your breakpoint automatically

That's it. No manual php.ini changes, no fussing with host.docker.internal, no separate Xdebug install.

Works the Same Everywhere

This screencast uses PhpStorm, but the same setup works identically with VS Code, on Linux, and on Windows with WSL2. If you're setting up a new machine, see:

• DDEV on Linux in 10 Minutes
• Watch: DDEV from scratch with Windows WSL2
• Watch: DDEV From Scratch with macOS

More on Xdebug and DDEV

• The ddev utility xdebug-diagnose --interactive command can help with port conflict and related setup problems. Try it out!
• Xdebug in DDEV: Understanding, Debugging, and Troubleshooting Step Debugging — the updated guide
• DDEV and Xdebug: Debugging and sorting out problems
• Xdebug.org and its step debugging documentation

Xdebug is created and maintained by Derick Rethans. He's been maintaining it for 20+ years. Send money to the Xdebug project!. The DDEV Foundation supports it as an upstream project, you can too.

Learn More

• Full details on DDEV's Xdebug integration, including troubleshooting, are in the DDEV documentation.

If you have questions, reach out in any of the support channels.

Follow our blog, Bluesky, LinkedIn, Mastodon, and join us on Discord. Sign up for the monthly newsletter.

This article was edited and refined with assistance from Claude Code.

Accessibility failures often surface after budgets, architecture, and delivery plans are already fixed. Mike Gifford argues that public agencies can reduce that pattern by contributing fixes upstream.

Discover how to leverage AI as a reasoning partner in Drupal development, moving beyond coding to high-level architecture and system design.

Editors often rely on developers for simple display variations. ERVMS moves those decisions into the editorial workflow without changing Drupal's existing display architecture.

Drupal Anti-Spam: NoBotIQ vs CAPTCHA, Honeypot, CleanTalk, and Other Solutions admin Fri, 07/10/2026 - 14:18

Hi friends! It's been a while since our last article, and you might have been wondering when we'd be back with something new. Thanks for your patience—we're excited to return with a fresh topic that many Drupal site owners, marketers, and developers deal with on a regular basis: spam. Drupal websites can be secure, flexible, and high-performing. But there is one issue that keeps bothering site owners, marketers, and developers again and again. It is spam.

Spam is no longer only about strange messages in a contact form. Today, it can mean fake registrations, low-quality leads, disposable emails, bot-driven submissions, and AI-generated junk content. All of this creates extra moderation work, pollutes your CRM, and wastes your team’s time.

That is exactly why Drupal anti-spam protection matters much more now than it did a few years ago.

Near the end of most Open Source licenses, usually in capital letters, sits a clause that disclaims almost everything: no warranty, no liability, use at your own risk.

For an organization that depends on that code, the clause is harsh. If the code fails and takes your data or revenue with it, the license owes you nothing. No fix, no refund, and no one to explain what went wrong.

That is the license doing its job. It makes the code available and protects the people who share it. Without that protection, sharing code could become a gift that backfires: a generous act turned into unlimited legal risk.

But the license can only answer the legal questions: who may use the code, on what terms, and what risk the authors are willing to accept. It cannot tell you what kind of Open Source project you are working with.

Some Open Source is "License-only Open Source": code released under an Open Source license, without active stewardship or any promise of ongoing care. There is no guarantee of updates, fixes, security response, or long-term support.

Other Open Source is "Stewarded Open Source": code cared for as shared infrastructure. Maintainers review contributions, fix bugs, respond to security issues, manage releases, provide long-term support, and much more. Organizations fund maintainers, support core development, donate infrastructure, and absorb costs end users never see.

Both types of projects are Open Source, but they are not the same. A weekend hobby project and business-critical software can ship under the exact same license. Legally, they look identical. Practically, they are worlds apart.

The difference is stewardship. The license makes code available; stewardship makes it dependable. And the more people or organizations depend on a project, the more stewardship it often requires.

Responsibility is the tax on relevance.

Distinguishing license-only from stewarded Open Source gives us the vocabulary to describe two very different realities that the words "Open Source" alone do not capture.

For example, the distinction becomes useful when we talk about contribution. If a company depends on Open Source, should it give back?

For license-only Open Source, the answer can be simple: no one is required to contribute, and that is the point. The code was shared freely, without a promise of care or an expectation of return.

Stewarded Open Source is different. The license may still require nothing, but the work does not happen for free. Someone is paying to keep your code usable, secure, and available. When you depend on that work, the question is not only what the license allows, but who helps carry the responsibilities beyond what the license requires.

The license says use at your own risk. Stewardship is what happens when people decide you should not have to.

This is the fifth post in our GitLab issue migration series. So far we’ve covered the immediate changes, the new workflow for migrated projects, how to use it, and what the migration looks like from a contributor’s perspective. This post is about which projects we’re migrating next, and why.

We are now migrating projects maintained by Ripple Makers, the individual members of the Drupal Association. If you’re a Ripple Maker who maintains one or more contrib projects, this is our thank you for your membership.

Why members first?

Migrating issues to GitLab, and running GitLab itself, has a real cost. There is engineering time for the migration tooling, upgrades for git.drupalcode.org, and ongoing work on the integrations that keep contribution credit, issue forks, and the rest of the Drupal.org glue working smoothly.

That cost is covered by the people and organizations who fund the Drupal Association: Ripple Makers and Drupal Certified Partners. As we schedule migration batches, we are prioritizing projects maintained by members and projects supported by Drupal Certified Partners.

To be clear: every project will eventually be migrated. Membership doesn’t change whether your project moves; it changes when. Prioritizing members is a small way to say thank you to the people whose contributions make the infrastructure itself possible.

Not a member yet?

If you’d like your projects prioritized, and, more importantly, if you’d like to support the infrastructure that the whole Drupal ecosystem runs on, this is a good moment:

• Become a Ripple Maker: individual membership in the Drupal Association.
• Become a Drupal Certified Partner: for agencies and organizations.

Membership funds don’t just pay for GitLab. They keep Drupal.org, project packaging, GitLab CI, automatic updates infrastructure, and more running for everyone, members and non-members alike.

Reporting bugs and getting help

Found a bug in the migration itself or in the integration between Drupal.org and GitLab? Please file it in the Drupal.org customizations issue queue.

Have a question, or want to share feedback on the new workflow? Join the #gitlab-issues-feedback channel on the Drupal community Slack.

We’re continuing to iterate on this transition based on what we hear from maintainers and contributors in migrated projects. Your feedback now shapes the experience for the rest of contrib later.

Related blog posts in this series:

• GitLab issue migration: immediate changes
• GitLab issue migration: the new workflow for migrated projects
• GitLab issue migration: how to use the new workflow
• GitLab issue migration: a contributor’s perspective

Related issues

• Opt-in your project for migration to GitLab Issues. Eventually, all projects will be migrated.
• Provide feedback on the GitLab issue migration.
• General issue for the GitLab migration.

By the Drupal AI Initiative

Following our announcement last week introducing Inside AI and Outside AI, we are excited to share how we are scaling our leadership and organizational structure to support these two parallel workstreams.

What started as an ambitious vision originally founded by Jamie Abrahams from FreelyGive quickly gained community-wide momentum. In June 2025, our founding partners – 1xINTERNET, Acquia, Dropsolid, FreelyGive, and Salsa Digital – came together to establish the official Drupal AI Initiative, providing a cohesive strategy, baseline funding, and dedicated staff. Since then, the initiative has grown rapidly to encompass over 30 partner organizations, with many of their team members stepping directly into key leadership and execution roles.

To support our rapid growth and ensure effective daily coordination, we are evolving our structure into a more robust, three-tier governance model comprising a Drupal AI Board, a Drupal AI Leadership Team, and our existing community of AI Partners.

The Drupal AI Leadership Team

The purpose of the Drupal AI Leadership Team is to coordinate day-to-day project execution, align technical and cross-functional work streams, and ensure all initiative activities successfully deliver on our strategic goals. 

At the center of this governance evolution, this team formalizes leadership roles that have organically emerged and evolved over the past year. Rather than introducing a brand-new operational layer, this structure officially empowers the individual contributors who have already been actively driving the initiative's day-to-day work.

By having dedicated, individual leads taking ownership of specific subject-matter areas, we ensure that every key aspect of the initiative has focused guidance. This structure also provides a natural avenue for our partner organizations to showcase their technical talent and gain visibility within the ecosystem, while placing experienced contributors in charge of critical technical and horizontal areas.

 

The Leadership Team's execution is divided into two distinct, cooperative disciplines:

• Functional Leads: Individuals who maintain direct ownership of specific functional modules or recipes (such as Agents, Search, or the Context Control Center) and align development roadmaps with the broader goals of the initiative.
• Cross-Functional Leads: Leads who provide horizontal support across the entire initiative for critical non-feature disciplines like UX, QA, Marketing, Documentation, and Community coordination.

This division ensures that technical teams can focus on delivering robust functionality, while cross-functional leads act as an internal agency to validate, test, document, and promote those features before they reach users.

In an upcoming post, we will share more details about the leadership team structure, introduce our current domain leads, and outline vacant positions.

The Drupal AI Board

Our founding partners, who previously made up the initiative's core steering group, are transitioning to become the members of the Drupal AI Board.

The Board serves as the strategic and supporting foundation for the Leadership Team, establishing a strong, predictable operational environment. Rather than individual developers having to balance ecosystem coordination, funding allocations, and administrative hurdles alongside daily coding, the Board takes on these responsibilities.

Composed of our founding partner companies, the Board is responsible for setting the high-level strategy, defining the general initiative direction, and prioritizing our long-term roadmap. In addition to guiding this overarching strategy, the Board provides baseline initiative funding and staff, manages overall ecosystem alignment, and secures ongoing partner resource commitments. This structural backing ensures a stable operational runway, allowing the Board to focus on defining leadership functions, appointing execution leads, and securing the necessary resource allocations so developers can focus strictly on build and delivery.

What Changes? (And What Stays the Same)

For the developers, builders, and content creators actively contributing to the initiative, the day-to-day experience will feel familiar, but with clearer support structures.

Our established sprinting procedures remain completely unchanged. The community and partner teams will continue to collaborate on their scheduled sprints.

However, we are introducing two key improvements:

1. Clear Authority and Direction: Our leads now have clear authority over their respective subject-matter areas. They will provide structured guidance and continuously groomed, public backlogs of issues for the contributors to Drupal AI.
2. Improved Delivery and Speed: With structured coordination, individual contributions will integrate more seamlessly into the broader roadmap. Distributing this responsibility across more shoulders allows us to increase our overall delivery speed and execute on more complex strategic goals simultaneously.

This structural evolution ensures that everything built by both Inside AI and Outside AI integrates seamlessly with the broader Drupal AI roadmap and aligns directly with our collective short term and long-term goals.

How to Get Involved

As we step into this new phase of growth, we are looking for dedicated partners and brilliant minds to help execute our goals.

• Become a Lead: If you have proven leadership within the Drupal AI ecosystem and want to actively guide a subject area (committing 1–2 days per week), we want to hear from you. Board-appointed lead positions are open to active, dedicated contributors.
• Contribute to the Initiative: You can get involved with the initiative's next phase by:
  • Exploring options to become an AI Partner to collaborate with our growing network of supporting organizations.
  • Joining the conversation in the #ai-initiative channel on Drupal Slack to connect with other contributors and the leadership team.

Our AI Partners

The Drupal AI Initiative is made possible by the generous funding, resources, and technical contributions of our partner network. We are incredibly grateful to these companies for driving the future of open-source AI:

Founding Partners

• 1xINTERNET
• Acquia
• Dropsolid
• FreelyGive
• Salsa Digital

Gold Partners

• amazee.io
• Axelerant
• EPAM Systems
• E-Sepia Web Innovation
• Esinergia
• Mearra
• OpenSense Labs
• Pantheon
• QED42
• Reading Room
• Seed EM
• Tag1 Consulting
• Vardot
• Zoocha

Silver Partners

• Brainsum
• Calibrate
• Cambridge University Press
• Cinder Systems
• drunomics
• Drupal Forge
• Elevated Third
• Foster Interactive
• Kalamuna
• ImageX
• Integral Vision
• Morpht
• OPTASY

You can view the full list and status of our contributing sponsors on the official Drupal AI Partners directory.
 

Join Martin, Andy and Mike as they discuss what Drupal site templates are and how they differ from Drupal's traditionally bare-bones starting point, aiming to reduce setup effort and total cost of ownership while making Drupal competitive again for small nonprofits and smaller sites. They compare building templates versus client sites, covering the evolution from early Layout Builder/Recipes work to today's simpler packaging via a Drush site:export workflow, plus tooling like DripYard Recipe Builder for extracting reusable "recipe" parts.

For show notes visit: https://www.talkingDrupal.com/cafe018

Topics Martin Anderson-Clutz

Based in London, Ontario, Martin transitioned from graphic design to web development, ultimately specializing in Drupal in 2005. Currently working as a Product Marketing Manager at Acquia, he is Triple Certified in Drupal and UX-certified by the world-renowned Nielsen Norman Group. His key contributions include: As a speaker & writer, presenting at Drupalcamps and Drupalcons, and a published blogger across multiple platforms, including the Acquia Dev Portal and opensource.com; as a podcast host, participating in the Talking Drupal podcast, including as the "Module of the Week" correspondent; and as an open source maintainer, developing and maintaining popular Drupal contrib modules and recipes, including Smart Date and Fullcalendar.

Andy Giles

Andy is a Drupal back-end developer. In 2012, he founded Blue Oak Interactive, a development and consulting agency focused on complex Drupal site builds, particularly in e-commerce. In 2025, he partnered with Mike Herchel to launch Dripyard, a premium Drupal theme designed to reduce the cost of ownership and enhance the developer experience for modern Drupal projects.

Mike Herchel

Mike is a founder & developer at Dripyard, and is a longtime contributor to Drupal. He has played a key role in modernizing Drupal's frontend architecture, performance, and accessibility, and is known for helping bring Drupal's component-driven development into mainstream use. Mike has delivered projects for organizations including IBM, the U.S. Small Business Administration, and the U.S. court system. He is a frequent speaker on performance, accessibility, and modern frontend practices.

• What Are Site Templates
• Drupal CMS Template Picker
• Why Templates Matter
• Building Templates Workflow
• Recipes And Custom Tooling
• Canvas And Theme Strategy
• React Components And AI
• Drupal 11.4 Compatibility
• Canvas Patterns Explained
• Pricing Adoption And AI
• AI In Their Workflow
• Internal Templates And Wrap Up

Guests

Martin Anderson-Clutz - mandclu.com mandclu

Andy Giles - andyg5000 Dripyard

Mike Herchel - mherchel Dripyard

Using AI to Moderate Content in an Existing Drupal Workflow Joel Steidl Wed, 07/08/2026 - 16:16 Drupal A New Solution to An Old Problem

Content moderation is a data processing problem. For large sites with many content contributors, moderators can get bogged down catching obvious content policy violations without having time to do real editorial work.

Meanwhile, AI is great at fast, consistent classification of text, which is exactly the kind of work that can clog an editorial queue. It’s not a replacement for human judgment: it makes mistakes, it can be gamed, and it lacks context. But as a first-pass filter, AI can meaningfully shrink the noise that reaches a human reviewer.

This post walks through adding that type of AI content filter to an existing Drupal workflow using contrib modules and no custom code.

Implementing the SolutionModules

The full solution uses zero custom code. Here are the key contrib modules:

• drupal/ai — Provider-agnostic AI framework
• drupal/ai_provider_openai — OpenAI integration for drupal/ai
• drupal/ai_integration_eca — ECA action plugins for AI operations, including a dedicated Moderation action
• drupal/key — Secure API key storage via environment variable
• drupal/eca — Event-Condition-Action automation engine

The Basic Setup

The assumption is that a site already has a working Content Moderation workflow. The AI gate slots in between author submission and the editor queue:

[Before] Draft → Needs Review → Published   [After] Draft → Needs Review → [AI gate] → AI Review Passed → Published ↘ Rejected

To support this, the workflow needs two new states (AI Review Passed, Rejected) and two new transitions (AI Approve, AI Reject). Those transitions should not be granted to any UI role as they’re triggered only by ECA.

The five modules listed above need to be installed, an AI provider configured with a securely stored API key, and the updated workflow applied to the relevant content type.

Workflow state diagram The ECA Model

This is the core of the implementation.

Create a new ECA model at Admin → Configuration → ECA. The model has five nodes:

1. Event — Workflow: state transition Fires when an article transitions to needs_review.

2. Action — Token: set value Stores [entity:body:value] into a token named moderation_input. This uses ECA’s token replacement, which resolves field values correctly at runtime. (A note on this: the more obvious Get field value action returns null for body fields in practice — token replacement is the right approach here.)

3. Action — Moderation (from AI Integration for ECA) Calls the AI provider’s moderation operation. Set model to openai / omni-moderation-latest, token input to moderation_input, and token result to ai_result. The result token exposes [ai_result:flagged] (1 or 0) and [ai_result:information] (per-category scores).

4. Action — Workflow: transition (condition: [ai_result:flagged] = 1) Transitions to rejected. Revision log: AI moderation: content flagged.

5. Action — Workflow: transition (condition: [ai_result:flagged] = 1, negated) Transitions to ai_review_passed. Revision log: AI moderation: content passed initial screening.

The conditions use ECA’s built-in Compare two scalar values plugin. Steps 4 and 5 share the same condition — one negated, one not.

ECA model visual Moderation action configuration panel Testing

Submitting a benign article routes it to ai_review_passed with the pass log entry. Submitting content that violates the violence policy routes it to rejected with the flagged log entry. Both transitions appear in the node’s revision history with the AI-stamped message.

Node revision history on a rejected article Going FurtherCustom Moderation Prompts

The OpenAI Moderation API uses fixed categories. If your policy doesn’t map to them cleanly — community guidelines, brand safety rules, domain-specific restrictions — you can replace the Moderation action with a Chat action and a configurable system prompt. The rest of the ECA model stays the same.

With a Chat action returning structured JSON (response_format: json_object), you define exactly what the AI evaluates and how it reports back. The downstream ECA conditions check the response token the same way. This makes the screening logic editable in the UI without a code change or redeploy.

Giving Authors a Path Forward

A bare rejection with no context isn’t great author experience. ECA can handle the follow-on steps too. On the rejection branch, you can chain additional actions before or after the transition: send the author an email using [ai_result:information] to surface which categories were flagged, set a message on the form, or move the node to a Needs Revision state rather than a hard Rejected — giving authors the ability to edit and resubmit rather than starting over.

You could also model a full revision loop: Rejected → Needs Revision → Needs Review (with the AI check firing again on resubmit). Whether that’s appropriate depends on your content volume and how much trust you extend to repeat offenders, but the workflow and ECA config support it without any custom code.

Closing Notes

The drupal/ai_integration_eca module is what makes this approach work cleanly. Without it, inserting AI into an ECA model would require a custom action plugin. With it, the entire integration is UI-configurable and exportable as config.

A few things worth knowing before you build on this:

• The ai_eca submodule inside drupal/ai is deprecated as of 1.x. Use drupal/ai_integration_eca (a separate package) instead.
• drupal/ai_integration_eca is still at RC as of this writing — worth checking for a stable release before going to production.

Nathaniel Woodland

coder.ddev.com gives you a full DDEV environment in the cloud, no local Docker required. This is a quick look at using it for a TYPO3 project with the freeform template.

For general background on coder.ddev.com, including access requirements and the other available templates, see the announcement post.

Watch the Video What You'll See

• How to get access to coder.ddev.com
• Creating a coder.ddev.com workspace with the freeform template
• Cloning the rfay/typo3demo project and running ddev coder-setup + ddev start
• Fixing a trustedHostsPattern error with ddev restart after Composer brings in the rest of the code
• The working site and TYPO3 backend on the workspace's *.coder.ddev.com subdomain
• Two ways to share it: natively with other coder.ddev.com users, or publicly with ddev share

Steps

1. Get access to coder.ddev.com either via your organization having "partner" status with DDEV Foundation or by asking for access.
2. Log in to coder.ddev.com with GitHub and create a workspace using the freeform template. The project name you choose matters, since coder.ddev.com uses it to set up proxying.
3. Open a terminal in the workspace (web terminal, VS Code Web, or SSH via the coder CLI) and clone your TYPO3 project.
4. Run ddev coder-setup once in the project directory, then ddev start. If the project has a post-start Composer install hook, like rfay/typo3demo, it'll finish setting itself up automatically.
5. If ddev launch shows a trusted-host error, it's because Composer brought in the rest of the code after the first ddev start already generated additional.php. Run ddev restart to regenerate it, then reload.

Sharing What You Built

The workspace can be shared with other coder.ddev.com users directly, without any extra setup.

It can also be shared with ddev share, since rfay/typo3demo uses a relative base (/camino) instead of a hardcoded URL. Projects that do hardcode a full URL in base need the pre-share/post-share hook fix described in Sharing Your TYPO3 Project with ddev share.

Learn More

• Introducing coder.ddev.com: DDEV in the Cloud
• github.com/ddev/coder-ddev — templates and source for the freeform, drupal-core, and drupal-contrib templates
• DDEV TYPO3 quickstart

If you have questions, reach out in any of the support channels.

Follow our blog, Bluesky, LinkedIn, Mastodon, and join us on Discord. Sign up for the monthly newsletter.

This article was edited and refined with assistance from Claude Code.

Architecture choices become clearer when the CMS is not the whole application. Yii3 helps frame where Drupal should lead and where a separate PHP service may belong.

The Drupal Paradox: Why Enterprise Complexity Becomes a Liability bhavinhjoshi Wed, 07/08/2026 - 16:37

 

In the enterprise world, Drupal is often chosen for its unparalleled flexibility and power. Organizations, including large-scale research institutions like CERN, have historically relied on Drupal to manage thousands of complex, interconnected websites. Yet, we are witnessing a trend where massive Drupal ecosystems are migrated to alternative platforms.

This migration is rarely about the CMS engine itself. It is a symptom of The Drupal Paradox: the same flexibility that makes Drupal the ideal choice for an enterprise also creates the conditions for its eventual mismanagement.

The Anatomy of Mismanagement

When an organization manages hundreds of websites, Drupal’s modular nature can become a double-edged sword. Mismanagement typically creeps in through three specific avenues:

• The "Module-First" Trap: Teams often prioritize speed by installing pre-built modules to solve business-critical problems rather than architecting a robust, custom solution.
• The Accumulation of Technical Debt: Over time, "vibe-coded" configurations and amateur patches are layered on top of the core architecture. This turns a stable system into a brittle, unmaintainable mess that becomes increasingly difficult to upgrade.
• The Documentation Void: When teams treat documentation as an afterthought, the system becomes a "black box." Once the original architects leave, the remaining team is paralyzed by the fear of breaking an undocumented system.

The Migration Fallacy

Many organizations view migration as a clean slate. They assume that moving to a new platform will solve the underlying technical and process issues. This is a mistake.

If an organization lacks the governance to manage a Drupal ecosystem, they will inevitably reproduce the same technical debt on any other platform they choose. Migration is not a cure for poor architectural discipline, it is simply a very expensive way to reset the clock on systemic failure.

Preventing the Paradox: A New Governance Standard

To ensure the longevity of an enterprise CMS, organizations must shift from a "content-editing" mindset to an "engineering-discipline" mindset:

• Enforce Architectural Governance: Every new module or custom feature must be vetted for its impact on performance and long-term maintenance. Decisions must be based on trade-offs, not convenience.
• Prioritize Documentation as Code: Documentation should be a mandatory component of the development lifecycle, not a "nice-to-have" add-on. If a change is not documented, it is not considered complete.
• Decouple Business Logic: Keep the CMS focused on content orchestration and move heavy business logic into independent microservices or APIs. This reduces the blast radius of any individual CMS failure.
• Reject "Vibe-Coding": Demand that your engineering team articulates the technical trade-offs of their decisions before they commit code. A professional engineer must be able to justify the "why" behind the "what."

Final Thoughts

Drupal is not failing, enterprise governance is. If you find your organization trapped in a "paradox" where your CMS feels like a burden, stop looking at migration as your only option. Start looking at the structural integrity of your team’s processes.

We don't believe in "quick fixes." We believe in building systems that respect your investment. If you are struggling with a paradox of your own, we approach enterprise architecture differently.

Drupal migration Drupal Planet Drupal WordPress Share this Copied to clipboard Add new comment

Before Drupal teams can build well, they need shared context, current site knowledge, consistent layout tools, and clear AI boundaries. Written responses from four Drupal Camp Asheville speakers show how those choices affect planning, discovery, front-end work, and governance.

People have increasingly been discovering git worktree for use in working on multiple features or bugs at the same time, or for having AI agents work in parallel. A DDEV contributor training covered this, and a Drupal Florida presentation.

TYPO3 projects sometimes provide a special challenge for git worktree if they have the full URL specified in config/sites/*/config.yaml's base, like base: https://typo3.ddev.site/. When you add a second git worktree checkout, DDEV names that project after its directory, giving it a different *.ddev.site hostname—but TYPO3's base is still trying to route the first worktree's hostname, so the new one fails with a 404 "not found".

This is the same underlying problem covered in Sharing Your TYPO3 Project with ddev share, but it can be fixed with a different post-start hook fix. (If your base is already a relative path like /camino, as in the DDEV TYPO3 quickstart, there's nothing to fix—every worktree works out of the box.)

Watch the Video What You'll See

• Removing name from project .ddev/config.yaml
• Using ddev config global --omit-project-name-by-default
• Setting up a second git worktree checkout of a TYPO3 project
• Each project getting its own hostname from its directory name
• The base URL mismatch breaking the second worktree
• Fixing it with a post-start hook which checks out the original TYPO3 config.yaml

Why Worktrees Get Different Hostnames

By default, DDEV names a project after the directory it lives in. Remove the name: key from .ddev/config.yaml (or set this globally with ddev config global --omit-project-name-by-default) and every git worktree checkout gets its own project name and *.ddev.site hostname automatically, matching its directory.

That's what you want for running several branches side by side, as covered in Contributor Training: git worktree for Multiple DDEV Projects—but it means a TYPO3 project with a hardcoded base containing a URL will only route correctly in whichever single worktree happens to match that hostname.

The Fix: post-start and post-stop Hooks

Unlike ddev share, where the tunnel URL is temporary and the pre-share/post-share hooks restore the original base afterward, a worktree's hostname is permanent for the life of that checkout. So instead of a temporary swap, use a post-start hook that sets base to match whatever hostname the current worktree actually has, every time it starts, and optionally git restore on ddev stop:

# .ddev/config.yaml hooks: post-start: - exec: | for f in config/sites/*/config.yaml; do cp "$f" "$f.post-start-backup" newbase=$(yq '.base' "$f" | sed -E 's#^https?://[^/]+##') [ -z "$newbase" ] && newbase="/" yq -i ".base = \"$newbase\"" "$f" done typo3 cache:flush post-stop: - exec-host: | git restore config/sites/*/config.yaml

The simplest answer is not to use the absolute base at all, just make it relative in the first place—base: / (or /your-path/ for a subpath)—which is hostname-independent and needs no hook. That works for git worktree, ddev share, and any other hostname change alike, as described in New ddev share Provider System.

Trusted Host Patterns

DDEV already automatically adds a trustedHostsPattern to additional.php for any hostname running under DDEV, so PHP's own host validation isn't a concern here—only TYPO3's base setting is.

return [ # ... 'SYS' => [ 'trustedHostsPattern' => '.*.*', 'devIPmask' => '*', 'displayErrors' => 1, ], ]; Setting Up the Database and Files

Each worktree is a separate DDEV project, so it needs its own database and files. See Setting Up the Database and Files in the git worktree training post for exporting from one checkout and importing into another.

Example project: rfay/typo3demo

A pre-built example project based on the TYPO3 docs and DDEV quickstart is at rfay/typo3demo, with the post-start hook described here already in place.

Learn More

For background on git worktree with DDEV in general, see Contributor Training: git worktree for Multiple DDEV Projects. For more on TYPO3's base URL and the ddev share version of this problem, see Sharing Your TYPO3 Project with ddev share and the docs on ddev share.

For another way to manage TYPO3 system routing check out the b13/host_variants extension, a more sophisticated way to manage what routes the TYPO3 router will accept and work with.

If you have questions, reach out in any of the support channels.

Follow our blog, Bluesky, LinkedIn, Mastodon, and join us on Discord. Sign up for the monthly newsletter.

This article was edited and refined with assistance from Claude Code.

Take Away

Batch and queue are fine until they aren't. Once you've hit their limits and if your site is large enough, and you will, Temporal is the answer. Crashes, retries, scaling across machines: handled, transparently, without touching your business logic. Here, Károly Négyesi, Edge Case Engineer walks through how Temporal integrates with Drupal and why it's the next step for sites that have outgrown what Drupal ships with.

Background

Beyond serving pages, a lot of websites have background processes they need to run. Importing third party data, indexing changes, generating reports and so on. Once a site becomes so large it is no longer feasible for a single PHP process to do this for every entity it cares about, things become more difficult.

What Drupal Offers

Drupal provides two APIs for long-running processes: batch and queue. A batch runs an operation, saves state and then runs it again until the operation says "stop". However, if an operation fails then the entire batch aborts. Queue lines up operations and runs them independently of each other so the error handling is somewhat better. If an operation fails then the rest of the operations can run but there is very little control over retries. These two are good for the basics, they are good enough to be included in Drupal core, but when you are dealing with larger sites they are woefully inadequate. I should know: I wrote the queue API originally.

What if we had an ability to run these processes without having to worry about crashes, retries, or scaling across machines with extensive reporting about what has happened? That system is Temporal, and this post will walk through how it integrates with Drupal.

Temporal Basics

In Temporal, your Drupal code is an activity. Activities are a single unit of work. It doesn't matter whether it takes a short or long time, for example transcoding media might take a long time, but it's still a single unit. A workflow tells Temporal which activities to run and how to retry them. It has a rich selection of retry strategies. It also controls various timeouts. One of the more interesting timeouts is the heartbeat for long-running activities: if the activity doesn't send a heartbeat within the specified time, it will be cancelled. Heartbeats can also carry progress information.

The workflow is a long-running process and if it stops for any reason, Temporal makes it resume where it stopped. When I first read this I thought "huh, maybe it somehow saves the memory state but that'd be very fugly" and no, that's not what it does. Instead, this magic is achieved by saving the inputs and outputs of every activity call in its own durable event log. There is a UI to see the log which also includes workflow events besides these activity events.

The Magic

Thanks to this event log, when a workflow is restarted the activities do not need to be rerun, the workflow fast-forwards to the point where it stopped based on the event log replay. I can't emphasize enough how important this is: no matter what crashes and when, the system completely transparently handles it. The activity calls a third party service that is temporarily down and so it needs to return with an error? PHP crashed with an out of memory error because Drupal leaks memory like a sieve? No need to worry about any of this, no need to write elaborate retry strategies for the remote call, no need to try to patch up the leaking sieve. Temporal will retry the activity, the workflow will continue and neither needs to care about errors and crashes.

A Little Theory

For this to work well, workflows need to be deterministic: given the same series of events, a workflow must always make the same decisions. For this reason, workflows should not consult databases, file systems, clocks, random numbers, and the like. That's a job for activities. Most workflows will even avoid logging to prevent any side effects, especially since Temporal already records all activity inputs and outputs.

And activities are recommended to be idempotent: running them multiple times should have the same result as running them once. This is important because they can be re-tried if they fail. A classic example of an idempotent operation is the stop button on a media player: no matter how many times you tap it the music will not play. The play/pause button, on the other hand, is the classic example for a non-idempotent operation. Within PHP, writing to a stream opened with fopen('filename', 'w') is idempotent: the contents of the file become the data written. On the other hand, if a stream is opened with fopen('filename', 'a') then the writes are not idempotent: the data is appended over and over again.

To further highlight the difference between the two, consider a database MERGE: the operation will want to report back whether the row was inserted or updated, so it is not deterministic, but it is idempotent because the database row ends up with the same data either way.

Enough of the theoretical talk, let's talk code!

Coding a Workflow

A workflow is a PHP class. To make it easy for Drupal to discover them, they are in the Drupal\mymodule\Temporal\Workflow namespace and the class has the Temporal\Workflow\WorkflowInterface attribute. This pattern should be familiar from writing plugins. This attribute is enough for Temporal to recognize this as a workflow class. Temporal also requires the workflow method to have the Temporal\Workflow\WorkflowMethod attribute.

While a workflow looks like a Drupal plugin, it is not. As we discussed workflows need to be deterministic and due to the complexity of Drupal it is almost impossible to guarantee any call into Drupal to be deterministic so it's best if workflows do not talk to Drupal at all. The integration encourages this: workflow classes are instantiated by Temporal directly without passing any arguments to the constructor.

The most important thing a workflow does is calling an activity. The Temporal PHP SDK's mechanism for this is a bit unusual at first, but it's the same pattern as mocks/stubs in phpunit: activity classes get a stub in the phpunit sense and the methods defined in the activity class are called on this stub.

For example:

/** @var \Drupal\temporal\Temporal\GenericActivity $activity */ $activity = Workflow::newActivityStub($activityClass); $ids = yield $activity->getIds();

(Irrelevant arguments are cut from this example, see the GenericWorkflowBase class shipping with the module for the rest.)

Calling a method on the activity stub returns a promise (from the ReactPHP package) that encapsulates this method invocation. Then yield hands back control to the Temporal PHP SDK, which resolves this promise by sending the activity to the Temporal server as a gRPC request. (Yes, yield can have a value, see the documentation for the rarely used Generator::send() for more.) It is not necessary to yield after every call: see ParallelGenericWorkflow for an example on how to instruct Temporal to run multiple activities in parallel.

Once you are used to this calling convention this is much easier to read than a traditional request builder. Now you can see why the code uses the old /** @var */ convention instead of asserting the type directly: as far as the IDE and the developer is concerned, $activity can be treated as an instance of $activityClass. But in reality, it's an ActivityProxy class.

When the Temporal server gets the request to call an activity, it might just send the relevant answer immediately if it is replaying the event log. Otherwise, it logs the activity inputs and puts the request in a task queue. The task queues are processed by workers, we will get back to them after discussing activities. First let's mention the two example workflows shipped with the module. Both call an activity for a large list of IDs (by default 1000), then small chunks of these (by default 20) are sent back to the activity for processing. One workflow launches a chunk worth of activities in parallel, the other sends the chunk in a single call. The former is good for something like search indexing; the latter is good for anything that writes the database and wants to keep database load lower by keeping many writes in a single transaction. A lot of tasks can be accomplished by writing an activity for one of these two, so writing a workflow is not always necessary.

Coding an Activity

Writing activities is much easier: the code does not need to talk to Temporal, these are normal Drupal plugins containing ordinary Drupal code and writing Drupal code is very easy ;). As usual for plugins, they need to be within a specific namespace, Drupal\mymodule\Temporal\Activity with the Temporal\Activity\ActivityInterface attribute on the class which, again, is enough for Temporal as well to recognize it as an activity. Methods are marked with the ActivityMethod attribute for Temporal.

While the code doesn't need to contain calls to Temporal, there are some considerations knowing they will be used by Temporal:

• As activity calls are remote calls in disguise, both the arguments and the return values need to be serializable.
• If there is an error – typically in calling third party services – that warrants a retry then the activity can simply let the exception propagate. The SDK will catch it and pass it to Temporal. For more fine-grained control the activity can throw an ApplicationFailure, which, among others, can tell Temporal whether the failure can be retried at all.
• Heartbeats are super easy to send: Activity::heartbeat($progress); It really must be noted how easy it is to work with the Temporal PHP SDK. We have a complex server-client architecture but most of the complexity is not visible at all: activity calls are hidden behind a proxy class and a simple yield, progress reporting is a single static method call and simple error handling is completely automatic.

An example activity is shipped with the module which re-saves every entity of an entity type.

Actually Trying It

Before we can get to trying it, there's one more thing we need to introduce: Workers. These are long-running processes that poll the Temporal task queues and run workflows and activities. To better support their long-running nature, Temporal uses the RoadRunner application server for them. The Drupal integration ships this worker as a Drush command and supplies a sample .rr.yaml RoadRunner configuration to run this command. Most of the time simply copying the configuration to the project root and running rr serve is all you need to do. Read the module README.md for more. Besides a Temporal server instance at least one worker is needed for Temporal to work. But you can run as many as the workload warrants.

To round it off, there's a Drush command to start workflows and another to send signals and queries to them.

To make local development easier, a DDEV add-on (chx/ddev-temporalio) has been developed as well, this spins up a Temporal server and a Temporal web UI. So in a ddev project, you can run

ddev get chx/ddev-temporalio ddev restart ddev composer require 'drupal/temporal:^2.1' ddev drush en -y temporal ddev drush temporal:workflow:start 'Drupal\temporal\Temporal\Workflow\GenericWorkflow' 'Drupal\temporal\Temporal\Activity\EntityResave' user

This will re-save every user entity. The first argument of the Drush temporal:workflow:start command is the name of the workflow. In turn, the first argument of this particular workflow is the activity class. This is not a Temporal convention or even a convention of the Drupal-temporal integration, it's simply convenient for such a generic workflow. The rest of the arguments are passed to the activity and the entity resave activity needs the entity type.

We started with talking about batch, let's finish with it, too: we actually integrated the Drupal batch system with temporal. In the next blog post we will talk about that. Teaser: you can start the batch and close the browser tab.

Running into the limits of Drupal's batch and queue? See how Tag1 scales Drupal.