Mastering Composer: Tips and Tricks for Using

I propose to readers of Habrakhabr a translation of the article “Mastering Composer - Tips and Tricks” by Bruno Skvorc.



Composer revolutionized package management in PHP and helped developers around the world create framework-independent and shared code. But still few people go beyond the basics of its functionality, so this article will try to highlight some useful techniques for its use.

Global Setup (Global)

Although this option is available described in the documentation, Composer can (and in most cases should) be set globally. Global installation means that instead of:
')

php composer.phar somecommand 

In any project you can simply enter:

 composer somecommand 

This makes it very easy to create new projects (for example, using the create-project command) anywhere in your file system.

To install Composer globally, follow these instructions .

Correct installation of dependencies

When reading introductory instructions or README files, many will write you something like:

Just add the following to your composer.json file :

 {
     "require": {
         "myproject": "someversion"
     }
 }

But this approach has several drawbacks. First, a simple copy-paste can lead to errors. Secondly, for a newbie, it may not be obvious where to put this code if it already has an extensive composer.json file, and this also leads to an error. Finally, some people will deal with Composer for the first time, and possibly face the command line for the first time. Therefore, it will be good practice to cover all kinds of cases in which beginners may feel insecure (do they have a graphic editor or will they use the command line? If the second is, does the text editor are installed in it, and if so, which one? Do you explain file editing procedure? What if the composer.json file does not yet exist in the project? Do you also describe the principle of creating a new file?).

The best way to add a new dependency to the composer.json file is to use the require command:

 composer require somepackage/somepackage:someversion 

This will add everything you need to the dependency file, bypassing manual intervention.

If you need to add packages to the require-dev section, add the --dev option to the command :

 composer require phpunit/phpunit --dev 

Also, the require command supports adding multiple packages at the same time; to do this, simply separate them with a space.

Lock files

The composer.lock file saves the current list of installed dependencies and their versions. Thus, at the time when the dependency versions are already updated, other people who will clone your project will receive the same versions. This allows you to make sure that everyone who gets your project has a “batch environment” identical to the one you used during development, and helps to avoid errors that might arise from updating versions.

The file composer.lock should almost always be added to the version control system ( not always ).

Also, the composer.lock file contains the hash of the composer.json file, so if you even just update the data about the author of the project, you will receive a warning that the lock file does not correspond to the .json file. In this case, the composer update --lock command will help, which will update only the lock file itself, without touching anything else.

Versioning

When specifying acceptable package versions, you can use exact matching ( 1.2.3 ), ranges with comparison operators ( <1.2.3 ), combinations of these operators ( > 1.2.3 <1.3 ), “last available” ( 1.2. * ), Tilde symbol ( ~ 1.2.3 ) and the caret ( ^ 1.2.3 ).

The last two instructions are worthy of a separate explanation:

• tilde indication ( ~ 1.2.3 ) will include all versions up to 1.3 (not inclusive), as in semantic versioning this is the moment of introducing new functionality. In this case, the last of the stable minor versions will be obtained. According to the documentation, with this indication only the last digit of the version can change.
• the insertion mark ( ^ 1.2.3 ) literally means “to fear only critical changes” and will include versions up to 2.0 . With regard to semver, changing the major version is the moment of making critical changes in the project, so versions 1.3 , 1.4 and 1.9 are suitable, while 2.0 is no longer.

Except when you know that you need a specific version of a package, I recommend always using ~ 1.2.3 format - this is the safest choice.

Local and global configuration

The default parameter values ​​are not set in stone. A detailed description of the possible configuration parameters ( config ), see the link .

For example, specifying:

 {
     "config": {
         "optimize-autoloader": true
     }
 }

you force Composer to optimize the classmap after each installation or update of packages (or, in other words, whenever a class autoload file is generated). This is a bit slower than creating a default autoloader, and slows as the project grows.

Another useful parameter might be cache-files-maxsize . In large projects (like eZ Publish or Symfony), the cache can fill up pretty quickly. Increasing the size of the cache to allow Composer to work quickly longer.

