ServBay를 이용한 CakePHP 프로젝트 생성 및 실행

ServBay는 macOS에 특화된 강력한 로컬 웹 개발 환경입니다. PHP, Node.js, Python, Go, Java 등의 다중 언어 런타임과 함께, MySQL, PostgreSQL, MongoDB, Redis 등 주요 데이터베이스 서비스를 Caddy 또는 Nginx 웹 서버와 통합 제공합니다. 이로 인해 개발자는 복잡한 환경설정 없이 손쉽게 로컬 프로젝트를 구축하고 관리할 수 있습니다.

이 문서에서는 ServBay 환경에서 CakePHP 프로젝트를 생성, 설정, 실행하는 과정을 안내합니다. CakePHP는 인기 있는 PHP 웹 프레임워크로, MVC(모델-뷰-컨트롤러) 구조와 빠른 개발 지원, 강력한 ORM, 내장 보안 기능으로 잘 알려져 있습니다. ServBay의 편리함과 결합하면, CakePHP 개발을 신속하게 시작할 수 있습니다.

CakePHP란 무엇인가요?

CakePHP는 오픈 소스 PHP 웹 어플리케이션 프레임워크로, 유연한 구조 속에서 빠르고 조직적인 웹 앱 개발을 위한 기본 토대를 제공합니다. "설정보다 관례" 원칙을 따르며, 반복적인 개발 작업을 크게 단순화시켜 줍니다.

CakePHP의 주요 특징 및 장점

• MVC 기반 구조: 명확한 코드 조직, 유지보수 및 확장성 용이
• 신속한 개발: 터미널에서 Bake 명령어로 코드 생성, 개발 속도 향상
• 강력한 ORM(객체 관계 매핑): 데이터베이스 작업을 단순화하며 다양한 RDBMS 지원
• 내장 보안성: CSRF 방지, SQL 인젝션 보호, 입력 검증 등 앱 보안 강화
• 유연한 템플릿 엔진: 다양한 View 기술과 연동 가능
• 활발한 커뮤니티와 풍부한 플러그인: 지원을 쉽게 구하고, 기능 확장에 용이
• 포괄적 문서: 자세한 가이드와 API 레퍼런스 제공

CakePHP는 단순한 API부터 복잡한 엔터프라이즈 시스템까지 다양한 웹 애플리케이션 구축에 적합합니다.

ServBay로 CakePHP 개발 환경 구축하기

ServBay는 CakePHP 개발에 필수적인 요소를 미리 통합하여 제공합니다.

• PHP 및 주요 확장 모듈 사전 설치
• Composer 패키지 매니저 기본 내장
• 사용이 간편한 웹 서버(Caddy/Nginx) 환경
• MySQL, PostgreSQL, Redis 등 데이터베이스 서비스 손쉬운 관리

ServBay를 통해 이 모든 구성요소 설치와 설정의 번거로움을 줄일 수 있습니다.

사전 준비 사항

작업을 시작하기 전에 아래 단계를 반드시 마쳐 주세요.

1. ServBay 설치: macOS에 ServBay를 다운로드 후 설치합니다.
2. ServBay 서비스 실행: ServBay 앱을 켜고, 필요한 패키지(예: PHP, 사용할 DB(MySQL 또는 PostgreSQL), Redis/Memcached 등 캐시 서비스)가 구동 중인지 확인하세요. 이는 ServBay 대시보드의 ‘패키지’ 탭에서 관리 가능합니다.
3. ServBay 기본 사용 익히기: ServBay에서 사이트 추가 및 설정 방법을 숙지하세요. 처음인 경우 ServBay 기본 가이드를 먼저 참고하길 권장합니다.

CakePHP 프로젝트 생성

ServBay에서는 웹 프로젝트 파일을 /Applications/ServBay/www 디렉토리에 모아두는 것을 추천합니다. 이 경로 내의 프로젝트는 ServBay가 자동 인식 및 관리할 수 있습니다.

1. 터미널 열기

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

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

   다음 명령어로 추천 저장 경로로 이동하세요:

   cd /Applications/ServBay/www

