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.
Vortex comes with a pre-configured composer.json
file based on
the Drupal Composer project,
extended to support additional features and tools.
See Working with packages for more information on how to add and manage dependencies in your project.
Drupal Composer project
Drupal Composer project provides a starter kit for managing your site dependencies with Composer.
Vortex extends the Drupal Composer project's composer.json
to support
additional features and tools.
Vortex team will keep the composer.json
file up-to-date with the
latest version of the composer.json
in the Drupal Composer project,
so you can always make sure you are using the best community practices.
composer.json
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 10 implementation of YOURSITE for YOURORG",
"license": "proprietary",
"type": "project",
"require": {
"php": ">=8.3",
"composer/installers": "^2.3",
"cweagans/composer-patches": "^1.7",
"drupal/admin_toolbar": "^3.5",
"drupal/clamav": "^2.0",
"drupal/coffee": "^1.4",
"drupal/config_split": "^1.9",
"drupal/config_update": "^2@alpha",
"drupal/core-composer-scaffold": "~10.3.2",
"drupal/core-recommended": "~10.3.2",
"drupal/environment_indicator": "^4.0",
"drupal/pathauto": "^1.13",
"drupal/redirect": "^1.10",
"drupal/redis": "^1.8",
"drupal/search_api": "^1.35",
"drupal/search_api_solr": "^4.3",
"drupal/shield": "^1.8",
"drupal/stage_file_proxy": "^2.1",
"drush/drush": "^13",
"oomphinc/composer-installers-extender": "^2",
"webflo/drupal-finder": "^1.3"
},
"require-dev": {
"behat/behat": "^3.14",
"dantleech/gherkin-lint": "^0.2.3",
"dealerdirect/phpcodesniffer-composer-installer": "^0.7",
"drevops/behat-format-progress-fail": "^1.2",
"drevops/behat-screenshot": "^1.5",
"drevops/behat-steps": "^2.4",
"drupal/core-dev": "~10.3.2",
"drupal/drupal-extension": "^5",
"ergebnis/composer-normalize": "^2.43",
"mglaman/phpstan-drupal": "^1.2",
"palantirnet/drupal-rector": "^0.20",
"phpcompatibility/php-compatibility": "^9.3",
"phpmd/phpmd": "^2.15",
"phpspec/prophecy-phpunit": "^2.2",
"phpstan/extension-installer": "^1.4",
"pyrech/composer-changelogs": "^1.8",
"vincentlanglet/twig-cs-fixer": "^3"
},
"conflict": {
"drupal/drupal": "*"
},
"repositories": [
{
"type": "composer",
"url": "https://packages.drupal.org/8"
},
{
"type": "composer",
"url": "https://asset-packagist.org"
}
],
"minimum-stability": "beta",
"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
},
"discard-changes": true,
"platform": {
"php": "8.3.12"
},
"sort-packages": true
},
"extra": {
"composer-exit-on-patch-failure": true,
"drupal-scaffold": {
"file-mapping": {
"[project-root]/.editorconfig": false,
"[project-root]/.gitattributes": false,
"[web-root]/.ht.router.php": false,
"[web-root]/.htaccess": false,
"[web-root]/INSTALL.txt": false,
"[web-root]/README.txt": false,
"[web-root]/example.gitignore": false,
"[web-root]/sites/example.settings.local.php": false,
"[web-root]/sites/example.sites.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"
],
"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
licence 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.
See Working with packages for more information on how to provide custom and override existing packages in your project.
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.asset-packagist
: Enables the installation of Bower and NPM packages via Composer. This is especially important for Drupal projects needing front-end libraries and tools, bridging the gap between Composer's PHP-centric ecosystem and the broader world of front-end package management.
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 not8.2.0
.composer/installers
: Allows to install packages to the correct location based on the specified package type such asdrupal-module
,drupal-theme
,drupal-profile
, etc.cweagans/composer-patches
: Allows applying patches to Composer packages, useful for incorporating fixes not yet in official releases. See Working with packages 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 (likeindex.php
,update.php
, etc.) from thedrupal/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 defaultvendor
directory within a project on a package-by-package basis. This plugin extends thecomposer/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.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.drupal/core-dev
: Includes development-specific dependencies and tools primarily for testing and code analysis, including PHPUnit, PHP_CodeSniffer with rules ( via Coder module).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 normalizingcomposer.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.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.pyrech/composer-changelogs
: Provides a summary of package changes (like updates, removals, and additions) after runningcomposer update
, improving the visibility of package changes and updates in your project.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.discard-changes
: When set totrue
, 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 thephp
version in the Docker containers.sort-packages
: When set totrue
, this configuration ensures that packages are sorted incomposer.json
andcomposer.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.
composer-exit-on-patch-failure
: This setting, when enabled, causes Composer to exit if a patch from thecweagans/composer-patches
plugin fails to apply.drupal-scaffold
: This setting controls which files should be scaffolded:locations
: Specifies the location of the web root (the directory containing theindex.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 asbower-asset
andnpm-asset
, that are handled by theoomphinc/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 thecomposer 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 thecomposer update
command is executed. It uses the same script aspre-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 thecomposer install
command completes. The scriptDrupalProject\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 thecomposer update
command. It calls the samecreateRequiredFiles
method as inpost-install-cmd
, ensuring that necessary files and configurations are updated or re-established following an update of dependencies.