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.

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