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 디렉터리에 저장하는 것을 권장합니다. 이를 통해 사이트 일괄 관리 및 사이트 설정(이전 "호스트" 설정) 등이 보다 편리합니다.

사전 준비사항

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

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

Webman 설치

Composer 이용 가능 여부 확인
ServBay에는 Composer가 기본 내장되어 있으며, 터미널에서 바로 사용할 수 있도록 설정되어 있습니다. 아래 명령으로 Composer가 정상 동작하는지 확인하세요:
bash
```
composer --version
```
1
Composer 버전 정보가 정상적으로 출력된다면 Composer 준비 완료입니다.
ServBay 웹사이트 디렉터리 이동
터미널을 열고 ServBay에서 권장하는 사이트 루트 디렉터리로 이동합니다.
bash
```
cd /Applications/ServBay/www
```
1
Composer로 Webman 프로젝트 생성
Composer의 create-project 명령으로 Webman 프레임워크를 원하는 디렉토리에 설치합니다. 예시 프로젝트명은 servbay-webman-app으로 설정하겠습니다.
bash
```
composer create-project workerman/webman servbay-webman-app
```
1
Composer가 Packagist로부터 Webman과 핵심 의존성을 servbay-webman-app 폴더에 다운로드하며 설치합니다.
프로젝트 디렉터리 이동
설치가 완료되면, 새로 생성된 프로젝트 디렉터리로 이동합니다.
bash
```
cd servbay-webman-app
```
1
필수 컴포넌트 추가 설치
데이터베이스 및 캐시 예제 시연을 위해 추가 Composer 패키지가 필요합니다. Webman은 일반적으로 illuminate/database(Laravel 데이터베이스 컴포넌트), illuminate/redis 등을 사용합니다. -W(--with-dependencies) 옵션은 의존성 충돌 방지를 위해 필요합니다.
bash
```
composer require -W illuminate/database illuminate/redis illuminate/pagination illuminate/events symfony/var-dumper
```
1
해당 명령을 통해 데이터베이스 ORM, Redis 클라이언트, 페이지네이션, 이벤트 디스패처, 디버깅용 VarDumper 등을 설치합니다.

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

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

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

webman_app 데이터베이스 생성

MySQL:

sql

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

PostgreSQL:
sql
```
CREATE DATABASE webman_app;
```
1

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

MySQL:

sql

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:

sql

\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
);

웹 프로젝트 코드 작성

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

라우트 설정

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

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']);

// 이외 라우트 추가 가능...

컨트롤러 파일 생성

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

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

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

<?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

<?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' => '[email protected]', // 예시 이메일
                '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' => '[email protected]', // 예시 이메일
                '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); // 에러처리
         }
    }
}

데이터베이스 연결 설정

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

php

<?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을 실행할 수 있습니다.

bash

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 활용에 실질적 도움이 되길 바랍니다.

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

Webman이란 무엇인가요? ​

Webman의 주요 특징 및 장점 ​

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

사전 준비사항 ​

Webman 설치 ​

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

웹 프로젝트 코드 작성 ​

Webman 프로젝트 실행 ​

프로젝트 테스트 ​

자주 묻는 질문 (FAQ) ​

마무리 ​