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

What's in Your Project Root?

What's in Your Project Root?

Let me ask you a question... What’s in *your* project root? If you take a look at PHP projects hosted on GitHub, you’ll find a plethora of configuration and other files in the project's root directory that are made out of everything. There’s JSON, Markdown, YAML, XML, and even some PHP (phew). Let’s talk about what all of these files do and what things you might be missing out on. From Composer to PHPUnit and from Travis to Phing, there are plenty of tools you can configure to improve the quality of your project, some with very little effort.

Jeremy Lindblom

March 14, 2015
Tweet

More Decks by Jeremy Lindblom

Other Decks in Programming

Transcript

  1. ?
    What's in your project root?
    By Jeremy Lindblom (@jeremeamia)

    View Slide

  2. ls

    View Slide

  3. build/
    docs/
    src/
    tests/
    vendor/
    .gitignore
    .gitattributes
    CHANGELOG.md
    LICENSE.md
    README.md
    Makefile
    composer.json
    composer.lock
    phpunit.xml

    View Slide

  4. .php?

    View Slide

  5. ★ DOCS ★
    ★ TESTS ★
    ★ BUILD ★
    ★ DEPLOY ★

    View Slide

  6. EVERYTHING NEEDED
    TO CODE, TEST,
    BUILD, & DEPLOY…

    View Slide

  7. EVERYTHING NEEDED
    TO CODE, TEST,
    BUILD, & DEPLOY…
    THAT'S NOT SENSITIVE!
    ★★★★★★★★★★★★★★

    View Slide

  8. THAT MEANS...
    ★ NO ★
    DATABASE PASSWORDS
    ACCESS TOKENS
    CREDENTIALS
    API KEYS

    View Slide

  9. — I work at —
    — on the —
    AWS SDK for PHP
    @awsforphp ★ aws/aws-sdk-php

    View Slide

  10. “My $500 Cloud Security Screwup“
    “My $2375 Amazon EC2 Mistake“
    “Attackers Scrape GitHub For Cloud
    Service Credentials, Hijack Account To
    Mine Virtual Currency“

    View Slide

  11. AWS Identity and
    Access Management
    We encourage the use of IAM User/Role
    credentials instead of root-level credentials

    View Slide

  12. •  Use IAM instance profile credentials on EC2
    •  Use a global credential file in your $HOME
    •  Use environment variables (e.g., getenv)
    In the AWS SDK, we document ways to…

    View Slide

  13. What's in your project root?

    View Slide

  14. Why is it in your project root?

    View Slide

  15. Why is it in your project root?
    †Does not apply to any actual PHP projects that I'm aware of.

    View Slide

  16. View Slide

  17. The 4 C's

    View Slide

  18. ★ COMPREHENSION
    ★ CONFIGURATION
    ★ COMPOSITION
    ★ CONSISTENCY

    View Slide

  19. ★ COMPREHENSION
    ★ CONFIGURATION
    ★ COMPOSITION
    ★ CONSISTENCY
    ★ CREDENTIALS

    View Slide

  20. View Slide

  21. ?
    SO, SRSLY, WTH IS IN HERE?

    View Slide

  22. IT DEPENDS…
    ?

    View Slide

  23. IT DEPENDS…
    What are you making?
    ★ APPLICATION ★
    ★ LIBRARY ★
    ★ TOOL ★

    View Slide

  24. ★ DIRS ★
    src/ or lib/
    tests/
    docs/
    bin/
    build/

    View Slide

  25. ★ DOCS ★
    README.md
    LICENSE.md or LICENSE
    CHANGELOG.md
    CONTRIBUTING.md
    phpdoc.xml

    View Slide

  26. README.md

    View Slide

  27. LICENSE(\.md)?
    MIT, BSD, GPL, LGPL, Apache 2, etc.
    LICENSES DEFINE THE TERMS FOR
    HOW OPEN SOURCE SOFTWARE CAN
    BE USED, MODIFIED, AND SHARED.
    Need help? choosealicense.com

    View Slide

  28. CHANGELOG.md
    # My Project
    ## 1.2.6
    ### Changed
    - Added super-awesome rainbow function.
    Need help? keepachangelog.com
    semver.org

    View Slide

  29. CONTRIBUTING.md

    View Slide

  30. ★ DOCS ★
    README.md
    LICENSE.md or LICENSE
    CHANGELOG.md
    CONTRIBUTING.md
    phpdoc.xml

    View Slide

  31. ★ COMPOSER ★
    vendor/
    composer.json
    composer.lock

    View Slide

  32. $ cat composer.json
    {
    "require": {
    "guzzlehttp/guzzle": "~5.0",
    "monolog/monolog": "~1.12.0"
    },
    "require-dev": {
    "phpunit/phpunit": "~4.0"
    },
    "autoload": {
    "psr-4":{"League\\Http\\":"src/"}
    }
    }

    View Slide

  33. $ composer install

    View Slide

  34. require 'vendor/autoloader.php';
    use GuzzleHttp\Client;
    $client = new Client();
    $url = 'http://example.com';
    $response = $client->get($url);

    View Slide

  35. SHOULD YOU
    COMMIT YOUR
    composer.lock
    FILE? THE ANSWER
    MAY SHOCK YOU.

    View Slide

  36. FOR APPLICATIONS?
    ★ YES ★
    FOR LIBRARIES?
    ★ SURE ★

    View Slide

  37. ★ JS/RB/PY ★
    package.json (npm)
    bower.json (bower)
    Gemfile (bundler)
    requirements.txt (pip)

    View Slide

  38. ★ GIT ★
    .git
    .gitignore
    .gitattributes

    View Slide

  39. .gitignore
    Tells Git to "ignore" certain files, so
    they are not included in the repo.

    View Slide

  40. $ cat .gitignore
    phpunit.xml

    composer.phar

    composer.lock

    vendor/

    build/artifacts/

    .idea
    *.log

    .DS_STORE

    Thumbs.db

    View Slide

  41. .DS_STORE

    Thumbs.db
    WHY?!?!?!?

    View Slide

  42. .gitattributes
    Among other things…
    It allows you choose which files to
    include in an archive of your repo.

    View Slide

  43. $ cat .gitattributes
    /tests export-ignore
    /vendor export-ignore
    /demos export-ignore
    .gitattributes export-ignore
    .gitignore export-ignore
    .travis.yml export-ignore
    build.xml export-ignore

    View Slide

  44. $ git archive -o proj.zip v1.0.2
    — It affects —

    View Slide

  45. $ git archive -o proj.zip v1.0.2
    $ composer install
    — It affects —
    — and —

    View Slide

  46. ★ TEST ★
    phpunit.xml
    phpunit.xml.dist
    features/
    phpspec.yml

    View Slide

  47. ★ TEST ★
    phpunit.xml
    phpunit.xml.dist
    features/
    phpspec.yml

    View Slide

  48. ???? YACF ????
    (Yet Another Config Format?)
    TEXT
    MARKDOWN
    XML
    JSON
    YAML
    INI
    RUBY
    BASH

    View Slide

  49. ★ TEST ★
    phpunit.xml
    phpunit.xml.dist
    features/
    phpspec.yml
    PHPUnit

    View Slide

  50. View Slide

  51. View Slide

  52. ★ TEST ★
    phpunit.xml
    phpunit.xml.dist
    features/
    phpspec.yml
    Behat

    View Slide

  53. ★ TEST ★
    phpunit.xml
    phpunit.xml.dist
    features/
    phpspec.yml
    PHPSpec

    View Slide

  54. ★ BUILD ★
    *.sh or *.bat
    Makefile
    build.xml
    Rakefile

    View Slide

  55. Makefile

    View Slide

  56. ★ ENV ★
    Vagrantfile
    Dockerfile

    View Slide

  57. Vagrant.configure(2) do |config|
    config.vm.box = "ubuntu/trusty64"
    config.vm.provider "virtualbox" do |vb|
    vb.memory = "2048"
    end
    config.vm.provision "shell", inline: <<-SHELL
    sudo apt-get update
    sudo apt-get install -y apache2 git hhvm
    sudo service apache2 restart
    sudo service hhvm restart
    SHELL
    end

    View Slide

  58. $ vagrant up

    View Slide

  59. JEDI
    MIND
    TRICK?

    View Slide

  60. ★ CI ★
    .travis.yml
    .scrutinizer.yml
    (also: Code Climate & SensioLabsInsight)
    .coveralls.yml

    View Slide

  61. language: php
    php:
    - 5.5
    - 5.6
    - 7.0
    - hhvm
    install: composer install
    script: vendor/bin/phpunit
    matrix:
    allow_failures:
    - php: 7.0
    - php: hhvm
    fast_finish: true

    View Slide

  62. View Slide

  63. ARE WE
    DONE
    YET?

    View Slide

  64. ★ ETC ★
    .hhconfig
    Procfile (heroku)
    fortrabbit.yml
    Other PaaS/Tools

    View Slide

  65. ★★★★★★★
    WHERE SHOULD
    YOU START?
    ★★★★★★★

    View Slide

  66. View Slide

  67. ★ thephpleague/skeleton ★
    src/
    tests/
    .gitignore
    .gitattributes
    .scrutinizer.yml
    .travis.yml
    CHANGELOG.md
    CONTRIBUTING.md
    LICENSE.md
    README.md
    composer.json
    phpunit.xml.dist

    View Slide

  68. ?
    What's in your project root?

    View Slide

  69. CODE
    DOCS
    TESTS
    BUILD
    DEPLOY
    TEXT
    MD
    JSON
    XML
    YAML
    INI
    BASH
    RUBY
    README.md
    LICENSE
    composer.json
    .gitignore
    .gitattributes
    phpunit.xml
    build.xml
    Vagrantfile
    .scrutinizer.yml
    .travis.yml

    View Slide

  70. CODE
    DOCS
    TESTS
    BUILD
    DEPLOY
    TEXT
    MD
    JSON
    XML
    YAML
    INI
    BASH
    RUBY
    README.md
    LICENSE
    composer.json
    .gitignore
    .gitattributes
    phpunit.xml
    build.xml
    Vagrantfile
    .scrutinizer.yml
    .travis.yml
    NO CREDENTIALS!!!

    View Slide

  71. Mr. Jackson admires his project root.

    View Slide

  72. Questions?
    By Jeremy Lindblom (@jeremeamia)
    https://joind.in/13084
    WHAT'S IN
    YOUR PROJECT
    ROOT?

    View Slide

  73. Resources
    •  h"ps://github.com/thephpleague/skeleton  
    •  h"ps://travis-­‐ci.org/  
    •  h"ps://scru9nizer-­‐ci.com/  
    •  h"p://choosealicense.com/  
    •  h"p://opensource.org/licenses  
    •  h"p://keepachangelog.com/  
    •  h"p://semver.org/  
    •  h"p://vagrantup.com/  
    •  h"ps://phpunit.de/manual/current/en/appendixes.configura9on.html  
    •  h"ps://www.phing.info/  
    •  h"p://www.phpdoc.org/  
    •  h"ps://help.github.com/ar9cles/github-­‐flavored-­‐markdown/  
    •  h"ps://github.com/aws/aws-­‐sdk-­‐php  

    View Slide