The document provides a comprehensive guide on releasing high-quality PHP packages, detailing best practices in project structure, testing, packaging, and ongoing maintenance. It emphasizes the importance of using semantic versioning, documentation, licensing, and community engagement for successful package management. Additionally, it includes resources and tools for developers to facilitate the process of creating and maintaining packages.

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
Director of Technology
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: 213,660
Packages on Packagist
1.6 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
Definition of Quality
Semantically
Versioned
Actively
Maintained
User Friendly Composer
Installable
Extensively
Documented
S A U C E

11. @colinodell
Project Structure

12. @colinodell
Project
Structure

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

14. @colinodell
Project & Vendor Name
PHP namespace = VendorNameProjectName
Packagist repo = vendor-name/project-name
• Choosing a name:
• Available
• Unique/memorable
• Easy to search
• Make names consistent

15. @colinodell

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

17. @colinodell
Source
Code

18. @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?)

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

20. @colinodell
Testing
Automating the testing process

21. @colinodell
Automated
Tests

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

23. @colinodell

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

25. @colinodell
Continuous Integration

26. @colinodell
Continuous Integration

27. @colinodell
Continuous Integration
• Run tests across all supported
versions
• Track code quality
• Scrutinizer CI
• Check code style
• StyleCI
• PHPCS

28. @colinodell
.travis.yml

29. @colinodell
.styleci.yml

30. @colinodell

31. @colinodell
Project
Structure

32. @colinodell
Packaging
Getting the code ready for distribution

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

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

35. @colinodell
Licensing

36. @colinodell
Licensing

37. @colinodell
Project
Structure

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

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

40. @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

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

42. @colinodell
Archive Settings - .gitattributes

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

44. @colinodell
Project
Structure

45. @colinodell
Packagist.org

46. @colinodell
Releasing
Launching your package

47. @colinodell
Semantic Versioning – semver.org
1.0.0 (stable)
or
0.1.0 (unstable)

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

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

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

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

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

53. @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

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

55. @colinodell

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

57. @colinodell

58. @colinodell
Tagging a
Release

59. @colinodell
Released!

60. @colinodell
Project
Structure

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

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

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

64. @colinodell
Issue / PR Templates

65. @colinodell
Issue / PR Templates

66. @colinodell
Issue / PR Templates

67. @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/

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

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

70. @colinodell
Project
Structure

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

72. @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

73. @colinodell
Questions?

74. @colinodell
@colinodell
Thanks!