ServBay 로컬 개발 환경에서 FuelPHP 프로젝트 생성 및 실행하기

FuelPHP란?

FuelPHP는 현대적인 웹 애플리케이션 구축을 위해 설계된 유연하고 모듈형의 PHP 프레임워크입니다. 계층적 모델-뷰-컨트롤러(HMVC - Hierarchical Model-View-Controller) 설계 패턴을 따르며, 풍부한 기능과 도구를 제공해 개발자가 고품질의 웹 애플리케이션을 빠르고 효율적으로 개발할 수 있도록 지원합니다. 뛰어난 유연성과 고성능, 확장성 덕분에 많은 PHP 개발자들에게 사랑받는 프레임워크입니다.

FuelPHP의 주요 기능 및 장점

HMVC 아키텍처: 계층적 MVC 설계 패턴을 지원하여 코드의 구조화, 재사용, 모듈화된 개발이 용이합니다. 대형 또는 복잡한 프로젝트에 특히 적합합니다.
고성능: FuelPHP는 성능 최적화를 중시하며, 높은 속도와 효율적인 리소스 활용으로 대용량 트래픽도 효과적으로 처리할 수 있습니다.
확장성: 프레임워크는 강력한 확장 메커니즘을 제공하여, 개발자가 서드파티 라이브러리 통합이나 커스텀 기능 추가를 쉽게 할 수 있습니다.
보안: 자동 입력 검증, 출력 필터링(XSS 방지), CSRF 보호, SQL 인젝션 예방 등 다양한 보안 기능을 기본 제공하여 안전한 애플리케이션 개발을 지원합니다.
활발한 커뮤니티: FuelPHP는 활발한 개발자 커뮤니티로부터 빠른 지원이나 다양한 자료를 얻을 수 있습니다.

이러한 장점 덕분에 FuelPHP는 개발자가 고성능, 안전성, 유지보수가 용이한 웹 애플리케이션을 신속하게 구축할 수 있게 해줍니다. 소규모 프로젝트부터 대규모 엔터프라이즈 급 시스템까지 폭넓게 활용 가능합니다.

ServBay를 이용한 FuelPHP 개발 환경 구축

ServBay는 개발자를 위해 설계된 로컬 웹 개발 환경으로, PHP, Caddy/Nginx/Apache, MySQL/PostgreSQL/MongoDB, Redis 등 다양한 서비스와 도구가 기본 탑재되어 있습니다. ServBay를 사용하면 FuelPHP 프로젝트에 필요한 실행환경을 간단하게 구성할 수 있으며, 각종 의존성을 직접 설치하거나 설정할 필요가 없습니다.

이 가이드에서는 ServBay의 PHP 환경, 웹서버(Caddy) 및 데이터베이스/캐시 서비스를 활용해 FuelPHP 프로젝트를 생성 및 실행하는 전체 흐름을 자세히 설명합니다. ServBay의 웹사이트 기능을 활용하여 웹서버를 설정하고, 손쉽게 프로젝트에 접근 및 테스트하는 방법을 안내합니다.

준비 사항

작업을 시작하기 전에 다음 조건을 충족하는지 확인하세요.

macOS에 ServBay가 정상적으로 설치 및 실행되고 있어야 합니다.
ServBay의 PHP 환경이 활성화되어 있어야 합니다(기본 활성화됨).
ServBay에서 사용할 데이터베이스(MySQL 등) 및 캐시 서비스(Redis, Memcached 등)가 실행 중이어야 합니다.
ServBay에는 Composer가 내장되어 있어 별도의 설치가 필요하지 않습니다.

FuelPHP 프로젝트 생성하기

권장 프로젝트 저장 경로

ServBay는 개발자가 웹사이트 프로젝트를 /Applications/ServBay/www 디렉토리 하위에 통합하여 관리하는 것을 권장합니다. 본 문서 역시 해당 경로를 예시로 사용합니다.

웹사이트 루트 디렉토리로 이동
터미널에서 ServBay 권장 디렉토리로 진입합니다:
bash
```
cd /Applications/ServBay/www
```
1
프로젝트 디렉토리 생성
FuelPHP 프로젝트 전용 디렉토리를 만들고 이동합니다:
bash
```
mkdir servbay-fuelphp-app
cd servbay-fuelphp-app
```
1
2
Composer로 FuelPHP 프로젝트 생성
프로젝트 디렉토리에서 Composer를 이용해 FuelPHP 프레임워크를 다운로드 및 초기화합니다. .는 현재 디렉토리에 설치하는 의미입니다:
bash
```
composer create-project fuel/fuel .
```
1
Composer가 FuelPHP 프레임워크 및 의존성을 servbay-fuelphp-app에 자동 설치합니다.