Please note that the configuration parameters can be set globally, and in this case will affect all projects (see config ). For example, to globally set the cache size parameter, you must either edit the file ~ / .composer / config.json , or run:

 composer config --global cache-files-maxsize "2048MiB" 

Profiling and verbose output (verbose)

If you add the --profile parameter to any command when using Composer on the command line, the output will contain not only the final result, for example:

 [174.6MB/54.70s] Memory usage: 174.58MB (peak: 513.47MB), time: 54.7s 

But also at the beginning of each line of output the command execution time and the used memory size will be added:

 [175.9MB/54.64s] Installing assets for Sensio\Bundle\DistributionBundle into web/bundles/sensiodistribution 

I use this option to define “slow” packages and to monitor the improvement or degradation of performance on different versions of PHP .

Like the previous one, the --verbose option will cause Composer to display more information about each operation being performed, letting you know exactly what is happening at the moment. Some people even install composer --verbose --profile with the default alias of the composer command.

Custom sources

If your project is not yet on Packagist, sometimes you just need to install the package from GitHub (for example, if the package is still under development). For this see our guide .

When you have your own version of a popular package on which your project depends, you can use custom sources in conjunction with contextual pseudonyms (inline aliasing) to substitute your own branch for a public package, as described here by Matthieu Napoli.

Acceleration Composer

Using the excellent method described by Mark Van Eijk , you can speed up Composer execution by calling it through HHVM.

Another way is by using the --prefer-dist option, when installed, Composer will download stable, packed versions of the project, instead of cloning from the version control system (which is much slower). This parameter is used by default, so you do not need to enable it on stable projects. If you need to load a project from source, use the --prefer-source parameter. For more information, see the install section here .

Reducing the size of the Composer project

If you are a developer of “Composer-friendly” projects, this part will also interest you. On this post in Reddit , you can use the .gitattributes file to ignore some files and folders while packing the package for the --prefer-dist mode.

 / docs export-ignore
 / tests export-ignore
 /.gitattributes export-ignore
 /.gitignore export-ignore
 /.travis.yml export-ignore
 /phpunit.xml export-ignore

How it works? When you upload a project to GitHub, it automatically makes available the “Download zip” link, with which you can download your project archive. Moreover, Packagist uses these automatically generated archives to download dependencies with the --prefer-dist option, which it then locally unzips (much faster than cloning project source files). If you add tests, documentation and other files that are not related to the logic of the project, the specified archives will not contain them, becoming much easier.

In this case, people who want to debug your library or run tests will need to specify the parameter --prefer-source .

PhpLeague took this approach and included it in its “package skeleton ”, so any project based on it would automatically be “dist friendly” .

Show

If you suddenly forget which version of PHP or its extensions you are using, or you need a list of all installed projects (with a description of each) with their versions, you can use the show command with the --platform ( -p ) and --installed ( -i ) options ):

Rehearsals (Dry Runs)

To simply see if the installation of new dependencies will succeed, you can use the --dry-run option for the install and update commands. Composer in this case will display all potential problems without directly executing the command itself. There will be no real changes in the project. This technique is great for testing complex dependencies and setting up changes before actually making them.

 composer update --dry-run --profile --verbose 

Project creation

Last but not least, what we have to mention is the create-project command .

The project creation command takes as its argument the name of the package, which it then clones and executes composer install inside it. This is great for project initialization - you no longer need to search for the Url of the required package on GitHub, clone it, go to the folder yourself, and execute the install command.

Major projects such as Symfony and Laravel already use this approach to initialize their “skeleton” applications, and many others are also joining.

For example, in Laravel it is used as follows:

 composer create-project laravel/laravel --prefer-dist --profile --verbose 

Two more parameters can be passed to the create-project command: the path to which the project should be installed (if not specified, the package name is used), and the version (the latter will be used if not specified).

Conclusion

I hope this list of tips and tricks of use has been useful to you. If we have missed something, tell us about it and we will update the article. And remember, if you forget any commands or options, just look at the cheat sheet . Happy Composing!