S A
Home » PHP » How to Choose PHP Version Used by Composer (with Examples)

How to Choose PHP Version Used by Composer (with Examples)

Updated: January 13, 2024 By: Guest Contributor Post a comment
Table Of Contents
1 Introduction
2 Understanding Composer’s require Key
3 Specifying the PHP Version
4 Platform Packages
5 Using Environment Variables
6 Updating the PHP Version
7 Selecting PHP Versions for Different Environments
8 Troubleshooting
9 Examples
9.1 Example 1: Specifying a Fixed PHP Version
9.2 Example 2: Allowing All PHP 7.4 Patches
10 Conclusion

Introduction

When working with PHP, managing dependencies is a task that Composer handles incredibly well. This reliable dependency management tool for PHP allows developers to specify the version of PHP as well as the versions of PHP libraries their project depends upon. Understanding how to specify and choose the right PHP version for a project is a critical skill for developers to ensure compatibility and stability of applications.

Understanding Composer’s require Key

The require section in the composer.json file is fundamental when declaring the dependencies of your PHP project. This section includes not only packages but also the version of PHP that your application requires. The given versions dictate which configurations Composer will use during install or update operations.

{ "require": { "php": "^7.2.5" // More packages can follow } }

Specifying the PHP Version

To determine the PHP version that Composer should use, you need to include the desired version in the require key of your composer.json file. Here’s an example specifying that the project must run on PHP version 7.2.5 or newer:

{ "require": { "php": "^7.2.5" } }

Composer understands a variety of version constraints:

  • The caret symbol (^) is used to specify versions that are compatible with the given release according to semantic versioning.
  • The tilde symbol (~) is a more conservative approach than the caret. It allows the last digit specified to go up.
  • An asterisk (*) can be used as a wildcard to represent any version.
  • You can specify exact versions with their numbers.
  • Greater than (>), less than (<), and other comparison operators can be used to set version ranges.

This provides a flexible way to define the environment your project should run in, while also making it possible to prevent breaking changes that could occur when packages are updated to a version with backwards incompatibilities.

Platform Packages

The platform key in your composer.json is a section that allows you to emulate your production environment’s PHP version locally or on continuous integration services. This can be especially useful when your local PHP version is different from the one used in production. For example:

{ "config": { "platform": { "php": "7.3.0" } } }

By setting the platform key in the config, you force Composer to resolve dependencies as if it were running on that given PHP version, irrespective of the PHP version currently installed on your system.

Using Environment Variables

You can also control the PHP version used by Composer via environment variables. For example, setting COMPOSER_RUNTIME_PLATFORM_PHP to the version you want to use, before invoking Composer would look like this in Unix-like environments:

COMPOSER_RUNTIME_PLATFORM_PHP=7.3.0 composer update

This approach doesn’t alter the composer.json file and can be useful for quickly switching between PHP versions when testing.

Updating the PHP Version

If you need to update the PHP version in the composer.json file:

  1. Change the version in the require or config section,
  2. Run composer update --lock to just update the lock file without updating other dependencies,
  3. Check that the new PHP version is correctly targeted by using composer show --platform.

Selecting PHP Versions for Different Environments

In cases where different environments (development, staging, production) use different PHP versions, it’s beneficial to configure Composer accordingly. This can be done using the aforementioned methods depending on whether the PHP version needs to be reflective of the composer.json file or be switched dynamically without changing the file.

Troubleshooting

If Composer does not respect the PHP version specified, ensure that:

  • The version format is correct,
  • No local scripts or plugins are overriding the PHP version settings,
  • Cache is not causing issues. Running composer clear-cache might solve such problems.

Examples

To see the PHP version selection in action, here are a couple of examples:

Example 1: Specifying a Fixed PHP Version

{ "require": { "php": "7.4.3" } }

In this case, Composer will resolve dependencies that require exactly PHP version 7.4.3.

Example 2: Allowing All PHP 7.4 Patches

{ "require": { "php": "7.4.*" } }

This configuration will accommodate any patch version within the PHP 7.4 release series.

Conclusion

Choosing the correct PHP version for Composer is an essential aspect of managing a PHP project’s environment and dependencies. By understanding and appropriately using version constraints, developers can ensure that their project runs smoothly across different environments. Clear documentation and adherence to semantic versioning principles will simplify dependency management, making Composer an even more robust tool for PHP development.

Search tutorials, examples, and resources