웹서버 설정 (ServBay 웹사이트 기능 사용)

브라우저에서 FuelPHP 프로젝트에 접속하려면 ServBay의 웹사이트 기능을 활용해 가상 호스트를 설정해야 합니다.

ServBay 메인 인터페이스를 엽니다.
왼쪽 메뉴의 웹사이트를 클릭합니다.
우측 상단의 웹사이트 추가 버튼 클릭.
팝업 창에서 아래 정보를 입력합니다:
- 이름: 예시로 My First FuelPHP Dev Site 등 알아보기 쉬운 이름을 입력
- 도메인: 예시로 servbay-fuelphp-test.local 과 같이 로컬 개발용 도메인 지정 (ServBay가 자동으로 호스트에 등록)
- 웹사이트 유형: PHP 선택
- PHP 버전: 원하는 PHP 버전 선택(예: 8.3)
- 웹사이트 루트 디렉토리: FuelPHP의 진입점은 public/index.php이므로, 웹사이트 루트 경로를 /Applications/ServBay/www/servbay-fuelphp-app/public로 설정
추가 버튼을 눌러 설정 저장

ServBay가 Caddy 설정을 자동 갱신 및 서비스 재시작 함으로써 새 도메인을 즉시 사용할 수 있습니다.

웹사이트 추가 절차는 ServBay 문서의 첫 웹사이트 추가하기도 참고할 수 있습니다.

FuelPHP 프로젝트 서비스 연결 설정

FuelPHP 프로젝트에서는 데이터베이스 및 캐시 서비스 연결 정보를 설정해야 합니다.

데이터베이스 설정

FuelPHP의 데이터베이스 설정 파일은 fuel/app/config/development/db.php입니다. 편집하여 사용 중인 데이터베이스 연결 정보를 입력하세요. ServBay 기본 MySQL 사용 예시:

php

<?php
/**
 * 개발 데이터베이스 설정. 전역 설정과 병합됩니다.
 */
return [
    'default' => [
        'connection' => [
            'dsn'      => 'mysql:host=localhost;dbname=fuel_dev', // fuel_dev 데이터베이스가 존재해야 합니다
            'username' => 'root', // ServBay MySQL 기본 사용자명
            'password' => 'root', // ServBay MySQL 기본 비밀번호 (로컬 개발 전용)
        ],
        'identifier' => '`', // MySQL은 식별자에 백틱(`) 사용 필요
    ],
];

주의:

