Managing Dependencies with Composer (php[world] 2014)

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 php[world] November 11th, 2014 @beausimensen beau.io joind.in/11908
3. Tutorial
4. Wi-Fi & PHP>=5.3.2 required if you want to play
5. Apache, nginx, other. PHP 5.4+ internal web server optional if you want to actually run the tutorial code (probably not a huge deal if you cannot!)
6. 1) SSID: composer-tutorial Password: phpworld getcomposer.composertut.local 2)
7. $ composer config home /home/username/.composer config.json: (this file is in the tutorial download) ! { "repositories": [ { "type": "composer", "url": "http://toran.composertut.local/repo/packagist/" }, { "packagist": false } ] }
8. $ composer config home /home/username/.composer config.json: (this file is in the tutorial download) ! { "repositories": [ { "type": "composer", "url": "http://toran.composertut.local/repo/packagist/" }, { "packagist": false } ] }
9. $ composer config home /home/username/.composer config.json: (this file is in the tutorial download) ! { "repositories": [ { "type": "composer", "url": "http://toran.composertut.local/repo/packagist/" }, { "packagist": false } ] }
10. $ composer show [pkg] shows information about a package
11. $ composer show silex/silex shows information about Silex
13. Dependency Management
14. composer.json
15. { “name”: “acme/my-project”, “description”: “Acme’s My Project”, “license”: “MIT”, “require”: { “silex/silex”: “1.1.*” }, “autoload”: { “psr-4”: { “Acme\\MyProject\\”: “src” } } }
16. { “name”: “acme/my-project”, “description”: “Acme’s My Project”, “license”: “MIT”, “require”: { “silex/silex”: “1.1.*” }, “autoload”: { “psr-4”: { “Acme\\MyProject\\”: “src” } } }
17. vendor-name/project-name A package's name cannot change and must be all lowercase
18. http://www.spdx.org/licenses/ Publishing to Packagist requires you choose a license!
19. { “name”: “acme/my-project”, “description”: “Acme’s My Project”, “license”: “MIT”, “require”: { “silex/silex”: “1.1.*” }, “autoload”: { “psr-4”: { “Acme\\MyProject\\”: “src” } } }
20. { “name”: “acme/my-project”, “description”: “Acme’s My Project”, “license”: “MIT”, “require”: { “silex/silex”: “1.1.*” }, “autoload”: { “psr-4”: { “Acme\\MyProject\\”: “src” } } }
21. $ 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 $
22. The packages are installed into a directory named vendor
23. vendor =
24. require “vendor/autoload.php”;
25. Basic Usage
26. Install Composer getcomposer.org/download
27. $ curl -sS https://getcomposer.org/installer | php $ php composer.phar --version WARNING Security people think this is bad (but it is all the rage)
28. $ chmod 755 composer.phar $ mv composer.phar ~/bin/composer $ composer --version
29. composer.json and composer.lock
30. composer.json describes a package and its dependencies
31. { “name”: “acme/my-project”, “description”: “Acme’s My Project”, “license”: “MIT”, “require”: { “silex/silex”: “1.1.*” }, “autoload”: { “psr-4”: { “Acme\\MyProject\\”: “src” } } }
32. composer.lock describes exactly what should be installed
33. $ 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 $
34. Check your composer.lock into your repository
35. Common Commands
36. $ 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.
41. $ composer update Installs dependencies from composer.json and creates or updates composer.lock.
46. $ 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"
47. $ composer require [pkg] Recommend way to add Composer packages to your project! ! composer require foo/bar
49. $ composer require --dev [pkg] Add a package as a dev requirement ! composer require --dev foo/bar
54. $ composer validate Check composer.json for common errors
56. $ composer diag Check environment and composer.json for common errors
59. $ composer show [pkg] shows information about a package
61. $ composer show --self shows information about THIS package
63. $ composer clearcache Because sometimes things get stale.
64. Vendor Tour
65. vendor =
68. { “name”: “acme/my-project”, “description”: “Acme’s My Project”, “license”: “MIT”, “require”: { “silex/silex”: “1.1.*” }, “autoload”: { “psr-4”: { “Acme\\MyProject\\”: “src” } } }
69. Autoloading
70. # Acme\User is not defined ! $user = new Acme\User(); ! # Acme\User is defined
71. Magic! since 5
72. function ($class) { if ($class === "Acme\\Account\\User") { // do something to cause this class // to become defined require __DIR__."/src/user.inc"; } }
73. Composer is a configurable autoloader
74. Each Composer package gets to configure its own rules
75. psr-0
76. PHP-FIG PHP Framework Interoperability Group php-fig.com
77. Namespaces are directories
78. Classes are files with .php suffix
79. Acme\Account\User
80. Acme/Account/User.php
81. PSR-0 also supports legacy PEAR style naming conventions
82. Acme\Account\User ! Acme_Account_User
83. Acme/Account/User.php ! Acme/Account/User.php
84. { "autoload": { "psr-0": { "Acme\\Account\\": "src" } } } ! new Acme\Account\User(); ! # src/Acme/Account/User.php
85. { "autoload": { "psr-0": { "Acme_Account_": "src" } } } ! new Acme_Account_User(); ! # src/Acme/Account/User.php
86. psr-4
87. PHP-FIG PHP Framework Interoperability Group php-fig.com
88. Composer currently recommends new projects use PSR-4
89. Very similar to PSR-0
90. Only supports namespaces (this means no PEAR style naming)
91. Requires a namespace prefix and base directory for mapping
92. Acme\Account\User (class) ! Acme\Account (namespace prefix) ! src (base directory) ! src/User.php (resulting file path)
93. { "autoload": { "psr-4": { "Acme\\Account\\": "src" } } } ! new Acme\Account\User(); ! # src/User.php
94. Migrating from PSR-0 to PSR-4
95. { "autoload": { "psr-0": { "Acme\\Account\\": "src" } } } ! new Acme\Account\User(); ! # src/Acme/Account/User.php
96. { "autoload": { "psr-4": { "Acme\\Account\\": "src/Acme/Account" } } } ! new Acme\Account\User(); ! # src/Acme/Account/User.php
97. files
98. Explicitly include specific files
99. { “autoload”: { “files”: [ “src/foo.class.php”, “src/bar.class.php” ] } }
100. { “autoload”: { “files”: [“src/functions.php”] } }
101. { “autoload”: { “files”: [“src/autoload.php”] } }
102. The files autoloader is really an alwaysloader
103. classmap
104. A key => value map of class names to files on disk
105. { “autoload”: { “classmap”: [ “src/includes/”, “resources/config.php” ] } }
106. It will look inside .php and .inc files to find classes
107. The classmap is generated anytime Composer dumps its autoloader
108. Extremely fast and powerful but not very developer friendly
109. { “name”: “acme/my-project”, “description”: “Acme’s My Project”, “license”: “MIT”, “require”: { “silex/silex”: “1.1.*” }, “autoload”: { “psr-4”: { “Acme\\MyProject\\”: “src” } } }
110. { “name”: “acme/my-project”, “description”: “Acme’s My Project”, “license”: “MIT”, “require”: { “silex/silex”: “1.1.*” }, “autoload”: { “psr-4”: { “Acme\\MyProject\\”: “src” } } }
111. Semantic Versioning
112. semver.org
113. MAJOR.MINOR.PATCH Which number do you increment and why?
114. MAJOR.MINOR.PATCH When you break backwards compatibility
115. MAJOR.MINOR.PATCH When you add backwards compatible features
116. MAJOR.MINOR.PATCH When you make backwards compatible bug fixes
117. Pre-Release Identifiers
118. 1.0.0-alpha 1.0.0-beta.2 1.0.0-RC3
119. Stability Pre-Release Identifiers
120. Version Constraints
121. Exact Version 1.0.2
122. Ranges >=1.0,<2.0
123. Wildcards 1.0.*
124. Next Significant Release Tilde Operator
125. Next Significant Release ~1.2 Minimum allowed version and only the last number listed can increase.
126. Next Significant Release ~1.2 >=1.2,<2
127. Next Significant Release ~1.2.3 >=1.2.3,<1.3
128. Semantic Versioning lets you know what you are getting into
129. Safe 1.3.* Only get bug fixes
130. Reasonably Safe 1.* Get bug fixes and new features
131. Crazy Sauce * Composer allows this, but don't. Just don't.
132. Version Constraint Considerations
133. –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).”
134. Libraries should generally have more permissive constraints
135. –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).”
136. End projects may want to have more restrictive constraints
137. Deep Dependency Resolution
138. { “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
139. { “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
140. { “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
141. Conflicts
142. { "require": { "silex/silex": "1.1.*", "pimple/pimple": "2.0.*@dev" } }
143. $ 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.
144. Versions from Tags
145. 2.0.1 2.0.1 (2.0.*)
146. v2.0.1 2.0.1 (2.0.*)
147. 2.0.1-RC1 2.0.1-RC1 (2.0.*@RC)
148. 3.4-cuddly-cat 3.4-cuddly-cat (3.4-cuddly-cat)
149. 2.0.1g 2.0.1g (2.0.1g)
150. Versions from Branches
151. Branches are considered @dev stability
152. Numbered branches are easy
153. 2.0 2.0.x-dev (2.0.*@dev)
154. Named branches default to their name with a dev- prefix
155. master dev-master (dev-master)
156. 2.0-experimental dev-2.0-experimental (2.0.*@dev won't work!)
157. Named branches can be aliased to be semver friendly
158. { “extra”: { “branch-alias”: { “dev-master”: “2.0.x-dev” } } }
159. master dev-master / 2.0.x-dev (dev-master or 2.0.*@dev)
160. Create a branch alias as soon as you start a new Composer package
161. (future you and your users will thank you)
162. Requiring non-stable versions
163. { “require”: { “symfony/yaml”: “3.5-cat”, “silex/silex”: “1.1@dev”, “pimple/pimple”: “dev-master”, “sculpin/core”: “2.0.*@beta” } }
164. { “require”: { “symfony/yaml”: “3.5-cat”, “silex/silex”: “1.1@dev”, “pimple/pimple”: “dev-master”, “sculpin/core”: “2.0.*@beta” } }
165. requiring dev-master considered harmful
166. Pretend dev-master doesn't exist
167. Send pull requests when you find a package that offers dev-master without a branch alias
168. { “name”: “acme/myapp” }
169. { “name”: “acme/myapp”, “require”: { “naughty/id-generator”: “1.0.*” } } ! ! { “name”: “naughty/id-generator”, “require”: { “ircmaxell/random-lib”: “dev-master” } }
170. { “name”: “acme/myapp”, “require”: { “naughty/id-generator”: “1.0.*”, ! “ircmaxell/random-lib”: “@dev” } } ! ! { “name”: “naughty/id-generator”, “require”: { “ircmaxell/random-lib”: “dev-master” } }
171. { “name”: “acme/myapp”, “require”: { “naughty/id-generator”: “1.0.*”, ! “ircmaxell/random-lib”: “dev-master” } } ! ! { “name”: “naughty/id-generator”, “require”: { “ircmaxell/random-lib”: “dev-master” } }
172. { “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” } }
173. { “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
174. { “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!
175. dev-master is viral
176. Once people start using dev-master for your package it can be hard to break them of that habit
177. Send pull requests when you find a package that requires dev-master when a branch alias exists
178. –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
179. Stability
180. Root package
181. The root package is the package defined in the working composer.json
182. A package is the root package while it is being developed
183. The root package gets to control all aspects of stability
184. Minimum stability
185. Controlled by the root package
186. Defaults to stable
187. { “minimum-stability”: “alpha” }
188. Applied to all packages for which the root package doesn't specify a stability
189. Package-by-package stability
190. Stability can be controlled on a package-by-package basis
191. { “require”: { “silex/silex”: “~1.1@dev”, “symfony/http-foundation”: “@beta” }, “minimum-stability”: “alpha” }
192. Stability solver errors are fun
193. { "require": { "sculpin/sculpin": "2.0.*" } }
194. $ 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
195. $ 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
196. { "require": { "sculpin/sculpin": "2.0.*@dev" } }
197. { "require": { "sculpin/sculpin": "2.0.*" }, "minimum-stability": "dev" }
198. Root package stability implications
199. Even if your package requires a dependency @dev, users of your package won't get it unless they explicitly ask for it.
200. { “name”: “silex/silex”, “require”: { “pimple/pimple”: “1.*@dev” } } Root Package
201. { “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
202. { “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
203. Dev Dependencies
204. dev dependencies can only be installed for the root package
205. Publishing and Discovery
206. packagist.org
207. Over 42,300 packages
208. Publishing is as easy as pasting your repository's GitHub URL
210. Check Packagist before you start a new library from scratch
211. Self Hosted Composer Repositories
212. Install Packagist Locally
213. Satis
214. Toran Proxy https://toranproxy.com/
215. [this page intentionally left blank]
216. Choose an autoloading strategy
217. Choose PSR-4 for new projects
218. Semantic Versioning lets you know what you're getting into
219. Libraries should generally have more permissive constraints
220. End projects may want to have more restrictive constraints
221. Create branch aliases
222. dev-master considered harmful
223. Use Packagist
224. #composer look for simensen and say "hi" freenode IRC
225. Questions? @beausimensen • beau.io @thatpodcast • thatpodcast.io ddd.io/phpworld2014 joind.in
226. Beau Simensen @beausimensen +BeauSimensen beau.io
227. Dragonfly Development @dflydev dflydev.com
228. boogio.com @wearboogio reflxlabsinc.com @reflxlabs