Phil Sturgeon Framework Interoperability Advocate How to - - PowerPoint PPT Presentation

▶
phil sturgeon
SMART_READER_LITE
LIVE PREVIEW

Phil Sturgeon Framework Interoperability Advocate How to - - PowerPoint PPT Presentation

Mar 24, 2024 7 likes •761 views

Phil Sturgeon Framework Interoperability Advocate How to successfully release an open-source PHP package (and become a better developer for it) The goods 1. Make 2. Market 3. Maintain Things to consider before you start Why you should and

slide-1
SLIDE 1
slide-2
SLIDE 2

Phil Sturgeon

Framework Interoperability Advocate

slide-3
SLIDE 3
slide-4
SLIDE 4
slide-5
SLIDE 5
slide-6
SLIDE 6

How to successfully release an open-source PHP package

(and become a better developer for it)

slide-7
SLIDE 7
  • 1. Make
  • 2. Market
  • 3. Maintain

The goods

slide-8
SLIDE 8

Things to consider before you start

Why you should and why you shouldn’t.

slide-9
SLIDE 9

Does it exist already?

Don’t clone, send pull requests instead.

slide-10
SLIDE 10

Share your unique way of solving a problem

Push the status quo.

slide-11
SLIDE 11

Do you have the time?

Releasing open source code requires a time commitment.

slide-12
SLIDE 12

You will meet people

Yay for nerd friends!

slide-13
SLIDE 13

You will learn, a lot

Contributing an open source package will push you as a developer.

GIT GitHub Issues Pull Requests Rebasing Testing TDD Semantic Versioning Code Coverage Composer Packagist Coding Standards PHP-FIG PSR DocBlocks Travis Scrutinizer CI Changelogs Licensing Code Sniffer Jekyll Shields.io Code Quality Milestones Releases Dependency Injection Coupling Cohesion

slide-14
SLIDE 14
  • 1. Make
slide-15
SLIDE 15

Design an API developers will want to use

The cornerstone to a successful package.

slide-16
SLIDE 16

// Create the transport $transport = Swift_SmtpTransport::newInstance('smtp.example.org', 25); $transport->setUsername('your username'); $transport->setPassword('your password'); // Create the email $message = Swift_Message::newInstance(); $message->setSubject('Your subject'); $message->setFrom(array('john@doe.com' => 'John Doe')); $message->setTo(array('foo@example.com')); $message->setBody('Here is the message itself'); $message->attach(Swift_Attachment::fromPath('document.pdf')); // Send the email $mailer = Swift_Mailer::newInstance($transport); $result = $mailer->send($message);

Send an email with Swift

slide-17
SLIDE 17

Mail::send('emails.welcome', $data, function ($message) { $message->subject('Welcome!')

  • >from('john@doe.com', 'John Doe')
  • >to('foo@example.com')
  • >attach('document.pdf');

});

Send an email with Laravel

slide-18
SLIDE 18

Name things right

It’s easy, like cache validation.

slide-19
SLIDE 19

// Current library $whoops = new Whoops\Run; $whoops->pushHandler(new Whoops\Handler\PrettyPageHandler); $whoops->register(); // Better class name $whoops = new Whoops\ErrHandler; $whoops->pushHandler(new Whoops\Handler\PrettyPageHandler); $whoops->register(); // Better example variable $errHandler = new Whoops\ErrHandler; $errHandler->pushHandler(new Whoops\Handler\PrettyPageHandler); $errHandler->register();

Whoops

slide-20
SLIDE 20

Have a clear focus

Pull in other libraries when needed.

slide-21
SLIDE 21

Utilize common design patterns

Techniques like dependency injection make your library easier use, maintain, read and test.

slide-22
SLIDE 22

Break apart large classes

Create more focused classes, and more

  • f them.
slide-23
SLIDE 23

Framework agnostic

Don’t limit yourself to just one framework.

slide-24
SLIDE 24

What versions of PHP should I support?

Is PHP 5.3 worth the effort?

slide-25
SLIDE 25

Source code on GitHub

Sorry Bitbucket, Google Code & SourceForge.

slide-26
SLIDE 26

Write tests

