Skip to content
Tutorials Center
My learning

Topics

Lesson 7 of 37 ยท Concepts and Installation

The Drupal Project Structure

Learn what every folder in a Composer-based Drupal project does: web, vendor, core, modules, themes, sites/default, settings.php, files and config.

A fresh Drupal project can look intimidating: dozens of folders, hundreds of files. In practice you only touch a few places, and knowing which ones are safe to edit protects you from losing work during an update. This lesson draws the map.

The layout described here is the one produced by drupal/recommended-project, the standard Composer template.

The top-level layout

TEXT
my-site/
  composer.json        your dependency list (commit)
  composer.lock        exact versions installed (commit)
  vendor/              PHP libraries, including Symfony (do not commit)
  config/sync/         exported configuration (commit)
  web/                 the document root: the only public folder
    index.php
    core/              Drupal core (never edit)
    modules/
      contrib/         downloaded modules (never edit)
      custom/          your modules
    themes/
      contrib/
      custom/
    profiles/
    libraries/         third-party JS/CSS libraries
    sites/
      default/
        settings.php
        services.yml
        files/         uploaded files (do not commit)

The key idea: only web/ is served to visitors. vendor/, config/ and composer.json live one level up, so a mistake in the web server configuration cannot expose them.

Folders you will use daily

  • web/modules/custom: your own modules, one folder per module.
  • web/themes/custom: your own themes.
  • config/sync: exported configuration YAML files. The place it lives is set in settings.php.
  • web/sites/default/settings.php: environment settings: database connection, hash salt, trusted hosts, config sync path.
  • web/sites/default/files: public uploads. Writable by the web server, so it must never execute scripts.

Folders you never edit

  • web/core: replaced on every core update.
  • web/modules/contrib and web/themes/contrib: replaced when you update those projects.
  • vendor/: managed by Composer.

If you need to change behavior, write a custom module that alters it with hooks or events (see the Modules and Hooks chapter), or apply a tested patch through composer.json, not by hand-editing.

settings.php

settings.php holds the parts that differ per environment. A shortened example:

PHP
<?php

$databases['default']['default'] = [
  'driver' => 'mysql',
  'database' => 'drupal',
  'username' => 'drupal',
  'password' => 'a-strong-local-password',
  'host' => '127.0.0.1',
  'port' => '3306',
  'prefix' => '',
];

$settings['hash_salt'] = 'a-long-random-string-generated-at-install';
$settings['config_sync_directory'] = '../config/sync';
$settings['trusted_host_patterns'] = [
  '^www\.example\.com$',
];

Never commit real credentials. A common pattern is to keep settings.php generic and load a settings.local.php (ignored by Git) at the bottom:

PHP
if (file_exists($app_root . '/' . $site_path . '/settings.local.php')) {
  include $app_root . '/' . $site_path . '/settings.local.php';
}

Settings such as development error display or disabled caching go in that local file. Production settings come from the server's own copy or environment variables.

services.yml

web/sites/default/services.yml can override service definitions and, for example, set Twig debug mode or cookie options during development. It is optional and is copied from default.services.yml.

Multisite

Drupal can run several sites from one codebase using extra folders under sites/, such as sites/example.com, each with its own settings.php, database and files. The file sites/sites.php maps domain names to folders. Many teams prefer separate projects today, but you should recognize the structure.

Exploring a tree as data

The stand-in below stores the layout as a nested object and prints it with indentation, marking which folders are editable. It is a teaching aid that mirrors the tree above.

JS Stand-in: the project tree and edit rules

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Where does a given file belong?

When you create something new, ask: is it code, configuration, content or an upload?

  • Code (modules, themes): web/modules/custom, web/themes/custom, in Git.
  • Configuration (content types, Views): exported to config/sync, in Git.
  • Content (nodes, users): lives in the database, not in Git.
  • Uploads: web/sites/default/files or private files, not in Git.

This four-way split is the backbone of every Drupal deployment: code and configuration travel through Git, content and uploads stay with the environment.

This second stand-in decides where something belongs.

JS Stand-in: where does it go?

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which folder is the web server's document root?

    Only web is public. Everything else lives outside it for safety.
  2. 2. Where should your own custom module be placed?

    Custom code goes in its own folder so updates never overwrite it.
  3. 3. What is settings.local.php typically used for?

    It keeps local credentials and development flags out of version control.
  4. 4. Which of these is stored in the database rather than Git?

    Content lives in the database; code and configuration travel through Git.

Summary

  • Only web/ is public; vendor/ and config/ stay outside it.
  • Never edit core or contrib; put your code in custom folders.
  • settings.php holds environment settings; keep secrets out of Git.
  • Code and configuration go through Git; content and uploads stay in each environment.

Next: Entities, Bundles and Fields: The Content Model