Let's Build a Composer Package (php[tek] 2024)

Slide 1

Slide 1 text

Ben Ramsey php[tek] • April 23, 2024 COMPOSER PACKAGE Let’s Build a

Slide 2

Slide 2 text

WELCOME A bit about me • Senior Sta ff Software Engineer at Intuit (working on Mailchimp API) • PHP 8.1 and 8.2 release manager • Author of many packages…

Slide 3

Slide 3 text

• ramsey/uuid • league/oauth2-client • skillshare/formatphp • ramsey/collection • ramsey/composer-repl • ramsey/conventional-commits • ramsey/devtools • ramsey/http-range • ramsey/php-library-starter-kit • ramsey/pygments • and more!

Slide 4

Slide 4 text

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.

Slide 5

Slide 5 text

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.

Slide 6

Slide 6 text

This is hands-on. (if you want it to be)

Slide 7

Slide 7 text

ASSUMPTIONS And caveats • You’ll need to install: • PHP 8.1+ — www.php.net/install • Composer — getcomposer.org/download • Git — git-scm.com/downloads

Slide 8

Slide 8 text

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

Slide 9

Slide 9 text

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

Slide 10

Slide 10 text

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

Slide 11

Slide 11 text

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

Slide 12

Slide 12 text

INSTALLING On on anything else • Other installation methods exist. • Check the documentation for your install method of choice.

Slide 13

Slide 13 text

ASSUMPTIONS And caveats • You’ll need accounts at: • GitHub — github.com/signup • Packagist — packagist.org/login/github • Codecov — codecov.io/login/gh

Slide 14

Slide 14 text

No content

Slide 15

Slide 15 text

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

Slide 16

Slide 16 text

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.

Slide 17

Slide 17 text

LET’S BRAINSTORM

Slide 18

Slide 18 text

What does our package do?

Slide 19

Slide 19 text

What does our package do? “Hello, World!”

Slide 20

Slide 20 text

What’s our package namespace?

Slide 21

Slide 21 text

What’s our package namespace? WildGarlic\HelloWorld

Slide 22

Slide 22 text

What’s our package name?

Slide 23

Slide 23 text

What’s our package name? wild-garlic/hello-world

Slide 24

Slide 24 text

WHAT IS A PACKAGE?

Slide 25

Slide 25 text

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.).†

Slide 26

Slide 26 text

† Usually

Slide 27

Slide 27 text

PACKAGE REQUIREMENTS Th e bare minimum • composer.json • Some code…maybe.

Slide 28

Slide 28 text

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\\": "./" } } }

Slide 29

Slide 29 text

PACKAGE REQUIREMENTS Th e bare minimum: HelloWorld.php

Slide 30

Slide 30 text

No content

Slide 31

Slide 31 text

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

Slide 32

Slide 32 text

PACKAGE REQUIREMENTS Th e bare minimum: We can require and use it greet('php[tek]');

Slide 33

Slide 33 text

That’s all, folks! (just kidding)

Slide 34

Slide 34 text

PACKAGE REQUIREMENTS Th e bare minimum: Links to examples • phptek2024-minimal branch on GitHub: • github.com/wild-garlic/hello-world/tree/phptek2024-minimal • dev-phptek2024-minimal version on Packagist: • packagist.org/packages/wild-garlic/hello-world#dev-phptek2024- minimal

Slide 35

Slide 35 text

ANATOMY OF A PACKAGE

Slide 36

Slide 36 text

Does directory structure matter?

Slide 37

Slide 37 text

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.”

Slide 38

Slide 38 text

This applies to developer experience, too.

Slide 39

Slide 39 text

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

Slide 40

Slide 40 text

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.)

Slide 41

Slide 41 text

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.

Slide 42

Slide 42 text

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.

Slide 43

Slide 43 text

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.

Slide 44

Slide 44 text

No content

Slide 45

Slide 45 text

## 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.

Slide 46

Slide 46 text

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.

Slide 47

Slide 47 text

No content

Slide 48

Slide 48 text

No content

Slide 49

Slide 49 text

If a package does not specify a license, it is not free software!

Slide 50

Slide 50 text

IMPORTANT FILES Other fi les? Yes. We’ll get to them in a bit.

Slide 51

Slide 51 text

CREATE OUR PACKAGE

Slide 52

Slide 52 text

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

Slide 53

Slide 53 text

Let’s create a package!

Slide 54

Slide 54 text

• We’ll use composer create-project. • Follow along, if you like. composer create-project ramsey/php-library-starter-kit hello-world

Slide 55

Slide 55 text

No content

Slide 56

Slide 56 text

No content

Slide 57

Slide 57 text

No content

Slide 58

Slide 58 text

No content

Slide 59

Slide 59 text

No content

Slide 60

Slide 60 text

No content

Slide 61

Slide 61 text

No content

Slide 62

Slide 62 text

No content

Slide 63

Slide 63 text

No content

Slide 64

Slide 64 text

No content

Slide 65

Slide 65 text

No content

Slide 66

Slide 66 text

No content

Slide 67

Slide 67 text

No content

Slide 68

Slide 68 text

No content

Slide 69

Slide 69 text

No content

Slide 70

Slide 70 text

No content

Slide 71

Slide 71 text

No content

Slide 72

Slide 72 text

PUBLISH OUR PACKAGE

Slide 73

Slide 73 text

No content

Slide 74

Slide 74 text

No content

Slide 75

Slide 75 text

No content

Slide 76

Slide 76 text

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

Slide 77

Slide 77 text

No content

Slide 78

Slide 78 text

No content

Slide 79

Slide 79 text

No content

Slide 80

Slide 80 text

No content

Slide 81

Slide 81 text

No content

Slide 82

Slide 82 text

No content

Slide 83

Slide 83 text

No content

Slide 84

Slide 84 text

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

Slide 85

Slide 85 text

No content

Slide 86

Slide 86 text

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

Slide 87

Slide 87 text

MAINTENANCE

Slide 88

Slide 88 text

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

Slide 89

Slide 89 text

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

Slide 90

Slide 90 text

No content

Slide 91

Slide 91 text

If you didn’t do it earlier, go register at Codecov using your GitHub account. codecov.io/login/gh

Slide 92

Slide 92 text

No content

Slide 93

Slide 93 text

No content

Slide 94

Slide 94 text

No content

Slide 95

Slide 95 text

No content

Slide 96

Slide 96 text

No content

Slide 97

Slide 97 text

No content

Slide 98

Slide 98 text

No content

Slide 99

Slide 99 text

No content

Slide 100

Slide 100 text

Badges?

Slide 101

Slide 101 text

We need those stinkin’ badges!

Slide 102

Slide 102 text

No content

Slide 103

Slide 103 text

No content

Slide 104

Slide 104 text

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

Slide 105

Slide 105 text

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

Slide 106

Slide 106 text

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.

Slide 107

Slide 107 text

YOU’RE A PHP PACKAGE DEVELOPER!

Slide 108

Slide 108 text

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?

Slide 109

Slide 109 text

Does your package check all the boxes?

Slide 110

Slide 110 text

THANK YOU! Keep in touch       ben.ramsey.dev phpc.social/@ramsey github.com/ramsey speakerdeck.com/ramsey www.linkedin.com/in/benramsey [email protected] joind.in/talk/bf3aa

Slide 111

Slide 111 text

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