The document provides guidance on creating and maintaining high-quality PHP packages. It discusses defining quality standards, project structure, testing, documentation, releasing packages, and ongoing maintenance. Key aspects include using semantic versioning, writing automated tests, generating documentation, following best practices for code quality, and being responsive to issues and pull requests. The goal is to create packages that are easily installed, well-maintained, and meet community standards.

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
Principal Engineer
at Unleashed Technologies

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

4. @colinodell
PEAR / PHPClasses.org

5. @colinodell

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

7. @colinodell
PHP-FIG, PSR-0, & Composer
321,100
Packages on Packagist
3.1 million
Unique Releases

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

9. @colinodell
Releasing Your Own Packages

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

11. @colinodell

12. @colinodell
Definition of Quality
Semantically
Versioned
Actively
Maintained
User Friendly Composer
Installable
Extensively
Documented
S A U C E

13. @colinodell
Project Structure

14. @colinodell
Project
Structure

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

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

17. @colinodell

18. @colinodell
composer.json

19. @colinodell
composer.json
• Project dependencies
• Include PHP version &
extensions

20. @colinodell
composer.json
• Project dependencies
• Include PHP version &
extensions
• Development dependencies

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

22. @colinodell
Source
Code

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

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

25. @colinodell
Testing
Automating the testing process

26. @colinodell
Automated
Tests

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

28. @colinodell

29. @colinodell
Automated Tests
• Not just unit tests:
• Functional tests
• Integration tests
• Acceptance tests
• Other good test frameworks:
• Phpspec
• Behat
• Codeception
• Don’t forget static analysis!

30. @colinodell
Static Analysis
Automated analysis of source code without executing the application
Checks for:
• Missing or incorrect type hints (param/return types and docblocks)
• Type errors
• Existence of methods and properties
• Unnecessary/useless code
• Correct argument types passed to (s)printf()
• etc.
Supports generics too!

31. @colinodell
Static Analysis

32. @colinodell
phpstan.neon.dist

33. @colinodell
psalm.xml

34. @colinodell
Continuous Integration

35. @colinodell
Continuous Integration
GitHub Actions

36. @colinodell
Continuous Integration
• Run tests across all supported
versions
• PHPUnit
• Check code style
• PHPCS
• Static code analysis
• Psalm
• PHPStan
• Track code quality metrics
• Scrutinizer CI

37. @colinodell
GitHub Actions
.github/workflows/tests.yml

38. @colinodell
phpcs.xml.dist

39. @colinodell

40. @colinodell
Project
Structure

41. @colinodell
Packaging
Getting the code ready for distribution

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

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

44. @colinodell
Licensing

45. @colinodell
Licensing

46. @colinodell
Project
Structure

47. @colinodell
Documentation:
README.md
• What problem your package solves
• Installation steps
• Configuration
• Sample Usage
• FAQs
• Link to more comprehensive docs
• Badges!

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

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

50. @colinodell
Archive Settings
Package consumers (probably) don’t want:
• Tests
• Dev dependencies
• Issue / PR templates
• GitHub Actions configuration
• Your .gitignore development settings
• Images used in README

51. @colinodell
Archive Settings - .gitattributes

52. @colinodell
Archive Settings:
composer.json
{

53. @colinodell
Project
Structure

54. @colinodell
Packagist.org

55. @colinodell
Releasing
Launching your package

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

57. @colinodell
Semantic Versioning – semver.org
x . y . z
Major . Minor . Patch

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

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

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

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

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

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

64. @colinodell

65. @colinodell
Upgrading Notes
• Documentation on upgrading between major versions
• Describe BC breaks
• Provide instructions for users to update their code
UPGRADE.md file or in site docs

66. @colinodell

67. @colinodell
Tagging a
Release

68. @colinodell
Tagging a
Release

69. @colinodell
Tagging a
Release

70. @colinodell
Released!

71. @colinodell
Project
Structure

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

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

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

75. @colinodell
Issue / PR Templates

76. @colinodell
Issue / PR Templates

77. @colinodell
Issue / PR Templates

78. @colinodell

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

80. @colinodell

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

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

83. @colinodell
Project
Structure

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

85. @colinodell
Further Reading
• https://github.com/thephpleague/skeleton
• http://phppackagechecklist.com
• https://getcomposer.org/doc/04-schema.md
• https://packagist.org/?type=phpcodesniffer-standard
• https://medium.com/bumble-tech/php-code-static-analysis-based-on-the-
example-of-phpstan-phan-and-psalm-a20654c4011d
• https://leanpub.com/principles-of-package-design

86. @colinodell
Questions?
Slides / Feedback: https://joind.in/talk/e81ae

87. @colinodell
Thank you!
Slides / Feedback: https://joind.in/talk/e81ae