Advanced Composer Usage – Using Zend Framework 3

2.12. Advanced Composer Usage

Earlier in this chapter, we have used Composer to install Zend Framework 3 library code. Now let's briefly describe some advanced Composer usage examples.

As we already know, the only required key in the composer.json file is require. This key tells what packages are required by your application:

{
    "require": {
        "php": "^5.6 || ^7.0",
        "zendframework/zend-component-installer": "^1.0 || ^0.3 || ^1.0.0-dev@dev",
        "zendframework/zend-mvc": "^3.0.1",
        "zfcampus/zf-development-mode": "^3.0",
        "zendframework/zend-mvc-form": "^1.0",
        "zendframework/zend-mvc-plugins": "^1.0.1",
        "zendframework/zend-session": "^2.7.1"
    }
}

2.12.1. Package Names and Versions

A package name consists of two parts: vendor name and project name. For example "zendframework/zend-mvc" package name consists of "zendframework" vendor name and "zend-mvc" project name. You can search for other packages from "zendframework" vendor through Packagist.org website (see the figure 2.8 for an example).

Figure 2.8. You can search packages on Packagist.org

A package also has an associated version number. A version number consists of major number, minor number, optional build number, and optional stability suffix (e.g. b1, rc1). Within the require key we specify which versions of the package are acceptable. For example, "^5.6" means that we can install versions greater than "5.6", but lower than "6.0" (that we can install only those packages that do not break backward compatibility). In table 2.2, possible ways of specifying acceptable versions are presented:

Table 2.2. Package Version Definitions

Definition Example	Description
3.0.1	Exact version. In this example, only the version 3.0.1 can be installed.
>=3.0.1	Greater or equal version can be installed (3.0.1, 3.2.1, etc.)
>3.0.1	Greater version can be installed (3.0.2 etc.)
<=3.0.1	Lower or equal version can be installed (1.0, 1.5, 2.0.0 etc.)
<3.0.1	Lower version can be installed (1.0, 1.1, 1.9, etc.)
!=3.0.1	All versions except this version can be installed.
>=3.0,<3.1.0	Any version belonging to this range of versions can be installed.
3.*	Any version having major number equal to 3 can be installed (minor number can be any).
~3.0	Any version starting from 3.0, but lower than the next major version (equivalent to >=3.0,<4.0).
^3.0	Any version starting from 3.0, but lower than the next major version (equivalent to >=3.0,<4.0). Similar to `~3.0`, but it sticks closer to semantic versioning, and will always allow non-breaking updates.

2.12.2. Installing and Updating Packages

We've seen how to use the php composer.phar install command to install our dependencies. As soon as you call this command, Composer will find, download and install the dependencies to your vendor subdirectory.

Is it safe to install dependencies with Composer?

Well, some people may be afraid of Composer-style dependency management, because they think someone can update the dependencies system-wide by mistake or intentionally, causing the web application to break. Note, that Composer never installs these system-wide, instead it installs them into your APP_DIR/vendor/ directory.

After installation, Composer also creates the APP_DIR/composer.lock file. This file now contains actual versions of the packages that were installed. If you run the install command again, Composer will encounter the composer.lock file, check which dependencies already installed and as all packages already installed, it just exits without doing anything.

Now assume that in some period of time new security updates for your dependency packages are released. You will want to update your packages to keep your website secure. You can do that by typing the following:

php composer.phar update

If you want to update only a single dependency, type its name as the following:

php composer.phar update zendframework/zend-mvc

After the update command, your composer.lock file will be updated, too.

What do I do if I want to roll back to a previous version of the package?

If the update procedure resulted in unwanted problems with your system, you can roll back by reverting the changes to your composer.lock file and issuing the install command again. Reverting changes to composer.lock is easy if you use a version control system, like GIT or SVN. If you don't use a version control system, make a backup copy of composer.lock before updating.

2.12.3. Adding a New Dependency

If you want to add new dependency to the application, you can either edit composer.json manually, or issue require command. For example, to install Doctrine ORM module to your web site (to add the "doctrine/doctrine-module" package to the application dependencies), type the following:

php composer.phar require doctrine/doctrine-module 2.*

The command above edits composer.json file, and downloads and installs the package. We will use this command later in chapter Managing Database with Doctrine, when becoming familiar with database management.

2.12.4. Virtual Packages

Composer can be used to require some functionality to present on your system. You've already seen how we require "php:^5.6". PHP package is a virtual package representing PHP itself. You can also require other stuff, like PHP extensions (see table 2.3 below).

Table 2.3. Virtual Composer Packages

Definition Example	Description
"php":"^5.6"	Require PHP version greater or equal than 5.6, but lower than 6.0.
ext-dom, ext-pdo-mysql	Require PHP DOM and PDO MySQL extensions
lib-openssl	Require OpenSSL library

You can use php composer.phar show --platform command to display a list of available virtual packages for your machine.

2.12.5. Composer and Version Control Systems

If you are using a version control system (like Git), you will be curious about what should be stored in Git: your application code only, or your application code plus all the Composer-installed dependencies in APP_DIR/vendor directory?

In general, it is not recommended to store your Composer-dependencies under version control, because this can make your repository really big and slow to check out and branch. Instead, you should store your composer.lock file under version control. The composer.lock file guarantees that everyone will install the same versions of dependencies as you have. This is useful in development teams having more than one developer, because all developers should have the same code to avoid unwanted issues with environment misconfiguration.

What if some dependence will be declared obsolete and removed from Packagist.org?

Well, the possibility of package removal is minimum. All packages are free and open-source, and the community of users can always restore the dependency even if it is removed from packagist. By the way, the same concept of dependency installation is used in Linux (remember APT or RPM manager?), so did anyone see any Linux package lost?

But there may be situations when you should store some dependent libraries under version control:

If you have to make custom changes to third-party code. For example, assume you have to fix a bug in a library, and you cannot wait for the library's vendor to fix it for you (or if the library vendor cannot fix the bug). In this case, you should place the library code under version control to ensure your custom changes won't be lost.
If you have written a reusable module or library and want to store it in the vendor directory without publishing it on Packagist.org. Because you don't have an ability to install this code from the Packagist, you should store it under version control.
If you want a 100% guarantee that a third-party package won't be lost. Although the risk is minimum, for some applications it is critical to be autonomous and not depend on package availability on Packagist.org.