3. 프로젝트 디렉토리 생성

   CakePHP 프로젝트용 새 하위 폴더 생성. 여기선 예시로 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 데이터베이스 사용 시, 아래 추가 패키지 설치:

   composer require cakephp/orm-pgsql

   MySQL을 사용하는 경우 별도 드라이버 설치 없이 기본 패키지에 내장되어 있습니다.

기본 설정

프로젝트를 만든 뒤, 데이터베이스 연결 정보 등 기본 환경 설정이 필요합니다.

1. 환경변수 및 데이터베이스 연결 설정

   CakePHP의 로컬 환경 설정은 config/app_local.php 파일에서 관리합니다. 해당 파일에서 Datasources 부분을 찾아 자신의 DB 연결 정보로 수정합니다. ServBay의 기본 DB ID는 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', // DB 서버 주소, ServBay는 기본적으로 로컬
           //'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,
   
           /**
            * Set identifier quoting to true if you are using words like "user" as your table name.
            * But if you are using words like "cake" you can set it to false.
            * If you don't know use true.
            */
           'quoteIdentifiers' => false,
   
           /**
            * Current limitations include the following:
            * - Most drivers do not support setting isolation levels via PDO options.
            *   Using them will result in an error.
            * - Not all drivers support setting the charset via PDO options.
            *   Using them will result in an error.
            * - PDO options are not supported for packaged drivers like Postgres from CakePHP.
            *   For Postgres, you only need to set the encoding.
            */
           'options' => [],
   
           //'url' => env('DATABASE_URL', null), // DATABASE_URL 환경변수 사용 시 활성화
       ],
   ],

   사용하는 DB 종류(MySQL/PostgreSQL)에 따라 driver(및 필요시 port) 설정을 맞춰주세요. database 명칭도 실제 사용할 데이터베이스명과 동일하게 해주세요.

웹 서버 설정 (ServBay에서 사이트 생성)

브라우저로 CakePHP 프로젝트에 접속하려면, ServBay에서 프로젝트 폴더로 연결된 새 사이트를 추가해야 합니다.

1. ServBay 대시보드 열기

   ServBay 아이콘을 클릭하여 대시보드 진입.

2. ‘사이트’ 탭으로 이동

   왼쪽 내비게이션에서 ‘사이트’(이전 명칭: ‘호스트’) 메뉴를 선택하세요.

3. 새 사이트 추가

   아래쪽 + 버튼 클릭, 새 사이트 등록. 양식에 아래 값을 입력합니다:

   • 이름: 식별하기 쉬운 이름, 예) My CakePHP Dev Site
   • 도메인: 예시) servbay-cakephp-test.local (ServBay가 자동으로 로컬 도메인 할당)
   • 사이트 유형: PHP 선택
   • PHP 버전: CakePHP 버전에 맞는 PHP(예: CakePHP 4+는 PHP 7.4+, 5+는 PHP 8.1+) 선택, 예시로 8.3
   • 사이트 루트(도큐먼트 루트): 중요! 웹서버 루트는 프로젝트 메인 폴더가 아니라 내부의 webroot까지 지정해야 함
     /Applications/ServBay/www/servbay-cakephp-app/webroot
     (servbay-cakephp-app은 실제 프로젝트 폴더명에 맞게 변경)

4. 저장 및 적용

   모든 항목 입력 후 우측 하단의 ‘저장’ 클릭. 설정 적용 안내가 나오면 ‘확인’ 선택. ServBay가 자동으로 Caddy 또는 Nginx 웹 서버를 재설정하여 입력한 도메인(servbay-cakephp-test.local)을 webroot 폴더로 연결시켜줍니다.

사이트 추가 세부 절차는 사이트 최초 추가 가이드를 참고하세요.

기본 환경 검증

