1. No category

PHP Package Management
with Composer
Clark Everetts, Zend Technologies, Inc.
COMMON 2015 Annual Meeting and Exposition
April 27 2015
1
Confidential - © All rights reserved. Zend Technologies, Inc.
© All rights reserved. Zend Technologies, Inc.
Welcome!
Clark Everetts, ZCE
• Zend Technologies, Inc. – The PHP Company
• 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 are at http://clarkeveretts.com/ and COMMON site
Make sure you have an
evaluation form.
2
© All rights reserved. Zend Technologies, Inc.
INTRODUCTION/BACKGROUND
3
© All rights reserved. Zend Technologies, Inc.
Why are we here? Our Agenda.
Composer:
•
•
•
•
•
What is it?
What problem does it solve?
What does it actually do?
How do I use it?
Do’s and Don’ts / Best Practices
Might use it just for
the cool logo …
4
© All rights reserved. Zend Technologies, Inc.
Composer is …
… a per-project PHP dependency manager
That’s all. Any questions?
5
© All rights reserved. Zend Technologies, Inc.
Composer is …
… a per-project PHP dependency manager
Let’s break it down.
6
© All rights reserved. Zend Technologies, Inc.
PHP Package Dependencies
… a per-project PHP dependency manager
• PHP project-related files only
• Can reference assets like Javascript, images, XML, CSS, etc.
• But not for managing Javascript or CSS libraries (more later)
• Primarily a development - not production – tool (“can” be prod*)
*but I’m not a fan
7
© All rights reserved. Zend Technologies, Inc.
What’s a “dependency”?
… a per-project PHP dependency manager
Your Project
“Project” == Application
DEPENDENCIES,
PACKAGES,
LIBRARIES
You wrote these to
reuse across apps.
8
3rd-Party
ZF2, Laravel, OAuth2,
Symfony
© All rights reserved. Zend Technologies, Inc.
Dependencies can have dependencies
… a per-project PHP dependency manager
Your Project
“Project” == Application == Library == Package
“I need
A, B, C, D”
A
B
C
“I need E”
D
“I need E”
E
F
Composer obtains all
specified dependencies.
“I need G, H”
G
9
DEPENDENCIES,
PACKAGES,
LIBRARIES
H
© All rights reserved. Zend Technologies, Inc.
Want to manage that yourself?
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
“I need these”
A
B
“I need
this”
C
“I need
that”
E
“I need the
other”
G
10
D
H
F
With your guidance, Composer
does all this for you.
© All rights reserved. Zend Technologies, Inc.
Who is getting updated?
… a per-project PHP dependency manager
Our project code didn’t
change; so neither does
the version number.
1.0.0
2.4.0
3.2.1
2.4.1
Dependency updated with
non BC-breaking change.
time
11
1.0.0
© All rights reserved. Zend Technologies, Inc.
3.2.1
Different versions of the same package
… a per-project PHP dependency manager
Application
A
Lib X
1.2.0
Two projects, each using a
different version of the same
dependency.
Lib Y
1.0.1
Composer is not a global
“package manager”
(PEAR, APT, YUM)
Application
B
Lib X
2.4.1
Why do this?
• Working with development version: Dev, Alpha, Beta, RC
• Update cycle for App A !== App B
Downside
• Potentially many copies of the exact same library code on disk.
12
© All rights reserved. Zend Technologies, Inc.
Lib Y
1.0.1
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.
13
© All rights reserved. Zend Technologies, Inc.
COMPOSER.JSON &
COMPOSER.LOCK
14
© All rights reserved. Zend Technologies, Inc.
Now What?
We’ve answered some questions, and raised others:
•
•
•
•
•
How do we inform Composer what dependencies a project has?
Where does it put them in the project?
Where does Composer obtain dependencies?
How does the project refer to those dependencies?
How do we install Composer and actually use it?
A closer look…
15
© All rights reserved. Zend Technologies, Inc.
Describing Project Dependencies
composer.json file tells Composer about your project’s needs
{
"name" : "Composer-Intro",
"require" : {
"zendframework/zend-log" : ">=2.3.5"
},
"repositories" : [ {
"type" : "composer",
"url" : "https://packagist.org/"
}]
}
Composer-Intro
composer.json
zendframework/
zend-log
>=2.3.5
composer.json
Light text - Optional
Bold text - Required
Note: >=2.3.5 is an Unbound Version Constraint
Eventual BC breaks likely; for illustration only!!
16
© All rights reserved. Zend Technologies, Inc.
?
?
?
Installing Project Dependencies – First Level/Direct
composer install
Before
After
Composer-Intro
zendframework/
zend-log
>=2.3.5
{
"require" : {
"zendframework/zend-log" : ">=2.3.5"
}
}
17
© All rights reserved. Zend Technologies, Inc.
New:
•Vendor Directory
•composer.lock file
Installing Project Dependencies – Further Levels
zend-log composer.json file contains 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 of those as zend-log
zend-servicemanager and zend-stdlib composer.json files each contain this:
{…
"require": {
No further code dependencies,
"php": ">=5.3.23",
},
Note PHP version requirement.
…
}
18
© All rights reserved. Zend Technologies, Inc.
Where dependencies are stored (by default)
Dependency Relationship
Directory Structure
Composer-Intro
Composer-Intro
zend-log
vendor
zend-log
zend-servicemanager
zend-servicemanager
zend-stdlib
zend-stdlib
19
© All rights reserved. Zend Technologies, Inc.
“Design-To” vs. “As-Built”
composer.json tells Composer what you want
Composer-Intro
Composer-Intro
zend-log
2.4.0
zendframework/
zend-log
>=2.3
zend-servicemanager
2.4.0
zend-stdlib
2.4.0
composer.lock tells you what you got
20
© All rights reserved. Zend Technologies, Inc.
“Design-To” vs. “As-Built” – Further Example
Composer resolves versions as best it can
Composer-Intro
Composer-Intro
zend-log
2.3.7
zendframework/
zend-log
>=2.3,<2.4
zend-servicemanager
2.3.7
zend-stdlib
2.3.7
actual versions installed recorded in composer.lock
21
© All rights reserved. Zend Technologies, Inc.
Problems Can Occur
Your Project
A
B
“I need E >=1.0,<1.2”
C
“I need E >=1.2,<2.0”
E version ?
22
© All rights reserved. Zend Technologies, Inc.
Flow for new composer install
With no composer.lock
Composer will …
composer.json
vendor
folder
4. Create
Your Application
composer.lock
Repository
23
© All rights reserved. Zend Technologies, Inc.
Flow for subsequent composer install
With existing
composer.lock
Composer will …
composer.json
vendor
folder
4. Update
1. Read
composer.lock
Your Application
2. Obtain lock file versions from
24
© All rights reserved. Zend Technologies, Inc.
Repository
Flow for any composer update
With existing
composer.lock
Composer will …
composer.json
vendor
folder
4. Update
1. Read
composer.lock
Your Application
2. Obtain packages’ latest compatible
release from
25
© All rights reserved. Zend Technologies, Inc.
Repository
Development Considerations
install === synchronize
Development
Workstation /
Vhost
Development
Workstation /
Vhost
26
Development
Workstation /
Vhost
composer update &
commit to local VCS
composer install
composer install
Packagist.org
Development
Workstation /
Vhost
© All rights reserved. Zend Technologies, Inc.
composer install
Production Considerations
Production
Server
composer install
composer update
You should be fired.
27
© All rights reserved. Zend Technologies, Inc.
Packagist.org
Production Considerations
composer install
with composer.lock file
“Build”
Server
Packagist.org
Better.
Production
Server
28
© All rights reserved. Zend Technologies, Inc.
Production Considerations
Local
Repository (VCS /
Change Mgt,
Packagist)
Test
Server
Or
Production
Server
Production
Server
Best.
29
© All rights reserved. Zend Technologies, Inc.
Building Deployment Fileset
Use lock file
Don’t install
development requirements
composer install - - prefer-dist - - no-dev - - optimize-autoloader
Download Distribution
Packages
30
© All rights reserved. Zend Technologies, Inc.
Generate PSR-0/4 classmap
for fast autoloading
MORE ON PACKAGES &
REPOSITORIES
31
© All rights reserved. Zend Technologies, Inc.
Where Does Composer Obtain Dependencies?
Composer downloads packages from repositories
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
32
© All rights reserved. Zend Technologies, Inc.
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!
• Don’t be cute or cryptic (with vendor or package name)
• Name should reflect package purpose
33
© All rights reserved. Zend Technologies, Inc.
Packages - composer.json – Real Example
{
34
"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)
© All rights reserved. Zend Technologies, Inc.
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)
35
© All rights reserved. Zend Technologies, Inc.
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
36
© All rights reserved. Zend Technologies, Inc.
Platform / Virtual Packages
Not Installable by Composer, Used for checking only
•
•
•
•
•
37
php – PHP version of the server Composer is installing packages to
hhvm (not applicable for IBM i)
ext-<name>
• “ext-ibm_db2” : “*”
lib-<name>
• curl
• iconv
• icu
• libxml
• openssl
• pcre
• uuid
• xsl
composer show --platform for a list of available platform packages
© All rights reserved. Zend Technologies, Inc.
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
38
© All rights reserved. Zend Technologies, Inc.
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 / Browseable
• Less work for people to find and use your package.
• Many, many, many packages available. Duplication.
39
© All rights reserved. Zend Technologies, Inc.
https://packagist.org/
40
© All rights reserved. Zend Technologies, Inc.
Private Repositories – Satis and Torin Proxy
Torin / Satis
Your Application
Proxy
Packagist.org
41
Satis – free
TorinProxy.com – license
fees support development
of Composer
© All rights reserved. Zend Technologies, Inc.
Public
Repositories
Private Repositories – Local Packagist
Your Application
composer.json /
composer.lock
Private
Repository
42
© All rights reserved. Zend Technologies, Inc.
SEMANTIC VERSIONING
43
© All rights reserved. Zend Technologies, Inc.
Semantic Versioning http://semver.org/
Version Numbers Have Meaning
Essentially, it is a promise from the development team
Not a guarantee, but a best effort
1.2.3 – numbers increment, can have pre-release suffix
Major.Minor.Patch
Patch: bug fixes; no BC breaks!; everyone using the package
should be confident in moving from 1.2.3 to 1.2.4
• Minor: introduce new features, but change no APIs; no BC breaks!
Changing internals should not affects 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.
•
•
•
•
•
44
© All rights reserved. Zend Technologies, Inc.
Semantic Versioning
Shortcut notations in Composer for version specifications
•
•
•
•
•
•
45
“Next Significant Release”
^1.2.3 means 1.2.3 <= x < 2.0.0
>=1.2.3,<2.0.0
Specifies a min version; last number specified can increment
Next Significant Release
~1.2.3 means 1.2.0 <= x < 1.3.0
>=1.2,<1.3.0
Specifies a min version; last number specified can increment;
assured none breaking changes will be accepted
© All rights reserved. Zend Technologies, Inc.
Best Practices
Do’s and Don’ts:
•
•
•
•
Unbound Version Constraints
Version Constraints combined with Wildcards
Wildcards by themselves
Install or update to the intended directory
Be careful out there!
46
© All rights reserved. Zend Technologies, Inc.
Best Practices / Do’s and Don’ts
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 or >=2.3
47
© All rights reserved. Zend Technologies, Inc.
Best Practices / Do’s and Don’ts
Do NOT attempt to specify a version constraint with a wildcard:
•
•
•
•
•
Example: >=2.*
Example: >=1.1.*
>=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 or >=2,<=3
Best Practice: ^2 (for semantic versioning)
48
© All rights reserved. Zend Technologies, Inc.
Best Practices / Do’s and Don’ts
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: use ~1.2.0 or >=1.2.0,<2.0.0
SemVer Best Practice: ^1
49
© All rights reserved. Zend Technologies, Inc.
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.
50
© All rights reserved. Zend Technologies, Inc.
Resources
•
•
•
•
•
•
•
•
•
•
•
•
•
51
Composer Manual - https://getcomposer.org/doc/
Semantic Versioning - http://semver.org/
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/composerschema.json
http://stackoverflow.com/questions/tagged/composer-php
Zend Webinars - http://www.zend.com/en/resources/webinars
http://www.zend.com/en/resources/news-and-events/newsroom
Latest Updates / Slides for this talk – http://clarkeveretts.com/
© All rights reserved. Zend Technologies, Inc.
THANK-YOU
[email protected]
+ClarkEverettsAtZend
@clarkphp
Slides for this talk are at http://clarkeveretts.com/ and COMMON site
52
© All rights reserved. Zend Technologies, Inc.