PHP 백엔드
로컬 실행 가이드

이 가이드는 개발 경험이 많지 않은 분을 위해 작성됐어요. 명령어의 의미를 몰라도 괜찮으니, 안내된 순서대로 따라해 주세요.

진행할 작업은 두 가지예요. 컴퓨터에 PHP를 설치하고, 결제 서버를 실행해요. 이 문서는 백엔드 서버를 띄우는 가이드이며, 결제 테스트 화면(프론트엔드)은 다루지 않아요.

미리 알아둘 용어

PHP 8.x를 컴퓨터에 설치해요. 이미 설치되어 있다면 이 단계는 건너뛰어도 돼요.

1. Windows — 공식 zip 받아 설치하기

1. 다운로드
   브라우저에서 windows.php.net/download에 접속한 뒤, VS17 x64 Non Thread Safe 항목의 Zip을 클릭해 다운로드해 주세요. (버전은 8.x 이상이면 돼요.)
2. 압축 해제 후 폴더 이동
   받은 zip 파일을 압축 해제해요. 생성된 폴더(예: php-8.3.x-Win32-...)를 C:\php로 옮기거나 이름을 C:\php로 변경해 주세요.
3. PATH 등록
   시작 버튼에서 "환경 변수"를 검색해 "시스템 환경 변수 편집"을 클릭한 뒤, "환경 변수" 버튼을 누르고 위쪽 사용자 변수의 Path를 선택하세요. 이어서 "편집" → "새로 만들기" → C:\php 입력 → 확인을 눌러 주세요. PowerShell을 새로 열어야 적용돼요.
4. 설치 확인
   PowerShell을 열고 아래 명령을 입력해 주세요. 버전 숫자(예: PHP 8.3.x)가 표시되면 완료예요.

   terminal복사

   php --version

2. macOS — Homebrew로 설치하기

1. Homebrew가 없다면 먼저 설치
   터미널을 열고 아래 명령을 입력해 주세요. 이미 설치되어 있다면 건너뛰셔도 돼요.

   terminal복사

   /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

2. PHP 설치
   terminal복사

   brew install php

3. 설치 확인
   버전 숫자가 표시되면 완료예요.

   terminal복사

   php --version

3. Linux (Ubuntu / Debian 계열)

1. 패키지 설치
   terminal복사

   sudo apt update && sudo apt install -y php php-curl php-mbstring php-openssl

2. 설치 확인
   terminal복사

   php --version

이제 서버를 실행해요. 아래 순서를 그대로 따라해 주세요. 명령은 한 줄씩 복사해 터미널에 붙여넣고 Enter를 누르시면 돼요.

1. 터미널 열기
   Windows는 PowerShell, Mac은 터미널 앱을 열어 주세요.
2. 프로젝트 폴더로 이동
   프로젝트를 저장한 폴더 안의 php 폴더로 이동해요. 아래의 <프로젝트 폴더> 부분을 본인이 저장한 실제 경로로 바꿔 주세요.

   terminal복사

   cd "<프로젝트 폴더>/php"

   경로 입력이 익숙하지 않다면, 터미널에 cd (cd 뒤에 공백 한 칸)를 입력한 뒤 php 폴더를 터미널 창으로 드래그해 주세요. 경로가 자동으로 채워져요. Windows는 폴더에서 Shift + 우클릭 → "경로로 복사" 후 붙여넣기 하시면 돼요.
3. PHP 내장 서버 실행
   아래 한 줄로 서버가 실행돼요. Windows · macOS · Linux 모두 동일한 명령이에요.

   terminal복사

   php -S localhost:8080 -t public public/router.php

   터미널에 PHP ... Development Server (http://localhost:8080) started 같은 메시지가 표시되면 완료예요.
4. 서버 실행 확인
   터미널에 PHP ... Development Server (http://localhost:8080) started 같은 메시지가 표시되면 서버가 실행된 거예요. 더 확실한 확인 방법은 다음 04를 참고해 주세요.

이 문서는 서버(백엔드) 실행을 위한 가이드예요. 화면(프론트엔드)이 아닌 서버의 정상 실행 여부를 응답으로 확인해요.

확인 방법

방법 1 · 터미널 메시지: 서버를 실행한 터미널에서 PHP ... Development Server (http://localhost:8080) started 같은 줄이 보이면 서버가 실행된 거예요.

방법 2 · 응답 확인: 브라우저 주소창에 http://localhost:8080/config를 입력하거나, 새 터미널에서 아래 명령을 실행해 주세요. {"site_cd":"T0000"}와 같은 응답이 표시되면 서버와 라우팅이 정상 동작하는 거예요.

curl http://localhost:8080/config

실행 중 자주 만나게 되는 문제와 해결 방법이에요. 대부분 PHP의 PATH 문제이거나, 포트가 이미 사용 중이어서 발생해요.

증상별 해결법

테스트가 끝나면 다음 방법으로 서버를 종료해 주세요.

서버가 동작 중인 터미널 창에서 Ctrl + C를 눌러 주세요. Mac도 동일해요. 서버가 종료되며, 터미널이 다시 명령을 입력할 수 있는 상태로 돌아와요.