Slide 1

Slide 1 text

PHP Dependency Management with Composer Clark Everetts, Zend Technologies/Rogue Wave 19 October 2015

Slide 2

Slide 2 text

2 Clark Everetts, ZCE • Zend Technologies, Inc. – The PHP Company / Rogue Wave • PHP since 2005 • Professional Services Consultant  Architecture and Performance Audits  PHP and Zend Framework Training  Application Development, Best Practices, etc. • [email protected] +ClarkEverettsAtZend @clarkphp • Slides for this talk at https://slideshare/ • Tweets: #zendcon • Rate & comment this session https://joind.in/15504 Welcome!

Slide 3

Slide 3 text

INTRODUCTION/ BACKGROUND

Slide 4

Slide 4 text

4 •(1st Half)  What is it?  What problem does it solve?  What does it actually do?  Composer.json & composer.lock  Packages, Repositories and Packagist  Semantic Versioning  Do’s and Don’ts / Best Practices •(2nd Half)  How to install it  How to use it Why are we here? Our Agenda. Might use it just for the cool logo …

Slide 5

Slide 5 text

5 Composer is … … a per-project PHP dependency manager That’s all. Any questions?

Slide 6

Slide 6 text

6 Composer is … … a per-project PHP dependency manager Let’s break it down.

Slide 7

Slide 7 text

7 … a per-project PHP dependency manager •PHP project-related files only •Can include assets like Javascript, images, XML, CSS, etc. •But not for managing Javascript or CSS libraries •Primarily a development - not production – tool (“can” be prod*) PHP Package Dependencies *but I’m not a fan

Slide 8

Slide 8 text

8 … a per-project PHP dependency manager What’s a “dependency”? You wrote these to reuse across apps. 3rd-Party ZF2, Laravel, OAuth2, Symfony Your Project DEPENDENCIES, PACKAGES, LIBRARIES “Project” == Application

Slide 9

Slide 9 text

9 … a per-project PHP dependency manager Dependencies can have dependencies Your Project DEPENDENCIES, PACKAGES, LIBRARIES “Project” == Application == Library == Package Composer obtains all specified dependencies. “I need A, B, C, D” “I need E” A B C E D F G H “I need E” “I need G, H”

Slide 10

Slide 10 text

10 Want to manage that yourself? “I need these” “I need this” A B C E D F G H “I need that” “I need the other” You’d need to: • Identify the direct dependencies of your project • Identify their dependencies, and all sub-dependencies • Locate the source code (PEAR, Git, Subversion, zip/gzip/bz2) • Download and install all of the source code • Make sure all the versions are compatible • Check for updates to any of the dependencies • Do it all again when updates are available With your guidance, Composer does all this for you.

Slide 11

Slide 11 text

11 … a per-project PHP dependency manager Different versions of the same package Application A Application B Lib Y 1.0.1 Lib X 2.4.1 Lib Y 1.0.1 Lib X 1.2.0 Two projects, each using a different version of the same dependency. Composer is not a global “package manager” (PEAR, APT, YUM) Why do this? • Working with development version: Dev, Alpha, Beta, RC • Update cycle for App A !== App B

Slide 12

Slide 12 text

12 … a per-project PHP dependency manager To Reiterate: per-project; not global Application A Application B Lib Y 1.0.1 Lib X 2.4.1 Lib Y 1.0.1 Lib X 2.4.1 Two projects, each using same version of the same dependency. Each project has it’s own copy. Pros • Like a PHAR (PHP Archive) file, all dependencies are available in the application directory tree. • Updates to the dependencies of one application do not affect another. Con • Potentially many copies of the exact same library source code on disk.

Slide 13

Slide 13 text

13 Composer is… … a per-project PHP dependency manager Knows what packages your application or library depends upon Obtains those packages, and all of their dependencies, and installs appropriate versions of them into your project When requested, checks for updates compatible with your project, and downloads into it any updated packages Allows you to pin multiple applications/libraries to the same or different versions of the packages they use. Composer makes it easier to manage application dependencies.

Slide 14

Slide 14 text

COMPOSER.JSON & COMPOSER.LOCK

Slide 15

Slide 15 text

15 Now What? Answered questions, raised others: How do we inform Composer what dependencies a project has? Where does it put the dependencies in the project? Where does Composer obtain dependencies? How does the project refer to those dependencies (access them when it needs them)? How do we install Composer and actually use it? A closer look…

