Symfony 프로젝트 생성 및 실행

ServBay는 macOS 전용으로 설계된 로컬 웹 개발 환경입니다. PHP, Node.js, Python, Go, Java 등 다양한 언어 런타임과 MySQL, PostgreSQL, MongoDB, Redis 등의 데이터베이스, 그리고 Apache·Caddy 웹 서버를 하나로 통합 제공하여, macOS에서 손쉽게 웹 프로젝트를 구축할 수 있도록 지원합니다. 본 가이드는 macOS에서 ServBay로 Symfony 프로젝트를 빠르게 생성하고 실행하는 단계별 방법을 안내합니다.

Symfony란 무엇인가요?

Symfony는 SensioLabs에서 개발한 오픈소스 PHP 웹 프레임워크입니다. 모던 웹 애플리케이션 및 API 구축을 위한 효율적이고 유연하며 강력한 도구 모음을 개발자에게 제공하는 것이 목적입니다. 업계 표준 웹 개발 관행을 따르며, 라우팅, 템플릿 엔진(Twig), 폼 처리, 인증, 의존성 주입 등 다양한 기능 컴포넌트를 통해 반복 작업을 크게 간소화합니다.

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가 잘 작동하는지 점검하세요.
bash
```
composer --version
```
1
프로젝트 디렉토리 생성
권장 루트 디렉토리에서 Symfony 프로젝트를 저장할 하위 폴더를 만듭니다.
bash
```
cd /Applications/ServBay/www
mkdir servbay-symfony-app
```
1
2
Composer로 Symfony 프로젝트 생성
생성한 폴더로 이동한 후, Composer를 이용해 Symfony의 website-skeleton 프로젝트 스캐폴딩을 작성합니다. 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 # 개발(Dev) 환경
APP_SECRET=your_secret_key # 임의의 고유 랜덤 문자열(보안용)

# 데이터베이스 연결 예시 (기본은 MySQL, 자세한 내용은 아래 참고)
# DATABASE_URL="mysql://db_user:[email protected]:3306/db_name?serverVersion=8.0&charset=utf8mb4"
# DATABASE_URL="postgresql://db_user:[email protected]: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 사용자 ID는 root, 비밀번호는 password입니다(실무 환경에서는 반드시 변경 요망). 본 가이드 예제에서는 servbay_symfony_app라는 DB명을 사용합니다.

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

브라우저에서 Symfony 프로젝트에 접근하려면, ServBay의 ‘사이트’ 기능으로 로컬 가상 호스트를 등록해야 합니다. Symfony의 정식 웹 루트는 프로젝트 내 public/ 폴더입니다.

ServBay 제어판을 열고 "사이트" (혹은 구버전의 경우 "호스트") 설정에서 사이트를 추가해 주세요:

이름(Name): 예) My Symfony Dev Site 등 알아보기 쉬운 별명을 정합니다.
도메인(Domain): 예) servbay-symfony-test.local과 같은 로컬 개발 도메인을 지정하면 됩니다. ServBay가 자동으로 로컬 호스트와 연결합니다.
사이트 유형(Website Type): PHP를 선택합니다.
PHP 버전(PHP Version): Symfony 프로젝트와 호환되는 최신 PHP(예: 8.3)를 선택하세요.
웹사이트 루트(Website Root): 가장 핵심인 설정입니다. Symfony는 반드시 /Applications/ServBay/www/servbay-symfony-app/public 경로로 지정해야 정상 작동합니다.

입력 후 저장·적용하면 ServBay가 웹 서버 구성을 자동 반영합니다. Caddy 혹은 Apache가 기본 웹서버이고, ServBay가 로컬 SSL 인증서를 자동 발급·신뢰 처리해 https:// 접속이 가능합니다.

자세한 단계별 설정은 ServBay 첫 사이트 추가하기 문서를 참고하세요.

기본 예제 코드 추가

사이트 설정이 정상인지 간편히 확인하려면, 루트 경로 라우팅 및 컨트롤러 예제를 추가해봅니다.

