ServBay에서 Webman 프로젝트 생성 및 실행하기

Webman이란 무엇인가요?

Webman은 Workerman을 기반으로 한 고성능 PHP 비동기 웹 프레임워크로, 대규모 동시성 및 고성능 웹 애플리케이션 구축을 위해 설계되었습니다. 기존의 동기식 블로킹 프레임워크와 달리, Webman은 이벤트 기반 및 비동기 논블로킹 I/O 모델을 채택하여 대량의 동시 요청 처리 시 탁월한 성능을 자랑합니다. 직관적이고 사용하기 쉬운 API와 유연한 확장성을 제공해, 실시간 애플리케이션, API 서비스, 마이크로서비스 구축에 매우 적합합니다.

Webman의 주요 특징 및 장점

• 고성능: Workerman 기반의 이벤트 드리븐 비동기 I/O로, 방대한 동시 접속을 처리할 수 있으며 처리량이 전통적인 동기식 프레임워크를 능가합니다.
• 쉬운 사용성: 직관적인 API와 다양한 기능을 제공해 개발자가 빠르게 학습 및 프로젝트 구축이 가능합니다.
• 다양한 프로토콜 지원: HTTP, WebSocket 등 여러 레이어의 애플리케이션 프로토콜을 기본 지원하여, 다양한 유형의 서비스를 손쉽게 만들 수 있습니다.
• 유연한 확장성: Composer 패키지, 플러그인, 미들웨어 등으로 손쉽게 프레임워크 기능을 확장할 수 있습니다.
• 적은 리소스 소모: 전통적인 웹 서버 + PHP-FPM 구조 대비, Webman은 상주 메모리형 애플리케이션으로 리소스 오버헤드가 더 적습니다.
• 강력한 커뮤니티: 활발한 개발자 커뮤니티와 풍부한 공식 문서 리소스를 보유하고 있습니다.

Webman은 고성능 · 고가용성 웹앱 및 API 서비스의 신속한 구축을 도와주며, 특히 고동시성·저지연 처리가 요구되는 환경에 이상적입니다.

ServBay에서 간단한 Webman 프로젝트 생성 및 실행

이 가이드에서는 ServBay 로컬 개발 환경을 활용하여 Webman 기반의 간단한 웹 프로젝트를 생성 및 실행하는 전체 과정을 안내합니다. Webman 설치, 기본 라우팅 및 컨트롤러 코드 작성, ServBay에서 제공하는 데이터베이스(MySQL, PostgreSQL) 및 캐시 서비스(Redis, Memcached) 통합 방법을 순차적으로 살펴봅니다.

TIP

ServBay에서는 모든 로컬 사이트 프로젝트를 /Applications/ServBay/www 디렉터리에 저장하는 것을 권장합니다. 이를 통해 사이트 일괄 관리 및 사이트 설정(이전 "호스트" 설정) 등이 보다 편리합니다.

사전 준비사항

시작하기 전, 아래 준비가 완료되었는지 확인하세요.

1. ServBay 설치: macOS에 ServBay가 정상적으로 설치되어 있어야 합니다. ServBay는 PHP, Composer, MySQL, PostgreSQL, Redis, Memcached 등 본 튜토리얼에 필요한 모든 패키지를 통합 제공하는 원스톱 로컬 개발 환경입니다.
2. 필요 패키지 활성화: ServBay 컨트롤 패널에서 다음 패키지들이 설치 및 실행 중임을 확인하세요.
   • 선택한 PHP 버전(PHP 8.x 등 최신 버전 권장)
   • Composer(ServBay에 기본 내장)
   • MySQL
   • PostgreSQL
   • Redis
   • Memcached
   • 선택한 PHP 버전에 memcached, redis, pdo_mysql, pdo_pgsql 등 필수 확장 모듈이 활성화되어 있어야 합니다. ServBay는 일반적으로 이들 확장을 기본 활성화하나, ServBay의 PHP 설정 화면에서 확인이 가능합니다.
3. 터미널 사용: macOS의 '터미널' 앱 사용에 익숙해야 합니다.

Webman 설치

