How to install and use Composer on Ubuntu 14.04

Introduction

Composer is a popular dependency management tool for PHP, which is created to facilitate installation and updates for project dependencies. This would check any other packages that a specific project depends on before installing them for you with the appropriate versions.
In this tutorial we will teach you how to install and get started with Composer on your Ubuntu 14.04 server.

Prerequisites

For this guide you will require the following:
A server running Ubuntu 14.04.
Access to the server as a regular user with sudo permission.

Step 1 – Installing the Dependencies

To start, you must ensure that your server has all the dependencies installed.
We do that by updating the package manager cache with the following command.

sudo apt-get update

Next, install the dependencies; you will need curl to be able to download Composer and php5-cli for installing and running it.
git is used by Composer to download project dependencies.
You may install everything with the following command.

sudo apt-get install curl php5-cli git

You may continue now to the next step.

Step 2 – Downloading and Installing Composer

Composer installation is fairly easily done with a single command.

curl -sS https://getcomposer.org/installer | sudo php -- --install-dir=/usr/local/bin --filename=composer

The command will download and install as a system-wide command named composer under ‘/usr/local/bin’. The output might look like the following.

Output
#!/usr/bin/env php
All settings correct for using ComposerDownloading...

Composer successfully installed to: /usr/local/bin/composer
Use it: php /usr/local/bin/composer

In order to test your installation, execute the following. composer
you should receive an output close to the following.

Output  
Composer version 1.0-dev (9859859f1082d94e546aa75746867df127aa0d9e) 2015-08-17 14:57:00 
Usage: command
[options] [arguments] 
Options: --help (-h)   Display this help message
--quiet (-q)     Do not output any message
--verbose (-v|vv|vvv) Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug
--version (-V)  Display this application version
--ansi   Force ANSI output
 --no-ansi   Disable ANSI output
--no-interaction (-n) Do not ask any interactive question
--profile  Display timing and memory usage information -
-working-dir (-d)    If specified, use the given directory as working directory
. . . .

Step 3 – Generating the composer.json File

To be able to use Composer in your project, you will require a ‘composer.json’ file.
The ‘composer.json’ file is meant to tell Composer the dependencies which it requires to have downloaded for your project as well as the versions of every package that are allowed to be installed.
This part is very important so that you can keep your project consistent.
Be sure to avoid installing unstable versions which will potentially cause backwards compatibility. You will not have to create this file manually; it is very easy to run into syntax errors once you do so.
Composer will auto-generate the ‘composer.json’ file after you add a dependency to your project with the require command.
Extra dependencies may also be added in the same way without the need to manually modify this file.
The procedure of using Composer to install a package as a dependency in a project normally includes the following steps:

1. Recognize what type of library the application needs.
2. Research a fitting open source library on ‘Packagist.org’, the official repository for Composer
3. Select the package you would like to depend on.
4. Execute composer require to include the dependency in the ‘composer.json’ file and then install the package.

We will show how this works in practice with a simple demo application.
The intention of this application is to transform a given sentence into a URL-friendly string called a slug. This is commonly used for converting page titles to URL paths.
Begin with creating a directory for your project.
Name it ‘slugify’

cd ~
mkdir slugify
cd slugify

Searching for Packages on Packagist

Next search ‘Packagist.org’ for a package able to help with generating slugs. Look for the term ‘slug’ on Packagist.
You should see two numbers on the right side of every package in the list. The number on the top displays the amount of times the package was installed whereas the number on the bottom displays how many times a package was starred on GitHub. You can reorder the search results based on these numbers; search for the two icons on the right-hand side of the search bar.
Generally speaking, any package with more installations and more stars are usually more stable as a lot of people are using them. It is very good to also check the package description for relevance if it is really what you are looking for.
What you require is a simple ‘string-to-slug’ converter. From the search results, the package ‘cocur/slugify’ appears to be a good match with a solid amount of installation and stars.
You will see that the packages on Packagist will have a vendor name and a package name. Every package will hold a unique identifier, a namespace, in the same format Github uses for its repositories.
Vendor/package. The library you would like to install uses the namespace ‘cocur/slugify’. The namespace is what you will want in order to get the package in your project.

 Requiring a Package

