Package development - Istanbul PHP

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 Istanbul PHP ! @hannesvdvreken @istanbulphp
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
16. https:/ /seld.be/notes/common-files-in-php-packages
18. BEGINNER STEPS Instructions to install composer require guzzlehttp/guzzle
19. BEGINNER STEPS Instructions to install NOT: “add guzzlehttp/guzzle to your composer.json”
22. 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')) }); }
23. 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')); }); }
25. BEGINNER STEPS - CODE STYLE Recommendations: PSR-2
26. BEGINNER STEPS - CODE STYLE Use of tooling phpcs, php-cs-fixer
27. BEGINNER STEPS - CODE STYLE Do it early boy-scouting file-per-file git blame open pull requests
29. BEGINNER STEPS - TESTS/SPECS Not just the happy path
30. BEGINNER STEPS - TESTS/SPECS It’s your insurance in multiple ways
33. BEGINNER STEPS - VERSIONING semver.org read it
34. BEGINNER STEPS - VERSIONING Release often
36. BEGINNER STEPS - CHANGELOG Document releases changelog.md
37. 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.
38. BEGINNER STEPS - CHANGELOG keepachangelog.com
40. changehub.io
41. BEGINNER STEPS - CHANGELOG upgrade.md
42. BEGINNER STEPS - CHANGELOG Release often
45. BEGINNER STEPS GitHub PC test service packagist
46. BEGINNER STEPS GitHub PC test service packagist git push
47. BEGINNER STEPS GitHub PC test service packagist webhook webhook
48. BEGINNER STEPS GitHub PC test service packagist analyses composer.json /stores version runs tests
49. BEGINNER STEPS GitHub PC test service packagist status green!
51. BEGINNER STEPS - README.MD Code samples copy-paste
52. 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');
54. BEGINNER STEPS No license is the worst http:/ /choosealicense.com/
56. BEGINNER STEPS - CONTRIBUTING Instructions how to test how to make pull request philosophy
57. BEGINNER STEPS Congrats, you’re no longer a newbie!
58. 2. Environments
59. INTERMEDIATE TIPS - ENVIRONMENTS Packages have environments too
60. INTERMEDIATE TIPS - ENVIRONMENTS dev/local test/ci production
61. INTERMEDIATE TIPS - ENVIRONMENTS - DEV & CI not in production: composer require --dev also installs require-dev dependencies
62. INTERMEDIATE TIPS - ENVIRONMENTS - CI CI only: code coverage reporting
63. INTERMEDIATE TIPS - ENVIRONMENTS - CI phpunit --coverage-html=/tmp/coverage/; vs phpunit --coverage-clover=/tmp/coverage.xml; ocular code-coverage:upload /tmp/coverage.xml;
64. INTERMEDIATE TIPS - ENVIRONMENTS - PROD Keep your tests out of other peoples production
65. INTERMEDIATE TIPS - CLEAN DISTS --prefer-dist
66. INTERMEDIATE TIPS - CLEAN DISTS .gitattributes
67. .gitattributes
68. INTERMEDIATE TIPS - CLEAN DISTS "autoload": { "psr-4": { "GuzzleHttp\\": "src/" } }, "autoload-dev": { "psr-4": { "GuzzleHttp\\Stubs\\": "tests/stubs/" } }
69. INTERMEDIATE TIPS - COMPOSER SCRIPTS Don’t do composer require --global when you need it in CI
70. INTERMEDIATE TIPS - COMPOSER SCRIPTS dev-dependencies + composer scripts
71. INTERMEDIATE TIPS - COMPOSER SCRIPTS "require-dev": { "phpunit/phpunit": "~1.0", }, "scripts": { "unit-tests": "phpunit —coverage-clover…" },
72. INTERMEDIATE TIPS - RECAP - dev dependencies - exclude files from distributions - composer scripts
73. 3. Package stability
74. STABILITY As package maintainer: Less major releases
75. STABILITY If a dependency has new major version, your package needs new major version.
76. Trick #1 STABILITY
77. Keep number of hard requirements low STABILITY
78. STABILITY - SOFT-REQUIREMENTS Soft requirements eg: use decorators
79. use Psr\Cache\CacheItemPool; class CacheDecorator implements … { … } STABILITY - SOFT-REQUIREMENTS
80. STABILITY - SOFT-REQUIREMENTS Even better: separate package
81. { "name": "league/flysystem-eventable-filesystem", "require": { "php": ">=5.4.0", "league/event": "~1.0", "league/flysystem": "~1.0" }, … STABILITY - SOFT-REQUIREMENTS
82. Trick #2 STABILITY - DECOUPLING
83. Depend on interface packages STABILITY - DECOUPLING
84. STABILITY - DECOUPLING Interface packages: - only interfaces - zero dependencies
86. concept virtual package is a high level placeholder for a dependency on a more low level implementation STABILITY - DECOUPLING
89. company/sdk requires (1.0.0) psr/cache-implementation requires (1.0.0) psr/cache
90. psr/cache-implementation provides (1.0.0) requires (1.0.0) league/flysystem requires (^1.0) cache/filesystem-adapter psr/cache
91. company/sdk application requires (x.y.z) requires (1.0.0) psr/cache-implementation
92. 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
93. STABILITY - DECOUPLING - BENEFITS Users can choose low level packages they want
94. STABILITY - DECOUPLING - BENEFITS Users don’t get locked-in to a major version
95. Prefer having less hard dependencies STABILITY - RECAP
96. Prefer requiring stabler packages STABILITY - RECAP
97. STABILITY - RECAP Prefer requiring virtual packages
98. DECOUPLING - OTHER CASES - Logging (PSR-3) - HTTP (PSR-7) - Caching (PSR-6) - File system (Flysystem)
100. Semver checker ^ vs ~ Marketing Communication (empathy)
101. RECAP 1. Beginner steps 2. Environments 3. Stability
102. Thank you! https:/ /joind.in/talk/7186c @hannesvdvreken @istanbulphp Thank you!
103. Time for questions. @hannesvdvreken @istanbulphp
104. • http:/ /mwl.be REFERENCES