Managing Dependencies with Composer (TrueNorthPHP 2015)

Traditionally, managing third-party code in PHP projects has not been a trivial task. Fortunately, the PHP community now has Composer, a top-notch dependency manager. Learn what Composer is and how you can put it to work for fun and profit. You will see how to set up a new project, find packages, as well as how to create and distribute your own packages.

Transcript

1. Managing Dependencies with Composer TrueNorthPHP November 4th, 2015 @beausimensen beau.io joind.in/15738 Tutorial Project: http://git.io/vTZnZ
3. Tutorial
4. Wi-Fi & PHP>=5.4 & GitHub required if you want to play
5. GitHub API Rate Limits :(
6. https://github.com/settings/tokens
7. $ composer config -g github-oauth.github.com <oauthtoken> Bypasses GitHub API rate limit problems by ensuring Composer will always make GitHub calls authenticated as your GitHub user.
8. $ cat ~/.composer/auth.json Contains your GitHub OAuth Token.
9. $ composer show [pkg] shows information about a package
10. $ composer show silex/silex shows information about Silex
11. Dependency Management
12. composer.json
13. { “name”: “acme/my-project”, “description”: “Acme’s My Project”, “license”: “MIT”, “require”: { “silex/silex”: “1.1.*” }, “autoload”: { “psr-4”: { “Acme\\MyProject\\”: “src” } } }
14. { “name”: “acme/my-project”, “description”: “Acme’s My Project”, “license”: “MIT”, “require”: { “silex/silex”: “1.1.*” }, “autoload”: { “psr-4”: { “Acme\\MyProject\\”: “src” } } }
15. vendor-name/project-name A package's name cannot change and must be all lowercase
16. http://www.spdx.org/licenses/ Publishing to Packagist requires you choose a license!
17. { “name”: “acme/my-project”, “description”: “Acme’s My Project”, “license”: “MIT”, “require”: { “silex/silex”: “1.1.*” }, “autoload”: { “psr-4”: { “Acme\\MyProject\\”: “src” } } }
18. { “name”: “acme/my-project”, “description”: “Acme’s My Project”, “license”: “MIT”, “require”: { “silex/silex”: “1.1.*” }, “autoload”: { “psr-4”: { “Acme\\MyProject\\”: “src” } } }
19. $ composer install Loading composer repositories with package information Installing dependencies (including require-dev) - Installing psr/log (1.0.0) - Installing symfony/routing (v2.3.7) - Installing symfony/debug (v2.3.7) - Installing symfony/http-foundation (v2.3.7) - Installing symfony/event-dispatcher (v2.3.7) - Installing symfony/http-kernel (v2.3.7) - Installing pimple/pimple (v1.1.0) - Installing silex/silex (v1.1.2) Writing lock file Generating autoload files $
20. The packages are installed into a directory named vendor
21. vendor =
22. require “vendor/autoload.php”;
23. Basic Usage
24. Install Composer getcomposer.org/download
25. $ curl -sS https://getcomposer.org/installer | php $ php composer.phar --version WARNING Security people think this is bad (but it is all the rage)
26. $ chmod 755 composer.phar $ mv composer.phar ~/bin/composer $ composer --version
27. composer.json and composer.lock
28. composer.json describes a package and its dependencies
29. { “name”: “acme/my-project”, “description”: “Acme’s My Project”, “license”: “MIT”, “require”: { “silex/silex”: “1.1.*” }, “autoload”: { “psr-4”: { “Acme\\MyProject\\”: “src” } } }
30. composer.lock describes exactly what should be installed
31. $ composer install Loading composer repositories with package information Installing dependencies (including require-dev) - Installing psr/log (1.0.0) - Installing symfony/routing (v2.3.7) - Installing symfony/debug (v2.3.7) - Installing symfony/http-foundation (v2.3.7) - Installing symfony/event-dispatcher (v2.3.7) - Installing symfony/http-kernel (v2.3.7) - Installing pimple/pimple (v1.1.0) - Installing silex/silex (v1.1.2) Writing lock file Generating autoload files $
32. Check your composer.lock into your repository
33. Common Commands
34. $ composer install If composer.lock exists, install exactly what is in the lock file. Otherwise, read composer.json to find out what should be installed, install the dependencies, and write out composer.lock.
35. $ composer update Installs dependencies from composer.json and creates or updates composer.lock.
36. $ composer require [pkg] Add a package to composer.json. The [pkg] is the name with a version constraint. foo/bar or foo/bar:1.0.0 or foo/bar=1.0.0 or "foo/bar 1.0.0"
37. $ composer require [pkg] Recommend way to add Composer packages to your project! composer require foo/bar
39. $ composer require --dev [pkg] Add a package as a dev requirement composer require --dev foo/bar
40. $ composer validate Check composer.json for common errors
41. $ composer diag Check environment and composer.json for common errors
42. $ composer show [pkg] shows information about a package
43. $ composer show --self shows information about THIS package
44. $ composer clearcache Because sometimes things get stale.
45. Vendor Tour
46. vendor =
47. { “name”: “acme/my-project”, “description”: “Acme’s My Project”, “license”: “MIT”, “require”: { “silex/silex”: “1.1.*” }, “autoload”: { “psr-4”: { “Acme\\MyProject\\”: “src” } } }
48. Autoloading
49. # Acme\User is not defined $user = new Acme\User(); # Acme\User is defined
50. Magic! since 5
51. function ($class) { if ($class === "Acme\\Account\\User") { // do something to cause this class // to become defined require __DIR__."/src/user.inc"; } }
52. Composer is a configurable autoloader
53. Each Composer package gets to configure its own rules
54. psr-0
55. PHP-FIG PHP Framework Interoperability Group php-fig.com
56. Namespaces are directories
57. Classes are files with .php suffix
58. Acme\Account\User
59. Acme/Account/User.php
60. PSR-0 also supports legacy PEAR style naming conventions
61. Acme\Account\User Acme_Account_User
62. Acme/Account/User.php Acme/Account/User.php
63. { "autoload": { "psr-0": { "Acme\\Account\\": "src" } } } new Acme\Account\User(); # src/Acme/Account/User.php
64. { "autoload": { "psr-0": { "Acme_Account_": "src" } } } new Acme_Account_User(); # src/Acme/Account/User.php
65. psr-4
66. PHP-FIG PHP Framework Interoperability Group php-fig.com
67. Composer currently recommends new projects use PSR-4
68. Very similar to PSR-0
69. Only supports namespaces (this means no PEAR style naming)
70. Requires a namespace prefix and base directory for mapping
71. Acme\Account\User (class) Acme\Account (namespace prefix) src (base directory) src/User.php (resulting file path)
72. { "autoload": { "psr-4": { "Acme\\Account\\": "src" } } } new Acme\Account\User(); # src/User.php
73. Migrating from PSR-0 to PSR-4
74. { "autoload": { "psr-0": { "Acme\\Account\\": "src" } } } new Acme\Account\User(); # src/Acme/Account/User.php
75. { "autoload": { "psr-4": { "Acme\\Account\\": "src/Acme/Account" } } } new Acme\Account\User(); # src/Acme/Account/User.php
76. files
77. Explicitly include specific files
78. { “autoload”: { “files”: [ “src/foo.class.php”, “src/bar.class.php” ] } }
79. { “autoload”: { “files”: [“src/functions.php”] } }
80. { “autoload”: { “files”: [“src/autoload.php”] } }
81. The files autoloader is really an alwaysloader
82. classmap
83. A key => value map of class names to files on disk
84. { “autoload”: { “classmap”: [ “src/includes/”, “resources/config.php” ] } }
85. It will look inside .php and .inc files to find classes
86. The classmap is generated anytime Composer dumps its autoloader
87. Extremely fast and powerful but not very developer friendly
88. { “name”: “acme/my-project”, “description”: “Acme’s My Project”, “license”: “MIT”, “require”: { “silex/silex”: “1.1.*” }, “autoload”: { “psr-4”: { “Acme\\MyProject\\”: “src” } } }
89. { “name”: “acme/my-project”, “description”: “Acme’s My Project”, “license”: “MIT”, “require”: { “silex/silex”: “1.1.*” }, “autoload”: { “psr-4”: { “Acme\\MyProject\\”: “src” } } }
90. Semantic Versioning
91. semver.org
92. MAJOR.MINOR.PATCH Which number do you increment and why?
93. MAJOR.MINOR.PATCH When you break backwards compatibility
94. MAJOR.MINOR.PATCH When you add backwards compatible features
95. MAJOR.MINOR.PATCH When you make backwards compatible bug fixes
96. Pre-Release Identifiers
97. 1.0.0-alpha 1.0.0-beta.2 1.0.0-RC3
98. Stability Pre-Release Identifiers
99. Version Constraints
100. Exact Version 1.0.2
101. Ranges >=1.0,<2.0
102. Wildcards 1.0.*
103. Next Significant Release Tilde and Caret Operators
104. Next Significant Release ~1.2 Minimum allowed version and only the last number listed can increase.
105. Next Significant Release ~1.2 >=1.2,<2
106. Next Significant Release ~1.2.3 >=1.2.3,<1.3
107. Next Significant Release ^1.2 Minimum allowed version and up to next major release.
108. Next Significant Release ^1.2 >=1.2,<2
109. Next Significant Release ^1.2.3 >=1.2.3,<2
110. Next Significant Release ^0.2 Safer handling for pre-1.0 versions.
111. Next Significant Release ^0.2 >=0.2,<0.3
112. Next Significant Release ^0.2.3 >=0.2.3,<0.3
113. Semantic Versioning lets you know what you are getting into
114. Safe 1.3.* Only get bug fixes
115. Reasonably Safe 1.* Get bug fixes and new features
116. Nope. * Composer allows this, but don't. Just don't.
117. Version Constraint Considerations
118. –Semantic Versioning “If the dependency specifications are too tight, you are in danger of version lock (the inability to upgrade a package without having to release new versions of every dependent package).”
119. Libraries should generally have more permissive constraints
120. –Semantic Versioning “If dependencies are specified too loosely, you will inevitably be bitten by version promiscuity (assuming compatibility with more future versions than is reasonable).”
121. End projects may want to have more restrictive constraints
122. Deep Dependency Resolution
123. { “name”: “silex/silex”, “require”: { “pimple/pimple”: “1.*” } } 1.1.0 1.1.0 1.1.1 1.0.2 1.0.1 1.0.0 2.0.0 Silex Pimple 0.0.1
124. { “name”: “silex/silex”, “require”: { “pimple/pimple”: “1.*” } } { “name”: “dflydev/doctrine-orm-service-provider”, “require”: { “pimple/pimple”: “~1.1”, “doctrine/orm”: “~2.3” } } 1.1.0 1.1.0 1.1.1 1.0.2 1.0.1 1.0.0 2.0.0 Silex Pimple 0.0.1 2.3.2 2.4.0 2.3.1 2.3.0 2.2.1 2.5.0 ORM 2.2.0 1.0.0 dflydev
125. { “name”: “acme/myapp”, “require”: { “dflydev/doctrine-orm-service-provider”: “1.0.*”, “silex/silex”: “1.1.*”, “pimple/pimple”: “~1.1.1”, “doctrine/orm”: “2.4.*” } } { “name”: “silex/silex”, “require”: { “pimple/pimple”: “1.*” } } { “name”: “dflydev/doctrine-orm-service-provider”, “require”: { “pimple/pimple”: “~1.1”, “doctrine/orm”: “~2.3” } } 1.1.0 1.1.0 1.1.1 1.0.2 1.0.1 1.0.0 2.0.0 Silex Pimple 0.0.1 2.3.2 2.4.0 2.3.1 2.3.0 2.2.1 2.5.0 ORM 2.2.0 1.0.0 dflydev 1.0.0 myapp
126. Conflicts
127. { "require": { "silex/silex": "1.1.*", "pimple/pimple": "2.0.*@dev" } }
128. $ composer install Loading composer repositories with package information Installing dependencies (including require-dev) Your requirements could not be resolved to an installable set of packages. Problem 1 - silex/silex v1.1.0 requires pimple/pimple 1.* -> satisfiable by pimple/pimple[1.0.0, 1.1.x-dev, v1.0.1, v1.0.2, v1.1.0]. - silex/silex v1.1.1 requires pimple/pimple 1.* -> satisfiable by pimple/pimple[1.0.0, 1.1.x-dev, v1.0.1, v1.0.2, v1.1.0]. - silex/silex v1.1.2 requires pimple/pimple ~1.0 -> satisfiable by pimple/pimple[1.0.0, 1.1.x-dev, v1.0.1, v1.0.2, v1.1.0]. - Can only install one of: pimple/pimple[2.0.x-dev, 1.0.0]. - Can only install one of: pimple/pimple[2.0.x-dev, 1.1.x-dev]. - Can only install one of: pimple/pimple[v1.0.1, 2.0.x-dev]. - Can only install one of: pimple/pimple[v1.0.2, 2.0.x-dev]. - Can only install one of: pimple/pimple[v1.1.0, 2.0.x-dev]. - Installation request for pimple/pimple 2.0.*@dev -> satisfiable by pimple/pimple[2.0.x-dev]. - Installation request for silex/silex 1.1.* -> satisfiable by silex/silex[v1.1.0, v1.1.1, v1.1.2]. Potential causes: - A typo in the package name - The package is not available in a stable-enough version according to your minimum-stability setting.
129. Versions from Tags
130. 2.0.1 2.0.1 (2.0.*)
131. v2.0.1 2.0.1 (2.0.*)
132. 2.0.1-RC1 2.0.1-RC1 (2.0.*@RC)
133. 3.4-cuddly-cat 3.4-cuddly-cat (3.4-cuddly-cat)
134. 2.0.1g 2.0.1g (2.0.1g)
135. Versions from Branches
136. Branches are considered @dev stability
137. Numbered branches are easy
138. 2.0 2.0.x-dev (2.0.*@dev)
139. Named branches default to their name with a dev- prefix
140. master dev-master (dev-master)
141. 2.0-experimental dev-2.0-experimental (2.0.*@dev won't work!)
142. Named branches can be aliased to be semver friendly
143. { “extra”: { “branch-alias”: { “dev-master”: “2.0.x-dev” } } }
144. master dev-master / 2.0.x-dev (dev-master or 2.0.*@dev)
145. Create a branch alias as soon as you start a new Composer package
146. (future you and your users will thank you)
147. Requiring non-stable versions
148. { “require”: { “symfony/yaml”: “3.5-cat”, “silex/silex”: “1.1@dev”, “pimple/pimple”: “dev-master”, “sculpin/core”: “2.0.*@beta” } }
149. { “require”: { “symfony/yaml”: “3.5-cat”, “silex/silex”: “1.1@dev”, “pimple/pimple”: “dev-master”, “sculpin/core”: “2.0.*@beta” } }
150. requiring dev-master considered harmful
151. Pretend dev-master doesn't exist
152. Send pull requests when you find a package that offers dev-master without a branch alias
153. { “name”: “acme/myapp” }
154. { “name”: “acme/myapp”, “require”: { “naughty/id-generator”: “1.0.*” } } { “name”: “naughty/id-generator”, “require”: { “ircmaxell/random-lib”: “dev-master” } }
155. { “name”: “acme/myapp”, “require”: { “naughty/id-generator”: “1.0.*”, “ircmaxell/random-lib”: “@dev” } } { “name”: “naughty/id-generator”, “require”: { “ircmaxell/random-lib”: “dev-master” } }
156. { “name”: “acme/myapp”, “require”: { “naughty/id-generator”: “1.0.*”, “ircmaxell/random-lib”: “dev-master” } } { “name”: “naughty/id-generator”, “require”: { “ircmaxell/random-lib”: “dev-master” } }
157. { “name”: “acme/myapp”, “require”: { “naughty/id-generator”: “1.0.*”, "dflydev/hawk": "1.0.*", "ircmaxell/random-lib": "dev-master" } } { “name”: “naughty/id-generator”, “require”: { “ircmaxell/random-lib”: “dev-master” } } { “name”: “dflydev/hawk”, “require”: { “ircmaxell/random-lib”: “~1.0@dev” } }
158. { “name”: “acme/myapp”, “require”: { “naughty/id-generator”: "1.0.*”, "dflydev/hawk": "1.0.*", "ircmaxell/random-lib": "dev-master" } } { “name”: “naughty/id-generator”, “require”: { “ircmaxell/random-lib”: “dev-master” } } { “name”: “dflydev/hawk”, “require”: { “ircmaxell/random-lib”: “~1.0@dev” } } 1.0.x-dev != dev-master
159. { “name”: “acme/myapp”, “require”: { “naughty/id-generator”: “1.0.*”, "dflydev/hawk": "1.0.*", "ircmaxell/random-lib": "@dev" } } { “name”: “naughty/id-generator”, “require”: { “ircmaxell/random-lib”: “~1.0@dev” } } { “name”: “dflydev/hawk”, “require”: { “ircmaxell/random-lib”: “~1.0@dev” } } Time to send a pull request!
160. dev-master is viral
161. Once people start using dev-master for your package it can be hard to break them of that habit
162. Send pull requests when you find a package that requires dev-master when a branch alias exists
163. –Michael Dowling “I'm working on a new version of Guzzle. If you're using composer: stop using dev-master. Use a tagged release. Especially in production.” https://twitter.com/mtdowling/status/440901351657054208
164. Stability
165. Root package
166. The root package is the package defined in the working composer.json
167. A package is the root package while it is being developed
168. The root package gets to control all aspects of stability
169. Minimum stability
170. Controlled by the root package
171. Defaults to stable
172. { “minimum-stability”: “alpha” }
173. Applied to all packages for which the root package doesn't specify a stability
174. Package-by-package stability
175. Stability can be controlled on a package-by-package basis
176. { “require”: { “silex/silex”: “~1.1@dev”, “symfony/http-foundation”: “@beta” }, “minimum-stability”: “alpha” }
177. Stability solver errors are fun
178. { "require": { "sculpin/sculpin": "2.0.*" } }
179. $ composer install Loading composer repositories with package information Installing dependencies (including require-dev) Your requirements could not be resolved to an installable set of packages. Problem 1 - The requested package sculpin/sculpin 2.0.* could not be found. Potential causes: - A typo in the package name - The package is not available in a stable-enough version according to your minimum-stability setting
180. $ composer install Loading composer repositories with package information Installing dependencies (including require-dev) Your requirements could not be resolved to an installable set of packages. Problem 1 - The requested package sculpin/sculpin 2.0.* could not be found. Potential causes: - A typo in the package name - The package is not available in a stable-enough version according to your minimum-stability setting
181. { "require": { "sculpin/sculpin": "2.0.*@dev" } }
182. { "require": { "sculpin/sculpin": "2.0.*" }, "minimum-stability": "dev" }
183. Root package stability implications
184. Even if your package requires a dependency @dev, users of your package won't get it unless they explicitly ask for it.
185. { “name”: “silex/silex”, “require”: { “pimple/pimple”: “1.*@dev” } } Root Package
186. { “name”: “silex/silex”, “require”: { “pimple/pimple”: “1.*@dev” } } { “name”: “dflydev/doctrine-orm-service-provider”, “require”: { “pimple/pimple”: “1.*@beta”, “silex/silex”: “1.1.*”, “doctrine/orm”: “~2.3” } } Root Package
187. { “require”: { “dflydev/doctrine-orm-service-provider”: “1.0.*”, “pimple/pimple”: “1.*@alpha” } } { “name”: “silex/silex”, “require”: { “pimple/pimple”: “1.*@dev” } } { “name”: “dflydev/doctrine-orm-service-provider”, “require”: { “pimple/pimple”: “1.*@beta”, “silex/silex”: “1.1.*”, “doctrine/orm”: “~2.3” } } Root Package
188. Dev Dependencies
189. dev dependencies can only be installed for the root package
190. Publishing and Discovery
191. packagist.org
192. Over 59,200 packages
193. Publishing is as easy as pasting your repository's GitHub URL
195. Check Packagist before you start a new library from scratch
196. Self Hosted Composer Repositories
197. Install Packagist Locally
198. Satis
199. Toran Proxy https://toranproxy.com/
200. [this page intentionally left blank]
201. Choose an autoloading strategy
202. Choose PSR-4 for new projects
203. Semantic Versioning lets you know what you're getting into
204. Libraries should generally have more permissive constraints
205. End projects may want to have more restrictive constraints
206. Create branch aliases
207. dev-master considered harmful
208. Use Packagist
209. #composer look for simensen and say "hi" freenode IRC
210. Questions? @beausimensen • @moniidev • @thatpodcast joind.in