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

개요: Yii 2란 무엇인가?

Yii 2는 현대적인 웹 애플리케이션의 신속한 개발을 위해 설계된, 고성능의 컴포넌트 기반 PHP 프레임워크입니다. MVC(모델-뷰-컨트롤러) 디자인 패턴을 따르며, 개발자가 확장 가능하고 고품질의 웹 애플리케이션을 효율적으로 구축할 수 있도록 다양한 기능과 도구를 제공합니다. 탁월한 성능, 유연한 구조, 내장된 강력한 기능(캐싱, 보안, RESTful API 개발 지원 등)으로 인해 많은 개발자에게 사랑받고 있습니다.

Yii 2의 주요 특징과 장점

고성능: Yii 2는 고도의 최적화가 적용되어 고부하 요청도 빠르게 처리할 수 있어, 성능이 중요한 애플리케이션 개발에 적합합니다.
모듈화: 프레임워크가 모듈화되어 있어 코드 조직과 컴포넌트 재사용이 용이합니다.
보안성: 입력 검증, 출력 필터링, CSRF/XSS 방어, 인증/권한 관리 등 다양한 보안 기능이 기본 제공됩니다.
쉬운 사용성: 간결하고 직관적인 API와 풍부한 문서로 러닝 커브가 낮아 빠르게 시작할 수 있습니다.
강력한 커뮤니티 지원: 활발한 개발자 커뮤니티와 다양한 써드파티 확장 패키지가 준비되어 있어 문제 해결이 쉽습니다.
통합 도구 제공: 데이터베이스 마이그레이션, 코드 생성 등의 작업을 돕는 CLI 도구가 기본 제공돼 개발 효율을 높입니다.

Yii 2는 엔터프라이즈급 애플리케이션, RESTful API, 포털 사이트 등 다양한 웹 프로젝트에 적합한 이상적인 프레임워크입니다.

ServBay에서 Yii 2 프로젝트 실행하기

ServBay는 macOS에서의 웹 개발을 위해 설계된 로컬 개발 환경으로, PHP, 다양한 데이터베이스(MySQL, PostgreSQL, MongoDB, Redis), 웹 서버(Caddy, Nginx) 그리고 Composer, Node.js, Python, Go, Java 등 여러 개발자 도구가 통합되어 있습니다. 개발자를 위해 즉시 사용할 수 있는 편리한 환경을 제공합니다.

이 가이드에서는 ServBay의 PHP 환경, Composer 도구, 데이터베이스 서비스를 활용하여 Yii 2 기본 애플리케이션 프로젝트를 생성하고 실행하는 방법을 설명합니다. ServBay의 “웹사이트” 기능으로 로컬 웹 서버를 설정하고, 간단한 단계만으로 사이트 접근 및 주요 기능 시연이 가능합니다.

사전 준비 사항

시작 전 다음 항목을 반드시 준비하세요.

macOS에서 ServBay가 성공적으로 설치 및 실행 중이어야 합니다.
ServBay에 필요한 PHP 버전(예: PHP 8.3 이상)이 설치 및 활성화되어 있어야 합니다.
MySQL 또는 PostgreSQL과 같은 데이터베이스 서비스, Memcached와 Redis 같은 캐시 서비스가 ServBay에서 설치 및 활성화되어 있어야 합니다.

설치된 소프트웨어 패키지 및 실행 상태는 ServBay 메인 화면에서 확인하고 관리할 수 있습니다.

Yii 2 프로젝트 생성하기

TIP

ServBay에서는 프로젝트 파일을 /Applications/ServBay/www 폴더에 저장하는 것을 권장합니다. 이렇게 하면 파일 구조가 깔끔하게 유지되고, ServBay의 '웹사이트' 기능 관리가 더욱 쉬워집니다.