이제 브라우저에서 방금 만든 도메인(https://servbay-cakephp-test.local)에 접속할 수 있습니다.

접속 시 CakePHP의 기본 환영 페이지가 보이면, PHP 환경과 웹 서버, ServBay 사이트 설정이 정상적으로 완료된 것입니다.

데이터베이스 및 캐시 서비스 통합

CakePHP는 강력한 ORM/캐시 추상화 계층을 제공하므로, ServBay의 DB/캐시 서비스와 손쉽게 연동할 수 있습니다.

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

아래는 CakePHP ORM을 활용해 ServBay의 MySQL 또는 PostgreSQL과 연결, users 테이블 생성 및 CRUD 연산을 수행하는 예제입니다.

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

   DB 마이그레이션에 앞서, ServBay DB 서버에 새 데이터베이스를 만듭니다. ServBay 내장 관리 툴(phpMyAdmin/MySQL용, pgAdmin/PostgreSQL용 또는 Navicat, DBeaver 등)을 이용해 127.0.0.1에서 root/password로 접속, servbay_cakephp_app 이름의 새 데이터베이스를 만드세요.

2. ORM Model 파일 생성

   CakePHP ORM은 데이터베이스 테이블을 모델 파일로 표현합니다. UsersTable.php 모델을 생성 후, src/Model/Table/UsersTable.php에 아래 코드 저장:

   <?php
   namespace App\Model\Table;
   
   use Cake\ORM\Table;
   use Cake\Validation\Validator; // 검증 규칙 필요 시
   
   class UsersTable extends Table
   {
       /**
        * Initialize method
        *
        * @param array $config The configuration for the Table.
        * @return void
        */
       public function initialize(array $config): void
       {
           parent::initialize($config);
   
           $this->setTable('users'); // 실제 테이블명 지정
           $this->setDisplayField('name'); // 기본 표시 필드
           $this->setPrimaryKey('id'); // PK 설정
   
           // 타임스탬프 동작 필요 시
           // $this->addBehavior('Timestamp');
       }
   
       /**
        * Default validation rules.
        *
        * @param \Cake\Validation\Validator $validator Validator instance.
        * @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 도구로 마이그레이션 파일 생성

   CakePHP는 DB 구조 관리를 위해 migration을 권장합니다. 프로젝트 루트(/Applications/ServBay/www/servbay-cakephp-app)에서 아래 명령 실행:

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

   위 명령으로 users 테이블 구조(이름, 이메일(고유값))가 담긴 마이그레이션 파일이 생성됩니다.

4. 데이터베이스 마이그레이션 실행

   생성한 users 테이블을 DB에 실제 반영:

   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',
             'password' => 'password',
             '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
   {
       /**
        * Displays a view
        *
        * @param array ...$path Path segments.
        * @return \Cake\Http\Response|null
        */
       public function display(...$path): ?Response
       {
           // 기본 display 메서드
           return new Response(['body' => 'Hello ServBay! This is the default page.']);
       }
   
       /**
        * 데이터베이스 예시: 사용자 추가
        */
       public function dbAddUser(): Response
       {
           $usersTable = TableRegistry::getTableLocator()->get('Users'); // Users Table 인스턴스
   
           // 새 사용자 엔티티 생성
           $user = $usersTable->newEntity([
               'name' => 'ServBay Demo User',
               'email' => '[email protected]' // ServBay 샘플 이메일 사용
           ]);
   
           // 저장 시도
           if ($usersTable->save($user)) {
               return new Response(['body' => 'User added successfully! User ID: ' . $user->id]);
           } else {
               // 저장 실패 시, 검증오류 등 상세 정보 반환
               $errors = $user->getErrors();
               return new Response(['body' => 'Failed to add user. Errors: ' . json_encode($errors)]);
           }
       }
   
       /**
        * 데이터베이스 예시: 사용자 목록 조회
        */
       public function dbListUsers(): Response
       {
           $usersTable = TableRegistry::getTableLocator()->get('Users');
   
           // 모든 사용자 조회
           $users = $usersTable->find()->all();
   
           // 결과를 JSON 인코딩해 출력
           return new Response(['body' => json_encode($users->toArray())]);
       }
   }

7. 데이터베이스 예제 라우트 실행

   브라우저에서

   • https://servbay-cakephp-test.local/db-add-user — 사용자 추가(성공 메시지 확인)
   • https://servbay-cakephp-test.local/db-list-users — DB의 사용자 리스트 확인(방금 추가한 사용자 확인)

이 과정을 통해 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'], // ServBay 기본 MEMCACHED
             'prefix' => 'servbay_cakephp_',
         ],
         // ... 추가 캐시 설정
     ],

   • Redis 예시:

     // config/app_local.php
     'Cache' => [
         'default' => [
             'className' => \Cake\Cache\Engine\RedisEngine::class,
             'host' => '127.0.0.1',
             'port' => 6379,
             'password' => null, // Redis 비밀번호 지정 시 입력
             'database' => 0,
             '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' 캐시를 Memcached로 설정 필요
   
           $cacheKey = 'servbay_memcached_test_key';
           $cachedData = Cache::read($cacheKey);
   
           $responseBody = '';
   
           if ($cachedData === false) {
               // 캐시 미스
               $responseBody = 'Cache miss! Writing "Hello Memcached!" to cache.';
               $dataToCache = 'Hello Memcached!';
               Cache::write($cacheKey, $dataToCache, 'default');
           } else {
               // 캐시 히트
               $responseBody = 'Cache hit! Data from cache: ' . $cachedData;
           }
   
           return new Response(['body' => $responseBody]);
       }
   
       /**
        * 캐시 예제: Redis 사용
        */
       public function cacheRedis(): Response
       {
           // app_local.php에서 'default' 캐시를 Redis로 설정 필요
   
           $cacheKey = 'servbay_redis_test_key';
           $cachedData = Cache::read($cacheKey);
   
           $responseBody = '';
   
           if ($cachedData === false) {
               // 캐시 미스
               $responseBody = 'Cache miss! Writing "Hello Redis!" to cache.';
               $dataToCache = 'Hello Redis!';
               Cache::write($cacheKey, $dataToCache, 'default');
           } else {
               // 캐시 히트
               $responseBody = 'Cache hit! Data from cache: ' . $cachedData;
           }
   
           return new Response(['body' => $responseBody]);
       }
   }

