PHP Series: How to Install a Composer Package?

What is a composer?

A composer is a tool for dependency management in PHP. It provides a standard format for managing dependencies and is an ideal solution when we work on complex projects that depend on multiple installation sources.

What is a composer package?

A composer package is any dependency in a project managed by the composer. A composer package is any component in a Magento project: theme, module, or language pack.

Where are the dependencies defined?

Project dependencies are defined in a composer.json file in your project root directory. Along with packages, you can also find common project properties and metadata.

When you clone a Magento project, you will find a composer.json file in the main root folder or the current module directory. The file may look like this:

{
    "name": "magento/updater",
    "description": "Test composer.json",
    "type": "project",
    "version": "0.74.0-beta2",
    "license": "OSL-3.0",
		"require": {
        "php": "~5.5.0|~5.6.0|~7.0.0|~7.1.0",
        "magento/product-community-edition": "0.74.0-beta12"
    },
    "autoload": {
        "psr-4": {
            "Magento\\": "app/code/Magento/"
        }
    }
}

You can see the dependency definitions under the require field. Each has a name matching the <vendor_name>/<package_name> pattern and a version specified.

How to specify which version of the package to install?

The version must follow the format X.Y.Z or vX.Y.Z with an optional suffix of -dev, -patch (-p), -alpha (-a), -beta (-b), or -RC. The patch, alpha, beta, and RC suffixes can also be followed by a number.

Here are some examples of the SemVer versioning approach in practice:

"require": {
    "vendor/package": "1.3.2", // exactly 1.3.2

    // >, <, >=, <= | specify upper / lower bounds
    "vendor/package": ">=1.3.2", // anything above or equal to 1.3.2
    "vendor/package": "<1.3.2", // anything below 1.3.2

    // * | wildcard
    "vendor/package": "1.3.*", // >=1.3.0 <1.4.0

    // ~ | allows last digit specified to go up
    "vendor/package": "~1.3.2", // >=1.3.2 <1.4.0
    "vendor/package": "~1.3", // >=1.3.0 <2.0.0

    // ^ | doesn't allow breaking changes (major version fixed - following semver)
    "vendor/package": "^1.3.2", // >=1.3.2 <2.0.0
    "vendor/package": "^0.3.2", // >=0.3.2 <0.4.0 // except if major version is 0
}

See more information here.

Where are the packages installed?

The source data for packages is obtained from public and private repositories (sets of libraries). By default, Composer looks for public packages on Packagist.org, but you can also declare custom repositories such as Github, Bitbucket, etc.

How to install a composer package?

Step 1: Check and manage package access

When we try to install a package from a private repository, It may require authentication. If we don’t configure credentials beforehand, the terminal will prompt you to enter credentials during the installation.

To manage access to private repositories beforehand, you need to get the public and private keys of the Magento repository and the GitHub access token. 

1. Obtain credentials for your repository

How to create the authentication keys in Magento?

• Log in to the Commerce Marketplace. If you don’t have an account, click Register
• Click your account name in the top-right of the page and select My Profile
• Click Access Keys in the Marketplace tab.

How to create a token in GitHub?

• Go to GitHub Settings -> Tokens and generate a new token
• Select the option for your token
• Generate the token.

2. Configure the auth.json (or set the environment variable) to persist the credentials.

How to configure the auth.json file?

• Check the auth.json file in your project directory. If you do not have it, please create one. Take a look at the following example:

{
    "http-basic": {
        "repo.magento.com": {
            "username": "<public-key>",
            "password": "<private-key>"
        }
    }
    "github-oauth": {
        "github.com": "<personal-access-token>"
    }
}

This example contains two sets of keys: One for Github and one for the Magento Repository. 

• Using a text editor, create an auth.json file in the main root folder project or the current module directory
• Copy and replace the values of the Composer Auth key

"<public-key>" / "<private-key>" / "<personal-access-token>" 

• Save the changes.

How to set up the COMPOSER_AUTH environment variable?

This example shows the process of configuring access to the Magento repository. You can also use the environment variables to set up authentication keys in your project:

