Skip to main content

Composer

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 Working with Composer packages for more information on how to add and manage dependencies in your project.

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​

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.3",
        "composer/installers": "^2.3",
        "cweagans/composer-patches": "^2.0",
        "drupal/admin_toolbar": "^3.6.2",
        "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.2.8",
        "drupal/core-recommended": "~11.2.8",
        "drupal/environment_indicator": "^4.0.25",
        "drupal/pathauto": "^1.14",
        "drupal/redirect": "^1.12",
        "drupal/redis": "^1.11",
        "drupal/robotstxt": "^1.6",
        "drupal/search_api": "^1.40",
        "drupal/search_api_solr": "^4.3.10",
        "drupal/seckit": "^2.0.3",
        "drupal/shield": "^1.8",
        "drupal/stage_file_proxy": "^3.1.6",
        "drush/drush": "^13.7.0",
        "oomphinc/composer-installers-extender": "^2.0.1",
        "webflo/drupal-finder": "^1.3.1"
    },
    "require-dev": {
        "behat/behat": "^3.27",
        "dantleech/gherkin-lint": "^0.2.3",
        "dealerdirect/phpcodesniffer-composer-installer": "^1.2.0",
        "drevops/behat-format-progress-fail": "^1.4",
        "drevops/behat-screenshot": "^2.2",
        "drevops/behat-steps": "^3.4.0",
        "drevops/phpcs-standard": "^0.6",
        "drupal/coder": "^9@alpha",
        "drupal/drupal-extension": "^5.1",
        "ergebnis/composer-normalize": "^2.48.2",
        "lullabot/mink-selenium2-driver": "^1.7.4",
        "lullabot/php-webdriver": "^2.0.7",
        "mglaman/phpstan-drupal": "^2.0.10",
        "mikey179/vfsstream": "^1.6.12",
        "palantirnet/drupal-rector": "^0.21.1",
        "phpcompatibility/php-compatibility": "^10.0@alpha",
        "phpmd/phpmd": "^2.15",
        "phpspec/prophecy-phpunit": "^2.4",
        "phpstan/extension-installer": "^1.4.3",
        "phpstan/phpstan": "^2.1.32",
        "phpunit/phpunit": "^11.5.45",
        "pyrech/composer-changelogs": "^2.2",
        "rector/rector": "^2.2.11",
        "vincentlanglet/twig-cs-fixer": "^3.11"
    },
    "conflict": {
        "drupal/drupal": "*"
    },
    "repositories": [
        {
            "type": "composer",
            "url": "https://packages.drupal.org/8"
        }
    ],
    "minimum-stability": "stable",
    "prefer-stable": true,
    "autoload": {
        "classmap": [
            "scripts/composer/ScriptHandler.php"
        ]
    },
    "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,
            "oomphinc/composer-installers-extender": true,
            "php-http/discovery": true,
            "phpstan/extension-installer": true,
            "pyrech/composer-changelogs": true,
            "tbachert/spi": true
        },
        "audit": {
            "abandoned": "report",
            "block-insecure": true
        },
        "bump-after-update": true,
        "discard-changes": true,
        "platform": {
            "php": "8.3.28"
        },
        "sort-packages": true
    },
    "extra": {
        "drupal-scaffold": {
            "file-mapping": {
                "[project-root]/.editorconfig": false,
                "[project-root]/.gitattributes": false,
                "[web-root]/.csslintrc": false,
                "[web-root]/.editorconfig": false,
                "[web-root]/.eslintignore": false,
                "[web-root]/.eslintrc.json": false,
                "[web-root]/.gitattributes": false,
                "[web-root]/.ht.router.php": false,
                "[web-root]/.htaccess": false,
                "[web-root]/INSTALL.txt": false,
                "[web-root]/README.md": false,
                "[web-root]/README.txt": 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,
                "[web-root]/web.config": false
            },
            "locations": {
                "web-root": "web/"
            }
        },
        "installer-paths": {
            "web/core": [
                "type:drupal-core"
            ],
            "web/libraries/{$name}": [
                "type:bower-asset",
                "type:drupal-library",
                "type:npm-asset"
            ],
            "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"
            ]
        },
        "installer-types": [
            "bower-asset",
            "npm-asset",
            "drupal-library"
        ],
        "patchLevel": {
            "drupal/core": "-p2"
        },
        "patches": {}
    },
    "scripts": {
        "pre-install-cmd": [
            "DrupalProject\\composer\\ScriptHandler::checkComposerVersion"
        ],
        "post-install-cmd": [
            "DrupalProject\\composer\\ScriptHandler::createRequiredFiles"
        ],
        "pre-update-cmd": [
            "DrupalProject\\composer\\ScriptHandler::checkComposerVersion"
        ],
        "post-update-cmd": [
            "DrupalProject\\composer\\ScriptHandler::createRequiredFiles"
        ]
    }
}

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.

  • drupal: Serves as the official source for Drupal modules, themes, and distributions. It's crucial for a Drupal project using Composer, as it allows access to Drupal-specific packages not available on Packagist.

