ServBay에서 Webman 프로젝트 생성 및 실행하기
Webman이란?
Webman은 Workerman 기반의 고성능 PHP 비동기 웹 프레임워크로, 대규모 동시성 및 고성능 웹 애플리케이션 구축을 위해 설계되었습니다. 기존 동기식 블로킹 프레임워크와 달리, Webman은 이벤트 드리븐 및 비동기 논블로킹 I/O 모델을 채택하여 다수의 동시 요청을 효과적으로 처리할 수 있습니다. 직관적이고 간결한 API와 유연한 확장성으로, 실시간 애플리케이션, API 서비스, 마이크로서비스 등 다양한 용도에 적합합니다.
Webman의 주요 특징 및 장점
- 고성능: 이벤트 드리븐과 비동기 논블로킹 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에서 프로젝트 관리 및 로컬 사이트(구 '호스트') 설정이 용이해집니다.
사전 준비
시작하기 전에 아래 준비를 완료해야 합니다.
- 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에서 기본 활성화되어 있습니다. PHP 설정 화면에서 추가로 확인할 수 있습니다.
- 터미널 사용 가능: macOS의 터미널 앱 사용에 익숙해야 합니다.
Webman 설치
Composer 사용 가능 여부 확인
ServBay는 Composer를 기본 포함하고 있으며, 터미널에서 바로 사용할 수 있도록 설정되어 있습니다. 터미널에 아래 명령어를 입력해 확인할 수 있습니다:
bashcomposer --version1Composer 버전 정보가 정상적으로 표시되면 준비가 완료된 것입니다.
ServBay 웹사이트 디렉토리로 이동
터미널을 열고 ServBay 추천 웹사이트 루트 디렉터리로 이동합니다:
bashcd /Applications/ServBay/www1Composer로 Webman 프로젝트 생성
Composer의
create-project명령으로 지정 디렉터리에 Webman 프레임워크를 설치합니다. 프로젝트 이름은servbay-webman-app으로 지정하겠습니다:bashcomposer create-project workerman/webman servbay-webman-app1Composer가 Packagist에서 Webman과 핵심 의존성을
servbay-webman-app디렉터리로 다운로드합니다.프로젝트 디렉터리로 이동
설치가 완료되면 새로 생성된 프로젝트 디렉터리로 이동하세요:
bashcd servbay-webman-app1필수 컴포넌트 설치
데이터베이스 및 캐시 기능을 시연하려면 추가 Composer 패키지가 필요합니다. Webman은 일반적으로
illuminate/database(Laravel의 DB 컴포넌트),illuminate/redis등을 사용합니다.-W(또는--with-dependencies) 옵션을 통해 의존성 충돌을 해결하면서 설치할 수 있습니다.bashcomposer require -W illuminate/database illuminate/redis illuminate/pagination illuminate/events symfony/var-dumper1이 명령으로 ORM, Redis 클라이언트, 페이징 컴포넌트, 이벤트 디스패처, 디버깅용 VarDumper까지 설치합니다.
데이터베이스 및 테이블 생성
예제 코드가 정상 작동하려면 ServBay의 MySQL 및 PostgreSQL에 대응하는 데이터베이스와 users 테이블을 만들어야 합니다. ServBay 기본 데이터베이스 root 계정 비밀번호는 password입니다.
ServBay가 제공하는 DB 관리 툴(phpMyAdmin 또는 pgAdmin, ServBay 컨트롤 패널에서 접근 가능)이나 명령줄에서 아래 SQL을 실행할 수 있습니다.
데이터베이스
webman_app생성- MySQL:sql
CREATE DATABASE IF NOT EXISTS webman_app CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;1 - PostgreSQL:sql
CREATE DATABASE webman_app;1
- MySQL:
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 );1
2
3
4
5
6
7 - PostgreSQL:sql
\c webman_app; -- 새로 만든 DB로 연결 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
2
3
4
5
6
7
- MySQL:
웹 프로젝트 코드 작성
이제 라우트 설정, 컨트롤러 생성, 데이터베이스/캐시 연동 로직을 추가해보겠습니다.
라우트 설정
프로젝트 루트의
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']); // 추가 라우트 정의 가능...1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21컨트롤러 파일 생성
app/controller디렉터리에IndexController.php,CacheController.php,DatabaseController.php파일을 만들고 각각 아래 코드를 추가하세요.app/controller/IndexController.php(루트 요청 처리)php<?php namespace app\controller; use support\Request; use support\Response; // Response 클래스 import class IndexController { /** * 루트 경로 요청 처리 예시 * @param Request $request 현재 요청 객체 * @return Response Response 객체 반환 */ public function index(Request $request): Response // 반환 타입 명시 { // 간단한 텍스트 응답 반환 return response('Hello ServBay & Webman!'); // 환영 메시지 업데이트 } }1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20app/controller/CacheController.php(Memcached, Redis 활용 예시)php<?php namespace app\controller; use support\Request; use support\Response; use Memcached; // Memcached 클래스 import use support\Redis; // Webman 제공 Redis Facade import class CacheController { /** * Memcached 활용 예시 * @param Request $request * @return Response */ public function memcached(Request $request): Response { // Memcached 서버 연결, ServBay 기본(localhost: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('Memcached 키 설정 실패', 500); } // 캐시 항목 가져오기 $value = $memcached->get('servbay_key'); // key 업데이트 // 값 반환 return response($value ?: 'Memcached 키 없음 또는 만료됨'); // 값 없을 시 안내 추가 } /** * Redis 활용 예시 * @param Request $request * @return Response */ public function redis(Request $request): Response { // Webman Redis Facade로 캐시 항목 설정 Redis::set('servbay_redis_key', 'Hello Redis from ServBay!'); // key, value 업데이트 // 캐시 항목 가져오기 $value = Redis::get('servbay_redis_key'); // key 업데이트 // 값 반환 return response($value ?: 'Redis 키 없음'); // 값 없을 시 안내 추가 } }1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52app/controller/DatabaseController.php(MySQL, PostgreSQL DB 작업 예시)php<?php namespace app\controller; use support\Request; use support\Response; use support\Db; // Webman Db Facade import class DatabaseController { /** * MySQL DB에 사용자 추가 * @param Request $request * @return Response */ public function mysqlAdd(Request $request): Response { try { // Db Facade로 '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('MySQL에 사용자 추가됨'); // 응답 메시지 업데이트 } catch (\Exception $e) { return response('MySQL에 사용자 추가 오류: ' . $e->getMessage(), 500); // 에러 처리 추가 } } /** * MySQL DB에서 사용자 목록 조회 * @param Request $request * @return Response */ public function mysqlGet(Request $request): Response { try { // Db Facade로 '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('MySQL에서 사용자 조회 오류: ' . $e->getMessage(), 500); // 에러 처리 추가 } } /** * PostgreSQL DB에 사용자 추가 * @param Request $request * @return Response */ public function pgsqlAdd(Request $request): Response { try { // Db Facade로 '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('PostgreSQL에 사용자 추가됨'); // 응답 메시지 업데이트 } catch (\Exception $e) { return response('PostgreSQL에 사용자 추가 오류: ' . $e->getMessage(), 500); // 에러 처리 추가 } } /** * PostgreSQL DB에서 사용자 목록 조회 * @param Request $request * @return Response */ public function pgsqlGet(Request $request): Response { try { // Db Facade로 '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('PostgreSQL에서 사용자 조회 오류: ' . $e->getMessage(), 500); // 에러 처리 추가 } } }1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
데이터베이스 연결 설정
프로젝트 루트의
config/database.php파일을 수정해 MySQL, PostgreSQL 연결 정보를 입력합니다. ServBay 기본 데이터베이스 호스트는127.0.0.1, MySQL 포트는3306, PostgreSQL 포트는5432, root 계정 비밀번호는password입니다.php<?php /** * 데이터베이스 설정 */ return [ // 기본 연결 데이터베이스 'default' => 'mysql', // 데이터베이스 연결 정보 리스트 '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 ], // 추가 데이터베이스 연결 가능... ], ];1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46중요 안내: 실 운영 환경에서는 반드시 기본 비밀번호를 변경하고, 소스 코드에 민감 정보(비밀번호 등)를 하드코딩하지 마십시오.
Webman 프로젝트 실행
Webman 프로젝트는 자체 start.php 스크립트로 Workerman 프로세스를 시작합니다. 기존 Nginx/Apache + PHP-FPM 방식이 아니라, Webman은 상주 메모리 기반의 비동기 애플리케이션입니다.
프로젝트 루트(/Applications/ServBay/www/servbay-webman-app)에서 아래 명령어로 Webman을 실행하세요:
bash
php start.php start1
명령 실행 후 Webman 시작 정보를 볼 수 있으며, 기본적으로 127.0.0.1:8787 포트에서 HTTP 요청을 대기합니다.
- 참고: 여기서
php명령은 ServBay 환경의 PHP 실행 파일입니다. ServBay가 터미널 환경을 자동 설정해 바로 사용할 수 있도록 합니다. - 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: "MySQL에 사용자 추가됨" 메시지로 MySQL DB의users테이블에 레코드가 삽입됩니다.http://localhost:8787/mysql: MySQL DB의users테이블 사용자 목록이 JSON 형식으로 출력됩니다.http://localhost:8787/pgsql-add: "PostgreSQL에 사용자 추가됨" 메시지로 PostgreSQL DB의users테이블에 레코드가 삽입됩니다.http://localhost:8787/pgsql: PostgreSQL DB의users테이블 사용자 목록이 JSON 형식으로 출력됩니다.
위 URL들에 접근할 때 문제가 발생하면, Webman 터미널 출력 오류 여부, ServBay 내 MySQL, PostgreSQL, Redis, Memcached 서비스 실행 상태, PHP 확장 활성화 여부를 점검하세요.
자주 묻는 질문(FAQ)
- Q:
php start.php start명령어를 찾을 수 없어요.- A: 터미널에서 반드시
servbay-webman-app프로젝트 디렉터리로 이동(cd)되어야 하며, ServBay가 설치한 PHP가 시스템 PATH에 정상 등록되어 있는지 확인하세요(대부분 자동 처리).
- A: 터미널에서 반드시
- Q:
localhost:8787접속이 안 될 때- A: 터미널에서 실행한
php start.php start명령의 오류 메시지를 확인하세요. 8787 포트가 다른 프로그램에 의해 사용 중인 경우 해당 포트를 Webman 설정 파일(config/server.php)에서 변경 가능합니다.
- A: 터미널에서 실행한
- Q: 데이터베이스 연결 오류 발생 시
- A: ServBay 내 MySQL과 PostgreSQL 서비스가 동작 중인지 확인하세요.
config/database.php의 연결 정보(호스트, 포트, DB명, 사용자명, 비밀번호)가 ServBay 환경과 일치하는지(기본: root, password) 확인하고, 반드시webman_appDB와users테이블을 생성했는지 재확인하세요.
- A: ServBay 내 MySQL과 PostgreSQL 서비스가 동작 중인지 확인하세요.
- Q: Memcached 또는 Redis 연결 실패
- A: ServBay 내 Memcached와 Redis 서비스가 실행 중인지 확인하세요.
app/controller/CacheController.php내 연결 주소와 포트가 맞는지(기본: 127.0.0.1:11211, 127.0.0.1:6379) 체크하고, PHP 버전의memcached,redis확장이 활성화되어 있는지 재확인하세요.
- A: ServBay 내 Memcached와 Redis 서비스가 실행 중인지 확인하세요.
요약
지금까지 ServBay 로컬 개발 환경에서 Webman 기반의 웹 프로젝트를 생성, 설정, 실행하는 모든 과정을 안내해드렸습니다. ServBay의 올인원 서비스를 활용해 Webman 개발 환경을 신속히 구축하고, 데이터베이스 및 캐시와 연동하는 방법을 습득하셨을 것입니다. Webman의 고성능 특성과 ServBay의 편리함이 결합되어, 비동기 PHP 애플리케이션 개발에 강력한 기반을 제공합니다. 이 가이드가 ServBay와 Webman을 활용한 멋진 웹 애플리케이션 개발에 도움이 되길 바랍니다.
