ServBay로 CakePHP 프로젝트 만들기 및 실행하기

ServBay는 macOS와 Windows를 모두 지원하는 로컬 웹 개발 환경으로, PHP, Node.js, Python, Go, Java 등 다양한 언어와 MySQL, PostgreSQL, MongoDB, Redis 등 여러 데이터베이스 서비스를 통합 제공합니다. 또한 Caddy 또는 Nginx 웹 서버와 함께 동작합니다. 이를 통해 개발자는 손쉽게 로컬 프로젝트를 구축하고 관리할 수 있는 편리하고 효율적인 개발 플랫폼을 누릴 수 있습니다.

이 문서에서는 ServBay 환경에서 CakePHP 프로젝트를 생성하고, 설정하며, 실행하는 방법을 설명합니다. CakePHP는 MVC(모델-뷰-컨트롤러) 패턴을 따르는 인기 있는 PHP 웹 프레임워크로, 빠른 개발, 강력한 ORM, 내장된 보안 기능 등으로 유명합니다. ServBay의 편리함과 결합되면, CakePHP 개발을 손쉽게 시작할 수 있습니다.

CakePHP란 무엇인가요?

CakePHP는 오픈소스 PHP 웹 애플리케이션 개발 프레임워크로, 신속하고 구조화된 웹 앱 개발을 위한 기본 구조를 제공합니다. 동시에 유연함을 잃지 않으면서 개발의 많은 반복적인 작업을 간소화하기 위해 "설정보다 관례" 원칙을 따릅니다.

CakePHP의 주요 특징 및 장점

• MVC 기반 구조: 코드 정리가 체계적이며, 유지보수와 확장이 쉽습니다.
• 빠른 개발: 명령줄 도구(Bake)를 통한 코드 자동 생성으로 개발을 가속화합니다.
• 강력한 ORM(객체-관계 매핑): 데이터베이스 연동이 간단하며, 여러 DB 시스템을 지원합니다.
• 내장 보안 기능: CSRF 보호, SQL 인젝션 방지, 입력 검증 등 다양한 보안 기능이 탑재되어 있습니다.
• 유연한 템플릿 엔진: 다양한 뷰 레이어 기술을 지원합니다.
• 활발한 커뮤니티와 풍부한 플러그인: 문제 해결이 빠르고, 기능 확장이 용이합니다.
• 상세한 문서: 완성도 높은 가이드와 API 참고문서를 제공합니다.

CakePHP는 API부터 대규모 엔터프라이즈 시스템까지 다양한 웹 애플리케이션 개발에 적합합니다.

ServBay로 CakePHP 개발 환경 구축하기

ServBay는 CakePHP 개발에 다음과 같은 통합 환경을 지원합니다:

• PHP 인터프리터와 필수 확장 모듈 사전 설치
• Composer 패키지 관리자 사전 설치
• 손쉬운 Web 서버(Caddy/Nginx) 설정
• MySQL, PostgreSQL, Redis 등의 데이터베이스 서비스 통합

ServBay를 사용하면 이러한 구성 요소를 별도의 설치 및 설정 없이 바로 사용할 수 있습니다.

사전 준비사항

작업을 시작하기 전에 아래 사항을 준비해 주세요:

1. ServBay 설치: macOS에 ServBay를 다운로드하여 성공적으로 설치합니다.
2. ServBay 서비스 활성화: ServBay 앱을 실행하고, 필요한 소프트웨어 패키지(예: PHP, 사용할 DB인 MySQL 또는 PostgreSQL, 그리고 캐시 서비스인 Redis 또는 Memcached)를 실행시킵니다. ServBay의 "패키지" 탭에서 서비스 관리를 할 수 있습니다.
3. ServBay 기본 사용법 익히기: 사이트 추가 및 설정 방법을 알고 있어야 합니다. 잘 모를 경우 ServBay 기본 사용법 안내서를 먼저 참고하세요.

CakePHP 프로젝트 생성하기

ServBay에서는 모든 웹 프로젝트 파일을 /Applications/ServBay/www 디렉터리에 통합 저장하는 것을 권장하며, 이를 통해 웹사이트 자동 인식 및 관리가 가능합니다.

1. 터미널 열기

   macOS 터미널 앱을 실행합니다.

