SymfonyのFormTypeでファイルアップロードフィールドを作る方法を完全解説！初心者でもわかる画像・ファイル送信入門

1. Symfonyのファイルアップロードとは？

1. Symfonyのファイルアップロードとは？

Symfonyのファイルアップロードとは、ユーザーが選んだ画像やPDFなどのファイルを、Web画面からサーバーに送信する仕組みです。普段の生活で例えると、書類を封筒に入れて郵便で送るようなものです。ここでいう封筒がフォーム、中身がファイルにあたります。

Symfonyでは、この封筒を作る役割をFormTypeが担当します。FormTypeを使うことで、入力チェックや安全対策もまとめて行えるのが特徴です。

2. FormTypeとは何をするもの？

2. FormTypeとは何をするもの？

FormTypeは、入力画面の設計図のような存在です。「ここには文字を入れる」「ここにはファイルを選ぶ」といったルールをあらかじめ決めておきます。初心者の方は、FormTypeを“申込用紙のひな形”だと思うと理解しやすいです。

Symfonyでファイルアップロードを行う場合、このFormTypeの中にファイル専用の入力欄を追加します。

3. ファイルアップロード用FormTypeの基本コード

3. ファイルアップロード用FormTypeの基本コード

まずは、Symfonyでファイルアップロードフィールドを持つFormTypeの基本例を見てみましょう。ここでは画像をアップロードする想定です。

namespace App\Form;

use Symfony\Component\Form\AbstractType;
use Symfony\Component\Form\FormBuilderInterface;
use Symfony\Component\Form\Extension\Core\Type\FileType;

class ImageUploadType extends AbstractType
{
    public function buildForm(FormBuilderInterface $builder, array $options)
    {
        $builder
            ->add('imageFile', FileType::class, [
                'label' => '画像を選択',
                'required' => true,
            ]);
    }
}

FileTypeは、ファイルを選択するための専用部品です。これを使うことで、ブラウザに「ファイルを選択」ボタンが表示されます。

4. コントローラーでFormTypeを使う流れ

4. コントローラーでFormTypeを使う流れ

次に、作成したFormTypeをコントローラーで使います。コントローラーは、フォームが送信された後の処理係です。例えるなら、郵便物を受け取って中身を確認する人です。

use App\Form\ImageUploadType;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;

public function upload(Request $request): Response
{
    $form = $this->createForm(ImageUploadType::class);
    $form->handleRequest($request);

    if ($form->isSubmitted() && $form->isValid()) {
        $data = $form->getData();
    }

    return $this->render('upload.html.twig', [
        'form' => $form->createView(),
    ]);
}

handleRequestは、フォームに入力された内容を読み取る命令です。ファイルもここで一緒に受け取られます。

5. Twigテンプレートでの表示方法

5. Twigテンプレートでの表示方法

次は画面側です。Twigテンプレートでは、FormTypeをそのまま表示できます。HTMLをたくさん書かなくてよいのがSymfonyの便利な点です。

{{ form_start(form, {'attr': {'enctype': 'multipart/form-data'}}) }}
    {{ form_row(form.imageFile) }}
    <button class="btn btn-primary">アップロード</button>
{{ form_end(form) }}

multipart/form-dataは、ファイルを送るための特別な設定です。これを忘れると、ファイルが送信されません。

6. アップロードされたファイルの正体を知ろう

6. アップロードされたファイルの正体を知ろう

Symfonyで受け取ったファイルは、UploadedFileという形になります。これは「一時的に預かっているファイル」です。机の上に一旦置いた書類のような状態で、まだ正式な保管場所には移動していません。

use Symfony\Component\HttpFoundation\File\UploadedFile;

$uploadedFile = $form->get('imageFile')->getData();

if ($uploadedFile instanceof UploadedFile) {
    $originalName = $uploadedFile->getClientOriginalName();
}

ここでは、元のファイル名を取得しています。初心者の方は「情報を取り出せるんだな」くらいの理解で大丈夫です。

7. よくあるエラーと初心者がつまずくポイント

7. よくあるエラーと初心者がつまずくポイント

Symfonyのファイルアップロードでよくある失敗は、「フォームは表示されるのにファイルが取得できない」ケースです。その原因の多くは、enctypeの指定忘れです。

また、FormTypeでrequiredをtrueにしていると、ファイルを選ばないとエラーになります。これは「必ず書類を入れてください」というルールを設定している状態です。

8. セキュリティ面で知っておきたい基本知識

8. セキュリティ面で知っておきたい基本知識

ファイルアップロードは便利ですが、安全面も重要です。SymfonyのFormTypeを使うことで、想定外のデータが送られにくくなります。初心者のうちは、「FormTypeを使う＝安全な入口を用意している」と覚えておくとよいでしょう。

特にSymfonyのファイルアップロード機能は、多くのWebサイトで使われており、実務でも頻出の知識です。