라우트 구성(config/routes.yaml)
config/routes.yaml 파일을 열고, 루트(/) 요청 시 호출할 컨트롤러 매핑을 아래와 같이 등록합니다:
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 메소드에 @Route("/")를 부여해 사이트 루트 경로에 해당 메소드가 실행되게 합니다. 접속 시 "Hello ServBay and Symfony!"라는 메시지가 출력됩니다.

웹사이트 접속 확인

웹 브라우저에서 ServBay에 등록한 도메인 https://servbay-symfony-test.local로 이동하세요. 정상일 경우 다음과 같은 결과가 보입니다.

Hello ServBay and Symfony!

정상 출력된다면 ServBay 웹 서버에서Symfony 프로젝트가 무사히 실행된 것입니다. 참고로 ServBay는 기본적으로 HTTPS(SSL)를 자동 구성하므로, 꼭 https://로 접근하세요.

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

Symfony는 주로 Doctrine ORM을 사용해 관계형 데이터베이스 작업을 하며, Symfony Cache 컴포넌트로 Redis·Memcached 등 캐시/NoSQL 연동을 지원합니다. ServBay에는 다양한 DB 및 대응 PHP 확장 라이브러리가 내장되어 있어, 프로젝트에서 바로 사용할 수 있습니다.

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

ServBay는 MySQL과 PostgreSQL을 모두 지원합니다. 아래는 두 데이터베이스를 Symfony에서 설정하고 사용하는 방법 예시입니다.

DB 연결 정보 설정
프로젝트 루트의 .env에서 사용하는 데이터베이스에 맞는 DATABASE_URL 부분의 주석을 해제하고, 환경에 맞게 수정하세요.
- MySQL의 경우 ServBay에서 기본 MySQL ID는 root, 비밀번호는 password, 포트는 3306입니다. 본인 설정에 따라 조정하세요.
  dotenv
```
# .env
DATABASE_URL="mysql://root:[email protected]:3306/servbay_symfony_app?serverVersion=8.0&charset=utf8mb4"
```
  1
  2
- PostgreSQL의 경우 기본 PostgreSQL ID는 root, 비밀번호는 password, 포트는 5432입니다.
  dotenv
```
# .env
DATABASE_URL="postgresql://root:[email protected]:5432/servbay_symfony_app?serverVersion=13&charset=utf8"
```
  1
  2
ServBay 제어판에서 해당 DB 서비스가 반드시 실행 중이어야 합니다.
데이터베이스 생성
servbay_symfony_app 데이터베이스가 없다면 ServBay에서 제공하는 phpMyAdmin, pgAdmin(제어판에서 접속 가능) 등으로 직접 DB를 생성하거나, Symfony 명령어로 만듭니다:
bash
```
php bin/console doctrine:database:create
```
1
Entity 및 마이그레이션 파일 생성
Doctrine Entity는 데이터베이스 테이블과 1:1로 매칭됩니다. Maker Bundle을 이용하면 Entity 및 DB 마이그레이션 파일 생성을 쉽게 할 수 있습니다.
- Entity 생성(예: User)
  bash
```
php bin/console make:entity User
```
  1
  프롬프트에 따라 필드(예: name(string), email(string, unique=yes) 등)를 추가하세요.
- 마이그레이션 파일 생성 Entity 변경 사항 반영용 마이그레이션 파일을 자동 생성합니다.
  bash
```
php bin/console make:migration
```
  1
  해당 SQL 작업 내용이 src/Migrations 폴더에 생성됩니다.
마이그레이션 적용
DB 구조를 실제 DB에 반영하려면 아래 명령을 실행합니다.
bash
```
php bin/console doctrine:migrations:migrate
```
1

DB 연동 예제 코드 추가

src/Controller/DefaultController.php를 수정해 Doctrine으로 DB 데이터 추가/조회하는 메소드를 추가합니다. 데이터베이스 연동에는 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 불러오기
use App\Entity\User; // User Entity 불러오기
use Symfony\Component\HttpFoundation\JsonResponse; // JSON 반환용

class DefaultController
{
    private $entityManager;

