Package development - PHP Tour

Registering your new awesome package to packagist is easy. But what about maintainability? What dependencies should you avoid? Have you considered reducing download size? How will you keep your users up to date with changes in newer versions? How do you best handle releases? How do you manage your package to behave in an optimal way both in other people's production environment as in your local package development environment?

Transcript

1. Package development #phptour ! @hannesvdvreken @afup
2. Hi, my name is Hannes.
3. "
4. madewithlove.be 20 × "&!'()
6. Package development Intermediate and advanced techniques
7. 1. Beginner steps 2. Environments 3. Package stability
8. 1. Beginner steps Everyone started out as a newbie.
12. BEGINNER STEPS No renaming keep the old one, but create a new
15. https:/ /seld.be/notes/common-files-in-php-packages
17. BEGINNER STEPS Instructions to install composer require guzzlehttp/guzzle
18. BEGINNER STEPS Instructions to install NOT: “add guzzlehttp/guzzle to your composer.json”
21. BEGINNER STEPS - VERSIONS Class Sdk { public function __construct(Framework\Config) { … } } /** * Register method. */ public function register() { // Register SDK class. $this->container->share('twilio', function () { return new Sdk($this->container->make('config')) }); }
22. BEGINNER STEPS - VERSIONS Class Sdk { public function __construct(array $options) { … } } /** * Register method. */ public function register() { // Register SDK class. $this->container->share('twilio', function () { $config = $this->app->get('config'); return new Sdk($config->get('services.twilio')); }); }
24. BEGINNER STEPS - CODE STYLE Recommendations: PSR-2
25. BEGINNER STEPS - CODE STYLE Use of tooling phpcs, php-cs-fixer
26. BEGINNER STEPS - CODE STYLE Do it early boy-scouting file-per-file git blame open pull requests
28. BEGINNER STEPS - TESTS/SPECS Not just the happy path
29. BEGINNER STEPS - TESTS/SPECS It’s your insurance in multiple ways
32. BEGINNER STEPS - VERSIONING semver.org read it
33. BEGINNER STEPS - VERSIONING Release often
35. BEGINNER STEPS - CHANGELOG Document releases changelog.md
36. BEGINNER STEPS - CHANGELOG # Change Log All notable changes to this project will be documented in this file. This project adheres to [Semantic Versioning](http://semver.org/). ## [Unreleased][unreleased] ### Changed - Improve argument against commit logs. ## [0.0.8] - 2015-02-17 ### Changed - Update year to match in every README example. - Reluctantly stop making fun of Brits only, since most of the world writes dates in a strange way. ### Fixed - Fix typos in recent README changes. - Update outdated unreleased diff link.
37. BEGINNER STEPS - CHANGELOG keepachangelog.com
39. changehub.io
40. BEGINNER STEPS - CHANGELOG upgrade.md
41. BEGINNER STEPS - CHANGELOG Release often
44. BEGINNER STEPS GitHub PC test service packagist
45. BEGINNER STEPS GitHub PC test service packagist git push
46. BEGINNER STEPS GitHub PC test service packagist webhook webhook
47. BEGINNER STEPS GitHub PC test service packagist analyses composer.json /stores version runs tests
48. BEGINNER STEPS GitHub PC test service packagist status green!
50. BEGINNER STEPS - README.MD Code samples copy-paste
51. BEGINNER STEPS - README.MD // open an image file $img = Image::make('public/foo.jpg'); // resize image instance $img->resize(320, 240); // insert a watermark $img->insert('public/watermark.png'); // save image in desired format $img->save('public/bar.jpg');
53. BEGINNER STEPS No license is the worst http:/ /choosealicense.com/
55. BEGINNER STEPS - CONTRIBUTING Instructions how to test how to make pull request philosophy
56. BEGINNER STEPS Congrats, you’re no longer a newbie!
57. 2. Environments
58. INTERMEDIATE TIPS - ENVIRONMENTS Packages have environments too
59. INTERMEDIATE TIPS - ENVIRONMENTS dev/local test/ci production
60. INTERMEDIATE TIPS - ENVIRONMENTS - DEV & CI not in production: composer require --dev also installs require-dev dependencies
61. INTERMEDIATE TIPS - ENVIRONMENTS - CI CI only: code coverage reporting
62. INTERMEDIATE TIPS - ENVIRONMENTS - CI phpunit --coverage-html=/tmp/coverage/; vs phpunit --coverage-clover=/tmp/coverage.xml; ocular code-coverage:upload /tmp/coverage.xml;
63. INTERMEDIATE TIPS - ENVIRONMENTS - PROD Keep your tests out of other peoples production
64. INTERMEDIATE TIPS - CLEAN DISTS --prefer-dist
65. INTERMEDIATE TIPS - CLEAN DISTS .gitattributes
66. .gitattributes
67. INTERMEDIATE TIPS - CLEAN DISTS "autoload": { "psr-4": { "GuzzleHttp\\": "src/" } }, "autoload-dev": { "psr-4": { "GuzzleHttp\\Stubs\\": "tests/stubs/" } }
68. INTERMEDIATE TIPS - COMPOSER SCRIPTS Don’t do composer require --global when you need it in CI
69. INTERMEDIATE TIPS - COMPOSER SCRIPTS dev-dependencies + composer scripts
70. INTERMEDIATE TIPS - COMPOSER SCRIPTS "require-dev": { "phpunit/phpunit": "~1.0", }, "scripts": { "unit-tests": "phpunit —coverage-clover…" },
71. INTERMEDIATE TIPS - RECAP - dev dependencies - exclude files from distributions - composer scripts
72. 3. Package stability
73. STABILITY As package maintainer: Less major releases
74. STABILITY If a dependency has new major version, your package needs new major version.
75. Trick #1 STABILITY
76. Keep number of hard requirements low STABILITY
77. STABILITY - SOFT-REQUIREMENTS Soft requirements eg: use decorators
78. use Psr\Cache\CacheItemPool; class CacheDecorator implements … { … } STABILITY - SOFT-REQUIREMENTS
79. STABILITY - SOFT-REQUIREMENTS Even better: separate package
80. { "name": "league/flysystem-eventable-filesystem", "require": { "php": ">=5.4.0", "league/event": "~1.0", "league/flysystem": "~1.0" }, … STABILITY - SOFT-REQUIREMENTS
81. Trick #2 STABILITY - DECOUPLING
82. Depend on interface packages STABILITY - DECOUPLING
83. STABILITY - DECOUPLING Interface packages: - only interfaces - zero dependencies
85. concept virtual package is a high level placeholder for a dependency on a more low level implementation STABILITY - DECOUPLING
88. company/sdk requires (1.0.0) psr/cache-implementation requires (1.0.0) psr/cache
89. psr/cache-implementation provides (1.0.0) requires (1.0.0) league/flysystem requires (^1.0) cache/filesystem-adapter psr/cache
90. company/sdk application requires (x.y.z) requires (1.0.0) psr/cache-implementation
91. company/sdk requires (1.0.0) psr/cache-implementation provides (1.0.0) requires (1.0.0) application requires (x.y.z) requires (0.5.0) requires (1.0.0) cache/filesystem-adapter psr/cache requires (^1.0) league/flysystem
92. STABILITY - DECOUPLING - BENEFITS Users can choose low level packages they want
93. STABILITY - DECOUPLING - BENEFITS Users don’t get locked-in to a major version
94. Prefer having less hard dependencies STABILITY - RECAP
95. Prefer requiring stabler packages STABILITY - RECAP
96. STABILITY - RECAP Prefer requiring virtual packages
97. DECOUPLING - OTHER CASES - Logging (PSR-3) - HTTP (PSR-7) - Caching (PSR-6) - File system (Flysystem)
99. Semver checker ^ vs ~ Marketing Communication (empathy)
100. RECAP 1. Beginner steps 2. Environments 3. Stability
101. Thank you! https:/ /joind.in/talk/28a72 @hannesvdvreken @afup
102. First: Questions, Then: Lunch! @hannesvdvreken @afup
103. • http:/ /mwl.be REFERENCES