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.

Transcript

1. Let’s Build a
   Composer Package
   Ben Ramsey

   24 Oct 2019 • php[world]
   

   View Slide

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
   

   View Slide

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:
   

   View Slide

4. Requirements.
   - PHP 7.2+
   - Composer
   

   View Slide

5. Homebrew: brew.sh
   

   brew install php@7.2
   export PATH="/usr/local/opt/php@7.2/bin:$PATH"
   php -v
   macOS
   

   View Slide

6. View Slide

7. Web Platform Installer:

   microsoft.com/web/downloads/platform.aspx
   php -v
   Windows
   

   View Slide

8. View Slide

9. View Slide

10. Use your favorite package manager.
    
    *nix
    

    View Slide

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

    View Slide

12. View Slide

13. View Slide

14. Getting started.
    

    View Slide

15. What problem do
    you want to solve?
    

    View Slide

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

    View Slide

17. View Slide

18. - MIT license
    - BSD 2-Clause “Simplified”
    - Apache License 2.0
    - GNU Library or “Lesser” General Public
    License (LGPL)
    

    View Slide

19. Now we can begin.
    

    View Slide

20. The project.
    

    View Slide

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

    View Slide

22. View Slide

23. Let’s Build!
    

    View Slide

24. Maintaining
    your package.
    

    View Slide

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
    

    View Slide

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
    

    View Slide

27. - PHPUnit, Atoum, Kahlan, etc.
    - Aim for sufficient code coverage
    - Make it easy to run your tests:

    composer test
    Testing.
    

    View Slide

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.
    

    View Slide

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.
    

    View Slide

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.
    

    View Slide

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"]
    }
    

    View Slide

32. View Slide

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.
    

    View Slide

34. View Slide

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.
    

    View Slide

36. View Slide

37. Building your
    community.
    

    View Slide

38. Readme.
    

    View Slide

39. View Slide

40. Contributing.
    

    View Slide

41. View Slide

42. Templates.
    

    View Slide

43. View Slide

44. Code of conduct.
    

    View Slide

45. View Slide

46. Automation.
    

    View Slide

47. View Slide

48. View Slide

49. Publishing.
    

    View Slide

50. View Slide

51. Enjoy the FOSS
    community.
    

    View Slide

52. Use a welcoming voice.
    

    View Slide

53. Build up.
    Don’t tear down.
    

    View Slide

54. View Slide

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/
    

    View Slide

56. View Slide

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
    

    View Slide