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

FuelPHP란 무엇인가요?

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

FuelPHP의 주요 기능 및 장점

HMVC 아키텍처: 계층형 MVC 디자인 패턴을 지원해 코드의 조직화, 재사용, 모듈형 개발이 가능하며, 대규모·복잡한 프로젝트에 특히 적합합니다.
고성능: FuelPHP는 설계 단계에서부터 성능 최적화에 중점을 두었으며, 효율적인 속도와 자원 활용으로 높은 동시 요청을 효과적으로 처리합니다.
확장 용이: 강력한 확장 메커니즘을 통해 개발자는 프로젝트에 맞춰 서드파티 라이브러리나 커스텀 기능을 쉽게 통합하거나 추가할 수 있습니다.
보안: 입력 자동 검증, 출력 필터링(XSS 방지), CSRF 보호, SQL 인젝션 예방 등 다양한 내장 보안 기능을 갖추고 있어 보다 안전한 애플리케이션 개발이 가능합니다.
강력한 커뮤니티 지원: 활발한 개발자 커뮤니티에서 신속한 지원과 다양한 서드파티 자원을 얻을 수 있습니다.

이러한 특장점을 통해 FuelPHP는 개발자가 작게는 개인 사이드 프로젝트에서부터 대규모 엔터프라이즈급 애플리케이션까지, 안전하고 쉽게 유지관리 가능한 고성능 웹 서비스를 빠르게 구축할 수 있도록 합니다.

ServBay로 FuelPHP 개발 환경 구축하기

ServBay는 개발자에게 맞춤화된 로컬 웹 개발 환경으로 PHP, Caddy/Nginx/Apache, MySQL/PostgreSQL/MongoDB, Redis 등 다양한 개발 필수 서비스를 미리 설치 제공합니다. ServBay를 활용하면 FuelPHP 프로젝트에 필요한 런타임 환경을 복잡한 별도 설치나 수동 설정 없이 손쉽게 마련할 수 있습니다.

이 가이드에서는 ServBay의 PHP 환경, Caddy 웹 서버, 그리고 데이터베이스 및 캐시 서비스를 이용해 FuelPHP 프로젝트를 생성하고 실행하는 방법을 단계별로 설명합니다. 웹사이트 기능을 활용해 손쉽게 웹 서버 설정 및 프로젝트 접근, 테스트까지 진행할 수 있습니다.

사전 준비 사항

시작 전에 아래 조건을 확인하세요:

macOS에 ServBay를 정상적으로 설치 및 실행했습니다.
ServBay의 PHP 환경이 활성화되어 있습니다(기본값으로 활성화됨).
ServBay에서 사용할 데이터베이스(예: MySQL), 캐시 서비스(예: Redis, Memcached)가 시작되어 정상 동작 중입니다.
ServBay에는 Composer가 기본 제공되어 별도 설치가 필요 없습니다.

FuelPHP 프로젝트 생성하기

웹 서버 설정 (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 등)에서 fuel_dev 이름의 데이터베이스를 직접 만들어야 합니다. ServBay 기본 MySQL 사용자명과 비밀번호는 모두 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', // 캐시 식별자
        'servers' => [
             'default' => [
                'host'   => '127.0.0.1', // Memcached 기본 주소
                'port'   => 11211,      // Memcached 기본 포트
                '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,      // Redis 기본 포트
        'database' => 0,         // Redis 데이터베이스 인덱스
    ],
    // 여러 Redis 연결 구성 가능
];

ServBay의 PHP 환경에는 보통 Redis 확장 모듈도 기본 내장되어 있습니다.

데이터베이스 & 캐시 서비스 연동 예제

FuelPHP에서 데이터베이스 및 캐시 서비스를 실제로 활용하는 방법을 코드 예제로 보여드립니다.

데이터베이스 테이블 준비 (FuelPHP Migrations 활용)

FuelPHP는 Oil 도구를 통해 마이그레이션(Migration) 기능을 제공합니다. 이는 데이터베이스 구조를 버전 관리하는 데 유용합니다.

