Composer, the dependency management tool for PHP, allows you to easily install or update 3rd PHP libraries required by your project. In this tutorial, we see how to use composer to download and use 3rd libraries.
The Existing PHP 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.
Composer init command: A simple wizard to create the composer.json
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.
1. Invoking the Composer init
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]:
2. Provide Package Meta Details [What Is Your Vendor, Package , Description and Author]
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@napuzba.com>
Minimum Stability:
3. Provide the minimum stability
Now you are asked to provide the minimum stability. This can be one of the values:
- stable
- RC
- beta
- alpha
- dev
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) []:
4. Provide the package type
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 []:
5. Provide the 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]?
6. Provide the the 3rd PHP Libraries
Now, you can add the dependencies – The 3rd PHP 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]?
7. Provide the 3rd development libraries
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 as we do not need 3rd PHP libraries for development.
Would you like to define your dev dependencies (require-dev) interactively [yes]? no8. Review The Generated composer.json
Now. the wizard displays the contents of composer.json. If you are satisfied with the result, press Enter to save the 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@napuzba.com"
}
],
"minimum-stability": "stable"
}
Do you confirm generation [yes]?
9. Ignore the vendor directory?
Now, the wizard asks whether you want that git ignore the changes made in the vendor directory.
The vendor directory is where the 3rd 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
Do you confirm generation [yes]?
Would you like the vendor directory added to your .gitignore [yes]?
10. Install the dependencies?
Now, you are asked whether to install dependencies now. Select no – we install the dependencies later.
...
Would you like the vendor directory added to your .gitignore [yes]?
Would you like to install dependencies now [yes]?
~/sites/my-app $
Now the wizard has finished to generate the composer.json file.
Generated Files Of Composer init Command
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$ Summary
We see how to generate composer.json file with composer init command. This file is contains all 3rd PHP libraries to your project depend on. In the next part we see how to composer to download those 3rd PHP libraries to the vendor directory and how can we require those 3rd PHP libraries in our project code.