3. 캐시 예제 실행

   • Memcached 설정 시 https://servbay-cakephp-test.local/cache-memcached 접속 — 최초는 “Cache miss”, 새로고침 시 “Cache hit” 표시
   • Redis 설정 시 https://servbay-cakephp-test.local/cache-redis 접속 — 동일 동작

이로써 CakePHP 프로젝트가 ServBay 내 캐시 서비스와 정상 연동되는 것을 검증할 수 있습니다.

참고 사항

• DB 계정 정보: ServBay의 기본 DB(username/password:root/password)는 로컬 개발용입니다. 운영 환경에서는 반드시 강력한 비밀번호 사용을 권장합니다.
• 사이트 루트: ServBay에 등록하는 웹사이트의 ‘루트 경로’는 반드시 CakePHP 프로젝트 내 webroot 폴더로 지정해야 합니다. (최상위 디렉토리 아님)
• PHP 버전: ServBay에서 선택한 PHP 버전이 사용하려는 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: 데이터베이스 연결이 실패합니다.
  • A: ServBay에서 해당 DB 서비스(MySQL/PostgreSQL)가 실행 중인지 확인.
  • config/app_local.php 내 DB 연결 정보(host, port, username, password, database)가 정확히 맞는지 점검.
  • 실제 데이터베이스(servbay_cakephp_app)를 DB 서버에서 생성했는지 확인.
• Q: Composer 명령(bin/cake)이 실행되지 않습니다.
  • A: 작업 중인 터미널이 CakePHP 프로젝트 루트(/Applications/ServBay/www/servbay-cakephp-app)에 위치한지 확인.
  • ServBay에서 PHP 및 Composer 패키지가 실행 중인지 확인.
  • 터미널에서 php 명령 접근이 가능한지 확인(ServBay는 일반적으로 PHP PATH를 자동 설정합니다. 필요시 ServBay 터미널에서 실행 또는 PATH 직접 설정).

마무리

ServBay를 활용하면 macOS에서 CakePHP 프로젝트의 로컬 개발 환경을 쉽고 빠르게 구축할 수 있습니다. 사전 설정된 PHP, Composer, 웹 서버, 데이터베이스 등 지원 덕분에 번거로운 환경설정 없이 개발 본연에 집중할 수 있습니다. 본 문서는 프로젝트 생성, 기본 설정, 웹 서버 연동, 관계형 데이터베이스 및 캐시 서비스 통합까지 종합 안내합니다. ServBay의 강력한 통합 환경을 활용해, 환경 구축이 아닌 코딩 그 자체에 열중해보세요.