Skip to content

Latest commit

 

History

History
155 lines (99 loc) · 5.85 KB

extend-using-composer.md

File metadata and controls

155 lines (99 loc) · 5.85 KB
Raw

Composer

Note: This section is under development.

Yii2 uses Composer as its dependency management tool. Composer is a PHP utility that can automatically handle the installation of needed libraries and extensions, thereby keeping those third-party resources up to date while absolving you of the need to manually manage the project's dependencies.

Installing Composer

In order to install Composer, check the official guide for your operating system:

All of the details can be found in the guide, but you'll either download Composer directly from http://getcomposer.org/, or run the following command:

curl -s http://getcomposer.org/installer | php

We strongly recommend a global composer installation.

Installing Composer Class Autoloader

Make sure the entry script of your application contains the following lines of code:

// install Composer's class autoloader
require(__DIR__ . '/../vendor/autoload.php');

// include Yii class file
require(__DIR__ . '/../vendor/yiisoft/yii2/Yii.php');

Working with composer

The act of installing a Yii application with

composer.phar create-project --stability dev yiisoft/yii2-app-basic

creates a new root directory for your project along with the composer.json and compoer.lock file.

While the former lists the packages, which your application requires directly together with a version constraint, while the latter keeps track of all installed packages and their dependencies in a specific revision. Therefore the composer.lock file should also be committed to your version control system.

These two files are strongly linked to the two composer commands update and install. Usually, when working with your project, such as creating another copy for development or deployment, you will use

composer.phar install

to make sure you get exactly the same packages and versions as specified in composer.lock.

Only if want to intentionally update the packages in your project you should run

composer.phar update

As an example, packages on dev-master will constantly get new updates when you run update, while running install won't, unless you've pulled an update of the composer.lock file.

There are several parameters available to the above commands. Very commonly used ones are --no-dev, which would skip packages in the require-dev section and --prefer-dist, which downloads archives if available, instead of checking out repositories to your vendor folder.

Composer commands must be executed within your Yii project's directory, where the composer.json file can be found. Depending upon your operating system and setup, you may need to provide paths to the PHP executable and to the composer.phar script.

Adding more packages to your project

To add two new packages to your project run the follwing command:

composer.phar require "cebe/indent:>=1.0.2" "cebe/yii2-gravatar:>1.1"

This will resolve the dependencies and then update your composer.json file. The above example says that a version greater than or equal to 1.0.3 of indent converter package and version 1.1 or greater of gravatar extension are required.

For details of this syntax, see the official Composer documentation.

The full list of available Composer-supported PHP packages can be found at packagist. You may also search packages interactively just by entering composer.phar require.

Manually editing your version constraints

You may also edit the composer.json file manually. Within the require section, you specify the name and version of each required package, same as with the command above.

{
    "require": {
        "michelf/php-markdown": ">=1.4",
        "ezyang/htmlpurifier": ">=4.6.0"
    }
}

Once you have edited the composer.json, you can invoke Composer to download the updated dependencies. Run

composer.phar update michelf/php-markdown ezyang/htmlpurifier

afterwards.

Depending on the package additional configuration may be required (eg. you have to register a module in the config), but autoloading of the classes should be handled by composer.

Using a specific version of a package

Yii always comes with the latest version of a required library that it is compatible with, but allows you to use an older version if you need to.

A good example for this is jQuery which has dropped old IE browser support in version 2.x. When installing Yii via composer the installed jQuery version will be the latest 2.x release. When you want to use jQuery 1.10 because of IE browser support you can adjust your composer.json by requiring a specific version of jQuery like this:

{
    "require": {
        ...
        "yiisoft/jquery": "1.10.*"
    }
}

FAQ

Getting "You must enable the openssl extension to download files via https"

If you're using WAMP check this answer at StackOverflow.

Getting "Failed to clone , git was not found, check that it is installed and in your Path env."

Either install git or try adding --prefer-dist to the end of install or update command.

Should I Commit The Dependencies In My Vendor Directory?

Short answer: No. Long answer, see here.

See also