1. Composer 이용 가능 여부 확인

   ServBay에는 Composer가 기본 내장되어 있으며, 터미널에서 바로 사용할 수 있도록 설정되어 있습니다. 아래 명령으로 Composer가 정상 동작하는지 확인하세요:

   composer --version

   Composer 버전 정보가 정상적으로 출력된다면 Composer 준비 완료입니다.

2. ServBay 웹사이트 디렉터리 이동

   터미널을 열고 ServBay에서 권장하는 사이트 루트 디렉터리로 이동합니다.

   cd /Applications/ServBay/www

3. Composer로 Webman 프로젝트 생성

   Composer의 create-project 명령으로 Webman 프레임워크를 원하는 디렉토리에 설치합니다. 예시 프로젝트명은 servbay-webman-app으로 설정하겠습니다.

   composer create-project workerman/webman servbay-webman-app

   Composer가 Packagist로부터 Webman과 핵심 의존성을 servbay-webman-app 폴더에 다운로드하며 설치합니다.

4. 프로젝트 디렉터리 이동

   설치가 완료되면, 새로 생성된 프로젝트 디렉터리로 이동합니다.

   cd servbay-webman-app

5. 필수 컴포넌트 추가 설치

   데이터베이스 및 캐시 예제 시연을 위해 추가 Composer 패키지가 필요합니다. Webman은 일반적으로 illuminate/database(Laravel 데이터베이스 컴포넌트), illuminate/redis 등을 사용합니다. -W(--with-dependencies) 옵션은 의존성 충돌 방지를 위해 필요합니다.

   composer require -W illuminate/database illuminate/redis illuminate/pagination illuminate/events symfony/var-dumper

   해당 명령을 통해 데이터베이스 ORM, Redis 클라이언트, 페이지네이션, 이벤트 디스패처, 디버깅용 VarDumper 등을 설치합니다.

데이터베이스 및 테이블 생성

예제 코드가 정상 동작하려면 ServBay의 MySQL과 PostgreSQL에 대응되는 데이터베이스와 users 테이블이 필요합니다. ServBay에서 기본 제공되는 데이터베이스 root 계정 비밀번호는 password 입니다.

ServBay 컨트롤 패널에서 phpMyAdmin, pgAdmin 등 내장 데이터베이스 관리 툴을 실행하거나 터미널에서 아래 SQL을 직접 실행할 수 있습니다.

1. webman_app 데이터베이스 생성

   • MySQL:

     CREATE DATABASE IF NOT EXISTS webman_app CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

   • PostgreSQL:

     CREATE DATABASE webman_app;

2. webman_app 데이터베이스에 users 테이블 생성

   • MySQL:

     USE webman_app;
     CREATE TABLE users (
         id INT AUTO_INCREMENT PRIMARY KEY,
         name VARCHAR(255) NOT NULL,
         email VARCHAR(255) NOT NULL UNIQUE,
         created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
     );

   • PostgreSQL:

     \c webman_app; -- 새로 생성한 데이터베이스 접속
     CREATE TABLE users (
         id SERIAL PRIMARY KEY,
         name VARCHAR(255) NOT NULL,
         email VARCHAR(255) NOT NULL UNIQUE,
         created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
     );

웹 프로젝트 코드 작성

이제 라우트 정의, 컨트롤러 생성, 데이터베이스/캐시 연동 로직 구현 예제를 추가해봅니다.

1. 라우트 설정

   프로젝트 루트의 config/route.php 파일을 열어 아래와 같은 라우트 코드를 추가하세요.

   <?php
   
   use Webman\Route;
   use app\controller\IndexController;
   use app\controller\CacheController;
   use app\controller\DatabaseController;
   
   // 루트 경로 라우트 정의, IndexController의 index 메서드로 연결
   Route::any('/', [IndexController::class, 'index']);
   
   // 캐시 관련 라우트 정의
   Route::any('/memcached', [CacheController::class, 'memcached']);
   Route::any('/redis', [CacheController::class, 'redis']);
   
   // 데이터베이스 관련 라우트 정의
   Route::any('/mysql-add', [DatabaseController::class, 'mysqlAdd']);
   Route::any('/mysql', [DatabaseController::class, 'mysqlGet']);
   Route::any('/pgsql-add', [DatabaseController::class, 'pgsqlAdd']);
   Route::any('/pgsql', [DatabaseController::class, 'pgsqlGet']);
   
   // 이외 라우트 추가 가능...

