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

1. Composer: ServBay에는 Composer 도구가 내장되어 있어 별도 설치가 필요 없습니다. 터미널에서 바로 composer 명령을 사용할 수 있습니다.

2. 프로젝트 디렉터리 생성: 터미널을 열고 ServBay의 기본 사이트 루트 디렉터리로 이동해 새 프로젝트 폴더를 만드세요.

   macOS:

   cd /Applications/ServBay/www
   mkdir servbay-yii2-app
   cd servbay-yii2-app

   Windows:

   cd C:\ServBay\www
   mkdir servbay-yii2-app
   cd servbay-yii2-app

3. Composer로 Yii 2 프로젝트 생성: servbay-yii2-app 폴더에서 다음 Composer 명령어로 Yii 2 기본 애플리케이션 템플릿을 설치합니다.

   composer create-project --prefer-dist yiisoft/yii2-app-basic .

   이 명령은 Yii 2 템플릿과 모든 의존성을 현재 폴더(.)에 설치합니다. 다운로드 및 설치가 끝나기까지 잠시 기다려 주세요.

4. 프로젝트 폴더 이동: 이후의 명령은 모두 프로젝트 루트 폴더에서 실행됩니다.

   macOS:

   cd /Applications/ServBay/www/servbay-yii2-app

   Windows:

   cd 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
   
   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 추천
   ];

   PostgreSQL 예시:

   <?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', // 기본 스키마
           ],
       ],
   ];

   실제 환경에 맞게 config/db.php를 수정해 주세요.

2. 캐시 및 Redis 컴포넌트 설정: 프로젝트 루트의 config/web.php에 있는 components 부분에 Memcached, Redis 설정을 추가하세요(ServBay 기본 포트: Memcached는 11211, Redis는 6379).

   <?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 인덱스
       ],
   
       // ... 추가 컴포넌트
   ],
   
   // ... 기타 설정

   ServBay에서 Memcached, Redis 서비스를 실행 중인지 반드시 확인하세요. Redis를 캐싱에 활용하려면 yiisoft/yii2-redis 패키지가 필요하며, 예시 템플릿에 따라 추가로 직접 설치할 수도 있습니다. Memcached는 일반적으로 yiisoft/yii2-memcached를 사용합니다.

웹 서버(ServBay 사이트) 설정

ServBay의 ‘사이트’ 기능을 사용하여 로컬 웹 서버(Caddy 또는 Nginx)를 Yii 2 프로젝트로 연결합니다.

1. ServBay 앱 열기: ServBay를 실행합니다.
2. 사이트 설정 메뉴 이동: ServBay UI에서 ‘사이트’ 또는 유사한 메뉴로 이동하세요.
3. 새 사이트 추가: ‘+’ 버튼이나 ‘추가’ 버튼으로 신규 사이트를 만듭니다.
4. 사이트 정보 입력:
   • 이름: 예시로 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
5. 저장 및 적용: 설정을 저장하세요. ServBay가 웹 서버 구성을 자동 적용합니다.

사이트 설정 상세 단계는 ServBay 공식 문서 참고: 첫 번째 사이트 추가하기.

ServBay는 개발 도메인에 신뢰된 SSL 인증서를 자동 발급ㆍ설정하므로 HTTPS로 안전하게 접근할 수 있습니다.

기능 시연용 샘플 코드 추가

데이터베이스 및 캐시 기능 시연을 위해 기본 컨트롤러에 샘플 액션을 추가합니다.

프로젝트 루트의 controllers/SiteController.php 파일에서 SiteController 클래스에 아래 메서드를 추가하세요:

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

actionMysqlAdd와 actionMysql에 예외 처리와 더 명확한 출력 형식을 추가했으며, 예시 사용자명과 이메일도 ServBay 브랜드에 맞게 수정하였습니다.

프로젝트 루트의 views/site/index.php(Index 액션 뷰)도 아래와 같이 편집하거나 기본값 그대로 둘 수 있습니다:

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

위 뷰파일에 새로운 컨트롤러 액션 링크를 추가하여 기능 테스트가 쉽게 가능합니다.

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

데이터베이스 연동 예시(actionMysqlAdd, actionMysql)를 사용하려면 반드시 users 테이블이 필요합니다. Yii는 데이터베이스 스키마 변경 관리를 위해 마이그레이션(Migration)을 권장합니다.

1. Gii 도구로 마이그레이션 파일 생성: 터미널에서 프로젝트 루트 디렉터리 위치를 확인 후, 아래 yiic 명령어로 마이그레이션 파일을 만드세요.

   프로젝트 루트 경로:

   • macOS: /Applications/ServBay/www/servbay-yii2-app
   • Windows: C:\ServBay\www\servbay-yii2-app

   php yii migrate/create create_users_table

   명령 실행 후 yes 입력, mYYYYMMDD_HHMMSS_create_users_table.php와 같이 새 PHP 마이그레이션 파일이 만들어집니다.

2. 마이그레이션 파일 편집: 생성된 파일의 up() 메소드에서 users 테이블 구조를 정의하세요.

   <?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}}');
       }
   }

   실제 파일명(mXXXXXXXXXXXXXX_create_users_table)은 명령 실행시 생성된 것을 사용하세요.

3. 마이그레이션 실행: 프로젝트 루트에서 아래 명령어로 마이그레이션을 적용하면, 데이터베이스에 users 테이블이 만들어집니다.

   php yii migrate

   yes 입력 후 정상적으로 성공 메시지가 출력되어야 합니다.

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

이제 웹 브라우저에서 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 연결 상태 및 리스트를 쉽게 확인할 수 있습니다.
• Memcached/Redis 연결 실패
  • 해당 서비스가 ServBay에서 실행 중인지 확인, config/web.php에서 각 컴포넌트의 host와 port가 올바른지 체크하세요(기본값: 127.0.0.1 및 각 서비스 포트).
• 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가 제공하는 다양한 도구로 개발 효율을 높일 수 있습니다.

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