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

Let's Build a Composer Package (Cascadia PHP 2024)

Let's Build a Composer Package (Cascadia PHP 2024)

Ben Ramsey

October 25, 2024
Tweet

More Decks by Ben Ramsey

Other Decks in Programming

Transcript

  1. WHO IS THIS FOR? ▸ Individuals who want to open

    source a library. ▸ Companies who want to open source a library. ▸ Others who just want to learn how it all works.
  2. WHAT WILL WE COVER? ▸ What makes a good or

    high quality Composer package? ▸ Common patterns of packages. ▸ How to publish a package. ▸ Maintaining a package and building a community.
  3. ASSUMPTIONS And caveats ▸ You’ll need to install: ▸ PHP

    8.1+ — www.php.net/install ▸ Composer — getcomposer.org/download ▸ Git — git-scm.com/downloads
  4. INSTALLING On macOS or Linux with Homebrew ▸ Go to

    brew.sh to download and install Homebrew. ▸ Install PHP, Composer, and Git with: brew install php composer git
  5. INSTALLING On Windows with Chocolatey ▸ Go to chocolatey.org/install to

    download and install Chocolatey. ▸ Install PHP, Composer, and Git with: choco install php composer git
  6. INSTALLING On Debian Bookworm or Ubuntu Jammy (or later) ▸

    Install using: ▸ If you get a PHP version earlier than 8.1, use Ondřej Surý's packages: deb.sury.org. apt install php composer git
  7. INSTALLING On Fedora 36 (or later) ▸ Install using: ▸

    If you get a PHP version earlier than 8.1, use Remi Collet's packages: rpms.remirepo.net. yum install php composer git
  8. INSTALLING On on anything else ▸ Other installation methods exist.

    ▸ Check the documentation for your install method of choice.
  9. ASSUMPTIONS And caveats ▸ You’ll need accounts at: ▸ GitHub

    — github.com/signup ▸ Packagist — packagist.org/login/github ▸ Codecov — codecov.io/login/gh
  10. ASSUMPTIONS And caveats ▸ This is all highly opinionated. ▸

    For example, I’m using: ▸ PHP Package Development Standards (PHP-PDS) ▸ PHPUnit ▸ PHP_CodeSni ff er ▸ PHPStan
  11. ASSUMPTIONS And caveats ▸ The tools I’m using aren’t necessarily

    requirements for creating packages. ▸ Well, PHP and Composer are. ▸ You could use Mercurial, Bitbucket, Travis CI, and Coveralls, for example. ▸ Or Pest, phpcs- fi xer, Phan, etc. ▸ This tutorial doesn’t cover these tools.
  12. A PACKAGE… ▸ Is a collection of code. ▸ Addresses

    a single problem or problem domain.† ▸ Provides a simple interface to underlying functionality.† ▸ Is often highly abstracted.† ▸ Is distributed through a package manager (i.e., npm, Cargo, pip, RubyGems, Composer, etc.).†
  13. PACKAGE REQUIREMENTS Th e bare minimum: composer.json { "name": "wild-garlic/hello-world",

    "description": "A basic Hello, World example.", "type": "library", "autoload": { "psr-4": { "WildGarlic\\HelloWorld\\": "./" } } }
  14. PACKAGE REQUIREMENTS Th e bare minimum: HelloWorld.php <?php declare(strict_types=1); namespace

    WildGarlic\HelloWorld; class HelloWorld { public function greet(string $name = 'World'): string { return "Hello, $name!"; } }
  15. PACKAGE REQUIREMENTS Th e bare minimum: We can require and

    use it composer require wild-garlic/hello-world:dev-cascadiaphp2024-minimal
  16. PACKAGE REQUIREMENTS Th e bare minimum: We can require and

    use it <?php declare(strict_types=1); namespace App; use WildGarlic\HelloWorld\HelloWorld; require_once 'vendor/autoload.php'; $hello = new HelloWorld(); echo $hello->greet('Cascadia PHP');
  17. PACKAGE REQUIREMENTS Th e bare minimum: Links to examples ▸

    cascadiaphp2024-minimal branch on GitHub: ▸ github.com/wild-garlic/hello-world/tree/cascadiaphp2024-minimal ▸ dev-cascadiaphp2024-minimal version on Packagist: ▸ packagist.org/packages/wild-garlic/hello-world#dev-cascadiaphp2024- minimal
  18. Jakob Nielsen, “End of Web Design,” July 22, 2000 (a.k.a.

    Jakob's Law of Internet User Experience) “Users spend most of their time on other sites.”
  19. DIRECTORY STRUCTURE PHP Package Development Standards (PHP-PDS) ▸ Research-based. ▸

    Evaluated thousands of Composer packages across the PHP ecosystem. ▸ Analyzed the results to derive the most common directory structure. ▸ php-pds.com
  20. bin/ command-line executables config/ con fi guration fi les docs/

    project documentation public/ web server fi les (rarely used in packages) resources/ other resources, i.e., data fi les, etc. src/ PHP source code tests/ test code ??? Other root-level directories are okay (i.e., tools/, etc.)
  21. DIRECTORY STRUCTURE Discussion ▸ The earlier minimal example placed HelloWorld.php

    in the package root. ▸ Some projects, like Symfony, follow this pattern for their components. ▸ I’ll assume src/ for the rest of my examples. ▸ Most packages will have src/ and tests/ at a minimum. ▸ Many also include docs/. ▸ Some include bin/, if providing command line tools.
  22. IMPORTANT FILES README ▸ README provides the most important information

    users need to know. ▸ Installation ▸ Usage ▸ Depending on the type of content, it might be named README.md, README.markdown, README.txt, README.rst, etc.
  23. IMPORTANT FILES CHANGELOG ▸ CHANGELOG provides a list of changes

    for each version of your package, including any backward-compatibility (BC) breaks. ▸ Helps users understand new features, fi xes, and potential issues they might encounter when upgrading. ▸ Meant for humans. ▸ No industry-standard format, though Keep A Changelog is popular.
  24. ## 3.5.0 - 2023-04-27 ### Added - Add an option

    for version 2.1 of the Contributor Covenant - Update GitHub workflows to support auto-merging of Dependabot pull requests ### Changed - Update ramsey/devtools to version 2.0 - Increase minimum PHP version to 8.1 ### Deprecated - Nothing. ### Removed - Nothing. ### Fixed - Stop passing `starter-kit` command name to avoid confusing newer versions of symfony/console. ### Security - Nothing.
  25. IMPORTANT FILES LICENSE ▸ What permissions do your users have?

    ▸ Two primary styles of open source licenses: ▸ Permissive ▸ Copyleft ▸ I am not a lawyer; this is not legal advice. ▸ Choose an OSI-approved or FSF-approved open source license.
  26. PHP LIBRARY STARTER KIT A starting point ▸ A starter

    kit for setting up a new PHP library package. ▸ Highly opinionated (built for me) ▸ PHPUnit for tests ▸ PHP_CodeSni ff er for coding standards (using ramsey/coding-standard) ▸ PHPStan and Psalm for static analysis ▸ CaptainHook to manage Git hooks
  27. ▸ We’ll use composer create-project. ▸ Follow along, if you

    like. composer create-project ramsey/php-library-starter-kit hello-world
  28. PUBLISH OUR PACKAGE Review: Push to GitHub ▸ Create repository

    at github.com/new. ▸ Connect your local repository to the remote one: ▸ Push the main branch to the remote repository: ▸ View your repository on GitHub! git remote add origin [email protected]:yourname/repository.git git push -u origin main
  29. PUBLISH OUR PACKAGE Review: Publish to Packagist ▸ Create package

    at packagist.org/packages/submit. ▸ Edit the CHANGELOG. ▸ Commit the changes, tag the release, and push. ▸ Packagist automatically picks up the new version! git add -p git commit -m "chore: prepare version 0.1.0" git tag -m "Version 0.1.0" 0.1.0 git push origin main 0.1.0
  30. PUBLISH OUR PACKAGE Review: Use our package in another project

    ▸ We can use our package in another project! ▸ composer.json mkdir my-new-project cd my-new-project composer require wild-garlic/hello-world { "require": { "wild-garlic/hello-world": "^0.1.0" } }
  31. LET’S EXPLORE What’s included in the starter kit? ▸ CaptainHook

    and Git hooks ▸ phly/keep-a-changelog ▸ madewithlove/license-checker ▸ Psalm and PHPStan ▸ PHPUnit ▸ PHP_CodeSni ff er ▸ ramsey/devtools ▸ ramsey/conventional-commits ▸ ramsey/composer-repl ▸ GitHub Actions work fl ow for continuous integration ▸ GitHub Actions work fl ow to auto- merge Dependabot pull requests
  32. LET’S EXPLORE What’s included in the starter kit? ▸ Useful

    commands: composer list composer help dev:changelog composer help dev:license composer help dev:analyze:phpstan composer help dev:analyze:psalm composer help dev:lint:style composer help dev:test:unit composer test composer repl
  33. If you didn’t do it earlier, go register at Codecov

    using your GitHub account. codecov.io/login/gh
  34. BUILDING COMMUNITY CONTRIBUTING.md ▸ Lets others know you accept contributions.

    ▸ Provides information on how to contribute to your project. ▸ Includes details such as setting up environments for testing. ▸ The starter kit provides an example you can use out-of-the-box. ▸ More info: mozillascience.github.io/working-open-workshop/contributing
  35. BUILDING COMMUNITY CODE_OF_CONDUCT.md ▸ A code of conduct indicates that

    you care about building a friendly and welcoming community. ▸ Sets the guidelines for what you expect from participants and what participants can expect from you. ▸ The starter kit includes a few you may use out-of-the-box. ▸ More info: opensource.guide/code-of-conduct
  36. BUILDING COMMUNITY SECURITY.md ▸ SECURITY.md is your project’s vulnerability disclosure

    policy (VDP). ▸ It describes how you’ll accept and respond to security vulnerability reports. ▸ The starter kit includes a policy created using HackerOne’s policy builder. ▸ You’ll want to customize this to suit your, or your organization’s, needs.
  37. EVALUATING QUALITY Th ings I look for in a package

    ▸ Are there tests? How comprehensive are they? ▸ What percentage of the code is covered by tests? ▸ Does the project use static analysis tools as part of its CI work fl ows? ▸ Does the project have CI work fl ows? ▸ Must have a README, CHANGELOG, and LICENSE. ▸ Are the maintainers friendly and responsive to issues and pull requests?
  38. THANK YOU! Keep in touch     

     ben.ramsey.dev phpc.social/@ramsey github.com/ramsey speakerdeck.com/ramsey www.linkedin.com/in/benramsey [email protected] bram.se/cascadia-composer     
  39. ATTRIBUTION • Fonts • Archivo Black by Omnibus-Type, SIL Open

    Font License, Version 1.1 • DM Mono by Colophon Foundry, SIL Open Font License, Version 1.1 • Playfair Display by Claus Eggers S ø rensen, SIL Open Font License, Version 1.1 • Saira by Omnibus-Type, SIL Open Font License, Version 1.1 • OpenMoji • “person shrugging” by Johanna Wellnitz, CC BY-SA 4.0 • “winking face” by Emily Jäger, CC BY-SA 4.0