2. ServBay 웹사이트 루트 디렉터리로 이동

   권장되는 디렉터리로 이동합니다:

   cd /Applications/ServBay/www

3. 프로젝트 디렉터리 만들기

   예제 프로젝트명으로 servbay-cakephp-app 서브디렉터리를 생성합니다:

   mkdir servbay-cakephp-app
   cd servbay-cakephp-app

4. Composer로 CakePHP 프로젝트 생성

   ServBay에는 Composer가 사전 설치되어 있습니다. 아래 명령어로 CakePHP 프로젝트 스켈레톤을 생성합니다:

   composer create-project --prefer-dist cakephp/app .

   이 명령은 최신 안정 버전의 CakePHP와 그 종속성들을 현재 디렉터리(.)에 설치합니다.

5. ORM 드라이버 설치 (PostgreSQL 사용 시)

   PostgreSQL DB를 사용할 경우, 추가 드라이버를 설치합니다:

   composer require cakephp/orm-pgsql

   MySQL의 경우에는 별도 드라이버 설치가 필요하지 않으며, 핵심 패키지에 포함되어 있습니다.

초기 설정

프로젝트 생성 후, 데이터베이스 연결 설정 등 기본 환경설정을 진행해야 합니다.

1. 환경 변수 설정 및 DB 연결 정보 기입

   CakePHP의 로컬 환경 설정은 config/app_local.php 파일에 집중되어 있습니다. 해당 파일의 Datasources 부분을 찾아서 DB 연결 정보를 입력합니다. ServBay의 기본 DB 사용자명은 root, 패스워드는 password입니다.

   예) MySQL 데이터베이스 연결 설정:

   // config/app_local.php
   'Datasources' => [
       'default' => [
           'className' => \Cake\Database\Connection::class,
           'driver' => \Cake\Database\Driver\Mysql::class, // PostgreSQL은 \Cake\Database\Driver\Postgres::class
           'persistent' => false,
           'host' => '127.0.0.1', // ServBay의 기본 DB 서버 주소
           //'port' => '3306', // MySQL 기본 포트 3306, PostgreSQL은 5432
           'username' => 'root', // ServBay 기본 사용자
           'password' => 'password', // ServBay 기본 비밀번호
           'database' => 'servbay_cakephp_app', // 사용할 데이터베이스명
           'encoding' => 'utf8mb4',
           'timezone' => 'UTC',
           'flags' => [],
           'cacheMetadata' => true,
           'log' => false,
   
           /**
            * 테이블명이 "user" 등 예약어일 때 식별자 쿼팅을 true로 설정
            */
           'quoteIdentifiers' => false,
   
           /**
            * 현재 제약사항:
            * - 대부분의 드라이버는 PDO 옵션으로 격리 수준 설정을 지원하지 않음
            * - 모든 드라이버가 PDO 옵션으로 charset을 설정하는 것을 지원하지 않음
            * - CakePHP의 포장된 Postgres 드라이버는 PDO 옵션을 지원하지 않음(encoding만 설정)
            */
           'options' => [],
   
           //'url' => env('DATABASE_URL', null), // DATABASE_URL 환경변수를 사용할 경우 활성화
       ],
   ],

   사용하는 DB 타입(MySQL 또는 PostgreSQL)에 맞게 driver와 port를 조정하고, database 이름은 생성할 데이터베이스와 일치시켜 주세요.

웹 서버 설정 (ServBay에서 사이트 만들기)

CakePHP 프로젝트를 브라우저로 접근하려면 ServBay에서 사이트를 추가하고 프로젝트 디렉터리에 연결해야 합니다.

1. ServBay 컨트롤 패널 열기

   ServBay 아이콘을 클릭하여 컨트롤 패널을 엽니다.

2. "웹사이트" 탭으로 이동

   패널 좌측에서 "웹사이트"(또는 예전 "호스트") 항목을 선택합니다.

