summaryrefslogtreecommitdiffhomepage
path: root/php-composer.html.markdown
blob: 16fed5823b6072bfa86ebd8d93543d4450f9b410 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
---
category: tool
tool: composer
contributors:
    - ["Brett Taylor", "https://github.com/glutnix"]
filename: LearnComposer.sh
---

[Composer](https://getcomposer.org/) is a tool for dependency management in PHP. It allows you to declare the libraries your project depends on and it will manage (install/update) them for you.

# Installing

```sh
# Installs the composer.phar binary into the current directory
curl -sS https://getcomposer.org/installer | php
# If you use this approach, you will need to invoke composer like this:
php composer.phar about

# Installs the binary into ~/bin/composer
# Note: make sure ~/bin is in your shell's PATH environment variable
curl -sS https://getcomposer.org/installer | php -- --install-dir=~/bin --filename=composer
```

Windows users should follow the [Windows installation instructions](https://getcomposer.org/doc/00-intro.md#installation-windows)

## Confirming installation

```sh
# Check version and list options
composer

# Get more help for options
composer help require

# Check if Composer is able to do the things it needs, and if it's up to date
composer diagnose
composer diag # shorthand

# Updates the Composer binary to the latest version
composer self-update
composer self # shorthand
```

# Usage

Composer stores your project dependencies in `composer.json`. You can edit this file, but it is best to let Composer manage it for you.

```sh
# Create a new project in the current folder
composer init
# runs an interactive questionnaire asking you for details about your project.  Leaving them blank is fine unless you are making other projects dependent on this one.

# If a composer.json file already exists, download the dependencies
composer install

# To download the just the production dependencies, i.e. excluding development dependencies
composer install --no-dev

# Add a production dependency to this project
composer require guzzlehttp/guzzle
# will figure out what the latest version of guzzlehttp/guzzle is, download it, and add the new dependency to composer.json's require field.

composer require guzzlehttp/guzzle:6.0.*
# will download the latest version matching the pattern (eg. 6.0.2) and add the dependency to composer.json's require field

composer require --dev phpunit/phpunit:~4.5.0
# will require as a development dependency. Will use the latest version >=4.5.0 and < 4.6.0

composer require-dev phpunit/phpunit:^4.5.0
# will require as a development dependency. Will use the latest version >=4.5.0 and < 5.0

# For more information on Composer version matching, see [Composer's documentation on Versions](https://getcomposer.org/doc/articles/versions.md) for more details

# To see what packages are available to install and currently installed
composer show

# To see what packages are currently installed
composer show --installed

# To find a package with 'mailgun' in its name or description
composer search mailgun
```

[Packagist.org](https://packagist.org/) is the main repository for Composer packages. Search there for existing third-party packages.

## `composer.json` vs `composer.lock`

The `composer.json` file stores your project's floating version preferences for each dependency, along with other information.

The `composer.lock` file stores exactly which version it has downloaded for each dependency. Never edit this file.

If you include the `composer.lock` file in your git repository, every developer will install the currently used version of the dependency. Even when a new version of a dependency is released, Composer will continue to download the version recorded in the lock file.

```sh
# If you want to update all the dependencies to their newest version still matching your version preferences
composer update

# If you want the new version of a particular dependency:
composer update phpunit/phpunit

# If you wish to migrate a package to a newer version preference, you may need to remove the older package and its dependencies first.
composer remove --dev phpunit/phpunit
composer require --dev phpunit/phpunit:^5.0

```

## Autoloader

Composer creates an autoloader class you can require from your application. You can make instances of classes via their namespace.

```php
require __DIR__ . '/vendor/autoload.php';

$mailgun = new Mailgun\Mailgun("key");
```

### PSR-4 Autoloader

You can add your own namespaces to the autoloader.

In `composer.json`, add a 'autoload' field:

```json
{
  "autoload": {
    "psr-4": {"Acme\\": "src/"}
  }
}
```
This will tell the autoloader to look for anything in the `\Acme\` namespace within the `src` folder.

You can also [use PSR-0, a Classmap or just a list of files to include](https://getcomposer.org/doc/04-schema.md#autoload). There is also the `autoload-dev` field for development-only namespaces.

When adding or modifying the autoload key, you will need to rebuild the autoloader:

```sh
composer dump-autoload
composer dump # shorthand

# Optimizes PSR0 and PSR4 packages to be loaded with classmaps too. Slow to run, but improves performance on production.
composer dump-autoload --optimize --no-dev
```

# Composer's Cache

```sh
# Composer will retain downloaded packages to use in the future. Clear it with:
composer clear-cache
```

# Troubleshooting

```sh
composer diagnose
composer self-update
composer clear-cache
```

## Topics not (yet) covered in this tutorial

* Creating and distributing your own packages on Packagist.org or elsewhere
* Pre- and post- script hooks: run tasks when certain composer events take place

### References

* [Composer - Dependency Manager for PHP](https://getcomposer.org/)
* [Packagist.org](https://packagist.org/)