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. 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 full-size slide

  2. What is a package?

    View full-size slide

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

    View full-size slide

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

    View full-size slide

  5. packagist.org/statistics

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

  10. Creating packages can
    be a little intimidating.

    View full-size slide

  11. Introducing
    The PHP Package Checklist
    phppackagechecklist.com

    View full-size slide

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

    View full-size slide

  13. Pick a name wisely

    View full-size slide

  14. Have a unique identifier
    in your package name.

    View full-size slide

  15. Twig
    Guzzle
    Monolog
    Flysystem
    Swift Mailer
    Eloquent
    Blade
    Aura

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

  20. Host source openly

    View full-size slide

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

    View full-size slide

  22. Recommendation: GitHub

    View full-size slide

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

    View full-size slide

  24. Autoloader friendly

    View full-size slide

  25. Use a PSR-4 compatible
    autoloader namespace.

    View full-size slide

  26. Distribute via Composer

    View full-size slide

  27. $ composer require league/glide

    View full-size slide

  28. {
    "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 full-size slide

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

    View full-size slide

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

    View full-size slide

  31. Place code in
    the /src folder.

    View full-size slide

  32. Framework agnostic

    View full-size slide

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

    View full-size slide

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

    View full-size slide

  35. Follow a coding style

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

  40. Write unit tests

    View full-size slide

  41. Aim to cover the
    majority of your code.

    View full-size slide

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

    View full-size slide

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

    View full-size slide

  44. DocBlock your code

    View full-size slide

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

    View full-size slide

  46. DocBlock serve as
    inline documentation.

    View full-size slide

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

    View full-size slide

  48. Can be automatically converted
    into API documentation.

    (see phpDocumentor)

    View full-size slide

  49. Use semantic versioning

    View full-size slide

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

    View full-size slide

  51. Semantic versioning
    allows developers to
    upgrade libraries safely.

    View full-size slide

  52. Keep a changelog

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

  56. Use continuous integration

    View full-size slide

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

    View full-size slide

  58. Write extensive documentation

    View full-size slide

  59. “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 full-size slide

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

    View full-size slide

  61. Consider hosting documentation
    on GitHub Pages.

    View full-size slide

  62. The formula to awesome docs:

    Tomorrow at 11am

    View full-size slide

  63. Include a license

    View full-size slide

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

    View full-size slide

  65. 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 full-size slide

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

    View full-size slide

  67. Welcome contributions

    View full-size slide

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

    View full-size slide

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

    View full-size slide