Composer Usage Tips
Composer is a tool for dependency management in PHP. It allows you to declare the libraries your project depends on and it will install and update them for you. We will learn:
- how to install Composer
- use it in new or existing project
Composer is an executable
.phar file that you download and install as follows.
Use the official installer Composer-Setup.exe.
All you need is 4 commands, which you can copy from this page.
Further more, by copying into folder that is in system's
PATH, Composer becomes globally accessible:
$ mv ./composer.phar ~/bin/composer # or /usr/local/bin/composer
Use in Project
To start using Composer in your project, all you need is a
composer.json file. This file describes the
dependencies of your project and may contain other metadata as well. The simplest
composer.json can look
We're saying here, that our application (or library) depends on package
nette/database (the package name consists
of a vendor name and the project's name) and it wants the version that matches the
^3.0 version constraint.
So, when we have the
composer.json file in the project root and we run:
Composer will download the Nette Database into directory
vendor. It also creates a
file, which contains information about exactly which library versions it installed.
Composer generates a
vendor/autoload.php file. You can simply include this file and start using the classes that
those libraries provide without any extra work:
require __DIR__ . '/vendor/autoload.php';
$db = new Nette\Database\Connection('sqlite::memory:');
Update Packages to the Latest Versions
To update all used packages to the latest version according to version constraints defined in
composer update. For example for dependency
"nette/database": "^3.0" it will install the latest
version 3.x.x, but not version 4.
To update the version constrains in the
composer.json file to e.g.
"nette/database": "^4.1", to
enable to install the latest version, use the
composer require nette/database command.
To update all used Nette packages, it would be necessary to list them all on the command line, eg:
composer require nette/application nette/forms latte/latte tracy/tracy ...
Which is impractical. Therefore, use a simple script Composer Frontline that will do it for you:
Creating New Project
New Nette project can be created by executing a simple command:
composer create-project nette/web-project name-of-the-project
name-of-the-project you should provide the name of the directory for your project and execute the
command. Composer will fetch the
nette/web-project repository from GitHub, which already contains the
composer.json file, and right after that install the Nette Framework itself. The only thing which remains is to check write permissions on directories
log/ and you're ready to go.
If you know what version of PHP the project will be hosted on, be sure to set it up.
Composer always installs the versions of packages that are compatible with the version of PHP you are currently using (or
rather, the version of PHP used on the command line when you run Composer). Which is probably not the same version your web host
is using. That's why it's very important to add information about the PHP version on your hosting to your
composer.json file. After that, only versions of packages compatible with the host will be installed.
For example, to set the project to run on PHP 8.2.3, use the command:
composer config platform.php 8.2.3
This is how the version is written to the
However, the PHP version number is also listed elsewhere in the file, in the
require section. While the first
number specifies the version for which packages will be installed, the second number tells what version the application itself is
written for. (Of course, it doesn't make sense for these versions to be different, so double entry is a redundancy.) You set this
version with the command:
composer require php 8.2.3 --no-update
Or directly in the
Ignoring PHP Version
Packages typically specify both the lowest version of PHP with which they are compatible and the highest version with which
they have been tested. If you plan to use an even newer version of PHP, perhaps for testing purposes, Composer will refuse to
install such a package. The solution is to use the
--ignore-platform-req=php+ option, which causes Composer to ignore
the upper limits of the required PHP version.
When upgrading packages or changing version numbers, conflicts happen. One package has requirements that conflict with another
and so on. However, Composer occasionally prints a false messages. It reports a conflict that doesn't really exist. In this case,
it helps to delete the
composer.lock file and try again.
If the error message persists, then it is meant seriously and you need to read from it what to modify and how.
Packagist.org – Global Repository
Packagist is the main package repository, in which Composer tries to search packages, if not told otherwise. You can also publish your own packages here.
What If We Don’t Want the Central Repository
If we have internal applications or libraries in our company, which cannot be hosted publicly on Packagist, we can create our own repositories for those project.
More on repositories in the official documentation.
A key feature of Composer is that it provides autoloading for all classes it installs, which you start by including a file
However, it is also possible to use Composer to load other classes outside the folder
vendor. The first option is
to let Composer scan the defined folders and subfolders, find all the classes and include them in the autoloader. To do this, set
autoload > classmap in
"src/", # includes the src/ folder and its subfolders
Subsequently, it is necessary to run the command
composer dumpautoload with each change and let the autoloading
tables regenerate. This is extremely inconvenient, and it is far better to entrust this task to RobotLoader, which performs the same activity automatically in the background and
The second option is to follow PSR-4. Simply saying, it is a system where the
namespaces and class names correspond to the directory structure and file names, ie
located in the file
/path/to/App/Router/RouterFactory.php. Configuration example:
"App\\": "app/" # the App\ namespace is in the app/ directory
See Composer Documentation for exactly how to configure this behavior.
Testing New Versions
You want to test a new development version of a package. How to do it? First, add this pair of options to the
composer.json file, which will allow you to install development versions of packages, but will only do so if there is
no stable version combination that meets the requirements:
We also recommend deleting the
composer.lock file, because sometimes Composer incomprehensibly refuses to install
and this will solve the problem.
Let's say the package is
nette/utils and the new version is 4.0. You install it with the command:
composer require nette/utils:4.0.x-dev
Or you can install a specific version, for example 4.0.0-RC2:
composer require nette/utils:4.0.0-RC2
If another package depends on the library and is locked to an older version (e.g.
^3.1), it is ideal to update the
package to work with the new version. However, if you just want to get around the limitation and force Composer to install the
development version and pretend it is an older version (e.g., 3.1.6), you can use the
composer require nette/utils "4.0.x-dev as 3.1.6"
You can call your own custom commands and scripts through Composer as if they were native Composer commands. Scripts located in
vendor/bin folder do not need to specify this folder.
As an example, we define a script in the
composer.json file that uses Nette
Tester to run tests:
"tester": "tester tests -s"
We then run the tests with
composer tester. We can call the command even if we are not in the root folder of the
project, but in a subdirectory.
We will show you a trick that will make open source authors happy. You can easily give a star on GitHub to the libraries that
your project uses. Just install the
composer global require symfony/thanks
And then run:
Composer is closely integrated with version control tool Git. If you do not use Git, it is necessary to tell it to Composer:
composer -g config preferred-install dist