Symfony 2/3/4/5/6 使用 DoctrineFixturesBundle 實作資料庫預設資料（Fixtures）完整教學

為什麼需要 Fixtures？

專案開發、測試、部署階段常需預載基礎資料（如管理員帳號、角色權限、選單項目、測試商品）。DoctrineFixturesBundle 提供標準化、可版控、可重複執行的資料初始化機制，是 Symfony 專案的必備工具。

安裝與設定三步驟

1. Composer 安裝（開發環境專用）

composer require --dev doctrine/doctrine-fixtures-bundle

對應 Symfony 版本相容性：

• Symfony 6.x → ^3.4
• Symfony 5.x → ^3.3
• Symfony 4.x → ^3.0
• Symfony 3.x → ^2.4

2. 註冊 Bundle（僅限 dev/test 環境）

// config/bundles.php
return [
    // ...
    Doctrine\Bundle\FixturesBundle\DoctrineFixturesBundle::class => ['dev' => true, 'test' => true],
];

或傳統 AppKernel.php 寫法：

if (in_array($this->getEnvironment(), ['dev', 'test'])) {
    $bundles[] = new Doctrine\Bundle\FixturesBundle\DoctrineFixturesBundle();
}

3. 建立 Fixture 類別

預設路徑：src/DataFixtures/（SF4+）或 src/AppBundle/DataFixtures/ORM/（SF3）

passwordHasher = $passwordHasher;
    }

    public function load(ObjectManager $manager): void
    {
        // 1. 建立角色
        $roleAdmin = new Role();
        $roleAdmin->setName('ROLE_ADMIN');
        $manager->persist($roleAdmin);

        $roleUser = new Role();
        $roleUser->setName('ROLE_USER');
        $manager->persist($roleUser);

        // 2. 建立管理員帳號
        $admin = new User();
        $admin->setEmail('admin@example.com');
        $admin->setRoles(['ROLE_ADMIN']);
        $admin->setPassword($this->passwordHasher->hashPassword($admin, 'secure_password_123'));
        $manager->persist($admin);

        // 3. 批次建立測試資料
        for ($i = 1; $i <= 10; $i++) {
            $user = new User();
            $user->setEmail("user{$i}@example.com");
            $user->setRoles(['ROLE_USER']);
            $user->setPassword($this->passwordHasher->hashPassword($user, 'password'));
            $manager->persist($user);
        }

        $manager->flush();
    }
}

執行指令與常用參數

# 基本載入（會先清空相關資料表）
php bin/console doctrine:fixtures:load

# 保留現有資料，僅追加（⚠️ 可能導致主鍵衝突）
php bin/console doctrine:fixtures:load --append

# 指定特定 fixture 目錄
php bin/console doctrine:fixtures:load --fixtures=src/DataFixtures/Custom

# 指定 Entity Manager（多資料庫專案）
php bin/console doctrine:fixtures:load --em=custom_em

# 無互動模式（CI/CD 適用）
php bin/console doctrine:fixtures:load --no-interaction

進階技巧：依賴順序與資料關聯

實作 DependentFixtureInterface 控制載入順序

use Doctrine\Common\DataFixtures\DependentFixtureInterface;

class UserFixtures extends Fixture implements DependentFixtureInterface
{
    public function load(ObjectManager $manager): void
    {
        // 此時 RoleFixtures 已執行完成，可安全引用
        $adminRole = $manager->getRepository(Role::class)->findOneBy(['name' => 'ROLE_ADMIN']);
        // ...
    }

    public function getDependencies(): array
    {
        return [RoleFixtures::class];
    }
}

使用 Reference 共享物件實例

// 在同一個 Fixture 類別內
$manager->persist($admin);
$this->addReference('admin_user', $admin);  // 註冊參考

// 稍後取用
$user = new User();
$user->setCreatedBy($this->getReference('admin_user'));

跨 Fixture 類別共享參考

// UserFixtures.php
public function load(ObjectManager $manager): void
{
    $admin = new User();
    // ...
    $this->setReference('admin_user', $admin);  // 注意：使用 setReference
    $manager->persist($admin);
}

// ArticleFixtures.php (implements DependentFixtureInterface)
public function load(ObjectManager $manager): void
{
    $admin = $this->getReference('admin_user');  // 取得共享實例
    $article->setAuthor($admin);
}

測試環境專用 Fixtures

建立 tests/DataFixtures/ 目錄，配置 phpunit.xml.dist：

<phpunit>
    <extensions>
        <extension class="Doctrine\Bundle\FixturesBundle\Test\FixturesExtension"/>
    </extensions>
</phpunit>

測試類別中自動載入：

use Doctrine\Bundle\FixturesBundle\Test\FixturesTrait;

class UserTest extends KernelTestCase
{
    use FixturesTrait;

    public function testUserCreation(): void
    {
        $this->loadFixtures([AppFixtures::class]);
        // ...
    }
}

常見問題與解決方案

官方資源

• DoctrineFixturesBundle 官方文件
• GitHub 專案

總結

DoctrineFixturesBundle 讓資料庫初始化資料成為程式碼一部分，支援版本控管、團隊協作、CI/CD 自動化部署。善用依賴排序、Reference 共享、批次處理等技巧，可建構健全、可維護的資料初始化體系。