Automated tests allow you to make stress-free changes.

slide-27
SLIDE 27

Composer & Packagist

The primary delivery mechanism for your library.

slide-28
SLIDE 28

composer.json

{ "name": "league/fractal", "description": "Handle the output of complex data structures ready for API output.", "homepage": "http://fractal.thephpleague.com/", "license": "MIT", "author": [{ "name": “Phil Sturgeon”, "email": “me@philsturgeon.uk" }], "autoload": { "psr-4": { "League\\Fractal\\": "src" } } }

slide-29
SLIDE 29
slide-30
SLIDE 30
slide-31
SLIDE 31

.gitattributes

/tests export-ignore /.gitattributes export-ignore /.gitignore export-ignore /.scrutinizer.yml export-ignore /.travis.yml export-ignore /phpunit.xml export-ignore

slide-32
SLIDE 32

Semantic Versioning

Allows developers to upgrade versions safely.

MAJOR.MINOR.PATCH BREAKING.NEW-FEATURES.BUG-FIXES

slide-33
SLIDE 33

Coding Standards

Adhere to PSR-2 as the coding style guide.

slide-34
SLIDE 34

DocBlocks

Allows for automated API documentation.

slide-35
SLIDE 35

Continuous Integration

Automate tests, PSR compliance checks, code coverage analysis & more.

slide-36
SLIDE 36

Have a license

An important step to protect your hard work.

slide-37
SLIDE 37

Contributor instructions

Help them, help you!

slide-38
SLIDE 38
slide-39
SLIDE 39
  • 2. Market
slide-40
SLIDE 40

Choosing a name

Memorable, short and cool (without being too hipster).

slide-41
SLIDE 41

The documentation

Your most important marketing tool.

slide-42
SLIDE 42

“Read the code” is an acceptable answer to“Where are the docs?”

Documentation myth #1

slide-43
SLIDE 43

Documentation myth #2

“Auto-generated docs are good enough”

slide-44
SLIDE 44

“All you need a README file”

Documentation myth #3

slide-45
SLIDE 45

“Documentation is easy.”

Documentation myth #4

slide-46
SLIDE 46

Documentation “must- haves”

How to do documentation right!

slide-47
SLIDE 47

The elevator speech

What it is and why it matters, in 160 characters or less.

slide-48
SLIDE 48

The simple example

Show me the code!!!

slide-49
SLIDE 49

Installation instructions

Make it easy for someone to get started.

slide-50
SLIDE 50

$ composer require league/fractal

Via Composer

slide-51
SLIDE 51

Keep a changelog

Include upgrade instructions for backwards breaking changes.

slide-52
SLIDE 52

Links to source & author

This is open source after all, make yourself available!

slide-53
SLIDE 53

Badges!

Badges help full in real-time information about your project.

slide-54
SLIDE 54
slide-55
SLIDE 55
slide-56
SLIDE 56
slide-57
SLIDE 57
slide-58
SLIDE 58
slide-59
SLIDE 59
slide-60
SLIDE 60
slide-61
SLIDE 61
slide-62
SLIDE 62

Some helpful design tools

Just a few of my favourites.

slide-63
SLIDE 63

Tell people!

Reddit Twitter Hacker News SitePoint phpweekly.com phpdeveloper.org

slide-64
SLIDE 64
  • 3. Maintain
slide-65
SLIDE 65

Watch it spread

See how your package is actually being used in the real world.

slide-66
SLIDE 66
slide-67
SLIDE 67
slide-68
SLIDE 68
slide-69
SLIDE 69

Issues and Pull Requests

Open source collaboration is amazing.

slide-70
SLIDE 70

Dealing with strong personalities

Sometimes open source collaboration can suck.

slide-71
SLIDE 71

Listen to those actually using it

Lots of people will have opinions, but have they ever used your package?

slide-72
SLIDE 72

Dealing with backwards compatibility

How to make improvements when they will break existing code.

slide-73
SLIDE 73

What to do when you lose interest

Pass off to someone with a vested interest.

slide-74
SLIDE 74

Thanks!

Follow me on Twitter at @philsturgeon

slide-75
SLIDE 75

https://joind.in/14935