Composer: ServBay에는 Composer 도구가 내장되어 있어 별도의 설치가 필요하지 않습니다. 터미널에서 바로 composer 명령어를 사용할 수 있습니다.
프로젝트 디렉터리 생성: 터미널을 열고 ServBay의 기본 웹 루트 디렉터리로 이동한 후, 새 프로젝트 폴더를 생성합니다.
bash
```
cd /Applications/ServBay/www
mkdir servbay-yii2-app
cd servbay-yii2-app
```
1
2
3
Composer로 Yii 2 프로젝트 생성: servbay-yii2-app 폴더에서 아래와 같이 Composer 명령어로 Yii 2 기본 애플리케이션 템플릿을 설치합니다.
bash
```
composer create-project --prefer-dist yiisoft/yii2-app-basic .
```
1
이 명령어는 Yii 2 기본 앱 템플릿과 모든 의존성을 현재 폴더(.)에 다운로드 및 설치합니다. Composer의 설치가 모두 완료될 때까지 기다리세요.
프로젝트 폴더로 이동: 현재 디렉터리가 프로젝트 루트(/Applications/ServBay/www/servbay-yii2-app)인지 반드시 확인하세요. 이후 명령어도 이 위치에서 실행되어야 합니다.
bash
```
cd /Applications/ServBay/www/servbay-yii2-app
```
1

초기 설정

Yii 2 프로젝트가 만들어졌다면 데이터베이스 연결 및 컴포넌트 설정 등 기본 구성을 진행해야 합니다.

데이터베이스 연결 설정: 프로젝트 루트의 config/db.php 파일을 편집해 ServBay에서 실행 중인 데이터베이스 서비스(MySQL 또는 PostgreSQL)와 설정(기본 사용자명은 보통 root, 비밀번호는 password, 변경한 경우 해당 값)을 입력합니다.

먼저, ServBay의 데이터베이스 서비스에서 새 데이터베이스(예: servbay_yii2_app)를 생성해야 합니다. ServBay 내장 Adminer 도구나 Sequel Ace, TablePlus 등 선호하는 DB 클라이언트로 데이터베이스를 만들 수 있습니다. Adminer는 ServBay 앱의 데이터베이스 메뉴에서 바로 접근 가능합니다.

MySQL 사용 시:

php

<?php

return [
    'class' => 'yii\db\Connection',
    'dsn' => 'mysql:host=127.0.0.1;dbname=servbay_yii2_app', // dbname은 생성한 데이터베이스명으로 변경
    'username' => 'root', // 데이터베이스 사용자명
    'password' => 'password', // 데이터베이스 비밀번호
    'charset' => 'utf8mb4', // 유니코드 지원을 위한 utf8mb4 권장
];

PostgreSQL 사용 시:

php

<?php

return [
    'class' => 'yii\db\Connection',
    'dsn' => 'pgsql:host=127.0.0.1;port=5432;dbname=servbay_yii2_app', // dbname과 port는 환경에 맞게 수정
    'username' => 'root', // 데이터베이스 사용자명
    'password' => 'password', // 데이터베이스 비밀번호
    'charset' => 'utf8',
    'schemaMap' => [
        'pgsql' => [
            'class' => 'yii\pgsql\Schema',
            'defaultSchema' => 'public', // PostgreSQL 기본 스키마
        ],
    ],
];

환경에 맞게 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 데이터베이스 인덱스
    ],

    // ... 기타 컴포넌트
],

// ... 기타 설정

ServBay에서 Memcached와 Redis 서비스가 반드시 실행 중이어야 합니다. Redis를 캐시로 사용하려면 yiisoft/yii2-redis가 필요합니다(Composer로 기본 설치되며, 필요시 composer require yiisoft/yii2-redis로 추가하세요). Memcached는 대체로 yiisoft/yii2-memcached를 사용하며, 기본 템플릿에 포함되어 있을 수 있습니다.

웹 서버(ServBay 웹사이트) 설정

ServBay의 “웹사이트” 기능으로 로컬 웹 서버(Caddy 또는 Nginx)에서 Yii 2 프로젝트를 서비스하도록 설정할 수 있습니다.