2. 컨트롤러 파일 생성

   app/controller 디렉터리에 IndexController.php, CacheController.php, DatabaseController.php 파일을 만들고, 각각 아래 코드를 추가합니다.

   • app/controller/IndexController.php: 루트 경로 처리 컨트롤러

     <?php
     
     namespace app\controller;
     
     use support\Request;
     use support\Response; // Response 클래스 임포트
     
     class IndexController
     {
         /**
          * 루트 경로 요청 처리 예시
          * @param Request $request 현재 요청 객체
          * @return Response Response 객체 반환
          */
         public function index(Request $request): Response // 반환 타입 명시
         {
             // 간단한 텍스트 응답 반환
             return response('Hello ServBay & Webman!'); // 환영 메시지
         }
     }

   • app/controller/CacheController.php: Memcached, Redis 연동 예시

     <?php
     
     namespace app\controller;
     
     use support\Request;
     use support\Response;
     use Memcached; // Memcached 클래스 임포트
     use support\Redis; // Webman 제공 Redis 파사드 임포트
     
     class CacheController
     {
         /**
          * Memcached 사용 예제
          * @param Request $request
          * @return Response
          */
         public function memcached(Request $request): Response
         {
             // Memcached 서버 연결, ServBay 기본주소 127.0.0.1:11211
             $memcached = new Memcached();
             $memcached->addServer('127.0.0.1', 11211);
     
             // 캐시 저장, 유효기간 60초
             $success = $memcached->set('servbay_key', 'Hello Memcached from ServBay!', 60); // key, value 갱신
             if (!$success) {
                  return response('Failed to set Memcached key', 500);
             }
     
             // 캐시 조회
             $value = $memcached->get('servbay_key'); // key
     
             // 값 반환
             return response($value ?: 'Memcached key not found or expired'); // 미존재·만료시 안내
         }
     
         /**
          * Redis 사용 예제
          * @param Request $request
          * @return Response
          */
         public function redis(Request $request): Response
         {
             // Webman Redis 파사드로 값 저장
             Redis::set('servbay_redis_key', 'Hello Redis from ServBay!'); // key, value 갱신
     
             // Webman Redis로 값 조회
             $value = Redis::get('servbay_redis_key'); // key
     
             // 값 반환
             return response($value ?: 'Redis key not found'); // 미존재시 안내
         }
     }

   • app/controller/DatabaseController.php: MySQL, PostgreSQL 예제

     <?php
     
     namespace app\controller;
     
     use support\Request;
     use support\Response;
     use support\Db; // Webman 제공 Db 파사드
     
     class DatabaseController
     {
         /**
          * MySQL 사용자 추가
          * @param Request $request
          * @return Response
          */
         public function mysqlAdd(Request $request): Response
         {
             try {
                 // 'mysql' DB에 데이터 입력
                 Db::connection('mysql')->table('users')->insert([
                     'name' => 'ServBay Webman MySQL User', // 예시 데이터 업데이트
                     'email' => 'mysql_demo@servbay.test', // 예시 이메일
                     'created_at' => date('Y-m-d H:i:s') // created_at 필드
                 ]);
                 return response('User added to MySQL'); // 응답 메시지
             } catch (\Exception $e) {
                 return response('Error adding user to MySQL: ' . $e->getMessage(), 500); // 에러 처리
             }
         }
     
         /**
          * MySQL 사용자 목록 조회
          * @param Request $request
          * @return Response
          */
         public function mysqlGet(Request $request): Response
         {
             try {
                 // 'mysql' DB 모든 사용자 조회
                 $users = Db::connection('mysql')->table('users')->get();
                 // JSON 응답
                 return response(json_encode($users), 200, ['Content-Type' => 'application/json']); // Content-Type 명시
             } catch (\Exception $e) {
                  return response('Error getting users from MySQL: ' . $e->getMessage(), 500); // 에러처리
             }
         }
     
         /**
          * PostgreSQL 사용자 추가
          * @param Request $request
          * @return Response
          */
         public function pgsqlAdd(Request $request): Response
         {
              try {
                 // 'pgsql' DB에 데이터 입력
                 Db::connection('pgsql')->table('users')->insert([
                     'name' => 'ServBay Webman PgSQL User', // 예시 데이터
                     'email' => 'pgsql_demo@servbay.test', // 예시 이메일
                     'created_at' => date('Y-m-d H:i:s') // created_at 필드
                 ]);
                 return response('User added to PostgreSQL'); // 응답 메시지
              } catch (\Exception $e) {
                 return response('Error adding user to PostgreSQL: ' . $e->getMessage(), 500); // 에러처리
              }
         }
     
         /**
          * PostgreSQL 사용자 목록 조회
          * @param Request $request
          * @return Response
          */
         public function pgsqlGet(Request $request): Response
         {
              try {
                 // 'pgsql' DB 모든 사용자 조회
                 $users = Db::connection('pgsql')->table('users')->get();
                 // JSON 응답
                 return response(json_encode($users), 200, ['Content-Type' => 'application/json']); // Content-Type 명시
              } catch (\Exception $e) {
                 return response('Error getting users from PostgreSQL: ' . $e->getMessage(), 500); // 에러처리
              }
         }
     }

