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.

Transcript

2. Jonathan Reinink Lone-wolf developer.
3. Plates A native PHP template system.
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') ); }
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
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!
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.
71. Some helpful design tools Just a few of my favourites.
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.
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