ServBay 앱 실행: ServBay를 실행합니다.
웹사이트 설정 이동: ServBay 메인 화면에서 “웹사이트” 또는 이와 유사한 메뉴로 이동합니다.
새 웹사이트 추가: 새 웹사이트 추가 버튼(+ 또는 ‘추가’)을 클릭합니다.
웹사이트 정보 입력:
- 이름: My First Yii 2 Dev Site 등 구분하기 쉬운 이름을 입력하세요.
- 도메인: 로컬 개발용 도메인(예: servbay-yii2-test.local) 기입. ServBay가 로컬 DNS를 자동으로 127.0.0.1로 매핑합니다.
- 사이트 유형: PHP 선택.
- PHP 버전: 원하는 PHP 버전(예: 8.3)을 지정하세요. 해당 버전이 ServBay에서 설치 및 활성화되어 있어야 합니다.
- 웹사이트 루트 디렉터리: 매우 중요한 설정입니다. Yii 2 기본 앱 템플릿의 웹 진입점은 web 폴더(예: /Applications/ServBay/www/servbay-yii2-app/web)입니다.
저장 후 적용: 설정을 저장하면 ServBay가 웹 서버 구성을 자동 반영하고 재시작합니다.

자세한 설정 절차는 ServBay 공식 문서: 첫 번째 웹사이트 추가하기를 참고하세요.

ServBay는 로컬 개발 도메인에 대해 SSL 인증서를 자동 발급 및 신뢰(CA 기반) 처리하므로 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() . ". 데이터베이스 서비스, 구성, 'users' 테이블 존재 여부를 확인하세요.");
        }
    }

    /**
     * 데이터베이스에서 사용자 조회 예제.
     * 'users' 테이블이 있어야 정상 실행됨.
     *
     * @return Response
     */
    public function actionMysql() // PostgreSQL 환경에서는 설정만 다르면 동일하게 사용 가능
    {
        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() . ". 데이터베이스 서비스, 구성, 'users' 테이블 존재 여부를 확인하세요.");
        }
    }

    // PostgreSQL 전용 action을 별도로 둘 수도 있으나, 보통 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;
    }
}

위 예시에서는 actionMysqlAdd, actionMysql에 오류 처리와 사용자명/이메일에 브랜딩된 샘플 값을 사용하였고, 출력 포맷도 더 명확하게 개선하였습니다.

views/site/index.php 파일(홈 화면 뷰)에서 링크만 추가하거나 내용을 수정할 수 있습니다:

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, 사용하려는 데이터베이스(MySQL/PostgreSQL) 서비스가 실행 중이며, `config/web.php`와 `config/db.php`에 올바로 설정되어 있는지 확인하세요.</p>
        <p>DB 예제의 경우 아래 마이그레이션을 참고해 'users' 테이블을 생성해야 합니다.</p>
    </div>
</div>

이렇게 하면 기능 테스트 용 링크가 추가되어 직접 테스트할 수 있습니다.

관계형 데이터베이스: 테이블 생성(마이그레이션)

DB 관련 예제(actionMysqlAdd, actionMysql)를 사용하려면, 먼저 데이터베이스에 users 테이블을 생성해야 합니다. Yii에서는 데이터베이스 구조 관리를 마이그레이션으로 권장합니다.

마이그레이션 파일 생성: 터미널에서 프로젝트 루트(/Applications/ServBay/www/servbay-yii2-app) 위치에 있는지 확인한 뒤, 아래 명령어로 새 마이그레이션 파일을 생성합니다.
bash
```
php yii migrate/create create_users_table
```
1
생성 과정에서 확인 메시지가 뜨면 yes 입력 후 진행하세요. migrations 폴더 아래에 mYYYYMMDD_HHMMSS_create_users_table.php형태 파일이 생성됩니다.

마이그레이션 파일 편집: 생성된 파일을 열어 up() 메소드에 테이블 구조를 작성합니다.

php

<?php

use yii\db\Migration;

