1. @colinodell
Releasing High-Quality
Packages
@colinodell

2. @colinodell@colinodell
PHP League Leadership Team
Maintainer of popular packages:
league/commonmark
league/html-to-markdown
colinodell/json5
Colin O'Dell
Lead Developer &
DevOps Engineer at
Unleashed Technologies

3. @colinodell
What Are Packages?
Reusable libraries;
installed via Composer

4. @colinodell
PEAR / PHPClasses.org

5. @colinodell
PHP-FIG, PSR-0, & Composer
2009: Framework Interoperability Group adopts PSR-0 autoloading
standard
2011: Composer development begins
2012: Composer released with PSR-0 support
Today: 197,000
Packages on Packagist
1.4 million
Unique Releases

6. @colinodell
Package Benefits
• Pre-written
• Reusable
• Community-maintained
• Framework-agnostic
• Easily installed
• Robust dependency resolution

7. @colinodell
Releasing Your Own Packages

8. @colinodell
Overview
Definition of Quality
Project Structure
Testing
Packaging
Releasing
Ongoing Maintenance
Development Best Practices

9. @colinodell

10. @colinodell
Project Structure

11. @colinodell
Project
Structure

12. @colinodell
Project & Vendor Name
There are only two hard things in Computer
Science: cache invalidation and naming things.
-- Phil Karlton

13. @colinodell
Project & Vendor Name
PHP namespace = VendorNameProjectName
Packagist repo = vendor-name/project-name
• Two parts:
• Vendor = person, group, company, or organization
• Project = individual package
• Choosing a vendor name:
• Available
• Unique
• Easy to search
• Make names consistent

14. @colinodell

15. @colinodell
composer.json
• Meta info
• Project dependencies
• Include PHP version &
extensions
• Development dependencies
• Autoloading configuration
• PSR-4 not PSR-0
• Separate namespace
for tests

16. @colinodell
Source
Code

17. @colinodell
Source Code
• Minimal dependencies; wide
constraint ranges
• Make framework agnostic
• Service providers for specific
frameworks okay
• Provide interfaces
• Use community standards (PSRs)
• Follow best practices and design
principles
• Consistent coding style (PSR-2?)

18. @colinodell
Project Hosting
Features:
• Project downloads
• Issue reporting
• Pull requests / code reviews
• Collaboration
• CI integrations

19. @colinodell
Testing
Automating the testing process

20. @colinodell
Automated
Tests

21. @colinodell
Unit Tests
• Test individual
components
• PHPUnit – defacto
standard
• Aim for 80% code
coverage

22. @colinodell

23. @colinodell
Automated Tests
• Not just unit tests:
• Functional tests
• Integration tests
• Acceptance tests
• Other good test frameworks:
• Phpspec
• Behat
• Codeception
• Use continuous integration!

24. @colinodell
Continuous Integration

25. @colinodell
Continuous Integration

26. @colinodell
Continuous Integration
• Run tests…
• Across all supported PHP versions
• Against future PHP versions
• Using minimal/older Composer
constraints
• Track code quality
• Scrutinizer CI
• Check code style
• StyleCI
• PHPCS

27. @colinodell
.travis.yml

28. @colinodell
.styleci.yml

29. @colinodell

30. @colinodell
Project
Structure

31. @colinodell
Packaging
Getting the code ready for distribution

32. @colinodell
Licensing
• Distribution
• Attribution
•Modifications
•Commercial Use
Permissive: MIT; BSD; ISC
Prevent Closed Source: GPLv3; Mozilla Public License
Documentation: Creative Commons

33. @colinodell
Licensing
• choosealicense.com
• creativecommons.org/choose

34. @colinodell
Licensing

35. @colinodell
Licensing

36. @colinodell
Project
Structure

37. @colinodell
Documentation:
README.md
• Badges
• What problem your package solves
• Installation steps
• Sample Usage
• Configuration

38. @colinodell
Documentation:
docblocks
Benefits:
• Read docs while coding
• IDE auto-completion
• Short description
• Parameter types, names, and
purposes
• Return types
• Any thrown exceptions

39. @colinodell
Documentation:
RTFM
• Advanced usage or configuration
• Additional code samples
• Other functionality
Where to host?
• GitHub Pages
• Jekyll
• MkDocs
• Other static site generator
• readthedocs.org
• Your own hosting

40. @colinodell
Archive Settings
Package consumers (probably) don’t want:
• Tests
• Dev dependencies
• Issue / PR templates
• Travis CI configuration
• Your .gitignore development settings

41. @colinodell
Archive Settings - .gitattributes

42. @colinodell
Archive Settings:
composer.json
{
{

43. @colinodell
Project
Structure

44. @colinodell
Packagist.org

45. @colinodell
Releasing
Launching your package

46. @colinodell
Semantic Versioning – semver.org
x . y . zMajor . Minor . Patch

47. @colinodell
Semantic Versioning – semver.org
2 . 4 . 5Major . Minor . Patch
Incompatible
Changes
Backwards-
Compatible;
New Features
Bug Fixes

48. @colinodell
2 . 4 . 6
2 . 4 . 5Major . Minor . Patch
Incompatible
Changes
Backwards-
Compatible;
New Features
Bug Fixes

49. @colinodell
2 . 5 . 0
2 . 4 . 5Major . Minor . Patch
Incompatible
Changes
Backwards-
Compatible;
New Features
Bug Fixes

50. @colinodell
3 . 0 . 0
2 . 4 . 5Major . Minor . Patch
Incompatible
Changes
Backwards-
Compatible;
New Features
Bug Fixes

51. @colinodell
Semantic Versioning – semver.org
0 . x . yMajor . Minor . Patch
Any 0.x.y release may break backwards compatibility!
My recommendation: treat X.Y as major.minor

52. @colinodell
CHANGELOG.md
• Follow https://keepachangelog.com

53. @colinodell

54. @colinodell
UPGRADE.md
• Documentation on upgrading between major versions
• Describe BC breaks
• Provide instructions for users to update their code

55. @colinodell

56. @colinodell
Tagging a
Release

57. @colinodell
Released!

58. @colinodell
Project
Structure

59. @colinodell
Ongoing Maintenance
Addressing issues, handling PRs, and maintaining your community

60. @colinodell
Maintainer Responsibilities
• Be responsive
• Triage issues; keep queue clean
• Review PRs & provide feedback
• Share responsibility with core contributors

61. @colinodell
CONTRIBUTING.md
• Requirements
• Considerations
• Process
• Tips

62. @colinodell
Issue / PR Templates

63. @colinodell
Issue / PR Templates

64. @colinodell
Issue / PR Templates

65. @colinodell
Issue / PR Templates

66. @colinodell
CODE_OF_CONDUCT.md
• Expresses values and rules that contributors should adhere to
• Promotes inclusion and contributions
• Defines unacceptable behavior and enforcement
• https://www.contributor-covenant.org/

67. @colinodell
.editorconfig
• Defines preferred indentation style and line breaks
• Automatically configures contributor IDEs
• Most major IDEs supported

68. @colinodell
.gitignore
Ensures certain files are never committed to Git

69. @colinodell
Project
Structure

70. @colinodell
Further Reading
Additional information and resources on creating high-quality PHP packages

71. @colinodell
Further Reading
• https://github.com/thephpleague/skeleton
• http://phppackagechecklist.com
• https://getcomposer.org/doc/04-schema.md
• https://leanpub.com/principles-of-package-design

72. @colinodell
Questions?

73. @colinodell
Feedback Appreciated!
https://joind.in/talk/42353
@colinodell
Thanks!