    // 의존성 주입으로 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
    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; // 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('[email protected]');

        // 엔티티 객체를 영속화
        $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(),
            ];
        }

        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 사용 시 ServBay의 기본 Memcached 포트는 11211입니다.
  dotenv
```
# .env
# ... 기타 설정 ...
CACHE_DSN=memcached://127.0.0.1:11211
```
  1
  2
  3
  ServBay 제어판에서 Memcached가 실행 중인지 반드시 확인하세요.
- Redis 사용 시 기본 Redis 포트는 6379입니다.
  dotenv
```
# .env
# ... 기타 설정 ...
CACHE_DSN=redis://127.0.0.1:6379
# Redis에 비밀번호가 있다면(기본 없음) 아래 형식 사용:
# CACHE_DSN=redis://:[email protected]:6379
```
  1
  2
  3
  4
  5
  역시 ServBay에서 Redis 서비스가 실행 중이어야 합니다.

Cache 사용 예제 코드 추가

src/Controller/DefaultController.php를 수정하여, Cache 컴포넌트를 활용한 예제 메소드를 추가합니다. 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 추가

class DefaultController
{
    private $entityManager;
    private $cache; // cache 속성 추가

    // CacheInterface 의존성 주입
    public function __construct(EntityManagerInterface $entityManager, CacheInterface $cache)
    {
        $this->entityManager = $entityManager;
        $this->cache = $cache; // 할당
    }

    // ... 기존 메소드 ...
}

그리고 config/routes.yaml에 다음 라우팅을 추가합니다:

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 추가

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-symfony-test.local) 및 웹 루트(/Applications/ServBay/www/servbay-symfony-app/public)가 정확한지 확인
Symfony 프로젝트의 로그(var/log/dev.log)에서 에러의 상세 원인 확인
프로젝트 루트에서 composer install 커맨드 실행
사용 중인 PHP 버전이 Symfony 프로젝트와 호환되는지 확인

Q: 데이터베이스 연결이 안되는 경우?

A: 다음을 확인하세요.

ServBay 제어판에서 해당 DB(MySQL, PostgreSQL)가 실행 중인지 점검
.env 파일의 DATABASE_URL 정보(사용자명, 비밀번호, 호스트 및 포트, DB명)가 정확한지 확인
DB 사용자 및 암호가 ServBay 기본(혹은 본인이 변경한 값)과 일치하는지 확인
연결할 DB(servbay_symfony_app)가 실제로 존재하는지 점검

Q: php bin/console 명령이 동작하지 않을 시 대처법?

A: 터미널의 현재 디렉토리가 /Applications/ServBay/www/servbay-symfony-app인지 확인하고, ServBay에서 제공하는 PHP가 시스템 PATH에 추가되어야 합니다(대부분 ServBay 설치 시 자동 처리됨). which php로 ServBay PHP가 사용 중인지 점검하세요.

마무리

이 가이드를 통해 ServBay를 이용해 macOS 환경에서 Symfony 프로젝트를 생성, 설정, 실행하는 기본적인 방법을 익혔습니다. ServBay는 Symfony 개발에 요구되는 필수 도구(PHP, Composer, 웹서버, DB, 캐시 등)를 일괄 제공하며, 복잡한 환경 셋업을 크게 간소화합니다. 앞으로 이 기반 프로젝트를 바탕으로 Symfony의 다양한 고급 기능을 익히거나, ServBay가 제공하는 타 소프트웨어 및 서비스를 활용해 자유롭게 개발 경험을 확장해 보세요.

Symfony 프로젝트 생성 및 실행 ​

Symfony란 무엇인가요? ​

Symfony의 주요 특징 및 장점 ​

ServBay로 Symfony 프로젝트 생성 및 실행 ​

준비 사항 ​

Symfony 프로젝트 만들기 ​

초기 환경설정 ​

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

기본 예제 코드 추가 ​

웹사이트 접속 확인 ​

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

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

캐시 및 NoSQL 예제(Symfony Cache) ​

자주 묻는 질문(FAQ) ​

마무리 ​