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

Zero to The PHP League - The story of Plates

Zero to The PHP League - The story of Plates

It's one thing to write a quick library that you and maybe a few coworkers will only ever use. It's an entirely different thing to put your work out there for the entire PHP community to analyze, test, poke, benchmark and critique. While there is potential for this process to be incredibly rewarding it can also be quite intimidating. Wouldn't it be nice to see what this looks like before you jump in? Come see how Plates (platesphp.com) became a thing last year while at the same time learning how to make your first open-source PHP package a success.

6074dbe5dfa361c9888a705f40a49af4?s=128

Jonathan Reinink

November 07, 2014
Tweet

Transcript

  1. None
  2. Jonathan Reinink Lone-wolf developer.

  3. Plates A native PHP template system.

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

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

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

    why you shouldn’t.
  8. Improve the language by providing quality packages Prevent others from

    reinventing the wheel.
  9. Share your unique way of solving a problem Push the

    status quo.
  10. 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
  11. You will meet people Yay for nerd friends!

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

  13. Do you have the time? Releasing open source code requires

    a time commitment.
  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. Allow for chaining An simple way to make code more

    readable.
  24. Mail::send('emails.welcome', $data, function ($message) { ! $message->subject('Welcome!') ->from('john@doe.com', 'John Doe')

    ->to('foo@example.com') ->attach('document.pdf'); }); Example of chaining
  25. Avoid the rabbit hole of inheritance Abstraction has a side

    affect of being abstract.
  26. Framework agnostic Don’t limit yourself to just one framework.

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

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

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

  30. Example of a unit test public function testSetDirectory() { $this->assertInstanceOf(

    'League\Plates\Engine', $this->engine->setDirectory(vfsStream::url('templates')) ); ! $this->assertEquals( $this->engine->getDirectory(), vfsStream::url('templates') ); }
  31. None
  32. Composer & Packagist The primary delivery mechanism for your library.

  33. composer.json { "name": "league/plates", "description": "Plates, the native PHP template…",

    "homepage": "http://platesphp.com", "license": "MIT", "autoload": { "psr-4": { "League\\Plates\\": "src" } } }
  34. .gitattributes /tests export-ignore /.gitattributes export-ignore /.gitignore export-ignore /.scrutinizer.yml export-ignore /.travis.yml

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

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

  39. DocBlocks Allows for automated API documentation.

  40. Example of DocBlocks /** * Add a new template folder

    for grouping templates into namespaces. * @param string $name * @param string $directory * @param boolean $fallback * @return Engine */ public function addFolder($name, $directory, $fallback = false) { $this->folders->add($name, $directory, $fallback); ! return $this; }
  41. Continuous Integration Automate tests, PSR compliance checks, code coverage analysis

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

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

  44. None
  45. 2. Market

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

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

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

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

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

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

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

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

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

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

  56. composer.json { "require": { "league/plates": "3.*" } } Via a

    command composer require league/plates
  57. Keep a changelog Include upgrade instructions for backwards breaking changes.

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

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

  60. Group similar content into topics Smart use of hierarchy makes

    complex topics more digestible.
  61. Beautiful docs for the average package Honestly, good design isn’t

    magic.
  62. Project Name © Copyright your tagline goes here Topic Page

    name Page name Page name Page name Topic Page name Page name Page name Page name Topic Page name Page name Page name Page name Page name Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
  63. None
  64. None
  65. None
  66. None
  67. None
  68. None
  69. None
  70. None
  71. Some helpful design tools Just a few of my favourites.

  72. None
  73. None
  74. None
  75. None
  76. None
  77. Tell people! Reddit Twitter Hacker News SitePoint phpweekly.com phpdeveloper.org

  78. 3. Maintain

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

    used in the real world.
  80. None
  81. None
  82. None
  83. Issues and Pull Requests Open source collaboration is amazing.

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

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

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

    will break existing code.
  87. What to do when you loose interest Pass off to

    someone with a vested interest.
  88. Thanks! Follow me on Twitter at @reinink