require​

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

  • php: Specifies the minimum PHP version required to run this project. This should be specified as a range rather than an exact version number. E.g. >=8.2 and not 8.2.0.
  • composer/installers: Allows to install packages to the correct location based on the specified package type such as drupal-module, drupal-theme, drupal-profile, etc.
  • cweagans/composer-patches: Enables git-based patching of Composer packages, useful for incorporating fixes not yet in official releases. Version 2.x uses git apply for cross-platform consistency and generates a patches.lock.json file to ensure reproducible builds with SHA-256 checksums. See Patching for more information on how to work with patches.
  • drupal/admin_toolbar, drupal/clamav, drupal/coffee, etc. - Drupal modules that provide various site administration and development helping functionalities that is usually installed across all of your Drupal sites. Vortex comes with pre-configured settings for some of the modules to make them work out of the box.
  • drupal/core-recommended: A package that provides a carefully selected set of dependencies, including specific versions, which are tested and recommended for a particular Drupal core version. It simplifies dependency management by ensuring compatibility and stability, as these dependencies are maintained and curated by the Drupal community.
  • drupal/core-composer-scaffold: Allows downloading and placing Drupal Scaffold files (like index.php, update.php, etc.) from the drupal/core project into their desired location inside the web root.
  • 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.
  • oomphinc/composer-installers-extender: Allows any package to be installed to a directory other than the default vendor directory within a project on a package-by-package basis. This plugin extends the composer/installers plugin to allow any arbitrary package type to be handled by their custom installer.
  • 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.

  • behat/behat: A PHP framework for Behavior-Driven Development (BDD), allowing you to write human-readable stories that describe the behavior of your application. It facilitates communication between developers, stakeholders, and clients.
  • dantleech/gherkin-lint: A linting tool for Gherkin feature files used in Behat tests. Ensures consistency and quality in BDD test scenarios by checking syntax and formatting.
  • dealerdirect/phpcodesniffer-composer-installer: This tool automatically configures PHP_CodeSniffer to use the coding standards (like PSR-2 or Drupal coding standards) installed in a project.
  • drevops/behat-format-progress-fail: Enhances the output format of Behat tests, focusing specifically on progress and failure scenarios. This makes it easier to spot and address test failures.
  • drevops/behat-screenshot: An extension for Behat that automatically captures screenshots when tests fail. This is helpful for debugging and understanding why a test failed.
  • drevops/behat-steps: Provides a collection of pre-defined step definitions for Behat. This package speeds up the process of writing new Behat tests by providing common step implementations.
  • drevops/phpcs-standard: A custom PHP_CodeSniffer coding standard that extends Drupal coding standards with additional rules and best practices specific to DrevOps projects.
  • drupal/coder: Provides PHP_CodeSniffer rules for Drupal coding standards. Version 9.x supports PHP_CodeSniffer 4.x and includes updated rules for modern Drupal development.
  • drupal/drupal-extension: A Behat extension that provides integration with Drupal, offering step definitions specific to Drupal functionality. It facilitates the creation and management of Drupal sites for testing purposes.
  • ergebnis/composer-normalize: A composer plugin for normalizing composer.json.
  • mglaman/phpstan-drupal: Integrates PHPStan static analysis with Drupal-specific code, helping identify potential issues and bugs in Drupal modules and themes.
  • palantirnet/drupal-rector: Automates the process of updating deprecated code, making Drupal upgrade processes more efficient.
  • phpcompatibility/php-compatibility: Provides a collection of sniffs for PHP_CodeSniffer to check PHP code for compatibility with different PHP versions, crucial for ensuring long-term maintainability. Version 10.x supports PHP_CodeSniffer 4.x.
  • phpmd/phpmd: PHP Mess Detector is a user-friendly tool that helps you detect several potential problems in your PHP code, including possible bugs, suboptimal code, and overcomplicated expressions.
  • phpspec/prophecy-phpunit: Integrates the Prophecy mocking library with PHPUnit to provide advanced mocking capabilities in tests.
  • phpstan/extension-installer: This package automatically installs and enables PHPStan extensions, streamlining the setup process for PHPStan in your project.
  • phpstan/phpstan: A static analysis tool for PHP that focuses on finding bugs in code without running it. Helps catch type errors, incorrect method calls, and other potential issues during development.
  • phpunit/phpunit: The industry-standard testing framework for PHP. Provides a comprehensive set of tools for writing and running unit tests, integration tests, and functional tests.
  • pyrech/composer-changelogs: Provides a summary of package changes (like updates, removals, and additions) after running composer update, improving the visibility of package changes and updates in your project.
  • rector/rector: An automated refactoring tool that instantly upgrades and refactors PHP code. Helps with code modernization, framework migrations, and automated application of coding standards.
  • vincentlanglet/twig-cs-fixer: This tool ensures that Twig templates adhere to a set coding standard, helping maintain consistency and readability in template files.

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.
  • audit: Introduced in Composer 2.9.0, this setting controls automatic security auditing of dependencies during composer install and composer update. Vortex enforces security best practices with the following configuration:
    • block-insecure (default: true): Blocks installation of packages with known security vulnerabilities unless explicitly ignored. This ensures security issues are addressed before deployment.
    • abandoned (default: report): Shows warnings for abandoned packages without failing the build. Allows visibility into package maintenance status while not blocking installations.
    • ignore (default: {}): Empty object ready for adding assessed and documented vulnerability exceptions. Use this to explicitly allow specific CVE/GHSA advisories that have been reviewed and accepted.
    • See Composer Security Auditing for comprehensive guidance on configuration options, ignoring specific advisories, running audits, 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.2.0). 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​

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

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.
  • installer-types: Specifies additional installer types, such as bower-asset and npm-asset, that are handled by the oomphinc/composer-installers-extender plugin.
  • 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 Working with packages for more information on how to work with patches.

scripts​

The scripts section defines custom scripts to be executed at specific points in Composer's workflow, enhancing the automation and maintenance of your Drupal project.

  • pre-install-cmd: Executes scripts before the composer install command is run. In your configuration, DrupalProject\composer\ScriptHandler::checkComposerVersion is specified, which ensures that the Composer version being used is compatible with your project setup. This is vital for maintaining consistency and avoiding issues due to version mismatches.
  • pre-update-cmd: Runs scripts before the composer update command is executed. It uses the same script as pre-install-cmd to check the Composer version, ensuring that updates to your project’s dependencies are compatible with your current Composer setup.
  • post-install-cmd: Invoked after the composer install command completes. The script DrupalProject\composer\ScriptHandler::createRequiredFiles is executed, which typically handles tasks like setting up default files and configurations necessary for the Drupal installation.
  • post-update-cmd: Executes scripts after the composer update command. It calls the same createRequiredFiles method as in post-install-cmd, ensuring that necessary files and configurations are updated or re-established following an update of dependencies.