/**
 * Handles the creation of table `{{%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}}');
    }
}

실제 파일명에 맞게 mXXXXXXXXXXXXXX_create_users_table을 수정하세요.

마이그레이션 실행: 터미널에서 프로젝트 루트 위치를 유지한 채, 아래 명령어로 마이그레이션을 실행하여 users 테이블을 데이터베이스에 생성합니다.
bash
```
php yii migrate
```
1
진행 도중 확인 메시지에 yes 입력. 정상적으로 완료되면 테이블이 생성된다는 안내가 나옵니다.

웹사이트 접속 및 기능 테스트

이제 웹 브라우저에서 ServBay에서 설정한 도메인(https://servbay-yii2-test.local)을 방문해 보세요.

https://servbay-yii2-test.local 방문 시, Yii 2 기본 환영 페이지와 함께 추가된 데모 링크를 볼 수 있습니다.
"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 테이블이 이미 생성된 경우 사용자가 정상적으로 추가됩니다(단, email이 유니크 필드라면 중복 추가 시 오류 가능).
"DB에서 사용자 조회" 클릭 또는 https://servbay-yii2-test.local/index.php?r=site/mysql 접속: DB 서비스와 구성, 그리고 users 테이블이 모두 정상적이라면, 저장된 사용자 데이터 리스트가 보입니다.

문제가 있다면 ServBay에서 관련 서비스(PHP, 웹 서버, DB, Memcached, Redis) 실행/상태 확인, Yii 2 프로젝트 설정(config/db.php, config/web.php) 및 테이블 정상 생성 여부를 반드시 점검하세요.

자주 묻는 질문(FAQ)

접속 오류 또는 인증서(SSL) 오류가 뜨는 경우? ServBay “웹사이트” 설정에서 도메인을 올바르게 추가했는지, ServBay 앱이 정상 작동 중인지 확인하세요. ServBay는 로컬 DNS 및 SSL 인증서를 자동으로 처리하며, 인증서 오류가 뜨면 ServBay User CA(또는 ServBay Public CA)를 신뢰 처리해야 합니다. 자세한 사항은 ServBay 공식 문서를 참고하세요.
Composer 명령이 실행되지 않음 ServBay 앱에서 Composer 패키지가 활성화되어 있는지, 그리고 macOS 터미널에서 명령어를 실행 중인지 확인하세요. ServBay는 내부 Composer를 자동으로 PATH에 추가합니다.
데이터베이스 연결 실패 ServBay에서 사용하려는 데이터베이스(MySQL/PostgreSQL)가 실행 중인지, config/db.php의 dsn, username, password가 ServBay DB 설정과 일치하는지 확인하세요. 또한 DB 관리도구(Adminer 등)로 servbay_yii2_app 데이터베이스가 생성되어 있는지도 확인해야 합니다.
Memcached/Redis 연결 실패 ServBay에서 해당 서비스를 실행 중인지, 그리고 config/web.php의 Memcached/Redis 컴포넌트의 host와 port가 맞는지(기본은 127.0.0.1 및 각 서비스 기본 포트) 확인하세요.
DB 마이그레이션(php yii migrate) 실패config/db.php 설정이 정확하고, 데이터베이스와 연결 가능한 상태인지, DB가 미리 생성되어 있는지 점검하세요.
actionMysqlAdd/actionMysql에서 테이블 없음 경고 마이그레이션(php yii migrate)을 선행해 users 테이블을 반드시 생성해야 합니다.
PHP 오류 로그를 보고 싶은데 어디서 확인하나요? ServBay 앱의 “로그” 메뉴에서 PHP 오류, 웹 서버 로그 등을 모두 조회할 수 있습니다. 문제 진단 시 참고하시기 바랍니다.

요약

ServBay를 활용하면 macOS에서 손쉽게 완벽한 로컬 개발 환경을 구축하고, Yii 2 프로젝트를 빠르게 시작할 수 있습니다. 내장 Composer, PHP 버전 관리, DB 및 캐시 서비스, 웹사이트 통합 관리 등 다양한 기능 덕분에 Yii 2를 처음 접하는 개발자도 어려움 없이 개발을 시작할 수 있습니다. 본 가이드의 절차대로 따라가면 복잡한 설정 없이 바로 개발을 시작할 수 있습니다.

성공적인 개발을 응원합니다!

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

개요: Yii 2란 무엇인가? ​

Yii 2의 주요 특징과 장점 ​

ServBay에서 Yii 2 프로젝트 실행하기 ​

사전 준비 사항 ​

Yii 2 프로젝트 생성하기 ​

초기 설정 ​

웹 서버(ServBay 웹사이트) 설정 ​

예제 코드 추가로 기능 시연 ​

관계형 데이터베이스: 테이블 생성(마이그레이션) ​

웹사이트 접속 및 기능 테스트 ​

자주 묻는 질문(FAQ) ​

요약 ​