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

Package development - PHP Tour

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?

39eb3f3d313b13f05534e496285040b8?s=128

Hannes Van De Vreken

May 24, 2016
Tweet

More Decks by Hannes Van De Vreken

Other Decks in Technology

Transcript

  1. Package development #phptour ! @hannesvdvreken @afup

  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. None
  17. BEGINNER STEPS Instructions to install composer require guzzlehttp/guzzle

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

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

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

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

  33. BEGINNER STEPS - VERSIONING Release often

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

  38. None
  39. changehub.io

  40. BEGINNER STEPS - CHANGELOG upgrade.md

  41. BEGINNER STEPS - CHANGELOG Release often

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

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

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

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