3. 새 웹사이트 추가

   하단의 + 버튼을 눌러 새 웹사이트를 추가하고 아래 정보를 입력합니다:

   • 이름(Name): 예) My CakePHP Dev Site 등 구분하기 쉬운 이름
   • 도메인(Domain): 예) servbay-cakephp-test.local 등 로컬 개발용 도메인 (ServBay가 자동 연결)
   • 웹사이트 타입(Site Type): PHP 선택
   • PHP 버전(PHP Version): CakePHP 버전에 맞는 버전 선택 (CakePHP 4+는 PHP 7.4+, CakePHP 5+는 PHP 8.1+ 필요), 예) 8.3
   • 문서 루트(Document Root): 중요! CakePHP의 실제 웹루트는 /Applications/ServBay/www/servbay-cakephp-app/webroot입니다. (servbay-cakephp-app은 실제 프로젝트명으로 변경)

4. 저장 및 적용

   모든 정보를 입력 뒤 우측 하단의 "저장" 클릭, 이후 적용 안내에 따라 확인합니다. ServBay는 Caddy 또는 Nginx 웹 서버에 해당 도메인을 자동 연결하며, 요청을 프로젝트의 webroot로 안내합니다.

자세한 웹사이트 추가 방법은 웹사이트 첫 추가하기 문서를 참고하세요.

기본 설정 확인

