Managing Dependencies with Composer (Sunshine PHP 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 Sunshine PHP February 8th, 2014
2. Beau Simensen @beausimensen beau.io
3. #composer look for simensen and say "hi" freenode IRC
4. Dragonfly Development @dflydev dflydev.com
5. boogio.com @wearboogio reflxlabsinc.com @reflxlabs
7. Dependency Management
8. Dependencies are external requirements
9. Managing dependencies for PHP projects has not always been trivial
10. Composer makes dependency management easier
11. composer.json
12. { “name”: “acme/my-project”, “description”: “Acme’s My Project”, “license”: “MIT”, “require”: { “silex/silex”: “1.1.*” }, “autoload”: { “psr-4”: { “Acme\\MyProject\\”: “src” } } }
13. { “name”: “acme/my-project”, “description”: “Acme’s My Project”, “license”: “MIT”, “require”: { “silex/silex”: “1.1.*” }, “autoload”: { “psr-4”: { “Acme\\MyProject\\”: “src” } } }
14. vendor-name/project-name A package's name cannot change and must be all lowercase
15. Vendor name should be unique to the developer, project, or company
16. { “name”: “acme/my-project”, “description”: “Acme’s My Project”, “license”: “MIT”, “require”: { “silex/silex”: “1.1.*” }, “autoload”: { “psr-4”: { “Acme\\MyProject\\”: “src” } } }
17. { “name”: “acme/my-project”, “description”: “Acme’s My Project”, “license”: “MIT”, “require”: { “silex/silex”: “1.1.*” }, “autoload”: { “psr-4”: { “Acme\\MyProject\\”: “src” } } }
18. $ 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 $
19. The dependencies are installed into a directory named vendor
20. vendor =
21. By all means, learn about vendor and what happens in there, but don't obsess. ! It isn't (usually) that important.
22. require “vendor/autoload.php”;
23. Autoloading
24. // // life without autoloading // ! require “../vendor/whizbang/classes.php”; ! $service = new Acme\WhizBang\Thing()
25. Autoloading your classes means you can just use them
26. # Acme\User is not defined ! $user = new Acme\User(); ! # Acme\User is defined
27. __autoload since 5
28. The __autoload function is called anytime a class does not exist
29. function __autoload($class) { if ($class === "Acme\\Account\\User") { // do something to cause this class // to become defined require __DIR__."/src/user.inc"; } }
30. The major limitation of __autoload is that it is only one function
31. spl_autoload_register since 5.1.2
32. With spl_autoload_register more than one autoloader implementation can be registered at the same time
33. spl_autoload_register( // Registers Acme's autoloader Acme::autoloader ); spl_autoload_register( // Registers Doctrine's autoloader Doctrine::autoloader ); spl_autoload_register(function($class) { // Register a rarely used class if ($class === "Acme\\RarelyUsed\\User") { require __DIR__."/src/user.inc"; } });
34. // this allowed projects to ship autoloaders with // their packages so they could be easily enabled ! require “../vendor/whizbang/bootstrap.php”; require “../vendor/awesomesoft/bootstrap.php”; require “../vendor/lessawesome/bootstrapper.php”; require “../vendor/ultraframework/classloader.php”; ! LessAwesome\BootStrapper::register(); ! UltraFramework\ClassLoader::register(array( “\\Acme\\MyApp\\” = “../src” ));
35. Composer is a configurable autoloader
36. Each Composer package gets to configure its own rules
37. require “vendor/autoload.php”;
38. Pick an autoloading strategy and configure Composer to use it
39. psr-0
40. PHP-FIG PHP Framework Interoperability Group php-fig.com
41. –Larry Garfield "For sufficiently vague definitions of 'accepted', May 2009 is the date I use."
42. Namespaces are directories
43. Classes are files with .php suffix
44. Acme\Account\User
45. Acme/Account/User.php
46. PSR-0 also supports legacy PEAR style naming conventions
47. Acme\Account\User ! Acme_Account_User
48. Acme/Account/User.php ! Acme/Account/User.php
49. Legacy rules are kinda convoluted
50. _ is converted to / but only in the class name
51. Acme\Web_Site\User_Controller
52. Acme/Web_Site/User/Controller.php
53. PSR-0 had a handful of other relatively insignificant* issues * the significance of the issues varies wildly depending on who you ask
54. { "autoload": { "psr-0": { "Acme\\Account\\": "src" } } } ! new Acme\Account\User(); ! # src/Acme/Account/User.php
55. { "autoload": { "psr-0": { "Acme_Account_": "src" } } } ! new Acme_Account_User(); ! # src/Acme/Account/User.php
56. psr-4
57. PHP-FIG PHP Framework Interoperability Group php-fig.com
58. Accepted December 3rd, 2013
59. Finally!
60. Very similar to PSR-0
61. Only supports namespaces so no PEAR style naming
62. Introduces a namespace prefix and base directory for mapping
63. Reduces the number of directories that are required to exist
64. Acme\Account\User (class) ! Acme\Account (namespace prefix) ! src (base directory) ! src/User.php (resulting file path)
65. { "autoload": { "psr-4": { "Acme\\Account\\": "src" } } } ! new Acme\Account\User(); ! # src/User.php
66. Composer currently recommends new projects use PSR-4
67. Migrate from PSR-0 to PSR-4
68. { "autoload": { "psr-0": { "Acme\\Account\\": "src" } } } ! new Acme\Account\User(); ! # src/Acme/Account/User.php
69. { "autoload": { "psr-4": { "Acme\\Account\\": "src/Acme/Account" } } } ! new Acme\Account\User(); ! # src/Acme/Account/User.php
70. files
71. Explicitly include specific files
72. { “autoload”: { “files”: [ “src/foo.class.php”, “src/bar.class.php” ] } }
73. { “autoload”: { “files”: [“src/functions.php”] } }
74. { “autoload”: { “files”: [“src/autoload.php”] } }
75. The files autoloader is really an alwaysloader
76. files are included right when vendor/autoload.php is
77. classmap
78. A key => value map of class names to files on disk
79. It will look inside .php and .inc files to find classes
80. The classmap is generated anytime Composer dumps its autoloader
81. Extremely fast and powerful but not super developer friendly
82. { “autoload”: { “classmap”: [ “src/includes/”, “resources/config.php” ] } }
83. { “name”: “acme/my-project”, “description”: “Acme’s My Project”, “license”: “MIT”, “require”: { “silex/silex”: “1.1.*” }, “autoload”: { “psr-4”: { “Acme\\MyProject\\”: “src” } } }
84. { “name”: “acme/my-project”, “description”: “Acme’s My Project”, “license”: “MIT”, “require”: { “silex/silex”: “1.1.*” }, “autoload”: { “psr-4”: { “Acme\\MyProject\\”: “src” } } }
85. Versioning
86. Pretty much anything can be used as a Composer version
87. If you want to leverage Composer to its fullest use Semantic Versioning
88. Semantic Versioning
89. semver.org
90. MAJOR.MINOR.PATCH Which number do you increment and why?
91. MAJOR.MINOR.PATCH When you break backwards compatibility
92. MAJOR.MINOR.PATCH When you add backwards compatible features
93. MAJOR.MINOR.PATCH When you make backwards compatible bug fixes
94. Pre-Release Identifiers Composer calls this "stability"
95. 1.0.0-alpha @alpha
96. 1.0.0-beta.1 @beta
97. 1.0.0-RC2 @RC
98. 1.0.0 (stable)
99. Version Constraints
100. Exact Versions 1.0.2
101. Ranges >=1.0.2,<2.0
102. Wildcards 1.0.*
103. Next Significant Release Tilde Operator
104. Next Significant Release ~1.2 >=1.2,<2.0
105. Next Significant Release ~1.2.3 >=1.2.3,<1.3
106. Semantic Versioning let's you know what you are getting into
107. Safe 1.3.* Only get bug fixes
108. Reasonably Safe 1.* Get bug fixes and new features
109. Crazy sauce * Composer allows this, but don't. Just dont.
110. Stability and the Root Package
111. Stability is controlled by the root package
112. Even if your package requires something @dev, users of your package won't get @dev unless they explicitly ask for it
113. The root package is defined in the working composer.json
114. { “require”: { “silex/silex”: “~1.1@dev”, “symfony/http-foundation”: “@beta” }, “minimum-stability”: “alpha” }
115. A package is only a root package when it is being developed
116. { “name”: “silex/silex”, “require”: { “pimple/pimple”: “1.*@dev” } }
117. { “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” } }
118. { “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” } } { “require”: { “dflydev/doctrine-orm-service-provider”: “1.0.*”, ! “pimple/pimple”: “1.0.*” } }
119. Version Constraint Considerations
120. –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).”
121. –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).”
122. Libraries should generally have more permissive constraints
123. End projects may want to have more restrictive constraints
124. VCS Repositories
125. Any VCS repository can be treated like a Composer package
127. Composer treats tags as versions for VCS repositories
128. Tags and Versions
129. If a tag can be parsed as semver, awesome!
130. If it cannot be parsed as semver, it is treated as an "exact" version
131. v2.0.1 2.0.1 (2.0.*)
132. 2.0.1 2.0.1 (2.0.*)
133. 2.0.1-RC1 2.0.1-RC1 (2.0.*@RC)
134. 2.0.1g 2.0.1g (2.0.1g)
135. 3.4-cuddly-cat 3.4-cuddly-cat (3.4-cuddly-cat)
136. Branches and Versions
137. Composer treats branches as @dev stability versions
138. Numbered branches are treated as development versions
139. 2.0 2.0.x-dev (2.0.*@dev)
140. Named branches default to their name with a dev- prefix
141. master dev-master (dev-master)
142. testing dev-testing (dev-testing)
143. 2.0-experimental dev-2.0-experimental (2.0.*@dev won't work!)
144. Named branches can be aliased to be semver friendly
145. { “extra”: { “branch-alias”: { “dev-master”: “2.0.x-dev” } } }
146. master dev-master / 2.0.x-dev (dev-master or 2.0.*@dev)
147. dev-master considered harmful
148. –Don Gilbert “When starting a new library that is to be distributed via Packagist / Composer, be SURE to set up your dev- master branch alias.” https://twitter.com/dilbert4life/status/380137097614458881
149. Publishing and Discovery
150. packagist.org
151. Publishing is as easy as pasting your repositories GitHub URL
152. { “name”: “acme/my-project”, “description”: “Acme’s My Project”, “license”: “MIT”, “require”: { “silex/silex”: “1.1.*” }, “autoload”: { “psr-4”: { “Acme\\MyProject\\”: “src” } } }
153. Discovery is as easy as typing something into the search box
154. Over 23,600 packages
155. Check Packagist before you start a new library from scratch
156. Basic Usage
157. Install Composer getcomposer.org/download
158. $ curl -sS https://getcomposer.org/installer | php $ php composer.phar --version WARNING Security people think this is bad, but it is all the rage
159. $ chmod 755 composer.phar $ mv composer.phar ~/bin/composer $ composer --version
160. composer.json and composer.lock
161. composer.json describes a package and its dependencies
162. { “name”: “acme/my-project”, “description”: “Acme’s My Project”, “license”: “MIT”, “require”: { “silex/silex”: “1.1.*” }, “autoload”: { “psr-4”: { “Acme\\MyProject\\”: “src” } } }
163. composer.lock describes exactly what should be installed
164. composer.lock is not meant for interactions with humans
165. Check your composer.lock into your repository
166. Common Commands
167. $ 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.
168. $ composer update Installs dependencies from composer.json and creates or updates composer.lock.
169. $ composer require [pkg] Add a package to composer.json. ! The [pkg] is the name with a version constraint. ! foo/bar:1.0.0 or foo/bar=1.0.0 or "foo/bar 1.0.0"
170. $ composer diag Check environment and composer.json for common errors
171. $ composer validate Check composer.json for common errors
172. #composer
173. Autoload your classes
174. Use Semantic Versioning
175. Devs don't let devs dev-master
176. Search Packagist first
177. Publish your code on Packagist
178. Questions? @beausimensen ddd.io/ssp14-composer