Symfony 프로젝트 생성 및 실행 가이드

ServBay는 macOS와 Windows에서 사용할 수 있는 전문 로컬 웹 개발 환경입니다. PHP, Node.js, Python, Go, Java 등 다양한 런타임과 MySQL, PostgreSQL, MongoDB, Redis 등 여러 데이터베이스를 내장하고 있으며, Apache와 Caddy 웹 서버도 지원합니다. 이 문서에서는 ServBay를 활용해 macOS와 Windows 환경에서 Symfony 프로젝트를 쉽고 빠르게 구축하고 실행하는 전 과정을 안내합니다.

Symfony란 무엇인가요?

Symfony는 SensioLabs에서 개발한 오픈소스 PHP 웹 프레임워크로, 현대적인 웹 애플리케이션 및 API 개발을 위한 효율적이고 강력한 툴셋을 제공합니다. 표준 웹 개발 베스트 프랙티스를 따르며, 라우팅, 템플릿 엔진(Twig), 폼 처리, 인증, DI 등 풍부한 기능 컴포넌트를 포함하고 있어 웹 개발의 반복 작업을 크게 줄여줍니다.

Symfony의 주요 특징과 장점

모듈화 설계: Symfony의 핵심은 재활용 가능한 컴포넌트 라이브러리로, 개발자는 필요에 따라 컴포넌트를 선택적으로 활용할 수 있어 경량부터 대형 프로젝트까지 폭넓게 적용 가능합니다.
높은 성능: 최적화된 아키텍처와 효과적인 캐시 처리, 그리고 최신 PHP 기능 지원을 통해 탁월한 성능을 제공합니다.
강력한 커뮤니티 지원: 대규모 개발자 커뮤니티, 풍부한 타사 번들(플러그인) 및 방대한 문서로 인해 문제 해결이 쉽습니다.
유연성: 다양한 서드파티 라이브러리와 확장 기능의 통합이 쉬워, 다양한 규모와 복잡도를 가진 프로젝트에 적합합니다.
안정성과 유지보수성: 올바른 코딩 규칙 및 디자인 패턴을 적용하여 테스트, 유지보수, 확장이 용이합니다.

Symfony는 소규모 API부터 대형 엔터프라이즈 시스템까지 모든 웹 프로젝트에 적합합니다.

ServBay로 Symfony 프로젝트 시작하기

ServBay는 Symfony 프로젝트 실행에 필요한 모든 구성 요소(적합한 PHP 버전, Composer, 웹 서버, 데이터베이스 및 캐시 서비스)를 통합 제공합니다. 이 섹션에서는 ServBay를 이용해 새 Symfony 프로젝트를 만들고 설정하는 방법을 단계별로 안내합니다.

준비사항

시작하기 전, 아래 사전 준비가 완료되어야 합니다:

ServBay 설치: macOS에 ServBay를 설치하고 실행 중이어야 합니다. 설치가 안 되어 있다면 ServBay 설치 가이드를 참고하세요.
ServBay 정상 동작: Caddy 또는 Apache, 사용 예정인 데이터베이스 등 ServBay의 핵심 서비스가 정상적으로 실행 중이어야 합니다.
기초 이해 필요: PHP, Composer 및 Symfony에 대한 기본적인 지식이 있으면 도움이 됩니다.

Symfony 프로젝트 생성

ServBay에서는 웹사이트 프로젝트를 /Applications/ServBay/www 디렉터리에 통합 관리할 것을 권장합니다. 이렇게 하면 ServBay가 프로젝트를 쉽게 감지하고 관리할 수 있습니다.

Composer 확인
ServBay는 Composer를 이미 내장하고 환경 변수까지 자동 설정하므로 별도 설치가 불필요합니다. 터미널에서 composer --version을 입력해 Composer가 정상적으로 사용 가능함을 확인하세요.
프로젝트 디렉터리 생성
추천 루트 디렉터리에서 새로운 Symfony 프로젝트 폴더를 만드세요:
bash
```
cd /Applications/ServBay/www
mkdir servbay-symfony-app
```
1
2
Composer로 Symfony 프로젝트 생성
새로 만든 디렉터리로 이동 후 Composer를 사용해 website-skeleton을 기반으로 Symfony 프로젝트를 만듭니다. website-skeleton은 일반적인 웹 애플리케이션에 필요한 의존성을 포함한 기본 본체입니다.
bash
```
cd /Applications/ServBay/www/servbay-symfony-app
composer create-project symfony/website-skeleton .
```
1
2
명령이 완료되면, Symfony의 핵심 파일 및 의존성이 해당 폴더로 다운로드 및 구성됩니다.

