Empower your PHP projects with Composer

Composer, the dependency management tool for PHP, allows you to easily install or update PHP libraries required by your project. In this tutorial, we see how to use composer to download and use 3rd libraries.

Using composer in existing project

Suppose you have a simple web application - a PHP project under my-app directory.

my-app
my-app/
└── index.php

The project contains simple PHP script called index.php. The script displays the “Hello World !!!".

main.php
<?php
echo "Hello World !!!";

Now, you are assigned the task of adding some logging to the web application. Instead of reinventing the wheel, you find a 3rd library monolog. After reading the docs, you find that the monolog library allows you to send your logs to files and more (sockets, inboxes, databases and various web services). Perfect - It fulfills all your requirements.

Reading the docs, you find that this 3rd library is released as a composer package. Let’s see how to download and use it in our project with the help of the composer tool.

Using composer init command

The composer tools store a list of dependencies of our project in a special file called composor.json. The composer init command provides an interactive wizard for creating a new composor.json file for our project. Let’s invoke this command in the project root directory to create our composor.json.

~/sites/my-app $ composer init

Welcome to the Composer config generator

This command will guide you through creating your composer.json config.

Package name (<vendor>/<name>) [kobi/my-app]: 

After a nice welcome message, you are asked to provide the full name of the new package

The the full package name is used to identify the package and it is composed from two parts - the vendor name and the the package name separated by /.

The vendor name – the first part of the full package name – should be a unique name to avoid name clashes. It can be your company name, your github name, a domain you owned and so on. The package name – the second part of the full package name – should be unique to the vendor and should give a hint what the package does.

The full package name has the same rule as the full name of a man. The full package name identifies the package among all the published packages, the same way the full name identifies the man among all the people. You can think that the vendor is the family name (or surname, last name) and the package name is the first name. As the family name associates the man to the family, the vendor name associates the package to the owner of the package (the vendor). As the first name identifies the man in the family, the package name identifies the package within all the packages published by the vendor.

Let’s say that our vendor name is demo and our package is my-app. Therefore we should write demo/my-app.

...
Package name (<vendor>/<name>) [kobi/my-app]: demo/my-app
Description []:

Now you are asked for description of the package. let’s write:

...
Description []: A simple demo how to use composer
Author [, n to skip]: 

Now you are asked to provide the author of the package.

The format should be “Author name <Author email>". If your project is already under git repository - your name should be displayed as default.

...
Author [, n to skip]: kobi <kobi@kistabug.com>
Minimum Stability:

Now you are asked to provide the minimum stability. This can be one of the values:

The values in the above list are in descending order. In other words, stable is the highest stability and dev is lowest.

For example, If we choose beta , the version of the matched packages by composer for this project have the stability : beta, RC and stable, while packages with alpha and dev will not be matched.

Let’s select stable for this project.

...
Minimum Stability: stable
Package Type (e.g. library, project, metapackage, composer-plugin) []:

Now you are asked to provide the package type. For this demo, we will use project.

...
Package Type (e.g. library, project, metapackage, composer-plugin) []: project
License []: 

Now you are asked to provide the license. For this demo, we will use MIT.

License []: MIT

Define your dependencies.

Would you like to define your dependencies (require) interactively [yes]?

Now, you can add the dependencies - The 3rd libraries your project depends on. Press enter to add or require the dependencies of the current project.

...
Would you like to define your dependencies (require) interactively [yes]?
Search for a package:

As we want to use the monolog library, we search for monolog.

...
Search for a package: monolog

Found 15 packages matching monolog

   [0] monolog/monolog 
   [1] symfony/monolog-bundle 
   [2] symfony/monolog-bridge 
   [3] easycorp/easy-log-handler Abandoned. Use  instead.
   [4] bramus/monolog-colored-line-formatter 
   [5] maxbanton/cwh 
   [6] wazaari/monolog-mysql 
   [7] theorchard/monolog-cascade 
   [8] flynsarmy/slim-monolog 
   [9] tylercd100/lern 
  [10] inpsyde/wonolog 
  [11] rahimi/monolog-telegram 
  [12] mero/yii2-monolog 
  [13] markhilton/monolog-mysql 
  [14] logentries/logentries-monolog-handle  
  
  Enter package # to add, or the complete package name if it is not listed:

The wizard displays all the packages where the string monolog appears in their full package name. Since we want monolog/monolog, let’s type 0. you can also write the full package name monolog/monolog.

...
Enter package # to add, or the complete package name if it is not listed: 0
Enter the version constraint to require (or leave blank to use the latest version):

Now you are asked to provide version constraint. You can find detailed syntax at version constraint. Let’s write 1.0.*

...
Enter the version constraint to require (or leave blank to use the latest version): 1.0.*
Search for a package: 

Now you can add other packages, in the same way you added the monolog/monolog package. leave empty and press enter to move to the next step.

...
Enter the version constraint to require (or leave blank to use the latest version): 1.0.*
Search for a package: 
Would you like to define your dev dependencies (require-dev) interactively [yes]?

Now, you can add development packages. Development packages are packages that are only required when you develop the package or the application. In other words, those packages are not used on production. Example for development packages can be unit testing libraries. For this project we skip this step by answering no

Would you like to define your dev dependencies (require-dev) interactively [yes]? no

{
  "name": "demo/my-app",
  "description": "A simple demo how to use composer",
  "type": "project",
  "require": {
      "monolog/monolog": "1.0.*"
  },
  "license": "MIT",
  "authors": [
      {
          "name": "kobi",
          "email": "kobi@kistabug.com"
      }
  ],
  "minimum-stability": "stable"
}

Do you confirm generation [yes]? 

Now. the wizard displays the contents of composer.json. If you are satisfied with the result, press Enter to save thecomposer.json

Do you confirm generation [yes]? 
Would you like the vendor directory added to your .gitignore [yes]?

Now, the wizard asks whether you want that git ignore the changes made in the vendor directory.

The vendor directory is where the 3td packages are installed. Adding the vendor directory to .gitignore notify git that the directory and files inside it should not be tracked for changes.

You probably want to answer yes to this question as the 3rd libraries are external and only used by your project. press enter

...
Would you like the vendor directory added to your .gitignore [yes]?
Would you like to install dependencies now [yes]?

Now, you are asked whether to install dependencies now. Select no - we install the dependencies later.

Would you like to install dependencies now [yes]? no
~/sites/my-app $

Now the wizard has finished to generate the composer.json file.

Let’s see the generated files.

my-app
my-app/
├── .gitignore
├── composer.json
└── index.php
.gitignore
/vendor/
composer.json
{
    "name": "demo/my-app",
    "description": "A simple demo how to use composer",
    "type": "project",
    "require": {
        "monolog/monolog": "1.0.*"
    },
    "license": "MIT",
    "authors": [
        {
            "name": "kobi",
            "email": "kobi@kistabug.com"
        }
    ],
    "minimum-stability": "stable"
}

The new composer.json is now part of source code and should be added to the project git repository. You should also commit the modified (or the new) .gitignore - This tells git to ignore the vendor directory which contains the downloaded 3rd libraries.

Would you like to install dependencies now [yes]? no
~/sites/my-app$ git add composer.json .gitignore
~/sites/my-app$  

In the next part we see how to install the project dependencies with composer.

Install dependencies with composer

How to install dependencies with composer