3. 데이터베이스 연결 설정

   프로젝트 루트의 config/database.php 파일을 열어 MySQL, PostgreSQL 연결 정보를 아래와 같이 설정합니다. ServBay의 기본 호스트는 127.0.0.1이고, 포트는 3306(MySQL), 5432(PostgreSQL)이며, 사용자 root, 비밀번호 password로 설정되어 있습니다.

   <?php
   /**
    * 데이터베이스 설정
    */
   return [
       // 기본 데이터베이스 연결
       'default' => 'mysql',
   
       // DB 연결 설정 목록
       'connections' => [
           'mysql' => [
               'driver'    => 'mysql',
               // ServBay 기본 MySQL 주소 및 포트
               'host'      => '127.0.0.1',
               'port'      => 3306,
               // 생성했던 DB 이름
               'database'  => 'webman_app',
               // ServBay 기본 MySQL 계정
               'username'  => 'root',
               // ServBay 기본 MySQL 비밀번호
               'password'  => 'password',
               'charset'   => 'utf8mb4',
               'collation' => 'utf8mb4_unicode_ci',
               'prefix'    => '',
               'strict'    => true,
               'engine'    => null,
           ],
           'pgsql' => [
               'driver'   => 'pgsql',
               // ServBay 기본 PostgreSQL 주소 및 포트
               'host'     => '127.0.0.1',
               'port'     => 5432,
                // 생성했던 DB 이름
               'database' => 'webman_app',
                // ServBay 기본 PostgreSQL 계정
               'username' => 'root',
                // ServBay 기본 PostgreSQL 비밀번호
               'password' => 'password',
               'charset'  => 'utf8',
               'prefix'   => '',
               'schema'   => 'public',
               'sslmode'  => 'prefer', // require, verify-ca, verify-full 등 지정 가능
           ],
           // 추가 DB 연결 가능 ...
       ],
   ];

   중요: 운영환경 배포 시에는 반드시 기본 데이터베이스 비밀번호를 변경하고, 코드 내에 민감 정보 하드코딩을 피하세요.

Webman 프로젝트 실행

Webman 프로젝트는 자체 제공하는 start.php 스크립트를 통해 Workerman 프로세스를 실행합니다. (전통적인 Nginx/Apache + PHP-FPM 방식과는 다르게) Webman은 상주 메모리형 비동기 애플리케이션입니다.

프로젝트 루트(/Applications/ServBay/www/servbay-webman-app)에서 아래 명령어로 Webman을 실행할 수 있습니다.

php start.php start