초기 설정

Symfony 프로젝트의 핵심 설정은 환경 변수로 관리하며, 일반적으로 프로젝트 루트의 .env 파일에 저장합니다.

환경 변수 설정 (.env)
프로젝트 루트의 .env 파일을 엽니다. 애플리케이션 환경, 데이터베이스 연결 정보, 보안 키 등 주요 환경값을 저장합니다. 필요에 따라 내용을 수정, 추가하세요.
아래와 같이 ServBay 환경에 맞게 수정이 필요합니다:
dotenv
```
# .env 예시
APP_ENV=dev # 개발 환경
APP_SECRET=your_secret_key # 시스템 보안을 위한 랜덤 고유 문자열로 대체

# 데이터베이스 연결 예시 (기본은 MySQL이며 추후 상세 설명)
# DATABASE_URL="mysql://db_user:db_password@127.0.0.1:3306/db_name?serverVersion=8.0&charset=utf8mb4"
# DATABASE_URL="postgresql://db_user:db_password@127.0.0.1:5432/db_name?serverVersion=13&charset=utf8"
# DATABASE_URL="sqlite:///%kernel.project_dir%/var/data.db"
```
1
2
3
4
5
6
7
8
your_secret_key는 안전한 랜덤 문자열로 바꿉니다. ServBay의 기본 DB 아이디는 root, 비밀번호는 password입니다(실제 운영환경에서는 반드시 변경하세요). 예시에서는 servbay_symfony_app라는 데이터베이스명을 사용합니다.

웹 서버(ServBay 웹사이트) 설정

Symfony 프로젝트를 브라우저로 접속하려면 ServBay의 "웹사이트" 기능을 활용해 로컬 가상 호스트를 생성해야 합니다. Symfony의 웹 루트 디렉터리는 프로젝트의 public/ 폴더입니다.

ServBay 컨트롤 패널에서 "웹사이트" 메뉴(구버전은 “호스트”) ‣ 새 웹사이트 추가:

이름(Name): 예시로 My Symfony Dev Site처럼 구분하기 쉬운 이름 지정
도메인(Domain): servbay-symfony-test.local 등 로컬 개발용 도메인 설정 (ServBay가 자동으로 로컬 도메인 처리)
웹사이트 유형(Website Type): PHP 선택
PHP 버전(PHP Version): 프로젝트에 맞는 최신 PHP 버전(예시: 8.3) 선택
웹사이트 루트(Website Root): 반드시 프로젝트의 public/으로 지정(/Applications/ServBay/www/servbay-symfony-app/public)

설정 후 저장 및 적용하면, ServBay가 웹 서버 구성을 자동 갱신합니다. ServBay는 기본적으로 Caddy 또는 Apache 서버를 사용하며, 로컬 도메인에 대해 자동으로 SSL 인증서를 발급 및 신뢰 처리하여 바로 HTTPS로 접속 가능합니다.

자세한 단계는 ServBay 첫 웹사이트 추가하기에서 확인하세요.

샘플 코드 추가

웹사이트 설정 검증을 위해 간단한 라우트 및 컨트롤러를 추가하여, 루트 경로 접근시 텍스트가 출력되도록 해보겠습니다.

라우트 설정 (config/routes.yaml)
config/routes.yaml 파일에 루트 / 경로 라우트를 정의하고, index 컨트롤러 메서드로 연결:
yaml
```
# config/routes.yaml
index:
    path: /
    controller: App\Controller\DefaultController::index
```
1
2
3
4

컨트롤러 생성 (src/Controller/DefaultController.php)

src/Controller/ 경로에 DefaultController.php 파일 생성 후 아래 코드 추가:

php

<?php
// src/Controller/DefaultController.php
namespace App\Controller;

use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Annotation\Route;

class DefaultController
{
    /**
     * @Route("/", name="index")
     */
    public function index(): Response
    {
        // 간단한 HTTP 응답 반환
        return new Response('Hello ServBay and Symfony!');
    }
}

위 코드는 기본 컨트롤러 클래스 DefaultController의 index 메서드를 루트 경로(/)와 연결하며, 접속 시 "Hello ServBay and Symfony!"라는 텍스트가 출력됩니다.

사이트 접속 테스트

