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

1. View Slide

2. Jonathan Reinink
   Lone-wolf developer.
   

   View Slide

3. Plates
   A native PHP template system.
   

   View Slide

4. View Slide

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

   View Slide

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

   View Slide

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

   View Slide

8. Improve the language by
   providing quality packages
   Prevent others from reinventing the wheel.
   

   View Slide

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

   View Slide

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
    

    View Slide

11. You will meet people
    Yay for nerd friends!
    

    View Slide

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

    View Slide

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

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

    View Slide

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
    

    View Slide

25. Avoid the rabbit hole
    of inheritance
    Abstraction has a side affect of being abstract.
    

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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')
    );
    }
    

    View Slide

31. View Slide

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

    View Slide

33. composer.json
    {
    "name": "league/plates",
    "description": "Plates, the native PHP template…",
    "homepage": "http://platesphp.com",
    "license": "MIT",
    "autoload": {
    "psr-4": {
    "League\\Plates\\": "src"
    }
    }
    }
    

    View Slide

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

    View Slide

35. View Slide

36. View Slide

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

    View Slide

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

    View Slide

39. DocBlocks
    Allows for automated API documentation.
    

    View Slide

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;
    }
    

    View Slide

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

    View Slide

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

    View Slide

43. Contributor instructions
    Help them, help you!
    

    View Slide

44. View Slide

45. 2. Market
    

    View Slide

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

    View Slide

47. The documentation
    Your most important marketing tool.
    

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

61. Beautiful docs for
    the average package
    Honestly, good design isn’t magic.
    

    View Slide

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.
    

    View Slide

63. View Slide

64. View Slide

65. View Slide

66. View Slide

67. View Slide

68. View Slide

69. View Slide

70. View Slide

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

    View Slide

72. View Slide

73. View Slide

74. View Slide

75. View Slide

76. View Slide

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

    View Slide

78. 3. Maintain
    

    View Slide

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

    View Slide

80. View Slide

81. View Slide

82. View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

87. What to do when you
    loose interest
    Pass off to someone with a vested interest.
    

    View Slide

88. Thanks!
    Follow me on Twitter at @reinink
    

    View Slide