• Type the following command:

export COMPOSER_AUTH='{"http-basic":{"repo.magento.com": {"username": "<public-key>", "pasword": "<private-key>"}}}'

• In the Value field, add the following and replace <public-key> and <private-key> with your Magento authentication credentials. 

Ensure the auth.json is in .gitignore to avoid leaking credentials into your git history.

Step 2: Add a package repository

You can add repositories to composer.json by running the command from the Magento root:

composer config repositories.<NAME> <TYPE> <URL/PATH>

Replace the following templates with:

• <NAME>—any (unique) name for the repository
• <TYPE>—the repository type (path for the local directory, git for Git repo, composer for composer repository)
• <URL/PATH>—the path to the repo, composer repository, or directory on the computer.

For example:

composer config repositories.module-core git https://github.com/scandiwebcom/Scandiweb-Assets-Core.git
composer config repositories.magesycho-magento2-easy-template-path-hints git [email protected]:MagePsycho/magento2-easy-template-path-hints.git

Step 3: Require a composer package

Run the require command:

# the ":<version>" is optional and can be ommited
composer require <vendor_name>/<package_name>:<version>

This will install and add the new package definitions to the composer.json file.

You could also do this manually by adding the package definition to the composer.json file described above and then running the composer update command in the terminal to install and update the packages.

How will this command modify composer.json?

The following line will be added to the file:

"require": {
		 "<vendor_name>/<package_name>": "<version>"
		 // ...
}

What happens when I run the composer require command?

• The require command adds new packages to the composer.json file from the current directory. If no file exists, one will be created on the fly
• The package will then download and install dependencies of itself. You will see the prompt if it cannot resolve some of them. If you do not want to resolve dependency versions interactively, you can pass them to the command.

What options are available for composer require command?

• —dry-run: Simulate the command without actually doing anything
• —no-scripts: Skips execution of scripts defined in composer.json
• —ignore-platform-req: ignore a specific platform requirement (php, hhvm, lib-* and ext-*) and force the installation even if the local machine does not fulfill it.

There are other options available too. See the complete list here.

Where will the package be installed?

The packages are installed in the vendor directory as a conventional folder for all third-party code in a project.

The composer install and composer require are often confused. Do not use the install command to add new packages. If a composer.lock file exists, the install command will install dependency versions specified in the composer.lock file instead of composer.json.

Step 4: Setup and enable the Magento module

To set up and enable a module, we need to follow these steps:

• Check the status module:

magento module:status 

• In case your module is disabled, you should enable it:

 magento module:enable <module_name>

• Once our module is enabled, you can set it up:

magento setup:upgrade

How to update an existing Composer package?

To get the latest versions of the dependencies (while still following the constraints specified in dependency definitions), you need to use the following command:

composer update <vendor_name>/<package_name>

For example, the following command updates the magento/product-community-edition package:

composer update magento/product-community-edition

If this doesn’t get you the package version you need, you should edit the version constraints specified in composer.json to match your needs.

What happens when I run the composer update command?

1. Read the composer.json file.
2. Search Packagist for the packages specified in that file.
3. Resolve the installation version for each package from the indicated versions and the stability settings.
4. For those packages with a new version available, download and install it, replacing the current version.
5. Resolve all dependencies for those versions.
6. Once the packages are installed, if composer.lock does not exist, create it to leave a “still photo” of the application’s execution environment. If it exists, update it.
7. Create the application’s class autoload files.

What options are available for the composer update command?

• —dry-run: Simulate the command without actually doing anything
• —ignore-platform-req: ignore a specific platform requirement (php, hhvm, lib-* and ext-*) and force the installation even if the local machine does not fulfill it.

There are other options available too. See the complete list here.

How to remove a package?

To remove a package, run the following command:

composer remove <vendor_name>/<package_name>

Was this article helpful? There’s more where this came from! Browse our tech category in the blog, book a Dedicated eCommerce Growth team, or contact our team directly!

Related articles:

PHP Series: How to Use a Composer Patch

PPHP Series: How to Publish a Composer Package

Share on: