Let's Build a Composer Package (php[world] 2019)

Let's Build a Composer Package (php[world] 2019)

You've downloaded and installed open source libraries, required them as Composer dependencies, and perused the source code of countless GitHub repositories. Now, you're ready to help others by creating your own Composer package. So, what does it take to build and publish an open source library? In this session, we'll take a look at some of the common patterns open source PHP libraries follow. Along the way, we'll cover: evaluating libraries for quality, common filesystem structures, the importance of tests and how to run them on Travis CI, publishing to Packagist, interacting with a community, and more. By the end of this workshop, you will have all the tools you need to distribute your own Composer package.

0c217b9a7dd0aa31ed40bd0f453727e1?s=128

Ben Ramsey

October 24, 2019
Tweet

Transcript

  1. Let’s Build a Composer Package Ben Ramsey
 24 Oct 2019

    • php[world]
  2. Hi. I’m Ben. - Organizer at Nashville PHP - Open

    source advocate - ramsey/uuid library - Craft beer nerd - @ramsey on Twitter - @ramsey@phpc.social on Mastodon
  3. - Learn the properties of a “good” package - Create

    a package - Push your package to a repository - Connect your repo to Travis CI & Coveralls - Publish your package on Packagist You will:
  4. Requirements. - PHP 7.2+ - Composer

  5. Homebrew: brew.sh 
 brew install php@7.2 export PATH="/usr/local/opt/php@7.2/bin:$PATH" php -v

    macOS
  6. None
  7. Web Platform Installer:
 microsoft.com/web/downloads/platform.aspx php -v Windows

  8. None
  9. None
  10. Use your favorite package manager. *nix

  11. Composer Install Composer: getcomposer.org/download php composer.phar --version Or composer --version

  12. None
  13. None
  14. Getting started.

  15. What problem do you want to solve?

  16. You own the code. How do you want others to

    use it?
  17. None
  18. - MIT license - BSD 2-Clause “Simplified” - Apache License

    2.0 - GNU Library or “Lesser” General Public License (LGPL)
  19. Now we can begin.

  20. The project.

  21. github.com/ramsey/php-library-skeleton

  22. None
  23. Let’s Build!

  24. Maintaining your package.

  25. - Add your tests/ directory - Add your docs/ directory

    - Add your phpunit.xml.dist file Add anything that shouldn’t be bundled into the distribution when someone requires your package with Composer. .gitattributes
  26. .gitattributes export-ignore .github/ export-ignore .gitignore export-ignore .travis.yml export-ignore docs/ export-ignore

    phpstan.neon export-ignore phpunit.xml.dist export-ignore tests/ export-ignore
  27. - PHPUnit, Atoum, Kahlan, etc. - Aim for sufficient code

    coverage - Make it easy to run your tests:
 composer test Testing.
  28. - PHPStan, Exakat, Phan, Psalm, PHP Inspections (JetBrains), etc. -

    Finds errors in your code without running it - Especially helpful when multiple people are working on the same project Static analysis.
  29. - PSR-12, Symfony, CakePHP, WordPress, etc. - Use PHP_CodeSniffer to

    ensure your code follows your chosen standards - Catch standards issues before code review Coding standards.
  30. - Just like with npm and package.json, Composer supports custom

    scripts - Custom scripts can help your contributors - Use them to consolidate tools into simple, easy-to-remember commands Scripts.
  31. "scripts": { "lint": "parallel-lint src tests", "phpcs": "phpcs src tests

    --standard=psr12 -sp --colors", "phpstan": [ "phpstan analyse src -c phpstan.neon --level max --no-progress", "phpstan analyse tests -c phpstan.neon --level 4 --no-progress" ], "phpunit": "phpunit --verbose --colors=always", "phpunit-ci": "phpunit --coverage-clover build/logs/clover.xml", "phpunit-coverage": "phpunit --coverage-html build/coverage", "test": ["@lint", "@phpcs", "@phpstan", "@phpunit"], "test-ci": ["@lint", "@phpcs", "@phpstan", "@phpunit-ci"] }
  32. None
  33. - Tells your users what has changed between versions -

    Log changes, no matter how big or small - Log what you’ve added, changed, deprecated, removed, fixed, & secured Changelog.
  34. None
  35. - Follow semantic versioning - Backwards-compatibility breaks? - Major release

    - New features that don’t break BC? - Minor release - Bug fixes that don’t break BC? - Patch release Versioning.
  36. None
  37. Building your community.

  38. Readme.

  39. None
  40. Contributing.

  41. None
  42. Templates.

  43. None
  44. Code of conduct.

  45. None
  46. Automation.

  47. None
  48. None
  49. Publishing.

  50. None
  51. Enjoy the FOSS community.

  52. Use a welcoming voice.

  53. Build up. Don’t tear down.

  54. None
  55. LINKS TO RESOURCES 1. Composer: https://getcomposer.org/ 2. Packagist: https://packagist.org/ 3.

    Open Source Licenses: https://opensource.org/licenses 4. ramsey/php-library-skeleton: https://github.com/ramsey/php-library-skeleton 5. PHP Framework Interoperability Group: http://www.php-fig.org/ 6. PHP Package Development Standards: http://php-pds.com/ 7. Semantic Versioning: http://semver.org/ 8. PHP CodeSniffer: https://github.com/squizlabs/PHP_CodeSniffer 9. PHPUnit: https://phpunit.de/ 10. phpstan: https://github.com/phpstan/phpstan 11. Travis CI: https://travis-ci.org/ 12. CHANGELOG.md: http://keepachangelog.com 13. Code of Conduct - Contributor Covenant: http://contributor-covenant.org/ - Citizen Code of Conduct: http://citizencodeofconduct.org/ 14. CONTRIBUTING.md: http://mozillascience.github.io/working-open-workshop/contributing/ 15. Open Source Guides: https://opensource.guide/ 16. A Beginner’s Guide to Creating a Readme: https://changelog.com/posts/a-beginners-guide-to-creating-a-readme 17. Use .gitattributes: https://blog.madewithlove.be/post/gitattributes/
  56. None
  57. benramsey.com @ramsey github.com/ramsey ben@benramsey.com THANK YOU. ANY QUESTIONS? If you

    want to talk more, feel free to contact me. Let’s Build a Composer Package Copyright © 2019 Ben Ramsey This work is licensed under Creative Commons Attribution- ShareAlike 4.0 International. For uses not covered under this license, please contact the author. Ramsey, Ben. “Let’s Build a Composer Package” php[world]. Sheraton Tysons Hotel, Tysons, VA. 24 Oct. 2019. Conference presentation. This presentation was created using Keynote. The text is set in Chunk Five and Helvetica Neue. The source code is set in Menlo. The iconography is provided by Font Awesome. Unless otherwise noted, all photographs are from Unsplash or Pixabay and are used with permission. @ramsey@phpc.social