composer.json

Composer is a dependency manager for PHP projects, including Drupal. It allows you to declare the libraries your project depends on and manages them for you.

tip

➡️ See Development > Composer for information on how to add and manage dependencies.

`composer.json`

Vortex comes with a pre-configured composer.json that lists essential dependencies for Drupal projects, along with development tools to help you maintain your code quality.

The composer.json file is the core configuration file for Composer, detailing your project's dependencies, scripts, and settings.

This section provides an overview of each part of the composer.json file, explaining its role and how it contributes to your project's setup and management.

Click here to see the contents of the composer.json file

{
    "name": "your_org/your_site",
    "description": "Drupal 11 implementation of YOURSITE for YOURORG",
    "license": "proprietary",
    "type": "project",
    "require": {
        "php": ">=8.4",
        "composer/installers": "^2.3",
        "cweagans/composer-patches": "^2.0",
        "drevops/vortex-tooling": "~1.3.0",
        "drupal/clamav": "^2.1",
        "drupal/coffee": "^2.0.1",
        "drupal/config_split": "^2.0.2",
        "drupal/config_update": "^2@alpha",
        "drupal/core-composer-scaffold": "~11.4.5",
        "drupal/core-recommended": "~11.4.5",
        "drupal/devel": "^5.5",
        "drupal/drupal_helpers": "^2.1.0",
        "drupal/environment_indicator": "^4.0.25",
        "drupal/generated_content": "^2.1.0",
        "drupal/migrate_plus": "^6.0.10",
        "drupal/migrate_tools": "^6.1.4",
        "drupal/navigation_extra_tools": "^1.3.2",
        "drupal/pathauto": "^1.15.0",
        "drupal/redirect": "^1.13.0",
        "drupal/redis": "^1.11",
        "drupal/reroute_email": "^2.3@RC",
        "drupal/robotstxt": "^1.6",
        "drupal/sdc_devel": "^1.0.3",
        "drupal/search_api": "^1.41.0",
        "drupal/search_api_solr": "^4.4.0",
        "drupal/seckit": "^2.0.3",
        "drupal/shield": "^1.8",
        "drupal/stage_file_proxy": "^4.0.0",
        "drupal/testmode": "^2.7.1",
        "drupal/xmlsitemap": "^2.0",
        "drush/drush": "^13.7.6",
        "webflo/drupal-finder": "^1.3.1"
    },
    "require-dev": {
        "behat/behat": "^3.32.0",
        "dantleech/gherkin-lint": "^0.2.4",
        "dealerdirect/phpcodesniffer-composer-installer": "^1.2.1",
        "drevops/behat-format-progress-fail": "^1.5.1",
        "drevops/behat-screenshot": "^2.4.2",
        "drevops/behat-steps": "^3.12.0",
        "drevops/phpcs-standard": "^0.7.0",
        "drupal/coder": "^9.0.1@alpha",
        "drupal/drupal-extension": "^6.1",
        "ergebnis/composer-normalize": "^2.52.0",
        "lullabot/mink-selenium2-driver": "^1.7.4",
        "lullabot/php-webdriver": "^2.0.7",
        "mglaman/phpstan-drupal": "^2.1.1",
        "mikey179/vfsstream": "^1.6.12",
        "palantirnet/drupal-rector": "^1.1.2",
        "phpcompatibility/php-compatibility": "^10.0@alpha",
        "phpspec/prophecy-phpunit": "^2.5",
        "phpstan/extension-installer": "^1.4.3",
        "phpstan/phpstan": "^2.2.8",
        "phpunit/phpunit": "^11.5.56",
        "pyrech/composer-changelogs": "^2.2",
        "rector/rector": "^2.6.1",
        "softcreatr/jsonpath": "^0.10 || ^1.0",
        "vincentlanglet/twig-cs-fixer": "^4.0.2"
    },
    "conflict": {
        "drupal/drupal": "*"
    },
    "repositories": [
        {
            "type": "composer",
            "url": "https://packages.drupal.org/8"
        },
        {
            "type": "path",
            "url": ".vortex/tooling",
            "options": {
                "versions": {
                    "drevops/vortex-tooling": "1.3.0"
                }
            }
        }
    ],
    "minimum-stability": "stable",
    "prefer-stable": true,
    "autoload-dev": {
        "classmap": [
            "tests/phpunit/"
        ]
    },
    "config": {
        "allow-plugins": {
            "composer/installers": true,
            "cweagans/composer-patches": true,
            "dealerdirect/phpcodesniffer-composer-installer": true,
            "drupal/core-composer-scaffold": true,
            "ergebnis/composer-normalize": true,
            "php-http/discovery": true,
            "phpstan/extension-installer": true,
            "pyrech/composer-changelogs": true,
            "symfony/runtime": true,
            "tbachert/spi": true
        },
        "bump-after-update": true,
        "discard-changes": true,
        "platform": {
            "php": "8.4.21"
        },
        "policy": {
            "advisories": {
                "block": false,
                "audit": "fail"
            },
            "abandoned": {
                "audit": "report"
            }
        },
        "sort-packages": true
    },
    "extra": {
        "drupal-scaffold": {
            "file-mapping": {
                "[project-root]/.editorconfig": false,
                "[project-root]/.gitattributes": false,
                "[web-root]/.csslintrc": false,
                "[web-root]/.eslintignore": false,
                "[web-root]/.eslintrc.json": false,
                "[web-root]/.ht.router.php": false,
                "[web-root]/.htaccess": false,
                "[web-root]/INSTALL.txt": false,
                "[web-root]/README.md": false,
                "[web-root]/example.gitignore": false,
                "[web-root]/robots.txt": false,
                "[web-root]/sites/example.settings.local.php": false,
                "[web-root]/sites/example.sites.php": false,
                "[web-root]/update.php": false
            },
            "locations": {
                "web-root": "web/"
            }
        },
        "installer-paths": {
            "web/core": [
                "type:drupal-core"
            ],
            "web/libraries/{$name}": [
                "type:drupal-library"
            ],
            "web/modules/contrib/{$name}": [
                "type:drupal-module"
            ],
            "web/profiles/contrib/{$name}": [
                "type:drupal-profile"
            ],
            "recipes/{$name}": [
                "type:drupal-recipe"
            ],
            "web/themes/contrib/{$name}": [
                "type:drupal-theme"
            ],
            "drush/Commands/contrib/{$name}": [
                "type:drupal-drush"
            ],
            "web/modules/custom/{$name}": [
                "type:drupal-custom-module"
            ],
            "web/profiles/custom/{$name}": [
                "type:drupal-custom-profile"
            ],
            "web/themes/custom/{$name}": [
                "type:drupal-custom-theme"
            ]
        },
        "patchLevel": {
            "drupal/core": "-p2"
        },
        "patches": {}
    }
}