이제 브라우저에서 설정한 도메인(예. https://servbay-cakephp-test.local)을 입력하여 사이트를 확인할 수 있습니다.

모든 설정이 올바르면 CakePHP의 기본 환영 페이지를 볼 수 있습니다. 이는 PHP 환경, 웹 서버, ServBay의 사이트 설정이 정상임을 의미합니다.

데이터베이스 및 캐시 서비스 연동

CakePHP는 강력한 ORM과 캐시 추상화를 제공해 ServBay 데이터베이스 및 캐시 서비스와 쉽게 연동할 수 있습니다.

관계형 데이터베이스 예제 (MySQL / PostgreSQL)

CakePHP ORM을 통해 ServBay MySQL 또는 PostgreSQL DB에 연결, 간단한 users 테이블 생성 후 데이터 CRUD를 해봅니다.

1. ServBay에서 데이터베이스 생성

   먼저 ServBay의 DB 관리 도구(phpMyAdmin, pgAdmin, Navicat 또는 DBeaver 등)로 DB서버(주소: 127.0.0.1, 사용자: root, 비밀번호: password)에 접속하고, servbay_cakephp_app 이름으로 새 DB를 생성합니다.

2. ORM Model 파일 생성

   UsersTable.php 파일을 생성하여 users 테이블을 모델링합니다.

   src/Model/Table/UsersTable.php에 아래 코드를 저장하세요:

   <?php
   namespace App\Model\Table;
   
   use Cake\ORM\Table;
   use Cake\Validation\Validator; // 검증 규칙 필요 시
   
   class UsersTable extends Table
   {
       /**
        * 초기화 메서드
        *
        * @param array $config 테이블 설정 정보
        * @return void
        */
       public function initialize(array $config): void
       {
           parent::initialize($config);
   
           $this->setTable('users'); // 실제 테이블명 지정
           $this->setDisplayField('name'); // 연관 처리 시 기본 표시 필드
           $this->setPrimaryKey('id'); // 기본키 지정
   
           // 타임스탬프 동작 추가 필요 시
           // $this->addBehavior('Timestamp');
       }
   
       /**
        * 기본 검증 규칙
        *
        * @param \Cake\Validation\Validator $validator Validator 인스턴스
        * @return \Cake\Validation\Validator
        */
       public function validationDefault(Validator $validator): Validator
       {
           $validator
               ->scalar('name')
               ->maxLength('name', 255)
               ->requirePresence('name', 'create')
               ->notEmptyString('name');
   
           $validator
               ->email('email')
               ->requirePresence('email', 'create')
               ->notEmptyString('email')
               ->add('email', 'unique', ['rule' => 'validateUnique', 'provider' => 'table']); // email 고유성 보장
   
           return $validator;
       }
   }

3. Bake 도구로 마이그레이션 파일 생성

   프로젝트 루트(/Applications/ServBay/www/servbay-cakephp-app)에서 Bake 도구로 users 테이블 구조를 정의하는 마이그레이션 파일을 생성합니다:

   bin/cake bake migration CreateUsers name:string email:string:unique

   위 명령은 name(문자열), email(문자열 및 고유성) 필드를 가진 users 테이블 생성 지시가 포함된 마이그레이션 파일을 만듭니다.

4. DB 마이그레이션 실행

   아래 명령으로 실제 데이터베이스에 users 테이블을 만듭니다:

   bin/cake migrations migrate

   성공하면 DB에서 users 테이블을 확인할 수 있습니다.

5. DB 연결 설정(미리 하지 않았다면)

   config/app_local.php의 Datasources.default가 실제 DB 정보와 일치하는지 확인합니다.

   • MySQL 예시:

     'Datasources' => [
         'default' => [
             'className' => \Cake\Database\Connection::class,
             'driver' => \Cake\Database\Driver\Mysql::class,
             'host' => '127.0.0.1',
             'username' => 'root',
             'password' => 'password',
             'database' => 'servbay_cakephp_app',
             // 기타 설정
         ],
     ],

   • PostgreSQL 예시:

     'Datasources' => [
         'default' => [
             'className' => \Cake\Database\Connection::class,
             'driver' => \Cake\Database\Driver\Postgres::class,
             'host' => '127.0.0.1',
             // 'port' => '5432', // 기본 포트
             'username' => 'root', // ServBay 기본 사용자
             'password' => 'password', // ServBay 기본 비밀번호
             'database' => 'servbay_cakephp_app',
             // 기타 설정
         ],
     ],

6. 예제 라우팅 및 컨트롤러 메서드 추가

   config/routes.php를 수정해 사용자 추가/조회용 라우트를 등록합니다:

   // config/routes.php
   use Cake\Routing\RouteBuilder;
   use Cake\Routing\Router;
   use Cake\Routing\Route\DashedRoute;
   
   Router::defaultRouteClass(DashedRoute::class);
   
   Router::scope('/', function (RouteBuilder $routes) {
       // ... 기존 라우팅
       $routes->connect('/', ['controller' => 'Pages', 'action' => 'display', 'home']);
   
       // DB 예제 라우팅
       $routes->connect('/db-add-user', ['controller' => 'Pages', 'action' => 'dbAddUser']);
       $routes->connect('/db-list-users', ['controller' => 'Pages', 'action' => 'dbListUsers']);
   
       // ... 기타 라우팅
       $routes->fallbacks(DashedRoute::class);
   });

   src/Controller/PagesController.php에서 DB 조작 메서드를 추가합니다:

   <?php
   namespace App\Controller;
   
   use Cake\Http\Response;
   use Cake\ORM\TableRegistry;
   use Cake\Datasource\Exception\RecordNotFoundException; // 검색 실패 예외
   
   class PagesController extends AppController
   {
       /**
        * 기본 페이지 출력
        *
        * @param array ...$path Path 세그먼트
        * @return \Cake\Http\Response|null
        */
       public function display(...$path): ?Response
       {
           // 기본 display 메서드
           return new Response(['body' => 'Hello ServBay! 이곳은 기본 페이지입니다.']);
       }
   
       /**
        * DB 예제: 사용자 추가
        */
       public function dbAddUser(): Response
       {
           $usersTable = TableRegistry::getTableLocator()->get('Users'); // Users Table 인스턴스 가져오기
   
           // 새 사용자 엔티티 생성
           $user = $usersTable->newEntity([
               'name' => 'ServBay Demo User',
               'email' => 'servbay-demo@servbay.test' // ServBay 브랜드 예시 이메일
           ]);
   
           // DB에 엔티티 저장 시도
           if ($usersTable->save($user)) {
               return new Response(['body' => '사용자가 성공적으로 추가되었습니다! 사용자 ID: ' . $user->id]);
           } else {
               // 저장 실패 시 검증 오류 등
               $errors = $user->getErrors(); // 검증 오류 메시지 가져오기
               return new Response(['body' => '사용자 추가 실패. 오류: ' . json_encode($errors)]);
           }
       }
   
       /**
        * DB 예제: 모든 사용자 목록 출력
        */
       public function dbListUsers(): Response
       {
           $usersTable = TableRegistry::getTableLocator()->get('Users'); // Users Table 인스턴스 가져오기
   
           // 모든 사용자 조회
           $users = $usersTable->find()->all();
   
           // 결과를 JSON으로 출력
           return new Response(['body' => json_encode($users->toArray())]); // Collection을 배열로 변환
       }
   }

7. DB 예제 접근하기

   브라우저에서:

   • https://servbay-cakephp-test.local/db-add-user로 사용자 추가 (성공 메시지 확인)
   • https://servbay-cakephp-test.local/db-list-users로 사용자 목록 조회(추가한 사용자 포함)

이 절차를 통해 CakePHP 프로젝트와 ServBay의 관계형 DB 연동이 성공적으로 이루어지며, 기본 ORM 활용법도 체험할 수 있습니다.

캐시 서비스 예제 (Memcached / Redis)

CakePHP는 일관된 캐시 API 덕분에 Memcached, Redis 등 다양한 캐시 엔진으로 쉽게 전환할 수 있습니다. ServBay는 PHP용 Memcached 및 Redis 확장과 서비스도 기본 제공합니다.

먼저 ServBay 컨트롤 패널 "패키지" 탭에서 Memcached 또는 Redis 서비스를 활성화 하세요.

1. 캐시 연결 설정

   config/app_local.php 파일의 Cache 부분을 설정합니다.

   • Memcached 예시:

     // config/app_local.php
     'Cache' => [
         'default' => [
             'className' => \Cake\Cache\Engine\MemcachedEngine::class,
             'servers' => ['127.0.0.1:11211'], // 기본 Memcached 주소와 포트
             'prefix' => 'servbay_cakephp_', // 캐시 키 접두어
         ],
         // 기타 캐시 설정
     ],

   • Redis 예시:

     // config/app_local.php
     'Cache' => [
         'default' => [
             'className' => \Cake\Cache\Engine\RedisEngine::class,
             'host' => '127.0.0.1', // 기본 Redis 주소
             'port' => 6379, // 기본 Redis 포트
             'password' => null, // Redis 비밀번호가 설정된 경우 입력
             'database' => 0, // Redis DB 인덱스
             'prefix' => 'servbay_cakephp_', // 캐시 키 접두어
         ],
         // 기타 캐시 설정
     ],

   활성화한 캐시 서비스에 맞춰 설정하세요.

2. 예제 라우팅 및 컨트롤러 메서드 추가

   config/routes.php에 예제 캐시 라우팅을 추가합니다:

   // config/routes.php
   // 기존 라우팅
   $routes->connect('/cache-memcached', ['controller' => 'Pages', 'action' => 'cacheMemcached']);
   $routes->connect('/cache-redis', ['controller' => 'Pages', 'action' => 'cacheRedis']);
   // 기타 라우팅

   src/Controller/PagesController.php에 캐시 활용 예제 메서드를 구현합니다:

   <?php
   namespace App\Controller;
   
   use Cake\Http\Response;
   use Cake\Cache\Cache; // Cache 클래스 임포트
   // 기타 use 문
   
   class PagesController extends AppController
   {
       // 기존 메서드(display, dbAddUser, dbListUsers)
   
       /**
        * 캐시 예제: Memcached 사용
        */
       public function cacheMemcached(): Response
       {
           // app_local.php에서 'default' 캐시가 MemcachedEngine으로 설정되어 있어야 함
   
           $cacheKey = 'servbay_memcached_test_key';
           $cachedData = Cache::read($cacheKey); // 캐시에서 데이터 읽기
   
           $responseBody = '';
   
           if ($cachedData === false) {
               // 캐시 미스
               $responseBody = '캐시 미스! "Hello Memcached!"를 캐시에 저장합니다.';
               $dataToCache = 'Hello Memcached!';
               Cache::write($cacheKey, $dataToCache, 'default'); // 데이터 캐시 저장
           } else {
               // 캐시 히트
               $responseBody = '캐시 히트! 캐시 데이터: ' . $cachedData;
           }
   
           return new Response(['body' => $responseBody]);
       }
   
       /**
        * 캐시 예제: Redis 사용
        */
       public function cacheRedis(): Response
       {
            // app_local.php에서 'default' 캐시가 RedisEngine으로 설정되어 있어야 함
   
           $cacheKey = 'servbay_redis_test_key';
           $cachedData = Cache::read($cacheKey); // 캐시에서 데이터 읽기
   
           $responseBody = '';
   
           if ($cachedData === false) {
               // 캐시 미스
               $responseBody = '캐시 미스! "Hello Redis!"를 캐시에 저장합니다.';
               $dataToCache = 'Hello Redis!';
               Cache::write($cacheKey, $dataToCache, 'default'); // 데이터 캐시 저장
           } else {
               // 캐시 히트
               $responseBody = '캐시 히트! 캐시 데이터: ' . $cachedData;
           }
   
           return new Response(['body' => $responseBody]);
       }
   }

3. 캐시 예제 접근하기

   브라우저에서:

   • Memcached 설정 시: https://servbay-cakephp-test.local/cache-memcached 접근(최초 미스, 새로고침 히트)
   • Redis 설정 시: https://servbay-cakephp-test.local/cache-redis 접근(동일)

CakePHP 프로젝트가 ServBay 캐시 서비스와 정상적으로 연동되는 것을 확인할 수 있습니다.

유의사항

• DB 계정 정보: ServBay의 기본 DB 계정(root/password)은 로컬 개발용으로만 사용하세요. 운영환경에서는 더 안전한 정보를 반드시 사용하세요.
• 문서 루트: ServBay 사이트의 "문서 루트"는 반드시 CakePHP webroot 디렉터리로 지정해야 합니다. 프로젝트 최상위 폴더가 아님에 주의하세요.
• PHP 버전 호환성: ServBay에서 선택한 PHP 버전이 사용하는 CakePHP 프레임워크와 호환되는지 반드시 확인하세요. CakePHP 공식 문서에서 요구 버전을 참고하세요.
• ServBay 포트: 기본 포트(80/443)가 다른 프로그램과 충돌할 경우 ServBay 설정에서 포트를 변경하고, 필요한 경우 hosts 파일 수정 또는 포트 번호를 입력해 접속해야 합니다.

자주 묻는 질문 (FAQ)

• Q: servbay-cakephp-test.local 접속 시 "페이지를 찾을 수 없음" 오류가 나타나나요?
  • A: ServBay에서 해당 사이트의 "문서 루트"가 /Applications/ServBay/www/servbay-cakephp-app/webroot에 정확히 연결되어 있는지 확인하세요.
  • ServBay의 웹 서버(Caddy/Nginx)가 정상 작동 중인지 확인합니다.
  • 시스템 hosts 파일이 servbay-cakephp-test.local을 127.0.0.1로 제대로 매핑하고 있는지 점검하세요(ServBay가 자동 처리하지만, 때로 직접 확인 필요).
  • CakePHP 프로젝트의 .htaccess 및 웹서버 설정 파일이 올바른지 확인(기본적으로 webroot/.htaccess는 정상입니다).
• Q: DB 연결 오류가 발생하나요?
  • A: ServBay에서 해당 DB 서비스(MySQL/PostgreSQL)가 실행 중인지 확인하세요.
  • config/app_local.php에서 DB 연결 정보(host, port, username, password, database)가 올바른지, ServBay DB 서비스 정보와 일치하는지 체크합니다.
  • DB 서버에서 servbay_cakephp_app 데이터베이스가 실제로 생성되었는지 확인하세요.
• Q: Composer 및 bin/cake 명령이 실행되지 않나요?
  • A: 현재 터미널 경로가 CakePHP 프로젝트 루트(/Applications/ServBay/www/servbay-cakephp-app)인지 확인하세요.
  • ServBay의 PHP와 Composer 패키지가 실행 중인지 확인합니다.
  • 터미널에서 php 명령을 인식하는지 점검하세요(ServBay는 PATH에 PHP를 포함시키는 경우가 많음). ServBay 내장 터미널이나 PATH 직접 설정도 방법입니다.

요약

ServBay를 이용하면 CakePHP 프로젝트용 로컬 개발 환경을 매우 빠르게 구축할 수 있습니다. PHP, Composer, 웹서버, 데이터베이스 서비스 등 필수 도구들이 사전 통합되어, 복잡한 환경 설정 과정 없이 프로젝트 시작이 가능합니다. 본 문서는 프로젝트 생성부터 기본 설정, 웹서버 연결, 관계형 DB 및 캐시 서비스 연동까지 CakePHP 개발 전 과정을 상세히 소개합니다. ServBay의 편리함으로 환경 구성에 드는 시간을 줄이고, 개발 자체에 더 집중할 수 있습니다.