PHPStan은 PHP 코드 정적 분석 도구로, 실제 실행 전에 코드의 잠재적인 오류를 찾아주는 개발 도구다.
특히 오래된 PHP 프로젝트나 유지보수 중인 쇼핑몰·예약 시스템처럼 규모가 큰 프로젝트에서 매우 유용하다.
“코드는 잘 실행되는데 왜 오류가 날까?”
이런 상황을 줄이고 싶다면 PHPStan을 한 번쯤 반드시 사용해보는 것이 좋다.
필자도 PHP 5.x 기반 프로젝트를 PHP 7.4로 마이그레이션할 때 PHPStan으로 숨겨진 오류를 상당수 발견했다.
실행은 되지만 잘못된 타입 사용이나 존재하지 않는 메서드 호출 같은 문제를 미리 잡을 수 있어서 유지보수 시간이 크게 줄었다.
PHPStan이 필요한 이유
PHP는 비교적 자유로운 문법을 제공한다.
그만큼 잘못된 코드가 있어도 실행 시점까지 문제를 발견하지 못하는 경우가 많다.
예를 들어 아래 같은 코드가 있다고 해보자.
<?php
$name = "1000";
$total = $name + "원";실행은 될 수도 있지만 의도하지 않은 결과가 발생할 수 있다.
또는 이런 경우도 많다.
<?php
$user->getUserName();실제로는 getUsername() 메서드인데 오타가 있어도
해당 코드가 실행되기 전까지는 오류를 발견하지 못한다.
이런 문제를 미리 검사해주는 것이 PHPStan이다.
PHPStan 주요 기능
타입 오류 감지
가장 많이 사용하는 기능이다.
- string에 숫자 연산 수행
- 배열인데 문자열처럼 사용
- null 가능 변수 접근
- int와 string 혼용
같은 문제를 분석해서 알려준다.
예시:
<?php
$total = "abc" + 100;PHPStan은 이런 코드를 분석해 타입 문제가 있다고 경고한다.
존재하지 않는 메서드 탐지
오타나 잘못된 객체 접근을 쉽게 찾을 수 있다.
<?php
$user->getNmae();실제 메서드가 없으면 분석 결과에 오류가 출력된다.
대규모 프로젝트에서는 이런 단순 오타를 찾는 데 시간이 오래 걸리는데,
PHPStan이 상당 부분 자동으로 처리해준다.
미사용 변수 확인
사용하지 않는 변수나 파라미터도 찾아준다.
<?php
$name = "test";선언만 하고 사용하지 않으면 경고가 출력될 수 있다.
코드 정리나 리팩토링 시 유용하다.
항상 true/false인 조건문 탐지
불필요한 조건문도 확인 가능하다.
<?php
if (true) {
}또는 절대 실행되지 않는 코드도 탐지한다.
복잡한 if문이 많은 관리자 페이지 개발 시 꽤 도움이 된다.
DocBlock 기반 타입 검사
PHPStan의 강력한 기능 중 하나다.
아래처럼 @param, @return 등을 분석해서 타입 검사를 강화한다.
<?php
/**
* @param int $price
* @return string
*/
function get_price($price) {
return $price;
}이 경우 반환값이 실제로는 int인데 string으로 선언되어 있으므로
PHPStan이 타입 오류를 알려준다.
특히 협업 프로젝트에서 코드 규칙을 유지할 때 효과적이다.
PHPStan 설치 방법
Composer로 설치
가장 일반적인 방법이다.
composer require --dev phpstan/phpstan
설치 후 아래 명령어로 실행한다.
vendor/bin/phpstan analyse /home/your/project/path
phpstan.phar 파일 직접 실행
Composer 사용이 어려운 서버라면 PHAR 파일만 업로드해서 사용할 수도 있다.
공식 다운로드: PHPStan GitHub Releases
다운로드 후 서버에 업로드한다.
실행:
php phpstan.phar analyse /home/your/project/path
실제 사용 사례
필자는 오래된 PHP 쇼핑몰 프로젝트를 점검하면서 PHPStan을 사용했다.
처음 실행했을 때:
- 존재하지 않는 함수 호출
- nullable 변수 접근
- 배열 키 오류
- 잘못된 return 타입
같은 문제가 수백 개 이상 발견됐다.
특히 “실행은 되지만 특정 상황에서만 터지는 오류”를 미리 찾을 수 있었던 점이 가장 좋았다.
운영 중인 사이트는 테스트 환경에서 모든 기능을 직접 눌러보기가 어렵다.
이럴 때 정적 분석 도구가 큰 도움이 된다.
PHPStan의 한계
PHPStan은 정적 분석 도구다.
즉:
- 실제 브라우저 동작 확인
- SQL 실행 결과 확인
- API 응답 확인
- JavaScript 오류 탐지
같은 것은 하지 못한다.
또한 개발 중 실시간으로 자동 수정해주는 도구는 아니다.
“현재 작성된 PHP 소스에 문제가 있는지 분석”하는 역할에 가깝다.
그래서 보통은:
- 개발 완료 후 점검
- 배포 전 검사
- 리팩토링 전 분석
- PHP 버전 업그레이드 전 검사
용도로 많이 사용한다.
PHPStan을 꼭 써야 하는 프로젝트
특히 아래 프로젝트라면 추천한다.
- 오래된 PHP 프로젝트
- PHP 5 → PHP 7/8 마이그레이션
- 유지보수 인력이 여러 명인 프로젝트
- 쇼핑몰·예약 시스템
- 관리자 기능이 많은 서비스
- 함수 수가 많은 레거시 코드
코드 규모가 커질수록 효과가 커진다.
정리
PHPStan은 PHP 코드의 잠재적인 오류를 실행 전에 분석해주는 강력한 정적 분석 도구다.
특히:
- 타입 오류
- 잘못된 메서드 호출
- 불필요한 조건문
- nullable 문제
- DocBlock 기반 타입 검사
등을 자동으로 확인할 수 있다.
레거시 PHP 프로젝트를 유지보수하거나 PHP 버전 업그레이드를 진행 중이라면
한 번쯤 꼭 적용해보는 것을 추천한다.