정상 실행 시 Webman 부팅 메시지와 함께 HTTP 요청을 기본적으로 127.0.0.1:8787에서 수신 대기합니다.

• 참고: 위 php 명령은 ServBay환경의 PHP를 사용합니다. ServBay는 터미널 환경을 자동 설정하여, ServBay에 설치된 PHP 버전을 바로 활용 가능하게 만듭니다.
• Webman을 백그라운드로 실행하려면 -d 옵션 사용: php start.php start -d
• Webman 서비스 정지는: php start.php stop
• Webman 서비스 재시작은: php start.php restart
• 무중단 요청 평탄 재시작은: php start.php reload

프로젝트 테스트

Webman이 정상 구동되어 127.0.0.1:8787 포트를 리스닝 상태로 두면, 브라우저에서 아래 URL을 테스트할 수 있습니다.

• http://localhost:8787/: "Hello ServBay & Webman!" 메시지가 출력됩니다.
• http://localhost:8787/memcached: "Hello Memcached from ServBay!"가 출력되면, Webman에서 ServBay의 Memcached 서비스 연동에 성공한 것입니다.
• http://localhost:8787/redis: "Hello Redis from ServBay!"가 출력되면 Webman에서 ServBay의 Redis 서비스 연동에 성공한 것입니다.
• http://localhost:8787/mysql-add: "User added to MySQL" 메시지. MySQL DB users 테이블에 레코드가 추가됩니다.
• http://localhost:8787/mysql: MySQL DB users 테이블의 사용자 목록이 JSON 포맷으로 출력됩니다.
• http://localhost:8787/pgsql-add: "User added to PostgreSQL" 메시지. PostgreSQL DB users 테이블에 레코드가 추가됩니다.
• http://localhost:8787/pgsql: PostgreSQL DB users 테이블 사용자 목록을 JSON 포맷으로 출력.

접속 중 문제 발생 시, Webman 터미널 오류 메시지, ServBay에서 MySQL, PostgreSQL, Redis, Memcached 패키지의 실행여부 및 PHP 확장 모듈 활성화 여부를 점검해 보세요.

자주 묻는 질문 (FAQ)

• Q: php start.php start 명령어가 실행되지 않을 때
  • A: 반드시 터미널에서 servbay-webman-app 프로젝트 폴더로 이동(cd)한 후 실행하세요. 또한, ServBay 설치 PHP가 PATH에 정확히 추가되어 있는지 확인(ServBay가 기본 자동 설정)하세요.
• Q: localhost:8787 접속 실패 메시지가 뜰 때
  • A: 터미널 내 php start.php start 실행 메시지에서 오류 여부를 확인하세요. 8787 포트가 다른 프로그램에서 사용 중인지 확인. 필요시 Webman의 config/server.php에서 포트 변경 가능.
• Q: 데이터베이스 연결 실패
  • A: ServBay에서 MySQL 및 PostgreSQL 패키지가 정상 실행 중인지 확인. config/database.php 내 주소, 포트, DB명, 계정, 비밀번호가 ServBay 설정과 일치하는지(기본 사용자 root, 비번 password) 검토. webman_app 데이터베이스 및 users 테이블 생성 여부 점검.
• Q: Memcached 또는 Redis 연결 실패
  • A: ServBay의 Memcached / Redis가 실행 중인지 확인. app/controller/CacheController.php 내 주소 및 포트가 기본값(127.0.0.1:11211, 127.0.0.1:6379)과 일치하는지 체크. PHP의 memcached, redis 확장 활성화 여부 확인.

마무리

이상으로 ServBay 로컬 개발 환경에서 기본적인 Webman 프로젝트를 생성, 설정, 실행하는 전 과정을 안내하였습니다. ServBay의 올인원 개발서비스를 활용해 빠른 Webman 환경 셋업은 물론, 데이터베이스, 캐시 연동까지 경험할 수 있습니다. Webman 고성능 구조와 ServBay의 편리함이 결합되어 비동기 PHP 애플리케이션 개발에 든든한 지원군이 되어줍니다. 본 가이드가 여러분의 ServBay 및 Webman 활용에 실질적 도움이 되길 바랍니다.