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

How to open source a PHP package (phpDay 2017)

How to open source a PHP package (phpDay 2017)

Jonathan Reinink

May 13, 2017
Tweet

More Decks by Jonathan Reinink

Other Decks in Technology

Transcript

  1. View Slide

  2. Jonathan Reinink
    I live in Canada.
    I have been writing PHP for 18 years.
    I spent a decade at marketing agency.
    I am now a contract developer.

    View Slide

  3. View Slide

  4. What is a package?

    View Slide

  5. Packages are important
    because they provide code
    you don’t have to write.

    View Slide

  6. Today there are
    139,000 PHP package
    available on Packagist.

    View Slide

  7. packagist.org/statistics

    View Slide

  8. Packages are a BIG
    part of what makes a
    language successful.

    View Slide

  9. Have you ever contributed an
    open-source PHP package?

    View Slide

  10. Contributing to open-source
    helps both you as developer and
    the greater PHP ecosystem.

    View Slide

  11. If your business relies heavily
    on certain packages, those are
    great places to get involved.

    View Slide

  12. Creating packages can
    be a little intimidating.

    View Slide

  13. Introducing
    The PHP Package Checklist
    phppackagechecklist.com

    View Slide

  14. View Slide

  15. View Slide

  16. Recommendations for
    open-source packages, but
    applicable to any PHP library.

    View Slide

  17. Pick a name wisely

    View Slide

  18. Have a unique identifier
    in your package name.

    View Slide

  19. Twig
    Guzzle
    Monolog
    Flysystem
    Swift Mailer
    Eloquent
    Blade
    Aura

    View Slide

  20. Ensure the name isn't already
    used by another project.

    View Slide

  21. Maintain consistency
    between this name and
    your PHP namespace.

    View Slide

  22. Avoid using last names
    or personal handles in
    your PHP namespaces.

    View Slide

  23. // Good:
    namespace Glide;
    namespace League\Glide;
    // Avoid:
    namespace Reinink\Glide;
    namespace Images;
    namespace ImageManipulations;
    namespace PHPGlide;
    namespace YoloImages;

    View Slide

  24. Host source openly

    View Slide

  25. Hosting your code
    openly encourages:
    • Contributions
    • Downloads
    • Code Reviews
    • Bug Reports

    View Slide

  26. Recommendation: GitHub

    View Slide

  27. Even if you prefer Bitbucket,
    SourceForge, or Google Code,
    your end users most likely won’t.

    View Slide

  28. Autoloader friendly

    View Slide

  29. Use a PSR-4 compatible
    autoloader namespace.

    View Slide

  30. Distribute via Composer

    View Slide

  31. $ composer require league/glide

    View Slide

  32. {
    "name": "league/glide",
    "require": {
    "intervention/image": "^2.1",
    "league/flysystem": "^1.0",
    "php": "^5.4 | ^7.0",
    "psr/http-message": "^1.0"
    },
    "autoload": {
    "psr-4": {
    "League\\Glide\\": "src/"
    }
    }
    }

    View Slide

  33. List your library on Packagist,
    the main Composer repository.

    View Slide

  34. View Slide

  35. Committing your
    composer.lock file has no
    impact on your end users.

    View Slide

  36. Place code in
    the /src folder.

    View Slide

  37. Framework agnostic

    View Slide

  38. Don't limit your library
    to one framework.

    View Slide

  39. Offer framework specific
    support for your package
    using service providers.

    View Slide

  40. View Slide

  41. Follow a coding style

    View Slide

  42. Highly recommended
    that you adhere to the
    PSR-2 coding style guide.

    View Slide

  43. A familiar coding style
    makes open-source code
    easier to contribute to.

    View Slide

  44. Do this quickly with an
    automated code fixer like
    PHP Coding Standards Fixer.
    cs.sensiolabs.org

    View Slide

  45. You can also use services
    like Nitpick or StyleCI to
    help you with this.

    View Slide

  46. Write unit tests

    View Slide

  47. Aim to cover the
    majority of your code.

    View Slide

  48. PHPUnit is the de facto
    testing framework in PHP.

    View Slide

  49. Alternatives: phpspec,
    Behat, atoum, Codeception.

    View Slide

  50. DocBlock your code

    View Slide

  51. /**
    * Set source file system.
    * @param Filesystem $source Source file system.
    */
    public function setSource(Filesystem $source)
    {
    $this->source = $source;
    }

    View Slide

  52. DocBlock serve as
    inline documentation.

    View Slide

  53. They can also improve code
    completion in IDEs, like PhpStorm.

    View Slide

  54. Can be automatically converted
    into API documentation.

    (see phpDocumentor)

    View Slide

  55. Use semantic versioning

    View Slide

  56. Follow the pattern:
    MAJOR.MINOR.PATCH
    BREAKING.NEW-FEATURES.BUG-FIXES

    View Slide

  57. Semantic versioning
    allows developers to
    upgrade libraries safely.

    View Slide

  58. semver.org

    View Slide

  59. View Slide

  60. Keep a changelog

    View Slide

  61. Show notable changes that have
    been made between releases.

    View Slide

  62. Consider following the
    Keep a CHANGELOG format.
    (see keepachangelog.com)

    View Slide

  63. View Slide

  64. {% for release in site.github.releases %}
    ## [{{ release.name }}]({{ release.html_url }})
    - {{ release.published_at | date: "%Y-%m-%d" }}
    {{ release.body | markdownify }}
    {% endfor %}

    View Slide

  65. Use continuous integration

    View Slide

  66. Use a service to
    automatically check coding
    standards and run tests.

    View Slide

  67. View Slide

  68. View Slide

  69. Write extensive documentation

    View Slide

  70. “Tests are hard so we practice to
    get better. Docs are hard… so we
    don’t write any and complain.”
    — Steve Klabnik, Senior Technical Writer
    (maintainer of the official Rust documentation)

    View Slide

  71. Don’t release an open source
    package unless your committed
    to writing good documentation.

    View Slide

  72. Consider hosting documentation
    on GitHub Pages.

    View Slide

  73. The formula to awesome docs:

    Tomorrow at 11am

    View Slide

  74. Include a license

    View Slide

  75. See choosealicense.com.
    Most PHP projects use
    the MIT License.

    View Slide

  76. The MIT License
    Copyright (c)
    Permission is hereby granted, free of charge, to any person obtaining a copy of this software and
    associated documentation files (the "Software"), to deal in the Software without restriction, including
    without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
    copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to
    the following conditions:
    The above copyright notice and this permission notice shall be included in all copies or substantial
    portions of the Software.
    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
    INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
    PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
    COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN
    AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
    WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

    View Slide

  77. At a minimum, include a
    LICENSE file with your library.

    View Slide

  78. Welcome contributions

    View Slide

  79. Have a CONTRIBUTING file,
    welcoming contributions to the project.

    View Slide

  80. View Slide

  81. Thanks!
    Follow me on Twitter at @reinink.
    Please rate this talk at joind.in/talk/74e5f.

    View Slide