Upgrade to Pro — share decks privately, control downloads, hide ads and more …

Package development - Istanbul PHP

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?

39eb3f3d313b13f05534e496285040b8?s=128

Hannes Van De Vreken

May 21, 2016
Tweet

Transcript

  1. Package development Istanbul PHP ! @hannesvdvreken @istanbulphp

  2. Hi, my name is Hannes.

  3. "

  4. madewithlove.be 20 × "&'()*

  5. None
  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.

  9. None
  10. None
  11. None
  12. BEGINNER STEPS No renaming keep the old one, but create

    a new
  13. None
  14. None
  15. https:/ /seld.be/notes/common-files-in-php-packages

  16. https:/ /seld.be/notes/common-files-in-php-packages

  17. None
  18. BEGINNER STEPS Instructions to install composer require guzzlehttp/guzzle

  19. BEGINNER STEPS Instructions to install NOT: “add guzzlehttp/guzzle to your

    composer.json”
  20. None
  21. None
  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')); }); }
  24. None
  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
  28. None
  29. BEGINNER STEPS - TESTS/SPECS Not just the happy path

  30. BEGINNER STEPS - TESTS/SPECS It’s your insurance in multiple ways

  31. None
  32. None
  33. BEGINNER STEPS - VERSIONING semver.org read it

  34. BEGINNER STEPS - VERSIONING Release often

  35. None
  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

  39. None
  40. changehub.io

  41. BEGINNER STEPS - CHANGELOG upgrade.md

  42. BEGINNER STEPS - CHANGELOG Release often

  43. None
  44. None
  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!

  50. None
  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');
  53. None
  54. BEGINNER STEPS No license is the worst http:/ /choosealicense.com/

  55. None
  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
  85. None
  86. concept virtual package is a high level placeholder for a

    dependency on a more low level implementation STABILITY - DECOUPLING
  87. None
  88. None
  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)
  99. None
  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