`name`

name is a unique identifier for the project in Composer's ecosystem consisting of a vendor name and the project's name.

`description`

A brief summary of the project's purpose.

`type`

type is used to specify the type of the package. This is important because it tells Composer and any systems integrating with Composer how to treat the package. The type key can influence how the package is installed and used.

`license`

license indicates the license of the project. Since Vortex is a template for your consumer sites that are usually proprietary, we use proprietary as the default value. More license identifiers are listed at the SPDX Open Source License Registry.

`repositories`

The repositories section defines custom package repositories, essential for accessing packages outside the default Packagist repository.

Repository	Type	Description
`packages.drupal.org/8`	`composer`	The official source for Drupal modules, themes and distributions, which are not published on Packagist.
`.vortex/tooling`	`path`	Resolves the in-tree tooling package while developing Vortex itself. The installer removes this entry during site creation, so your project installs `drevops/vortex-tooling` from Packagist instead.

`require`

The require section specifies the essential packages and libraries your project needs.

The Documentation column links to the page covering that package in more depth. A Settings link means Vortex ships a per-module override file that applies environment-aware defaults for that module. Some modules still need a running service or environment-specific values on top of those defaults.

➡️ See Modules for what each override actually configures and where each module is installed.

Package	Description	Documentation
`php`	The minimum PHP version required to run this project. Specify a range such as `>=8.4` rather than an exact version such as `8.4.0`.
`composer/installers`	Installs packages into the correct location based on their package type, such as `drupal-module`, `drupal-theme` or `drupal-profile`.
`cweagans/composer-patches`	Patches Composer packages with `git apply`, incorporating fixes that are not yet in an official release. Patch metadata and SHA-256 checksums are recorded in `patches.lock.json` for reproducible builds.	Patching
`drevops/vortex-tooling`	Ships the Vortex operational scripts - build, provision, deployment and notification tooling - that your site runs from `vendor/drevops/vortex-tooling/src/`.
`drupal/clamav`	Scans uploaded files for malware with the ClamAV engine before they are saved.	Settings
`drupal/coffee`	Adds a keyboard shortcut to jump straight to any administration page by typing its name.
`drupal/config_split`	Splits configuration into sets that are conditionally imported, enabling environment-specific configuration such as development-only modules.	Settings
`drupal/config_update`	Provides tools and Drush commands to report, revert and import configuration changes relative to the defaults shipped by modules.
`drupal/core-composer-scaffold`	Downloads Drupal Scaffold files such as `index.php` and `update.php` from the `drupal/core` project and places them inside the web root.
`drupal/core-recommended`	Pins the set of dependency versions that the Drupal community tests and recommends for a particular core version, ensuring compatibility and stability.
`drupal/devel`	A suite of development tools for inspecting variables, entities and the service container while debugging.	Settings
`drupal/drupal_helpers`	A collection of helper functions that simplify writing update hooks and deployment operations.	Drupal helpers
`drupal/environment_indicator`	Shows a colored banner identifying the current environment to prevent accidental changes on the wrong site.	Settings
`drupal/generated_content`	Generates deterministic placeholder content from declarative definitions for development and testing.	Generated content, Settings
`drupal/migrate_plus`	Extends the core Migrate API with extra source and process plugins and configuration-entity migrations.	Migrations
`drupal/migrate_tools`	Provides Drush commands and a UI to run, roll back and monitor migrations.	Migrations
`drupal/navigation_extra_tools`	Adds administration shortcuts - clear caches, run cron, run database updates - to the core Navigation module.
`drupal/pathauto`	Automatically generates URL aliases for content based on configurable patterns.
`drupal/redirect`	Manages URL redirects and creates them automatically when content URLs change.
`drupal/redis`	Integrates Drupal with the Redis in-memory store for cache and lock backends.	Settings
`drupal/reroute_email`	Reroutes all outbound email to a configured address on non-production environments to avoid emailing real users.	Settings
`drupal/robotstxt`	Manages the `robots.txt` file from the admin UI, useful when it cannot be placed on disk (for example, in multisite setups).	Settings
`drupal/sdc_devel`	Development and validation tooling for Single Directory Components (SDC), reporting issues in component definitions and templates.
`drupal/search_api`	Provides a framework for building search experiences with pluggable indexing backends.
`drupal/search_api_solr`	A Search API backend that integrates Apache Solr for fast, scalable search.
`drupal/seckit`	Adds configurable security-hardening HTTP headers, including Content Security Policy and anti-framing protection.	Settings
`drupal/shield`	Protects non-production environments behind HTTP basic authentication.	Settings
`drupal/stage_file_proxy`	Fetches media files from a remote site on demand, so local environments do not need a full copy of the files directory.	Settings
`drupal/testmode`	Adjusts site behavior during automated tests, for example by filtering out generated content from listings.	Testmode, Settings
`drupal/xmlsitemap`	Generates a multilingual XML sitemap to help search engines index the site.	Settings
`drush/drush`	A command-line shell and scripting interface for Drupal, providing a wide range of utilities to manage and interact with your Drupal sites.	Drush
`webflo/drupal-finder`	Locates Drupal installations in a directory structure.

