Why the Drupal Web Root Matters

A Composer-based Drupal project contains application dependencies and a public web directory, but only the public directory should be served. Starting PHP or a web server from the wrong root can break resource discovery, expose private files, or create failures that look like theme and configuration defects.

Separate the project root from the public root

The project root contains composer.json, vendor, configuration, and operational files. The Drupal web root contains index.php, core, modules, themes, and public assets. Configure the server document root to the web directory and route requests through Drupal’s front controller.

Prefer application-relative discovery

Application code should use Drupal services, extension paths, stream wrappers, and the kernel’s root rather than embedding development-machine absolute paths. Relative paths are safe only when their base is explicit. A process working directory is an operational detail; the application root is part of Drupal’s runtime contract.

Keep environments portable

Put database credentials, trusted hosts, reverse-proxy details, and environment-specific settings outside reusable theme and module code. Verify deployments with status checks, cache rebuilds, anonymous requests, authenticated requests, and asset loading. The same codebase should move between local, staging, and production without path edits.

Working example

$theme_path = \Drupal::service('extension.list.theme')->getPath('example');
$template_directory = DRUPAL_ROOT . '/' . $theme_path . '/templates';

Key Takeaways

• Serve only Drupal’s public web directory.
• Use Drupal-aware paths instead of machine-specific absolute paths.
• Treat runtime root and environment configuration as deployment contracts.

Further Reading

• Recommended project structure
• Drupal documentation