마이그레이션 파일 생성
프로젝트 루트(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'); // 기본키, 인덱스, 엔진, 문자셋 설정
    }

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

마이그레이션 실행
프로젝트 루트(servbay-fuelphp-app)에서 아래 명령어로 마이그레이션을 실행하여 테이블을 생성합니다:
bash
```
php oil refine migrate
```
1
정상적으로 실행되면 fuel_dev 데이터베이스에 users 테이블이 생성됩니다.

컨트롤러 예제 코드 추가

fuel/app/classes/controller/welcome.php 파일을 열어 데이터베이스와 캐시 사용 예시 메서드를 추가하세요:

php

<?php
use Fuel\Core\Controller;
use Fuel\Core\Response;
use Fuel\Core\Cache;
use Fuel\Core\DB; // DB 파사드 불러오기
use Fuel\Core\Redis; // Redis 파사드 불러오기

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) {
            // 예: 이메일 중복 시 예외 처리
            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 파사드를 (use Fuel\Core\DB;, use Fuel\Core\Redis;) 통해 직접 사용할 수 있습니다.
Memcached, Redis 키에는 servbay_ 접두사를 붙여 충돌 방지를 했습니다.
MySQL 쓰기 예시에는 타임스탬프 및 간단한 에러 핸들링, 구체적인 예시 문구가 포함되어 있습니다.
FuelPHP 1.x에서 Redis 인스턴스는 \Redis_Db::instance()로 호출합니다.

라우팅 설정

위에서 작성한 컨트롤러 액션을 URL로 접근하려면 fuel/app/config/routes.php 파일에 라우팅을 추가해야 합니다. FuelPHP의 기본 라우팅은 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 또는 ServBay Public CA가 신뢰되도록 설정되어야 하며, 브라우저에서 신뢰하지 않는 인증서 경고가 뜬다면 시스템에서 ServBay CA 인증서를 신뢰하도록 설정했는지 확인하세요.

유의 사항

ServBay 메인 화면에서 입력한 PHP 버전, Caddy(또는 Nginx/Apache), MySQL, Redis, Memcached 등 각종 서비스가 실행 중인지 반드시 확인하세요.
ServBay 내 데이터베이스 관리 도구를 통해 fuel_dev 데이터베이스를 직접 생성해야 합니다(또는 db.php에 이미 존재하는 다른 DB를 지정). FuelPHP의 마이그레이션 도구(oil refine migrate)는 테이블만 생성하며 DB 자체는 자동 생성하지 않습니다.
FuelPHP의 공개 엔트리 파일은 public/index.php입니다. 따라서 ServBay에서 웹사이트를 설정할 때 사이트 루트 디렉터리를 반드시 해당 프로젝트의 public 하위 폴더로 지정해야 합니다.

마무리

ServBay를 활용하면 macOS에서 FuelPHP 프로젝트를 위한 완벽한 로컬 개발 환경을 쉽고 빠르게 구성할 수 있습니다. 이 가이드에서는 프로젝트 생성, ServBay 웹사이트 기능 설정, 데이터베이스·캐시 연동, 그리고 예제 코드 구현까지 모든 핵심 프로세스를 실습 형태로 상세하게 다뤘습니다. ServBay의 다양한 내장 서비스와 간소화된 설정 프로세스로 여러분의 개발 생산성이 크게 향상될 것입니다.

이 가이드가 ServBay에서 FuelPHP 개발을 즐겁고 순조롭게 시작하는 데 도움이 되길 바랍니다!

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

FuelPHP란 무엇인가요? ​

FuelPHP의 주요 기능 및 장점 ​

ServBay로 FuelPHP 개발 환경 구축하기 ​

사전 준비 사항 ​

FuelPHP 프로젝트 생성하기 ​

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

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

데이터베이스 설정 ​

캐시 설정 (Memcached와 Redis) ​

데이터베이스 & 캐시 서비스 연동 예제 ​

데이터베이스 테이블 준비 (FuelPHP Migrations 활용) ​

컨트롤러 예제 코드 추가 ​

라우팅 설정 ​

웹사이트 접근 및 테스트 ​

유의 사항 ​

마무리 ​