`require-dev`

The require-dev section lists packages used for development purposes, like code quality checks and testing. These tools are essential for development but not required in production environments. This distinction helps to keep the production deployment streamlined and efficient, while still supporting a comprehensive and effective development environment.

Package	Description	Documentation
`behat/behat`	A PHP framework for Behavior-Driven Development (BDD), running human-readable stories that describe the behavior of your application. It facilitates communication between developers, stakeholders and clients.	Behat
`dantleech/gherkin-lint`	Lints the Gherkin feature files used in Behat tests, checking syntax and formatting for consistency.	Gherkin Lint
`dealerdirect/phpcodesniffer-composer-installer`	Registers the coding standards installed through Composer with PHP_CodeSniffer, so they can be referenced by name.	PHPCS
`drevops/behat-format-progress-fail`	A Behat output formatter that prints compact progress and expands the detail only for failing scenarios.	Behat
`drevops/behat-screenshot`	Automatically captures a screenshot when a Behat scenario fails, which helps to understand why a test failed.	Behat
`drevops/behat-steps`	A collection of pre-defined Behat step definitions for Drupal, speeding up the process of writing new tests.	Behat
`drevops/phpcs-standard`	A PHP_CodeSniffer coding standard that extends the Drupal coding standards with additional rules and best practices.	PHPCS
`drupal/coder`	Provides the PHP_CodeSniffer rules for the Drupal coding standards. The 9.x line targets PHP_CodeSniffer 4.x.	PHPCS
`drupal/drupal-extension`	A Behat extension that integrates with Drupal, offering Drupal-specific step definitions and bootstrapping the site for testing.	Behat
`ergebnis/composer-normalize`	A Composer plugin that normalizes the formatting and key order of `composer.json`.
`lullabot/mink-selenium2-driver`	A maintained fork of the Mink Selenium2 driver that lets Behat control real browsers through Selenium WebDriver.	Behat
`lullabot/php-webdriver`	A maintained fork of the PHP WebDriver client used by the Mink Selenium2 driver to communicate with browsers.	Behat
`mglaman/phpstan-drupal`	Teaches PHPStan about Drupal APIs, so static analysis understands hooks, services and entities in modules and themes.	PHPStan
`mikey179/vfsstream`	A virtual file system for PHPUnit tests, allowing file operations to be exercised without touching the real file system.	PHPUnit
`palantirnet/drupal-rector`	Rector rules that rewrite deprecated Drupal code, making core upgrades more efficient.	Rector
`phpcompatibility/php-compatibility`	PHP_CodeSniffer sniffs that check code for compatibility with specific PHP versions. The 10.x line targets PHP_CodeSniffer 4.x.	PHPCS
`phpspec/prophecy-phpunit`	Integrates the Prophecy mocking library with PHPUnit to provide advanced mocking capabilities in tests.	PHPUnit
`phpstan/extension-installer`	Automatically registers the installed PHPStan extensions, removing the need to wire them up by hand.	PHPStan
`phpstan/phpstan`	A static analysis tool that finds type errors, incorrect method calls and other bugs without running the code.	PHPStan
`phpunit/phpunit`	The industry-standard PHP testing framework, used here for unit, kernel and functional tests.	PHPUnit
`pyrech/composer-changelogs`	Prints a summary of package additions, updates and removals after running `composer update`.
`rector/rector`	An automated refactoring tool that upgrades and modernizes PHP code.	Rector
`softcreatr/jsonpath`	A JSONPath implementation required by the `drevops/behat-steps` JSON assertion steps.	Behat
`vincentlanglet/twig-cs-fixer`	Checks and fixes Twig templates against a coding standard, keeping template files consistent and readable.	Twig CS Fixer