Since you know what package you would like to install, you may run composer require to have it as a dependency as well as generating the ‘composer.json’ file for the project.

composer require cocur/slugify
Output
Using version ^1.3 for cocur/slugify
./composer.json has been created
Loading composer repositories with package information
Updating dependencies (including require-dev)
  - Installing cocur/slugify (v1.3)
    Downloading: 100%        
Writing lock file
Generating autoload files

As you may notice from the output, Composer has automatically decided what version of the package needs to be used.
If you look at your project’s directory now, it should contain two new files: ‘composer.json’ and ‘composer.lock’ as well as a vendor directory.

ls -l

Output
total 12
-rw-rw-r-- 1 joey joey   59 Sep  9 16:22 composer.json
-rw-rw-r-- 1 joey joey 2835 Sep  9 16:22 composer.lock
drwxrwxr-x 4 joey joey 4096 Sep  9 16:22 vendor

The file ‘composer.lock’ is made for storing information about what versions of each package is installed and ensures the same versions are used in case anyone else clones your project and installs its dependencies.
The directory ‘vendor’ is where the project dependencies are located. The ‘vendor’ folder should not be committed into version control, you only have to include the ‘composer.json’ and ‘composer.lock’.

Understanding Version Constraints

Looking at the contents of your ‘composer.json’ file, you should see something like in the following.

cat composer.json

{
     “require”: {
        “cocur/slugify”: “^1.3”
      }
}

You might see the special character ‘^’ before the version number on ‘composer.json’. Composer supports different constraints and formats for defining the needed package version so you are able to add flexibility while also holding your project stable.
The caret ‘^’ operator used by the auto-generated ‘composer.json’ file is the suggested operator for maximum interoperability, following semantic versioning. In our case, it determines 1.3 as the minimum compatible version and allows updates to any future version below 2.0.
Normally, you should not need to tamper with version constraints in your ‘composer.json’ file. Though, certain situations may need you to manually edit the constraints. For example; when a major new version of your required library is released and you would like to update or when the library you want to use does not follow semantic versioning.
You may see some examples here which will probably give you an idea of how Composer version constraints work.

Step 4 – Including the Autoload Script

Composer also allows an autoload script to get autoloading for free. It will make it a lot easier to work with your dependencies and determine your own namespaces.
The one thing you will have to do is include the ‘vendor/autoload.php’ file in your PHP scripts before any class instantiation.
Returning to the slugify example application, you can create a ‘test.php’ script where you can use the ‘cocur/slugify’ library.

vim test.php
test.php
<?php
require __DIR__ . '/vendor/autoload.php';
use Cocur\Slugify\Slugify;
$Slugify = new Slugify();
echo $Slugify->Slugify('Hello World, this is a test and I need to make a slug from it!');

You may execute the script in the command line with the below.

php test.php

It will produce the output ‘hello-world-this-is-a-test-and-i-need-to-make-a-slug-from-it’.

Step 5 – Updating the Project Dependencies

Any time you would like to update your project’s dependencies, you just have to run the update command.

composer update

This will check for any new versions of the libraries you require in your project. In the case that a newer version is found and is compatible with the version constraint defined in the ‘composer.json’ file, it will switch the last version installed.
The ‘composer.lock’ file will be updated to reflect these changes.
You may also update one or more specific libraries by executing the following.

composer update vendor/package vendor2/package2

Conclusion

Composer is a very powerful tool every PHP developer will require in their utility belt.
Despite giving an easy and reliable way for managing project dependencies, it also allows a new de facto standard for sharing and discovering any PHP packages made by the community.
This tutorial covered the main parts required to getting started with Composer on Ubuntu 14.04.