ServBay에서 Yii 2 프로젝트 생성 및 실행하기
개요: Yii 2란 무엇인가요?
Yii 2는 현대적인 웹 애플리케이션을 빠르고 효율적으로 개발할 수 있도록 설계된 고성능, 컴포넌트 기반의 PHP 프레임워크입니다. MVC(Model-View-Controller) 디자인 패턴을 따르며, 확장성 있고 고품질의 웹 프로젝트를 빠르게 구축할 수 있는 다양한 기능과 도구를 제공합니다. 뛰어난 성능, 유연한 구조, 강력한 내장 기능(캐싱, 보안, RESTful API 개발 지원 등) 덕분에 많은 개발자들에게 인기 있는 프레임워크입니다.
Yii 2의 주요 특징 및 장점
- 고성능: 고도의 최적화를 통해 높은 동시 접속을 지원하며, 성능이 중요한 어플리케이션 개발에 적합합니다.
- 모듈성: 모듈화 설계로 인해 코드 관리와 컴포넌트 재사용이 쉽습니다.
- 보안: 입력 검증, 출력 필터링, CSRF/XSS 방지, 인증/권한 관리 등 다양한 보안 기능이 내장되어 있습니다.
- 쉬운 사용법: 직관적인 API와 상세한 문서를 제공하여 진입 장벽이 낮고 빠른 학습이 가능합니다.
- 강력한 커뮤니티 지원: 활발한 개발자 커뮤니티와 풍부한 확장 라이브러리를 통해 문제 해결에 도움을 받을 수 있습니다.
- 통합 도구: 데이터베이스 마이그레이션, 코드 생성 등 커맨드라인 도구를 통해 개발 효율성을 높여줍니다.
Yii 2는 엔터프라이즈 애플리케이션, RESTful API, 포털 사이트 등 다양한 웹 프로젝트를 위한 이상적인 선택입니다.
ServBay에서 Yii 2 프로젝트 실행하기
ServBay는 macOS와 Windows를 위한 로컬 웹 개발 환경으로, PHP, 여러 데이터베이스(MySQL, PostgreSQL, MongoDB, Redis), 웹 서버(Caddy, Nginx), 기타 개발 도구(Composer, Node.js, Python, Go, Java 등)를 한 곳에 통합하여 ‘즉시 사용 가능한’ 편리한 개발 플랫폼을 제공합니다.
이 가이드에서는 ServBay가 제공하는 PHP 환경, Composer 도구, 데이터베이스 서비스로 Yii 2 기본 애플리케이션을 설치하고 실행하는 방법을 안내합니다. ServBay의 ‘사이트’ 기능을 통해 로컬 웹 서버를 쉽게 구성하고, 프로젝트 접근 및 주요 기능 시연을 단계별로 설명합니다.
사전 준비
아래 항목을 먼저 확인해 주세요:
- macOS 또는 Windows 시스템에 ServBay를 정상적으로 설치 및 실행하였는지 확인하세요.
- 프로젝트에 사용할 PHP 버전(예: PHP 8.3 이상)이 ServBay에 설치되어 활성화되어 있어야 합니다.
- 사용할 데이터베이스(MySQL 또는 PostgreSQL), 캐시 서버(Memcached, Redis)가 ServBay에 설치ㆍ활성화되어 있어야 합니다.
ServBay 메인 화면에서 설치/실행 중인 소프트웨어 패키지와 상태를 손쉽게 확인ㆍ관리할 수 있습니다.
Yii 2 프로젝트 생성하기
TIP
ServBay는 아래 디렉터리에 프로젝트 파일을 저장할 것을 권장합니다. 파일 구조가 더 깔끔해지고 ServBay의 ‘사이트’ 관리가 쉬워집니다:
- macOS:
/Applications/ServBay/www
- Windows:
C:\ServBay\www
Composer: ServBay에는 Composer 도구가 내장되어 있어 별도 설치가 필요 없습니다. 터미널에서 바로
composer
명령을 사용할 수 있습니다.프로젝트 디렉터리 생성: 터미널을 열고 ServBay의 기본 사이트 루트 디렉터리로 이동해 새 프로젝트 폴더를 만드세요.
macOS:
bashcd /Applications/ServBay/www mkdir servbay-yii2-app cd servbay-yii2-app
1
2
3Windows:
cmdcd C:\ServBay\www mkdir servbay-yii2-app cd servbay-yii2-app
1
2
3Composer로 Yii 2 프로젝트 생성:
servbay-yii2-app
폴더에서 다음 Composer 명령어로 Yii 2 기본 애플리케이션 템플릿을 설치합니다.bashcomposer create-project --prefer-dist yiisoft/yii2-app-basic .
1이 명령은 Yii 2 템플릿과 모든 의존성을 현재 폴더(
.
)에 설치합니다. 다운로드 및 설치가 끝나기까지 잠시 기다려 주세요.프로젝트 폴더 이동: 이후의 명령은 모두 프로젝트 루트 폴더에서 실행됩니다.
macOS:
bashcd /Applications/ServBay/www/servbay-yii2-app
1Windows:
cmdcd C:\ServBay\www\servbay-yii2-app
1
초기 설정
프로젝트 생성 후에는 데이터베이스 연결 등 기본 설정이 필요합니다.
데이터베이스 연결 설정: 프로젝트 루트의
config/db.php
파일을 편집합니다. ServBay에서 사용할 데이터베이스(MySQL 또는 PostgreSQL)와 환경에 맞게 연결 정보를 수정하세요(기본 사용자:root
, 기본 비밀번호:password
, 직접 변경한 경우 해당 값 적용).먼저 ServBay의 데이터베이스 서비스에서 새 데이터베이스(예:
servbay_yii2_app
)를 생성하세요. Adminer 도구(ServBay 제공) 혹은 Sequel Ace, TablePlus 등 선호하는 클라이언트로 데이터베이스를 만들 수 있습니다. Adminer는 ServBay 앱 데이터베이스 섹션에서 접근 가능합니다.MySQL 예시:
php<?php return [ 'class' => 'yii\db\Connection', 'dsn' => 'mysql:host=127.0.0.1;dbname=servbay_yii2_app', // dbname은 생성한 DB명 'username' => 'root', // DB 사용자명 'password' => 'password', // DB 비밀번호 'charset' => 'utf8mb4', // 문자셋은 utf8mb4 추천 ];
1
2
3
4
5
6
7
8
9PostgreSQL 예시:
php<?php return [ 'class' => 'yii\db\Connection', 'dsn' => 'pgsql:host=127.0.0.1;port=5432;dbname=servbay_yii2_app', // dbname과 port 확인 'username' => 'root', // DB 사용자명 'password' => 'password', // DB 비밀번호 'charset' => 'utf8', 'schemaMap' => [ 'pgsql' => [ 'class' => 'yii\pgsql\Schema', 'defaultSchema' => 'public', // 기본 스키마 ], ], ];
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15실제 환경에 맞게
config/db.php
를 수정해 주세요.캐시 및 Redis 컴포넌트 설정: 프로젝트 루트의
config/web.php
에 있는components
부분에 Memcached, Redis 설정을 추가하세요(ServBay 기본 포트: Memcached는 11211, Redis는 6379).php<?php // ... 기타 설정 'components' => [ // ... 기존 컴포넌트(request, cache, user, errorHandler, log, urlManager 등) 'cache' => [ 'class' => 'yii\caching\MemCache', 'servers' => [ [ 'host' => '127.0.0.1', 'port' => 11211, // Memcached 기본 포트 'weight' => 100, ], ], ], 'redis' => [ 'class' => 'yii\redis\Connection', 'hostname' => '127.0.0.1', 'port' => 6379, // Redis 기본 포트 'database' => 0, // Redis DB 인덱스 ], // ... 추가 컴포넌트 ], // ... 기타 설정
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
28ServBay에서 Memcached, Redis 서비스를 실행 중인지 반드시 확인하세요. Redis를 캐싱에 활용하려면
yiisoft/yii2-redis
패키지가 필요하며, 예시 템플릿에 따라 추가로 직접 설치할 수도 있습니다. Memcached는 일반적으로yiisoft/yii2-memcached
를 사용합니다.
웹 서버(ServBay 사이트) 설정
ServBay의 ‘사이트’ 기능을 사용하여 로컬 웹 서버(Caddy 또는 Nginx)를 Yii 2 프로젝트로 연결합니다.
- ServBay 앱 열기: ServBay를 실행합니다.
- 사이트 설정 메뉴 이동: ServBay UI에서 ‘사이트’ 또는 유사한 메뉴로 이동하세요.
- 새 사이트 추가: ‘+’ 버튼이나 ‘추가’ 버튼으로 신규 사이트를 만듭니다.
- 사이트 정보 입력:
- 이름: 예시로
My First Yii 2 Dev Site
와 같이 쉽게 구분 가능한 이름 입력 - 도메인: 로컬 개발시 사용할 도메인 설정(예:
servbay-yii2-test.local
). ServBay가 로컬 DNS로127.0.0.1
에 자동 매핑해줍니다. - 사이트 유형:
PHP
선택 - PHP 버전: 사용할 PHP 버전 선택(예:
8.3
), 설치 및 활성화 필수 - 사이트 루트 디렉터리: 매우 중요한 단계입니다. Yii 2 기본템플릿의 공개 진입점은
web
디렉터리입니다.- macOS:
/Applications/ServBay/www/servbay-yii2-app/web
- Windows:
C:\ServBay\www\servbay-yii2-app\web
- macOS:
- 이름: 예시로
- 저장 및 적용: 설정을 저장하세요. ServBay가 웹 서버 구성을 자동 적용합니다.
사이트 설정 상세 단계는 ServBay 공식 문서 참고: 첫 번째 사이트 추가하기.
ServBay는 개발 도메인에 신뢰된 SSL 인증서를 자동 발급ㆍ설정하므로 HTTPS로 안전하게 접근할 수 있습니다.
기능 시연용 샘플 코드 추가
데이터베이스 및 캐시 기능 시연을 위해 기본 컨트롤러에 샘플 액션을 추가합니다.
프로젝트 루트의 controllers/SiteController.php
파일에서 SiteController
클래스에 아래 메서드를 추가하세요:
php
<?php
namespace app\controllers;
use Yii;
use yii\web\Controller;
use yii\web\Response;
use yii\db\Exception as DbException; // 데이터베이스 예외 클래스 임포트
class SiteController extends Controller
{
/**
* 홈페이지 표시.
*
* @return string
*/
public function actionIndex()
{
return $this->render('index');
}
/**
* Memcached 사용 예시.
*
* @return Response
*/
public function actionMemcached()
{
$cache = Yii::$app->cache;
$key = 'my_memcached_test_key';
$data = 'Hello Memcached from ServBay!';
$duration = 60; // 60초 캐시
if ($cache->set($key, $data, $duration)) {
$value = $cache->get($key);
return $this->asText("Memcached에 성공적으로 저장되었습니다. 가져온 값: " . $value);
} else {
return $this->asText("Memcached에 데이터를 저장하지 못했습니다. Memcached 서비스 및 설정을 확인해 주세요.");
}
}
/**
* Redis 사용 예시.
*
* @return Response
*/
public function actionRedis()
{
$redis = Yii::$app->redis;
$key = 'my_redis_test_key';
$data = 'Hello Redis from ServBay!';
try {
if ($redis->set($key, $data)) {
$value = $redis->get($key);
return $this->asText("Redis에 성공적으로 저장되었습니다. 가져온 값: " . $value);
} else {
return $this->asText("Redis에 데이터를 저장하지 못했습니다. Redis 서비스 및 설정을 확인해 주세요.");
}
} catch (\yii\base\Exception $e) {
return $this->asText("Redis 오류: " . $e->getMessage() . ". Redis 서비스 및 설정을 확인해 주세요.");
}
}
/**
* 데이터베이스에 사용자 추가 예시.
* 'users' 테이블이 있어야 동작합니다.
*
* @return Response
*/
public function actionMysqlAdd() // PostgreSQL에 맞게 설정하면 사용 가능
{
try {
$count = Yii::$app->db->createCommand()->insert('users', [
'name' => 'ServBay Demo User', // 브랜딩 예시 이름
'email' => 'demo-user@servbay.test', // 브랜딩 예시 이메일
])->execute();
return $this->asText("사용자 추가 성공. 영향을 받은 행 수: " . $count);
} catch (DbException $e) {
return $this->asText("데이터베이스에 사용자 추가 실패. 오류: " . $e->getMessage() . ". DB 서비스, 설정을 확인하고 'users' 테이블이 존재하는지 확인해 주세요.");
}
}
/**
* 데이터베이스에서 사용자 조회 예시.
* 'users' 테이블이 있어야 동작합니다.
*
* @return Response
*/
public function actionMysql() // PostgreSQL도 동일 db 컴포넌트 사용 가능
{
try {
$users = Yii::$app->db->createCommand('SELECT id, name, email FROM users')->queryAll();
// 출력 포맷 정리, 민감 정보/혼란 방지
$output = "조회된 사용자 목록:\n";
foreach ($users as $user) {
$output .= "- ID: {$user['id']}, 이름: {$user['name']}, 이메일: {$user['email']}\n";
}
return $this->asText($output);
} catch (DbException $e) {
return $this->asText("데이터베이스에서 사용자 조회 실패. 오류: " . $e->getMessage() . ". DB 서비스, 설정, 'users' 테이블 존재 여부를 확인해 주세요.");
}
}
// PostgreSQL 전용 액션을 추가할 수도 있으나, 보통 db 컴포넌트 공용 가능
// public function actionPgsqlAdd() { ... }
// public function actionPgsql() { ... }
/**
* 출력을 일반 텍스트로 반환.
* @param string $text
* @return Response
*/
protected function asText($text)
{
Yii::$app->response->format = Response::FORMAT_RAW;
Yii::$app->response->getHeaders()->add('Content-Type', 'text/plain');
return $text;
}
/**
* 출력을 JSON 형식으로 반환.
* @param mixed $data
* @return Response
*/
protected function asJson($data)
{
Yii::$app->response->format = Response::FORMAT_JSON;
return $data;
}
}
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
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
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
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
actionMysqlAdd
와 actionMysql
에 예외 처리와 더 명확한 출력 형식을 추가했으며, 예시 사용자명과 이메일도 ServBay 브랜드에 맞게 수정하였습니다.
프로젝트 루트의 views/site/index.php
(Index 액션 뷰)도 아래와 같이 편집하거나 기본값 그대로 둘 수 있습니다:
php
<?php
/* @var $this yii\web\View */
/* @var $name string */
/* @var $message string */
/* @var $exception Exception */
use yii\helpers\Html;
$this->title = 'My Yii2 Application on ServBay'; // 제목 업데이트
?>
<div class="site-index">
<div class="jumbotron">
<h1>축하합니다!</h1>
<p class="lead">Yii2 애플리케이션을 성공적으로 생성하고 ServBay로 환경을 구성했습니다!</p>
<p><a class="btn btn-lg btn-success" href="https://www.yiiframework.com">Yii 시작하기</a></p>
</div>
<div class="body-content">
<h2>기능 시연</h2>
<ul>
<li><a href="<?= Html::toRoute('site/memcached') ?>">Memcached 테스트</a></li>
<li><a href="<?= Html::toRoute('site/redis') ?>">Redis 테스트</a></li>
<li><a href="<?= Html::toRoute('site/mysql-add') ?>">DB에 사용자 추가</a> (테이블 ‘users’ 필요)</li>
<li><a href="<?= Html::toRoute('site/mysql') ?>">DB 사용자 조회</a> (테이블 ‘users’ 필요)</li>
</ul>
<p>ServBay에서 Memcached, Redis, 선택한 DB(MySQL/PostgreSQL) 서비스가 실행 중이며 `config/web.php`, `config/db.php`에 설정이 정확한지 꼭 확인하세요.</p>
<p>DB 예시를 수행하려면 아래 단계대로 ‘users’ 테이블을 생성해야 합니다.</p>
</div>
</div>
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
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
위 뷰파일에 새로운 컨트롤러 액션 링크를 추가하여 기능 테스트가 쉽게 가능합니다.
관계형 데이터베이스: 테이블 구조 생성(마이그레이션)
데이터베이스 연동 예시(actionMysqlAdd
, actionMysql
)를 사용하려면 반드시 users
테이블이 필요합니다. Yii는 데이터베이스 스키마 변경 관리를 위해 마이그레이션(Migration)을 권장합니다.
Gii 도구로 마이그레이션 파일 생성: 터미널에서 프로젝트 루트 디렉터리 위치를 확인 후, 아래 yiic 명령어로 마이그레이션 파일을 만드세요.
프로젝트 루트 경로:
- macOS:
/Applications/ServBay/www/servbay-yii2-app
- Windows:
C:\ServBay\www\servbay-yii2-app
bashphp yii migrate/create create_users_table
1명령 실행 후
yes
입력,mYYYYMMDD_HHMMSS_create_users_table.php
와 같이 새 PHP 마이그레이션 파일이 만들어집니다.- macOS:
마이그레이션 파일 편집: 생성된 파일의
up()
메소드에서users
테이블 구조를 정의하세요.php<?php use yii\db\Migration; /** * `{{%users}}` 테이블 생성 처리. */ class mXXXXXXXXXXXXXX_create_users_table extends Migration // XXXXXXXXXXXXXX는 타임스탬프 { /** * {@inheritdoc} */ public function up() { $this->createTable('{{%users}}', [ // {{%users}}는 프리픽스 설정 지원 'id' => $this->primaryKey(), 'name' => $this->string()->notNull(), 'email' => $this->string()->notNull()->unique(), 'created_at' => $this->timestamp()->defaultExpression('CURRENT_TIMESTAMP'), 'updated_at' => $this->timestamp()->defaultExpression('CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP'), ]); // 선택: 인덱스 설정으로 조회 성능 향상 $this->createIndex( 'idx-users-email', '{{%users}}', 'email', true // 유니크 인덱스 지정 ); } /** * {@inheritdoc} */ public function down() { // 인덱스 제거 $this->dropIndex( 'idx-users-email', '{{%users}}' ); // 테이블 제거 $this->dropTable('{{%users}}'); } }
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실제 파일명(
mXXXXXXXXXXXXXX_create_users_table
)은 명령 실행시 생성된 것을 사용하세요.마이그레이션 실행: 프로젝트 루트에서 아래 명령어로 마이그레이션을 적용하면, 데이터베이스에
users
테이블이 만들어집니다.bashphp yii migrate
1yes
입력 후 정상적으로 성공 메시지가 출력되어야 합니다.
웹사이트 접속 및 기능 테스트
이제 웹 브라우저에서 ServBay에서 설정한 도메인 https://servbay-yii2-test.local
에 접속할 수 있습니다.
https://servbay-yii2-test.local
접속시, Yii 2 기본 템플릿 환영 페이지와views/site/index.php
에 추가한 시연 링크가 나타납니다.- "Memcached 테스트" 링크 또는
https://servbay-yii2-test.local/index.php?r=site/memcached
접속: Memcached가 정상 작동 시 "Memcached에 성공적으로 저장되었습니다..." 출력. - "Redis 테스트" 링크 또는
https://servbay-yii2-test.local/index.php?r=site/redis
접속: Redis가 정상 작동 시 "Redis에 성공적으로 저장되었습니다..." 출력. - "DB에 사용자 추가" 링크 또는
https://servbay-yii2-test.local/index.php?r=site/mysql-add
접속: DB 서비스∙설정 정상,users
테이블까지 있으면 "사용자 추가 성공..." 출력(매번 신규 사용자 추가). - "DB 사용자 조회" 링크 또는
https://servbay-yii2-test.local/index.php?r=site/mysql
접속: DB 서비스∙설정 정상,users
테이블 존재 시, DB에서 조회한 사용자 목록 출력.
문제가 발생한다면, ServBay의 각 서비스(PHP, 웹 서버, 데이터베이스, Memcached, Redis)가 정상 실행 중인지, Yii 2 프로젝트의 각 설정파일(config/db.php
, config/web.php
)이 올바른지, DB 테이블이 마이그레이션으로 성공적으로 생성됐는지 확인하세요.
자주 묻는 질문 (FAQ)
- 도메인 접근 불가 또는 SSL 인증서 오류
- ServBay ‘사이트’ 설정에 도메인 등록이 정확한지, ServBay 앱이 실행 중인지 확인하세요. ServBay는 로컬 DNS와 SSL 인증서를 자동 관리합니다. 인증서 오류 시 ServBay User CA 혹은 Public CA를 시스템에 신뢰 추가해야 하며, 자세한 방법은 ServBay 문서를 참고하세요.
- Composer 명령 실행 안됨
- ServBay 앱에서 Composer 패키지가 활성화되어 있는지, macOS 터미널에서 명령을 실행 중인지 확인하세요. ServBay가 Composer를 PATH에 자동 추가해줍니다.
- DB 연결 실패
- 해당 DB 서비스(MySQL/PostgreSQL)가 ServBay에서 실행 중인지 확인,
config/db.php
의dsn
,username
,password
값과 ServBay DB 설정이 일치하는지 확인하세요. 데이터베이스(servbay_yii2_app
) 생성도 필요합니다. Adminer 도구로 DB 연결 상태 및 리스트를 쉽게 확인할 수 있습니다.
- 해당 DB 서비스(MySQL/PostgreSQL)가 ServBay에서 실행 중인지 확인,
- Memcached/Redis 연결 실패
- 해당 서비스가 ServBay에서 실행 중인지 확인,
config/web.php
에서 각 컴포넌트의host
와port
가 올바른지 체크하세요(기본값:127.0.0.1
및 각 서비스 포트).
- 해당 서비스가 ServBay에서 실행 중인지 확인,
- DB 마이그레이션(
php yii migrate
) 실패config/db.php
가 정상적으로 설정되어 있고, DB 서비스와 DB가 생성되어 있는지 확인하세요. 마이그레이션 명령은 DB 접속이 되어야 실행됩니다.
actionMysqlAdd
/actionMysql
에서 테이블 없음 오류- 반드시 먼저 마이그레이션 명령(
php yii migrate
)으로users
테이블을 생성해야 합니다.
- 반드시 먼저 마이그레이션 명령(
- PHP 오류 로그 확인 방법
- ServBay는 PHP와 웹 서버 로그를 통합 관리합니다. 앱 UI의 ‘로그’ 메뉴에서 상세 로그를 확인하며, 문제 진단에 유용합니다.
요약
ServBay를 활용하면 macOS와 Windows에서 완전히 구성된 로컬 개발환경에서 Yii 2 프로젝트를 손쉽게 실행할 수 있습니다. Composer, 다양한 PHP 버전, 내장 데이터베이스와 캐시 서비스, 편리한 웹사이트 관리 기능까지 갖춰져 있어 개발 프로세스가 한층 간결해집니다. 이 가이드대로 진행하면 빠르게 Yii 2 개발을 시작하고, ServBay가 제공하는 다양한 도구로 개발 효율을 높일 수 있습니다.
성공적인 개발을 응원합니다!