웹 브라우저에서 ServBay에 설정한 도메인(예시: https://servbay-symfony-test.local)을 입력하세요. 정상적으로 설정됐다면 다음과 같은 화면을 볼 수 있습니다:

Hello ServBay and Symfony!

즉, ServBay 웹 서버를 통해 Symfony 프로젝트가 성공적으로 동작하는 것입니다. ServBay는 자동으로 HTTPS 인증을 처리하므로, https:// 접속을 권장합니다.

데이터베이스 및 캐시 사용 예시

Symfony는 데이터베이스 처리에 Doctrine ORM, 캐시 및 NoSQL 처리에 Symfony Cache 컴포넌트를 주로 사용합니다. ServBay는 관련 데이터베이스 서비스와 PHP 확장을 제공하므로, Symfony 프로젝트에서 바로 이용할 수 있습니다.

관계형 데이터베이스 예시 (Doctrine ORM)

ServBay는 MySQL과 PostgreSQL을 지원합니다. 각각의 설정과 사용법을 예시로 안내합니다.

데이터베이스 연결 설정
.env 파일에서 사용하는 데이터베이스에 따라 주석을 해제하고 적절히 수정하세요.
- MySQL 예시: ServBay의 MySQL 기본 아이디는 root, 비밀번호는 password, 포트는 3306입니다(환경에 따라 조정).
  dotenv
```
# .env
DATABASE_URL="mysql://root:password@127.0.0.1:3306/servbay_symfony_app?serverVersion=8.0&charset=utf8mb4"
```
  1
  2
- PostgreSQL 예시: 기본 아이디는 root, 비밀번호 password, 포트는 5432입니다.
  dotenv
```
# .env
DATABASE_URL="postgresql://root:password@127.0.0.1:5432/servbay_symfony_app?serverVersion=13&charset=utf8"
```
  1
  2
ServBay 컨트롤 패널에서 해당 DB 서비스(MySQL 또는 PostgreSQL) 구동을 반드시 확인하세요.
데이터베이스 생성
데이터베이스(servbay_symfony_app)가 없으면, ServBay에서 제공하는 phpMyAdmin 또는 pgAdmin(컨트롤 패널에서 바로 접속 가능)으로 직접 생성하거나, 아래 Symfony 명령으로 만들 수 있습니다:
bash
```
php bin/console doctrine:database:create
```
1
엔티티(Entity) 및 마이그레이션 생성
Doctrine Entity는 데이터베이스 테이블에 해당합니다. Maker Bundle로 엔티티 및 마이그레이션을 손쉽게 만들 수 있습니다.
- 엔티티 생성 (예: User 엔티티):
  bash
```
php bin/console make:entity User
```
  1
  예를 들어 name(string), email(string, unique=yes) 필드를 추가할 수 있습니다.
- 마이그레이션 파일 생성:
  bash
```
php bin/console make:migration
```
  1
  src/Migrations 폴더에 테이블 생성 SQL이 담긴 마이그레이션 파일이 생깁니다.
마이그레이션 실행
아래 명령으로 마이그레이션을 적용해 DB 구조를 실제로 생성합니다:
bash
```
php bin/console doctrine:migrations:migrate
```
1

데이터베이스 조작 샘플 추가

src/Controller/DefaultController.php에 샘플 라우트 및 메서드를 추가해 Doctrine을 통한 데이터 기록 및 조회를 보여줍니다. EntityManagerInterface 주입이 필요합니다.

우선 컨트롤러 생성자에서 EntityManagerInterface를 주입하세요:

php

<?php
// src/Controller/DefaultController.php
namespace App\Controller;

use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Annotation\Route;
use Doctrine\ORM\EntityManagerInterface; // EntityManagerInterface import
use App\Entity\User; // User 엔티티 import
use Symfony\Component\HttpFoundation\JsonResponse; // JSON 응답 반환용

class DefaultController
{
    private $entityManager;

    // DI로 EntityManagerInterface 인스턴스 받기
    public function __construct(EntityManagerInterface $entityManager)
    {
        $this->entityManager = $entityManager;
    }

    /**
     * @Route("/", name="app_index")
     */
    public function index(): Response
    {
        return new Response('Hello ServBay and Symfony!');
    }

    // ... 기타 메서드 ...
}

그리고 새로운 라우트를 config/routes.yaml에 추가하세요:

yaml

# config/routes.yaml
# ... 기타 라우트 ...
mysql_add_user:
    path: /mysql-add-user # 또는 /pgsql-add-user (사용하는 DB에 따라)
    controller: App\Controller\DefaultController::addUser
mysql_get_users:
    path: /mysql-users # 또는 /pgsql-users
    controller: App\Controller\DefaultController::getUsers

컨트롤러 파일에 추가 메서드 구현:

php

<?php
// src/Controller/DefaultController.php
namespace App\Controller;

use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Annotation\Route;
use Doctrine\ORM\EntityManagerInterface;
use App\Entity\User;
use Symfony\Component\HttpFoundation\JsonResponse;

class DefaultController
{
    private $entityManager;

    public function __construct(EntityManagerInterface $entityManager)
    {
        $this->entityManager = $entityManager;
    }

    /**
     * @Route("/", name="app_index")
     */
    public function index(): Response
    {
        return new Response('Hello ServBay and Symfony!');
    }

    /**
     * @Route("/add-user", name="app_add_user")
     */
    public function addUser(): Response
    {
        $user = new User();
        // ServBay 브랜드를 활용한 데모 데이터
        $user->setName('ServBay Demo User');
        $user->setEmail('demo-user@servbay.test');

        // 객체 저장 준비
        $this->entityManager->persist($user);
        // DB에 실제 저장
        $this->entityManager->flush();

        return new Response('User added successfully!');
    }

    /**
     * @Route("/get-users", name="app_get_users")
     */
    public function getUsers(): JsonResponse
    {
        // DB에서 모든 User 엔티티 가져오기
        $users = $this->entityManager->getRepository(User::class)->findAll();

        // 배열로 변환해 JsonResponse에 넘김
        $usersArray = [];
        foreach ($users as $user) {
            $usersArray[] = [
                'id' => $user->getId(),
                'name' => $user->getName(),
                'email' => $user->getEmail(),
            ];
        }

        // JSON 응답 반환
        return new JsonResponse($usersArray);
    }
}

샘플 접속 테스트
- https://servbay-symfony-test.local/add-user로 접근하면 유저 추가됨.
- https://servbay-symfony-test.local/get-users로 접근하면 등록된 유저 목록(JSON 형식)을 조회할 수 있습니다.

캐시 및 NoSQL 데이터베이스 예시 (Symfony Cache)

ServBay는 Redis 및 Memcached 서비스와 관련 PHP 확장을 기본 제공하며, Symfony Cache 컴포넌트를 활용해 바로 사용할 수 있습니다.

캐시 연결 설정
.env 파일에 캐시 서버 연결 값을 설정하세요.
- Memcached 사용 시: 기본 포트는 11211입니다.
  dotenv
```
# .env
# ... 기타 환경값 ...
CACHE_DSN=memcached://127.0.0.1:11211
```
  1
  2
  3
  ServBay 패널에서 Memcached 서비스가 반드시 실행 중인지 확인하세요.
- Redis 사용 시: 기본 포트는 6379입니다.
  dotenv
```
# .env
# ... 기타 환경값 ...
CACHE_DSN=redis://127.0.0.1:6379
# 비밀번호 필요 시(ServBay 기본 무비밀번호):
# CACHE_DSN=redis://:your_password@127.0.0.1:6379
```
  1
  2
  3
  4
  5
  Redis 서비스 활성화도 확인하세요.

캐시 활용 예시 코드 추가

src/Controller/DefaultController.php에서 Symfony Cache 컴포넌트를 활용해 Memcached 또는 Redis와 연동하는 방법을 보여줍니다. CacheInterface 주입이 필요합니다.

컨트롤러 생성자에서 CacheInterface를 주입하세요:

php

<?php
// src/Controller/DefaultController.php
namespace App\Controller;

use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Annotation\Route;
use Doctrine\ORM\EntityManagerInterface;
use App\Entity\User;
use Symfony\Component\HttpFoundation\JsonResponse;
use Symfony\Contracts\Cache\CacheInterface; // CacheInterface import

class DefaultController
{
    private $entityManager;
    private $cache; // 캐시 객체 프로퍼티 추가

    // 생성자에서 캐시 객체 받기
    public function __construct(EntityManagerInterface $entityManager, CacheInterface $cache)
    {
        $this->entityManager = $entityManager;
        $this->cache = $cache;
    }

    // ... 기타 메서드 ...
}

라우트 파일에 새 라우트 추가:

yaml

# config/routes.yaml
# ... 기타 라우트 ...
cache_example:
    path: /cache-example
    controller: App\Controller\DefaultController::cacheExample

캐시 샘플 메서드 구현:

php

<?php
// src/Controller/DefaultController.php
namespace App\Controller;

use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Annotation\Route;
use Doctrine\ORM\EntityManagerInterface;
use App\Entity\User;
use Symfony\Component\HttpFoundation\JsonResponse;
use Symfony\Contracts\Cache\CacheInterface;
use Symfony\Component\Cache\Item\ItemInterface; // ItemInterface import

class DefaultController
{
    private $entityManager;
    private $cache;

    public function __construct(EntityManagerInterface $entityManager, CacheInterface $cache)
    {
        $this->entityManager = $entityManager;
        $this->cache = $cache;
    }

    // ... 기타 메서드 ...

    /**
     * @Route("/cache-example", name="app_cache_example")
     */
    public function cacheExample(): Response
    {
        // 캐시에서 데이터 조회
        $cacheItem = $this->cache->get('my_symfony_cache_key', function (ItemInterface $item) {
            // 캐시 미존재시 실행
            $item->expiresAfter(3600); // 1시간 유효

            // 예시: 복잡한 DB 조회 대신 현재 시간 반환
            $data = "Data generated at " . date('Y-m-d H:i:s');

            return $data;
        });

        // $cacheItem: 캐싱된 데이터 혹은 새로 생성된 데이터
        $output = "From Cache: " . $cacheItem;

        return new Response($output);
    }
}

샘플 실행 테스트
- https://servbay-symfony-test.local/cache-example로 첫 접근시 데이터가 생성 및 캐싱되고, 이후엔 캐시에서 바로 읽어옵니다.(Memcached 또는 Redis 활용)

자주 묻는 질문 (FAQ)

Q: https://servbay-symfony-test.local 접속시 페이지 없음/500 오류 발생 시?

A: 아래를 차례로 확인하세요:

ServBay가 실행 중인지, 웹사이트 서비스(Caddy 또는 Apache)가 가동 중인지 체크
ServBay 웹사이트의 도메인(servbay-symfony-test.local)설정 및 "웹사이트 루트"가 /Applications/ServBay/www/servbay-symfony-app/public로 정확히 지정되었는지 확인
Symfony 로그(var/log/dev.log)에서 상세 오류 확인
프로젝트 루트에서 composer install 실행으로 모든 의존성 설치 확인
PHP 버전이 프로젝트와 호환되는지 체크

Q: 데이터베이스 연결이 되지 않을 때?

A: 아래 항목을 점검하세요:

ServBay 컨트롤 패널에서 해당 데이터베이스(MySQL/PostgreSQL) 서비스가 켜져있는지
.env의 DATABASE_URL이 올바른지(아이디, 비번, 호스트, 포트, DB명)
사용자 아이디/비밀번호가 ServBay 기본값 혹은 본인이 수정한 값과 일치하는지
연결하려는 데이터베이스(servbay_symfony_app)가 실제로 존재하는지

Q: php bin/console 명령이 작동하지 않을 때?

A: 터미널의 현재 경로가 /Applications/ServBay/www/servbay-symfony-app고, ServBay의 PHP가 시스템 PATH에 포함되어 있는지 확인(설치 시 기본적으로 자동 설정됨). which php로 실제 적용중인 PHP 경로를 확인하세요.

마무리

이 가이드를 따라 macOS 환경에서 ServBay로 Symfony 기초 프로젝트를 생성, 구성, 실행하는 전 단계가 완료되었습니다. ServBay는 PHP, Composer, 웹 서버, 데이터베이스, 캐시 등 Symfony 개발에 필요한 모든 핵심 요소를 한 번에 제공하며, 복잡한 환경 설정 과정도 단순화하여 신속한 개발에 도움을 줍니다. 이제 해당 기초 프로젝트를 바탕으로 추가적인 Symfony 학습 및 ServBay가 제공하는 다양한 소프트웨어와 서비스를 활용해 보시기 바랍니다.

Symfony 프로젝트 생성 및 실행 가이드 ​

Symfony란 무엇인가요? ​

Symfony의 주요 특징과 장점 ​

ServBay로 Symfony 프로젝트 시작하기 ​

준비사항 ​

Symfony 프로젝트 생성 ​

초기 설정 ​

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

샘플 코드 추가 ​

사이트 접속 테스트 ​

데이터베이스 및 캐시 사용 예시 ​

관계형 데이터베이스 예시 (Doctrine ORM) ​

캐시 및 NoSQL 데이터베이스 예시 (Symfony Cache) ​

자주 묻는 질문 (FAQ) ​

마무리 ​