PHP 패키지 체크리스트

현대 PHP 개발에 필수적인 14가지 항목. 번역 글.

2015년 4월 17일

PHP Package Checklist의 번역 글이다. 패키지 개발을 하지 않고 있더라도 PHP 개발을 하고 있다면 충분히 염두해볼 만한 내용이 포함되어 있고 참고할 이야기가 많다.

패키지명을 현명하게 선택하기

  • 다른 프로젝트에서 사용되고 있지 않은 이름을 선택한다.
  • 패키지명과 PHP 네임스페이스가 일치하도록 관리한다.
  • 성이나 개인 닉네임을 PHP 네임스페이스로 사용하지 않는다.

소스를 공개적으로 호스팅하기

  • 공개 프로젝트는 GitHub를 무료로 사용할 수 있다.
  • GitHub은 이슈를 관리하고 기능 요청이나 풀 리퀘스트에 도움이 된다.
  • 대안으로 Bitbucket도 사용할 수 있다.

Autoloader 친화적으로 개발하기

  • PSR-4와 호환이 되는 네임스페이스를 사용한다.
  • 코드는 src 폴더 내에 넣는다.

Composer를 통해 배포하기

  • PHP를 위한 의존성 관리 도구인 Composer에서 라이브러리를 사용 가능하게 한다.
  • Composer의 주 리포지터리인 Packagist에 등록한다.

프레임워크에 대해 독립적으로 개발하기

  • 프로젝트를 하나의 프레임워크에 제한을 두지 않는다.
  • 서비스 프로바이더를 제공해 특정 프레임워크에서 사용할 수 있도록 지원한다.

코딩 스타일을 따르기

  • PSR-2 코딩 스타일 가이드를 철저히 지킬 것을 강력하게 권장한다.
  • 빠르게 자동으로 코드를 수정해주는 PHP Coding Standards Fixer를 사용한다.
  • 코딩 표준에 대해 자동으로 확인해주는 PHP Code Sniffer를 사용한다.

유닛 테스트를 작성하기

  • 주요 코드를 커버하는 것에 초점을 둔다.
  • PHPUnit은 사실상 표준인 PHP 유닛 테스트 프레임워크다.
  • 대안으로 phpspec, Behat, atoum, Codeception이 있다.

DocBlock을 사용하기

  • 인라인 문서화를 위해 DocBlock을 제공한다.
  • DocBlock은 PhpStorm과 같은 IDE의 코드 완성을 향상하는데 도움이 된다.
  • phpDocumentor를 활용해 API 문서로 자동 변환이 가능하다.

유의적 버전을 사용하기

  • 버전 번호를 관리하는데 유의적 버전을 사용한다.
  • 주버전.부버전.수버전(MAJOR.MINOR.PATCH) 시스템을 사용한다.
  • 개발 버전의 업그레이드는 변경으로 인해 깨지는 것을 걱정하지 않도록 안전하게 제공해야 한다.
  • 릴리즈마다 tag로 버전을 적는 것을 잊지 말자.

변경 로그를 유지하기

  • 매 릴리즈를 할 때마다 변경 로그를 깔끔하게 공개한다.
  • Keep a CHANGELOG 양식을 사용하는 것을 고려한다.

지속적인 통합(continuous integration)을 사용하기

  • 자동으로 코딩 표준과 테스트를 구동하는 서비스를 사용한다.
  • 다양한 버전의 PHP에서 테스트를 구동하는 좋은 방법이다.
  • 풀 리퀘스트가 제출될 때 자동으로 구동할 수 있다.
  • Travis-CI, scrutinizer, circleci를 사용할 수 있다.

상세한 문서를 작성하기

  • 좋은 문서화는 성공적인 패키지에 필수적인 요소다.
  • 적어도 설명을 포함한 README를 작성해 리포지터리에 포함한다.
  • 문서를 GitHub Pages로 제공하는 것을 고려한다.
  • 대안으로 Read the Docs를 활용할 수 있다.

라이센스를 포함하기

  • 라이센스를 포함하는 것은 현재까지 한 일을 보호할 수 있는 작은 방법이다.
  • choosealicense.com 사이트를 참고한다. 대부분의 PHP 프로젝트는 MIT 라이센스를 사용한다.
  • 적어도 LICENSE 파일은 라이브러리에 포함해야 한다.
  • Dockblock에도 라이센스를 포함할 것을 고려해본다.

기여를 환영하기

  • 당신의 프로젝트를 누군가 돕길 원한다면 당연히 그걸 물어봐야 한다.
  • CONTRIBUTING 파일을 사용해 프로젝트 기여를 환영하자.
  • 이 파일에 테스트와 같은 프로젝트 요구 사항을 설명하는 내용을 작성한다.

위 리스트의 모든 내용을 한번에 적용할 수 없다면 필요한 부분부터 점차적으로 적용해 나가도록 하자. Autoloader는 익숙해지면 include 지옥에서 벗어날 수 있는 강력한 기능이다. 위에서 소개된, 코딩 스타일을 자동으로 교정해주는 도구들은 문법 고민을 덜어주고 비지니스 로직에 집중할 수 있도록 돕는다. 현대적인 PHP 개발을 생각하고 있다면 위 모든 항목 하나하나 살펴보는 것이 도움이 된다.

더 읽을 거리