Slide 16

Slide 16 text

16 composer.json file tells Composer about your project’s needs Describing Project Dependencies Composer-Intro zendframework/ zend-log >=2.3.5 { "name" : "Composer-Intro", "require" : { "zendframework/zend-log" : “>=2.3.5" }, "repositories" : [ { "type" : "composer", "url" : "https://packagist.org/" } ] } Light text - Optional Bold text - Required composer.json composer.json ? ? ? Note: >=2.3.5 is an Unbounded Version Constraint Eventual BC breaks (semantic versioning). Done here for illustration, for when we discuss dependency updates.

Slide 17

Slide 17 text

17 composer install Installing Project Dependencies – First Level/Direct Composer-Intro zendframework/ zend-log >=2.3.5 New: •Vendor Directory •composer.lock file After Before { "require" : { "zendframework/zend-log" : “>=2.3.5" } }

Slide 18

Slide 18 text

18 zend-servicemanager and zend-stdlib composer.json files each contained this: { … "require": { "php": ">=5.3.23", }, … } Installing Project Dependencies – Further Levels zend-log composer.json file contained this: { … "require": { "php": ">=5.3.23", "zendframework/zend-servicemanager": "self.version", "zendframework/zend-stdlib": "self.version" }, … } zend-log needs two more packages, use same version as zend-log No further code dependencies Note PHP version requirement (platform package in Composer)

Slide 19

Slide 19 text

19 Where dependencies are stored (by default) Composer-Intro vendor zend-stdlib zend-log Dependency Relationship zend-servicemanager Composer-Intro Directory Structure zend-log zend-servicemanager zend-stdlib

Slide 20

Slide 20 text

20 .json vs. .lock – Think: “Design-To” vs. “As-Built” Composer-Intro zendframework/ zend-log >=2.3.5 composer.json tells Composer what you want composer.lock tells you what you got Composer-Intro zend-stdlib 2.4.0 zend-log 2.4.0 zend-servicemanager 2.4.0

Slide 21

Slide 21 text

21 “Design-To” vs. “As-Built” – Further Example Composer-Intro Composer resolves versions as best it can actual versions installed recorded in composer.lock Composer-Intro zend-stdlib 2.3.9 zend-log 2.3.9 zend-servicemanager 2.3.9 zendframework/ zend-log >=2.3,<2.4

Slide 22

Slide 22 text

22 Problems Can Occur Your Project “I need E >=1.0,<1.2” A B C E version ? “I need E >=1.2,<2.0”

Slide 23

Slide 23 text

23 Initial composer install Your Application composer.json Repository composer.lock vendor folder 4. Create With no composer.lock Composer will …

Slide 24

Slide 24 text

24 1. Read Subsequent composer install Your Application composer.json Repository composer.lock vendor folder With existing composer.lock Composer will … 2. Obtain lock file versions from

Slide 25

Slide 25 text

25 Any composer update Your Application composer.json Repository composer.lock vendor folder 4. Update Composer will …

Slide 26

Slide 26 text

26 Development Considerations D Development Workstation / Vhost Packagist.org, Local repos composer install B Development Workstation / Vhost A Development Workstation / Vhost composer update & commit to local VCS composer install C Development Workstation / Vhost composer install install === “synchronize”

Slide 27

Slide 27 text

27 Production Considerations Production Server Packagist.org composer install composer update Please do NOT do this.

Slide 28

Slide 28 text

28 Production Considerations “Build” Server Packagist.org composer install with composer.lock file Better. Production Server

Slide 29

Slide 29 text

29 Production Considerations Test Server Best. Production Server Local Repository (VCS / Change Mgt, Packagist) Production Server Or Local Repository (VCS / Change Mgt, Packagist)

Slide 30

Slide 30 text

MORE ON PACKAGES & REPOSITORIES

Slide 31

Slide 31 text

31 Composer downloads packages from repositories Where Does Composer Obtain Dependencies? Package • A directory with files in it • Package description - composer.json • Name • Version • Source Definition • Repository location (URI) • Repository Type • Package Type • Dist – packaged (usually a stable release) • Source – source code (for development) • Can be both

Slide 32

Slide 32 text

32 More About Packages - Naming Package Names • vendor-name/project-name • psr/log • pear/log • zendframework/log • Best practice: use-dashes/as-word-separators • Vendor names must be unique • If you are going to publish packages: • Remember: they persist! You and the world will have to live with them. • Don’t be cute or cryptic (with vendor or package name) • Name should reflect package purpose

Slide 33

Slide 33 text

33 Packages - composer.json – Real (former) Example { "name": "zendframework/zend-log", "description": "component for general purpose logging", "license": "BSD-3-Clause", "keywords": ["zf2“, "log“, "logging”], "homepage": "https://github.com/zendframework/zf2", "autoload": { "psr-4": { "Zend\\Log\\": "" } }, "require": { "php": ">=5.3.23", "zendframework/zend-servicemanager": "self.version", "zendframework/zend-stdlib": "self.version" }, (cont. next slide)

Slide 34

Slide 34 text

34 Packages - composer.json – Real Example (cont.) "require-dev": { "zendframework/zend-console": "self.version", "zendframework/zend-db": "self.version", "zendframework/zend-escaper": "self.version", "zendframework/zend-mail": "self.version", "zendframework/zend-validator": "self.version" }, "suggest": { "ext-mongo": "*", "zendframework/zend-console": "Zend\\Console component", "zendframework/zend-db": "Zend\\Db component", "zendframework/zend-escaper": "Zend\\Escaper component, for use in the XML formatter", "zendframework/zend-mail": "Zend\\Mail component", "zendframework/zend-validator": "Zend\\Validator component" }, (cont. next slide)

Slide 35

Slide 35 text

35 Packages - composer.json – Real Example (cont.) "extra": { "branch-alias": { "dev-master": "2.3-dev", "dev-develop": "2.4-dev" } } } Notice anything missing? • package type – omit, “library”, or custom • package version • Best to omit for Composer, VCS repositories (uses branch/tags) • Format: X.Y.Z or vX.Y.Z, with optional RC, beta, alpha, patch • 1.4.26 • 2.5.6-RC3 • 1.2.3-p2 • 1.2.3-RC

Slide 36

Slide 36 text

36 Platform / Virtual Packages Not Installable by Composer, Used for checking only • php – PHP version of the server Composer is installing packages to • hhvm (not applicable for IBM i) • ext- • “ext-ibm_db2” : “*” • lib- • curl • iconv • icu • libxml • openssl • pcre • uuid • xsl • composer show --platform for a list of available platform packages

Slide 37

Slide 37 text

37 More About Repositories Repository • A download source for packages, specified by URL • A list of packages and versions in a packages.json file • Types • Composer – uses Packagist software, can public or private • VCS – Git, SVN, Hg • VCS client needed for “regular” git, svn, or hg repos • Uses APIs for GitHub, BitBucket (no client needed) • PEAR – public or private • Package – zip; use only if none of the above are possible

Slide 38

Slide 38 text

38 Repositories: Packagist.org Packagist.org Package Archivist Just a Composer Repository… • … but it is the primary repository for open source packages • Open Source Project Best Practice: register it at packagist.org • Searchable / Browsable • Less work for people to find and use your package. • Many, many, many packages available. There is duplication…

Slide 39

Slide 39 text

39 https://packagist.org/

Slide 40

Slide 40 text

40 Composer Private Repositories – Satis and Torin Proxy Your Application Packagist.org Proxy Torin / Satis Public Repositories Satis – free TorinProxy.com – license fees support development of Composer Why? 1. Speed. 2. Happier network security staff.

Slide 41

Slide 41 text

41 Private Repositories – Local Packagist Your Application composer.json / composer.lock Private Repository

Slide 42

Slide 42 text

SEMANTIC VERSIONING

Slide 43

Slide 43 text

43 Semantic Versioning http://semver.org/ Version Numbers Have Meaning • Essentially, it is a promise from the development team • Not a guarantee, but best effort • 1.2.3 – numbers increment, can have pre-release suffix • Major.Minor.Patch • Patch: bug fixes; no BC breaks! No API changes! Everyone using the package should be confident in moving from 1.2.3 to 1.2.4 • Minor: introduce new features, but change no prior APIs; no BC breaks! Changing internals (refactoring) should not affect package users. Everyone using the package should be confident in moving from 1.2.3 to 1.3.0. • Major: API changes; BC breaks (whether intentional or not). Example: 1.3.14 to 2.0.0 • For developers, not marketing department.

Slide 44

Slide 44 text

44 Semantic Versioning and Composer Version Constraints Shortcut notations in Composer for version constraints • “Next Significant Release” • ^1.2.3 is same as >=1.2.3,<2.0.0 and means 1.2.3 <= x < 2.0.0 • Specifies a min version, and all non API-changing updates • Another (older form of) “Next Significant Release” • ~1.2.3 is same as >=1.2,<1.3.0 and means 1.2.0 <= x < 1.3.0 • Specifies a min version; last number specified can increment • For this example, we accept only bug-fixes, no new features. • ~1.2 is same as >=1.2,<2.0 and means 1.2.0 <= x < 2.0.0 • For this example, we accept all non-breaking changes • https://getcomposer.org/doc/articles/versions.md

Slide 45

Slide 45 text

45 Some Best Practices •Do’s and Don’ts: • Building a deployment fileset with Composer • Unbound Version Constraints • Version Constraints combined with Wildcards • Wildcards by themselves • Install or update to the intended directory Be careful out there!

Slide 46

Slide 46 text

46 Don’t install development requirements Use lock file Download Distribution Packages composer install - - prefer-dist - - no-dev - - optimize-autoloader Generate PSR-0/4 classmap for fast autoloading Building Deployment Filesets

Slide 47

Slide 47 text

47 Do NOT use unbound version constraints (>=, no upper bound): Example: >=2.3 Example: >=1.1.* (note that * is not the problem here, >= is) Example: dev-master Composer will install new updates, as long as they become available, without regard to backwards-compatibility. (You’ll get 2.3.5, 10.5.23, etc.) Solution: >=2.3,<3.0 or ~2.3 Solution: >=1.1.0,<1.2 or ~1.1.0 Best Practice: Use ^2.3 Use ^1.1 Best Practices Do’s and Don’ts

Slide 48

Slide 48 text

48 •Do NOT attempt to specify a version constraint with a wildcard: • Example: >=2.* >=2 means any version at least 2.0.0 (2.0.5, or 2.9.9, or 3.0.7, 10.3.2, etc.) 2.* means any version in the interval [2.0.0, 3.0.0), or 2.0.0-2.9.9999 • Composer can’t tell if you want 3.0.0 to be considered, or not. Composer: “Invalid, I’m throwing an error” Solution: use >=2,<3 Best Practice: ^2 (for semantic versioning) Best Practices Do’s and Don’ts

Slide 49

Slide 49 text

49 Do NOT use a wildcard (except for virtual extension packages) Example: 1.2.* is bad – slows composer down Looks at all patch level releases, and all their sub-dependencies Also limits composer to versions < 1.3 forever Composer: “Don’t make me work so hard!” Solution: (if you really want < 1.3) use ~1.2.0 or >=1.2.0,<1.3 or (if you really want >= 1.2) use ~1.2.0 or >=1.2.0,<2.0.0 or SemVer Best Practice: ^1.2 Best Practices Do’s and Don’ts

Slide 50

Slide 50 text

50 Best Practices Do’s and Don’ts •Make SURE you’re in right folder when issuing composer install • Will read composer.json in that folder, create vendor folder, and .lock file • Regardless of existence of .lock file in project root directory • Same for composer update! Part of your vendor folder could be updated with packages not compatible with other packages Run composer install /update from root of your project.

Slide 51

Slide 51 text

51 Resources • Composer Manual - https://getcomposer.org/doc/ • Semantic Versioning - http://semver.org/ • Autoloading - http://www.php-fig.org/psr/psr-4/ • JSON (JavaScript Object Notation) - http://json.org/ • Help - https://groups.google.com/forum/#!forum/composer-users • IRC - #composer on freenode irc://irc.freenode.org/composer • Packagist Semver Checker – http://semver.mwl.be/ • Composer.json Schema https://getcomposer.org/doc/04-schema.md https://github.com/composer/composer/blob/master/res/composer-schema.json http://stackoverflow.com/questions/tagged/composer-php

Slide 52

Slide 52 text

THANK-YOU [email protected] +ClarkEverettsAtZend @clarkphp Slides for this talk at http://slideshare/ Tweets: #zendcon Rate & comment on this session https://joind.in/15504 Your feedback is invaluable!