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

Building Extraordinary Packages

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.

Phil Sturgeon

May 31, 2015
Tweet

More Decks by Phil Sturgeon

Other Decks in Programming

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('[email protected]' => 'John Doe'));
    $message->setTo(array('[email protected]'));
    $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('[email protected]', 'John Doe')
    ->to('[email protected]')
    ->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": “[email protected]"
    }],
    "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