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.

14df293d6c5cd6f05996dfc606a6a951?s=128

Phil Sturgeon

May 31, 2015
Tweet

Transcript

  1. None
  2. Phil Sturgeon Framework Interoperability Advocate

  3. None
  4. None
  5. None
  6. How to successfully release an open-source PHP package (and become

    a better developer for it)
  7. 1. Make 2. Market 3. Maintain The goods

  8. Things to consider before you start Why you should and

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

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

    status quo.
  11. Do you have the time? Releasing open source code requires

    a time commitment.
  12. You will meet people Yay for nerd friends!

  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
  14. 1. Make

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

    to a successful package.
  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
  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
  18. Name things right It’s easy, like cache validation.

  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
  20. Have a clear focus Pull in other libraries when needed.

  21. Utilize common design patterns Techniques like dependency injection make your

    library easier use, maintain, read and test.
  22. Break apart large classes Create more focused classes, and more

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

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

    worth the effort?
  25. Source code on GitHub Sorry Bitbucket, Google Code & SourceForge.

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

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

  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" } } }
  29. None
  30. None
  31. .gitattributes /tests export-ignore /.gitattributes export-ignore /.gitignore export-ignore /.scrutinizer.yml export-ignore /.travis.yml

    export-ignore /phpunit.xml export-ignore
  32. Semantic Versioning Allows developers to upgrade versions safely. MAJOR.MINOR.PATCH BREAKING.NEW-FEATURES.BUG-FIXES

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

  34. DocBlocks Allows for automated API documentation.

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

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

    work.
  37. Contributor instructions Help them, help you!

  38. None
  39. 2. Market

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

    hipster).
  41. The documentation Your most important marketing tool.

  42. “Read the code” is an acceptable answer to“Where are the

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

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

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

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

  47. The elevator speech What it is and why it matters,

    in 160 characters or less.
  48. The simple example Show me the code!!!

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

  50. $ composer require league/fractal Via Composer

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

  52. Links to source & author This is open source after

    all, make yourself available!
  53. Badges! Badges help full in real-time information about your project.

  54. None
  55. None
  56. None
  57. None
  58. None
  59. None
  60. None
  61. None
  62. Some helpful design tools Just a few of my favourites.

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

  64. 3. Maintain

  65. Watch it spread See how your package is actually being

    used in the real world.
  66. None
  67. None
  68. None
  69. Issues and Pull Requests Open source collaboration is amazing.

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

  71. Listen to those actually using it Lots of people will

    have opinions, but have they ever used your package?
  72. Dealing with backwards compatibility How to make improvements when they

    will break existing code.
  73. What to do when you lose interest Pass off to

    someone with a vested interest.
  74. Thanks! Follow me on Twitter at @philsturgeon