Building Extraordinary Packages

Back in the day, we had PEAR packages. These were often very well written, but due to PEARs lack of popularity we ended up just using mega-frameworks and writing bundles, modules, cells and sparks for that framework. Since then Composer has been a bit of a savior, but the way in which we make these packages is still new and scary.

There are a lot of talks about building good code, and writing OOP well, but how do you make a Composer package that is as high in quality as you can? Things like SemVer, avoiding NIH syndrome verses knowing WHEN to fork or make a new package, responsible deprecation and loads more.

The League of Extraordinary Packages is a group of developers who have banded together to build solid, well tested PHP packages using modern coding standards. The name might be a little silly, but the group dedicates itself to active maintenance, handing over projects when a lead has to step aside, working together and an absolute dedication to following and supporting standards.

Transcript

1. View Slide

2. Phil Sturgeon
   Framework Interoperability Advocate
   

   View Slide

3. View Slide

4. View Slide

5. View Slide

6. How to successfully release
   an open-source PHP package
   (and become a better developer for it)
   

   View Slide

7. 1. Make
   2. Market
   3. Maintain
   The goods
   

   View Slide

8. Things to consider before
   you start
   Why you should and why you shouldn’t.
   

   View Slide

9. Does it exist already?
   Don’t clone, send pull requests instead.
   

   View Slide

10. Share your unique way of
    solving a problem
    Push the status quo.
    

    View Slide

11. Do you have the time?
    Releasing open source code requires a time commitment.
    

    View Slide

12. You will meet people
    Yay for nerd friends!
    

    View 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
    

    View Slide

14. 1. Make
    

    View Slide

15. Design an API developers
    will want to use
    The cornerstone to a successful package.
    

    View 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
    

    View 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
    

    View Slide

18. Name things right
    It’s easy, like cache validation.
    

    View 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
    

    View Slide

20. Have a clear focus
    Pull in other libraries when needed.
    

    View Slide

21. Utilize common
    design patterns
    Techniques like dependency injection make your
    library easier use, maintain, read and test.
    

    View Slide

22. Break apart large
    classes
    Create more focused classes, and more
    of them.
    

    View Slide

23. Framework agnostic
    Don’t limit yourself to just one framework.
    

    View Slide

24. What versions of PHP should
    I support?
    Is PHP 5.3 worth the effort?
    

    View Slide

25. Source code on GitHub
    Sorry Bitbucket, Google Code & SourceForge.
    

    View Slide

26. Write tests
    Automated tests allow you to make stress-free changes.
    

    View Slide

27. Composer & Packagist
    The primary delivery mechanism for your library.
    

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

    View Slide

29. View Slide

30. View Slide

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

    View Slide

32. Semantic Versioning
    Allows developers to upgrade versions safely.
    MAJOR.MINOR.PATCH
    BREAKING.NEW-FEATURES.BUG-FIXES
    

    View Slide

33. Coding Standards
    Adhere to PSR-2 as the coding style guide.
    

    View Slide

34. DocBlocks
    Allows for automated API documentation.
    

    View Slide

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

    View Slide

36. Have a license
    An important step to protect your hard work.
    

    View Slide

37. Contributor instructions
    Help them, help you!
    

    View Slide

38. View Slide

39. 2. Market
    

    View Slide

40. Choosing a name
    Memorable, short and cool (without being too hipster).
    

    View Slide

41. The documentation
    Your most important marketing tool.
    

    View Slide

42. “Read the code” is an acceptable answer
    to“Where are the docs?”
    Documentation myth #1
    

    View Slide

43. Documentation myth #2
    “Auto-generated docs are good
    enough”
    

    View Slide

44. “All you need a README file”
    Documentation myth #3
    

    View Slide

45. “Documentation is easy.”
    Documentation myth #4
    

    View Slide

46. Documentation “must-
    haves”
    How to do documentation right!
    

    View Slide

47. The elevator speech
    What it is and why it matters, in 160 characters or less.
    

    View Slide

48. The simple example
    Show me the code!!!
    

    View Slide

49. Installation instructions
    Make it easy for someone to get started.
    

    View Slide

50. $ composer require league/fractal
    Via Composer
    

    View Slide

51. Keep a changelog
    Include upgrade instructions for
    backwards breaking changes.
    

    View Slide

52. Links to source & author
    This is open source after all, make yourself available!
    

    View Slide

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

    View Slide

54. View Slide

55. View Slide

56. View Slide

57. View Slide

58. View Slide

59. View Slide

60. View Slide

61. View Slide

62. Some helpful design tools
    Just a few of my favourites.
    

    View Slide

63. Tell people!
    Reddit
    Twitter
    Hacker News
    SitePoint
    phpweekly.com
    phpdeveloper.org
    

    View Slide

64. 3. Maintain
    

    View Slide

65. Watch it spread
    See how your package is actually being used in
    the real world.
    

    View Slide

66. View Slide

67. View Slide

68. View Slide

69. Issues and Pull Requests
    Open source collaboration is amazing.
    

    View Slide

70. Dealing with strong
    personalities
    Sometimes open source collaboration can suck.
    

    View Slide

71. Listen to those
    actually using it
    Lots of people will have opinions, but have they ever
    used your package?
    

    View Slide

72. Dealing with backwards
    compatibility
    How to make improvements when they will
    break existing code.
    

    View Slide

73. What to do when you lose
    interest
    Pass off to someone with a vested interest.
    

    View Slide

74. Thanks!
    Follow me on Twitter at @philsturgeon
    

    View Slide