ServBay의 phpMyAdmin이나 Adminer 등 DB 관리 도구에서 반드시 fuel_dev 데이터베이스를 직접 생성해야 합니다. 기본 사용자명/비밀번호는 모두 root(로컬 개발에만 권장).
'identifier' => ''` 설정은 MySQL에서 테이블/필드명을 올바르게 인식하기 위해 꼭 필요합니다.

캐시 설정 (Memcached 및 Redis)

FuelPHP는 다양한 캐시 드라이버를 지원합니다. fuel/app/config/cache.php에서 캐시 연결 정보를 설정하세요. ServBay에서 Memcached, Redis 서비스가 실행 중임을 확인하세요.

Memcached 설정 (fuel/app/config/cache.php):

Memcached를 기본 캐시로 사용하려면:

php

<?php
return [
    'driver' => 'memcached', // 기본 드라이버를 memcached로 지정
    'memcached' => [
        'cache_id' => 'fuel', // 캐시 ID
        'servers' => [
             'default' => [
                'host'   => '127.0.0.1', // Memcached 기본 주소
                'port'   => 11211,      // 기본 포트
                'weight' => 100,
            ],
        ],
        'compression' => false, // 압축 사용 여부
    ],
    // ... 기타 캐시 드라이버 설정
];

ServBay의 PHP는 일반적으로 Memcached 확장 모듈을 기본 포함합니다.

Redis 설정 (fuel/app/config/redis.php):

Redis를 사용할 경우, 별도의 redis.php 파일에 구성합니다:

php

<?php
return [
    'default' => [
        'hostname' => '127.0.0.1', // Redis 기본 주소
        'port'     => 6379,        // 기본 포트
        'database' => 0,           // DB 인덱스
    ],
    // 여러 Redis 연결 설정 가능
];

ServBay의 PHP도 Redis 확장을 기본 제공합니다.

데이터베이스 및 캐시 서비스 코드 예시

FuelPHP가 DB 및 캐시 서비스와 상호작용하는 예시 코드를 추가해보겠습니다.

데이터베이스 테이블 준비 (FuelPHP 마이그레이션 사용)

FuelPHP의 Oil 도구로 데이터베이스 마이그레이션(버전별 스키마 관리)이 가능합니다.

마이그레이션 파일 생성
프로젝트 루트(servbay-fuelphp-app)에서 Oil로 users 테이블 마이그레이션 파일 생성:
bash
```
php oil generate migration create_users_table
```
1
fuel/app/migrations 하위에 타임스탬프가 포함된 파일이 생성됩니다.

마이그레이션 파일 편집

새로 생성한 파일(fuel/app/migrations/xxxxxxxxxxxx_create_users_table.php)의 up()/down() 메서드를 편집:

php

<?php
namespace Fuel\Migrations;

use Fuel\Core\DBUtil;

class Create_users_table
{
    public function up()
    {
        // users 테이블 생성
        DBUtil::create_table('users', [
            'id'          => ['type' => 'int', 'constraint' => 11, 'auto_increment' => true],
            'name'        => ['type' => 'varchar', 'constraint' => 100],
            'email'       => ['type' => 'varchar', 'constraint' => 100, 'unique' => true],
        ], ['id'], true, 'InnoDB', 'utf8mb4_unicode_ci'); // PK 지정, 인덱싱 사용, 엔진 및 문자셋 지정
    }

    public function down()
    {
        // users 테이블 삭제(롤백)
        DBUtil::drop_table('users');
    }
}

마이그레이션 실행
프로젝트 루트에서 Oil로 마이그레이션을 적용:
bash
```
php oil refine migrate
```
1
정상적으로 실행되면 fuel_dev DB에 users 테이블이 생성됩니다.

예시 컨트롤러 코드 추가

fuel/app/classes/controller/welcome.php에 DB/캐시 활용 액션 메서드를 추가:

php

<?php
use Fuel\Core\Controller;
use Fuel\Core\Response;
use Fuel\Core\Cache;
use Fuel\Core\DB; // DB facade 임포트
use Fuel\Core\Redis; // Redis facade 임포트

class Controller_Welcome extends Controller
{
    // 기본 홈페이지 액션
    public function action_index()
    {
        return Response::forge('Hello ServBay!');
    }

    // Memcached 예제 액션
    public function action_memcached()
    {
        // 캐시에서 값 조회
        $value = Cache::get('servbay_memcached_key');

        if ($value === false) {
            // 캐시에 값이 없으면 데이터 저장
            $value = 'Hello Memcached from ServBay!';
            Cache::set('servbay_memcached_key', $value, 60); // 60초 캐싱
            $value .= ' (from cache)';
        } else {
            $value .= ' (cached)';
        }

        return Response::forge($value);
    }

    // Redis 예제 액션
    public function action_redis()
    {
        // 기본 연결로 Redis 인스턴스 가져오기
        $redis = \Redis_Db::instance(); // FuelPHP 1.x은 Redis_Db::instance() 사용
        // 여러 연결 구성시에는 \Redis_Db::instance('connection_name') 사용 가능

        // Redis에 데이터 저장
        $redis->set('servbay_redis_key', 'Hello Redis from ServBay!');

        // Redis에서 데이터 읽기
        $value = $redis->get('servbay_redis_key');

        return Response::forge($value);
    }

    // MySQL 데이터 추가 액션
    public function action_mysql_add()
    {
        try {
            // users 테이블에 새 레코드 삽입
            $result = DB::insert('users')->set([
                'name' => 'ServBay Demo User ' . time(), // 유니크 보장용 타임스탬프
                'email' => 'demo_user_' . time() . '@servbay.test',
            ])->execute(); // execute() 결과에 새 ID 포함

            return Response::forge('User added with ID: ' . $result[0]);
        } catch (\Database_Exception $e) {
            // DB 예외 처리(중복 email 등)
            return Response::forge('Error adding user: ' . $e->getMessage(), 500);
        }
    }

    // MySQL 데이터 조회 액션
    public function action_mysql()
    {
        // users 테이블 전체 조회
        $users = DB::select('id', 'name', 'email')->from('users')->execute()->as_array();

        // JSON 형식으로 사용자 리스트 반환
        return Response::forge(json_encode($users, JSON_PRETTY_PRINT));
    }
}

참고:

DB, Redis facade를 직접 import(use Fuel\Core\DB; 등)하여 사용합니다.
Memcached/Redis 키는 servbay_ 프리픽스 사용으로 충돌 방지.
MySQL 추가 예제에는 타임스탬프와 에러 처리 로직을 포함하여 실제 개발 상황에 맞췄습니다.
FuelPHP 1.x 기준으로 Redis 인스턴스 획득 방식(\Redis_Db::instance()).

라우트 설정

URL로 새 Action에 접근하려면 fuel/app/config/routes.php에 라우트 구성 필요. 기본적으로 Controller_Welcome용 라우트가 있지만, memcached, redis, mysql_add, mysql 등 명시적 추가가 필요합니다.

fuel/app/config/routes.php에 아래처럼 추가/수정합니다:

php

<?php
return array(
    '_root_'  => 'welcome/index',  // 기본 라우트: welcome 컨트롤러의 index 액션
    '_404_'   => 'welcome/404',    // 404 에러 페이지 라우트

    // 추가한 예제 액션 라우트
    'memcached'   => 'welcome/memcached',
    'redis'       => 'welcome/redis',
    'mysql_add'   => 'welcome/mysql_add',
    'mysql'       => 'welcome/mysql',

    // ... 기타 라우트 설정
);

웹사이트 접속 및 테스트

이제 ServBay에서 등록한 도메인 https://servbay-fuelphp-test.local을 브라우저에서 접속하여 FuelPHP 프로젝트와 여러 서비스 연동을 테스트할 수 있습니다.

기본 페이지 접속: https://servbay-fuelphp-test.local
- 예상 출력: Hello ServBay!
Memcached 테스트: https://servbay-fuelphp-test.local/memcached
- 첫 방문: Hello Memcached from ServBay! (from cache) (캐시 서비스 정상일 경우)
- 재접속: Hello Memcached from ServBay! (cached) (캐시서비스가 정상 및 캐시 미만료)
Redis 테스트: https://servbay-fuelphp-test.local/redis
- 예상 출력: Hello Redis from ServBay! (Redis 서비스 정상)
MySQL에 사용자 추가: https://servbay-fuelphp-test.local/mysql_add
- 예상 출력: User added with ID: [생성된ID] (MySQL/DB/테이블 정상일 때)
MySQL 사용자 리스트 조회: https://servbay-fuelphp-test.local/mysql
- 예상 출력: users 테이블의 전체 기록(JSON 배열/리스트, 테이블에 데이터가 있을 경우)

HTTPS 관련: ServBay는 로컬 웹사이트에 SSL 인증서를 자동 생성 및 할당하며, ServBay User CA 또는 Public CA를 신뢰하도록 지원합니다. 브라우저에서 인증서 신뢰 관련 경고가 발생하면, ServBay CA 인증서를 OS에 정상 등록했는지 확인하세요.

유의사항

ServBay 메인화면에서 사용하는 PHP 버전, 웹서버(Caddy/Nginx/Apache), MySQL(사용 시), Redis(사용 시), Memcached(사용 시) 등 모든 서비스가 실행 중임을 항상 확인하세요.
ServBay의 DB관리 도구에서 반드시 fuel_dev 데이터베이스를 직접 생성해야 합니다(혹은 db.php에 미리 생성된 DB를 지정). FuelPHP의 마이그레이션 도구(oil refine migrate)는 지정한 DB 내에 테이블만 생성하며 DB 자체는 자동생성하지 않습니다.
FuelPHP의 진입점은 public/index.php이므로, ServBay 웹사이트 기능에서 웹사이트 루트 디렉토리는 반드시 프로젝트의 public 서브폴더로 지정해야 합니다.

요약

ServBay를 활용하면 macOS에서 FuelPHP 개발에 필요한 모든 로컬 환경을 손쉽고 빠르게 세팅할 수 있습니다. 이 가이드에서는 FuelPHP 프로젝트 생성, ServBay의 웹사이트 가상호스트 설정, 데이터베이스와 캐시 서비스 연결, 그리고 예제 코드 및 테스트 절차까지 필요한 모든 단계를 자세히 소개했습니다. ServBay의 통합 서비스와 간편한 설정은 개발 생산성을 크게 향상시켜 줄 것입니다.

본 지침서를 참고하여 ServBay 기반의 FuelPHP 개발을 원활하게 시작하시길 바랍니다!

ServBay 로컬 개발 환경에서 FuelPHP 프로젝트 생성 및 실행하기 ​

FuelPHP란? ​

FuelPHP의 주요 기능 및 장점 ​

ServBay를 이용한 FuelPHP 개발 환경 구축 ​

준비 사항 ​

FuelPHP 프로젝트 생성하기 ​

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

FuelPHP 프로젝트 서비스 연결 설정 ​

데이터베이스 설정 ​

캐시 설정 (Memcached 및 Redis) ​

데이터베이스 및 캐시 서비스 코드 예시 ​

데이터베이스 테이블 준비 (FuelPHP 마이그레이션 사용) ​

예시 컨트롤러 코드 추가 ​

라우트 설정 ​

웹사이트 접속 및 테스트 ​

유의사항 ​

요약 ​