`conflict`

The conflict section prevents installation conflicts with standalone Drupal core, crucial for avoiding version clashes and ensuring consistency in core files.

`minimum-stability`

The minimum-stability setting controls the minimum stability level of the packages that Composer is allowed to install. By setting it to "stable", you are instructing Composer to prefer stable versions of packages over their unstable (like beta or alpha) versions.

`prefer-stable`

The prefer-stable settings, when set to true, instructs Composer to prefer stable versions of packages even when the minimum-stability setting allows less stable versions. This is especially useful in a mixed stability scenario where some dependencies might not have a stable release yet. It ensures that Composer will use stable versions wherever possible, thus providing a balance between stability and the need for newer features or fixes that might only be available in a less stable package version.

`config`

The config section specifies key configurations for Composer's behavior in the project.

allow-plugins: This setting specifies which Composer plugins are allowed to run. It's a security measure to prevent the execution of untrusted code from third-party plugins. Each plugin needs to be explicitly allowed to ensure it can execute.
policy: Introduced in Composer 2.10.0, this unified setting controls security auditing and version blocking of dependencies. Vortex configures it to keep vulnerabilities visible without blocking installs:
- advisories.block (set to false): security advisories do not block composer install, composer update, or composer require, keeping builds reproducible when new advisories are published upstream.
- advisories.audit (set to fail): composer audit still fails on advisories, so they remain visible locally and in CI.
- abandoned.audit (set to report): abandoned packages are reported as warnings without failing the audit.
- See Composer Security Auditing for the full reference, ignoring advisories, and best practices.
bump-after-update: Automatically updates version constraints in composer.json to match currently installed package versions after running composer update. Vortex sets this to true to bump all dependencies, ensuring version constraints stay in sync with installed versions. Available values: true (all dependencies), false (disabled), "dev" (only dev dependencies), or "no-dev" (only non-dev dependencies).
discard-changes: When set to true, any local changes made to the dependencies (packages under version control like Git) are discarded without prompting when you run composer install or composer update. Composer will overwrite the local changes with the data from the source repository.
platform: Specifies the PHP version of the platform environment where the current project runs. This should be specified as an exact version number (e.g. 8.4.21). It should be kept in sync with the php version in the Docker containers.
sort-packages: When set to true, this configuration ensures that packages are sorted in composer.json and composer.lock. It makes these files more readable and helps reduce merge conflicts in version control.

