[Wiki] How to use the official Yii installer for Composer

How to use Composer with the Yii Framework

This way of using Composer is different from the Phundament 3 based wiki in that it is using the new official Composer installer for Yii. It is also only making use of Packagist not the packages at packages.phundament.com. This wiki doesn't aim to replace the Phundament 3 based wiki it is just another way of doing it and I really like the fact that it can use Packagist directly and not a separate repository.

Why should I use Composer?

Because Composer makes it easy to keep track of versions of third party code. Almost all good extensions and modules are stored on GitHub and could easily be added to Packagist. Yii 2 will be using Composer as the way to install extensions and modules and Yii 1.1.x doesn't have any official support for Composer. A while ago an official installer for Yii extensions and Modules was released and I think we should start making use of it.

How do I create a new Yii web application and install extensions and modules?

Installing Yii

Since it doesn't look like Packagist properly supports the tags in the official Yii repository I suggest you install Yii the way you normally do.

I also think that the Yii framework isn't something you require from your web application but rather something you build your application on top of.

Create a new web application

Open a linux shell.

I will use /home/user/my_test_app/ for the application.

Now create the application using the webapp option in yiic.

After doing so you should have the application installed in /home/user/my_test_app/.

You should have this list of files and folders in the base folder:

assets
css
index.php
protected
images
index-test.php
themes

Install Composer

We are now going to install Composer in the right directory.

Go to /home/user/my_test_app/.

Now install composer in this directory:

curl -sS https://getcomposer.org/installer | php

When done run php composer.phar in the same directory. If you get the help text for Composer everything is OK.

tip: If you are creating many web application it might be better to install Composer globally.

Configure composer.json

Create a file called composer.json in your application directory. In my case /home/user/my_test_app/.

Edit the file to look like this

{
    "name": "my_vendor_name/my_test_app",
    "require": {
        "composer/installers": "~1.0",
        "br0sk/yiiron": "1.0.2"
    },
    "config": {
        "vendor-dir": "protected/vendors"
    }
}

This look very much like normal composer file except for the that we require the composer/installers. This package includes the official Composer installers.

There is now an official Yii installer and that is the one I am using for the Yiiron extension that will serve as an example extension for now.

Using this installer makes it possible to set your project as an extension or a module.

The Yiiron Composer file looks like this:

{
    "name": "br0sk/yiiron",
    "type": "yii-extension",
    "license": "New BSD License",
    "authors": [
        {
            "name": "John Eskilsson",
            "email": "john.eskilsson@gmail.com",
            "homepage": "http://br0sk.blogspot.co.uk",
            "role": "Developer"
        }
    ],
    "require": {
        "composer/installers": "~1.0",
        "iron-io/iron_core": "0.1.3",
        "iron-io/iron_worker": "1.3.8",
        "iron-io/iron_mq": "1.4.5",
        "iron-io/iron_cache": "0.1.2"
    }
}

This will force the extension to be installed in /home/user/my_test_app/protected/extensions/ setting the type to yii-module makes your project install in /home/user/my_test_app/protected/module/.

tip: If you want to override where a specific extension should be installed you can add this section to your composer file

"extra": {
    "installer-paths": {
        "protected/extensions2/{$name}": ["br0sk/yiiron"]
    }
}

This will make it possible to install the extensions to a folder of choice. This can be very useful if you for instance have called your protected folder something else. In this case yiiron will be installed in /home/user/my_test_app/protected/extensions2/.

Remember that this section is individual for each extension and module. Here is an example for several extensions and modules.

"extra": {
    "installer-paths": {
    "protected/extensions2/{$name}/": ["br0sk/yiiron", "anothervendor/anotherextension"],
    "protected/modules2/${name}/": ["br0sk/module1", "br0sk/module2"]
    }
}

note: installer-paths is only valid for packages installed using a custom installer like yii-extension.

Do also notice how we override the default Composer vendor folder like this

    "config": {
        "vendor-dir": "protected/vendors"
    }

This way we make the vendor classes that might be required by the extension and modules be store outside the actual extension and module folders in a clean way. This way we don't risk to use extensions that import different versions of vendor files. Composer will complain if so is the case.

Run a composer update

Now run composer to install the required libraries:

php composer.phar update

When you run this it will install Yiiron to /home/user/my_test_app/protected/extensions/yiiron/ and the iron.io files to /home/user/my_test_app/protected/vendors/iron-io. Normally the composer installed files would go to /home/user/my_test_app/vendor/ but since we override that using "vendor-dir": "protected/vendors" we will use the proper directory for vendor code in the Yii folder structure.

Limitations

One big problem with this solution is that not all Yii extensions and modules are using Composer and the ones that do are probably not yet making use of the Yii installer yet. If everybody was using it we could have a decent Composer integration even for Yii 1.1.x. So start implementing this for your extensions and modules and we will see were it takes us.

Resources

For questions and feed back use the wiki support thread