`autoload-dev`

The autoload-dev section is essential for defining how Composer automatically loads PHP development-specific classes within the project, without needing to manually include or require each class file.

`extra`

The extra section serves as a source of custom configuration for various packages. These packages read settings from this section to tailor their behavior according to the specific needs and structure of your Drupal project.

patches.lock.json: Automatically generated by cweagans/composer-patches v2.x. This file contains patch metadata and SHA-256 checksums, and must be committed to version control (like composer.lock). It ensures reproducible builds across teams and CI/CD environments by verifying patch integrity and making the patch state explicit and trackable.
drupal-scaffold: This setting controls which files should be scaffolded:
- locations: Specifies the location of the web root (the directory containing the index.php file).
- file-mapping: Determines which files are managed by the scaffold process. Vortex comes with sensible defaults, but you can customize this section to suit your needs.
installer-paths: Defines custom installation paths for various types of packages like Drupal modules, themes, and libraries.
patchLevel: Defines the patch level for specific packages, in this case, drupal/core. The -p option followed by a number (e.g., -p1, -p2) in patch commands specifies the number of leading directories to strip from the file paths found in the patch file. This determines how the paths in the patch file are interpreted relative to the current directory where the patch is being applied.
patches: Specifies the patches to be applied to specific packages. ➡️ See Development > Composer > Patching

Dependency bumping

Dependency bumping updates version constraints in your composer.json to match currently installed versions. This prevents accidental downgrades when adding new dependencies and improves dependency resolution performance.

Vortex enables this automatically via the bump-after-update configuration. Every time you run composer update, your version constraints are updated to reflect the installed versions.

note

Vortex enables automatic bumping because it's designed for application projects (Drupal sites) where you control the entire dependency tree. This keeps your version constraints synchronized with tested versions and prevents accidental downgrades.

This approach is not recommended for libraries (reusable packages). Libraries should keep version constraints as broad as possible to avoid dependency hell for downstream users. If you're building a library, use bump-after-update: "dev" to only bump development dependencies, or disable automatic bumping and run composer bump --dev-only manually.

Manual bumping

# Bump all dependencies
composer bump

# Bump specific package
composer bump drupal/core-recommended

# Bump only development dependencies
composer bump --dev-only

# Preview changes without modifying files
composer bump --dry-run

composer.json​

name​

description​

type​

license​

repositories​

require​

require-dev​

conflict​

minimum-stability​

prefer-stable​

config​

autoload-dev​

extra​

Dependency bumping​

Manual bumping​