File Upload trong Laravel - [Phần 1] Tạo form, xử lý file, lưu trữ file

Chào mừng bạn đến với series hướng dẫn File Upload trong Laravel trên blog thuanbui.me!

Đây là một chuỗi bài viết nhằm tổng kết lại những kiến thức mình vừa học được từ khóa học Laravel File Uploads của Laravel Daily. Mục đích vừa để giúp mình ôn lại kiến thức thêm 1 lần nữa, vừa để dành lưu trữ để sau này có thể quay lại tra cứu khi cần. Hy vọng sẽ hữu ích được cho các bạn mới làm quen với Laravel như mình.

Bài viết đầu tiên này sẽ bao gồm các nội dung chính sau:

Yêu cầu trước khi bắt đầu

Để theo dõi và thực hành theo series này, bạn cần có:

Kiến thức cơ bản về Laravel: Biết cách tạo project mới, chạy migration, route, controller, v.v.
Môi trường phát triển Laravel đã cài đặt sẵn

Trong series này, mình thiết lập Laravel trên macOS, sử dụng Laravel Herd.

Nếu bạn dùng macOS và chưa cài Herd, có thể xem hướng dẫn tại đây:

https://thuanbui.me/cai-dat-laravel-tren-macos-voi-herd/

Nếu bạn sử dụng Windows, tham khảo hướng dẫn cài đặt Laravel với Docker + WSL 2 + Laravel Sail

https://thuanbui.me/cai-dat-laravel-tren-windows-11-voi-wsl2-docker-desktop-laravel-sail/

I. Tạo form upload file

Trước tiên tạo dự án Laravel 12 mới để sử dụng cho việc học File Upload trong Laravel

1
laravel new upload

Mở file web.php, tạo Route mới cho việc upload file

1
Route::get('/upload', [UploadController::class, 'index'])->name('upload.index');
2
Route::post('/upload', [UploadController::class, 'store'])->name('upload.store');

Tạo giao diện form upload resources/views/upload.blade.php

1
<!DOCTYPE html>
2
<html lang="en">
3
<head>
4
    <meta charset="UTF-8">
5
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
6
    <title>Upload File</title>
7
    <script src="https://cdn.tailwindcss.com"></script>
8
</head>
9
<body class="bg-gray-100 font-sans antialiased">
10
    <div class="container mx-auto mt-10 p-6 bg-white rounded-lg shadow-md max-w-md">
11
        <h1 class="text-2xl font-bold mb-6 text-center text-gray-700">Upload File</h1>
12
        <form action="{{ route("upload.store") }}" method="POST" enctype="multipart/form-data" class="space-y-4">
13
            @csrf
14
            <div>
15
                <label for="file" class="block text-sm font-medium text-gray-700 mb-1">Choose file</label>
16
                <input type="file" name="file" id="file"
17
                       class="block w-full text-sm text-gray-500
18
                              file:mr-4 file:py-2 file:px-4
19
                              file:rounded-full file:border-0
20
                              file:text-sm file:font-semibold
21
                              file:bg-blue-50 file:text-blue-700
22
                              hover:file:bg-blue-100"/>
23
            </div>
24
            <button type="submit"
25
                    class="w-full bg-blue-500 hover:bg-blue-700 text-white font-bold py-2 px-4 rounded focus:outline-none focus:shadow-outline">
26
                Upload
27
            </button>
28
        </form>
29
    </div>
30
</body>
31
</html>

Chú ý: Bắt buộc phải thêm enctype="multipart/form-data" vào phần thông số của <form>, nếu thiếu thì sẽ không upload được file.

II. Xử lý file upload

Tạo UploadController

1
php artisan make:controller UploadController

Tạo function index() và store() trong file UploadController.php

1
<?php
2

3
namespace App\Http\Controllers;
4

5
use Illuminate\Http\Request;
6

7
class UploadController extends Controller
8
{
9
    /**
10
     * Hiển thị trang upload file.
11
     *
12
     * @return \Illuminate\View\View
13
     */
14
    public function index()
15
    {
16
        return view('upload');
17
    }
18

19
    /**
20
     * Xử lý việc upload file.
21
     *
22
     * @param  \Illuminate\Http\Request  $request
23
     * @return \Illuminate\Http\RedirectResponse
24
     */
25
    public function store(Request $request)
26
    {
27

28
        // Tạo biến mới để lưu đường dẫn và tên file gốc
29
        $storedFilePath = null;
30
        $originalFilename = null;
31

32
        // Kiểm tra xem request có chứa file với tên là 'file' không
33
        if ($request->hasFile('file')) {
34
            // Lấy đối tượng file từ request
35
            $file = $request->file('file');
36

37
            // Lấy tên file gốc từ client
38
            $originalFilename = $file->getClientOriginalName();
39

40
            // Lưu file vào thư mục 'uploads' trên disk 'public' (thường là storage/app/public/uploads)
41
            // Laravel sẽ tự động tạo tên file ngẫu nhiên khi lưu
42
            // Phương thức store() trả về đường dẫn tương đối của file đã lưu (ví dụ: 'uploads/ten_file_duy_nhat.jpg')
43
            $storedFilePath = $file->store('uploads', 'public');
44

45
            return "File uploaded to: " . $storedFilePath;
46
        }
47

48
        return "No file uploaded.";
49
    }
50
}

III. Lưu file vào local disk public

1. Sử dụng hàm store

Dòng 43: $file->store('uploads', 'public') sẽ lưu file vào thư mục uploads nằm trong disk public. Disk public này được khai báo trong file cấu hình config/filesystems.php

1
      'public' => [
2
            'driver' => 'local',
3
            'root' => storage_path('app/public'),
4
            'url' => env('APP_URL').'/storage',
5
            'visibility' => 'public',
6
            'throw' => false,
7
            'report' => false,
8
        ],

File sau khi upload sẽ được lưu trong thư mục storage/app/public/uploads, tên file sẽ được Laravel thay đổi thành tên ngẫu nhiên sau khi upload.

Thử nghiệm thử: truy cập http://upload.test, và upload file, Laravel sẽ lưu vào thư mục uploads và đổi tên file thành tên ngẫu nhiên.

1
File uploaded to: uploads/xxxxxxxxxxxx.png

2. Sử dụng hàm storeAs

Trong trường hợp muốn giữ lại tên file gốc khi upload, mình sẽ chuyển qua sử dụng hàm storeAs thay vì store. Đổi dòng 43 thành

1
            // Lưu file vào thư mục 'uploads' trên disk 'public' (thường là storage/app/public/uploads)
2
            // sử dụng tên file gốc ($originalFilename).
3
            // Lưu ý: Nếu file cùng tên đã tồn tại, nó sẽ bị ghi đè.
4
            // Phương thức storeAs() trả về đường dẫn tương đối của file đã lưu (ví dụ: 'uploads/ten_file_goc.jpg')
5
            $storedFilePath = $file->storeAs('uploads', $originalFilename, 'public');

Hàm storeAs sẽ yêu cầu 3 tham số: thư mục upload (uploads), tên file ($originalFilename), và disk (public).

Tuy nhiên với code hiện tại, khi upload file có cùng tên thì file mới sẽ ghi đè lên file cũ. Do đó cần phải cập nhật lại code để tùy biến lại tên file khi upload, tránh tình trạng ghi đè file

3. Tránh ghi đè file cũ khi các file trùng tên nhau

Cập nhật lại hàm store của UploadController, để các file trùng tên sẽ tự động được thêm hậu tố -1 , -2 ở cuối tên file, tránh ghi đè lên file cũ.

1
 public function store(Request $request)
2
    {
3
        // Tạo biến mới để lưu đường dẫn và tên file gốc
4
        $storedFilePath = null;
5
        $originalFilename = null;
6

7
        // Kiểm tra xem request có chứa file với tên là 'file' không
8
        if ($request->hasFile('file')) {
9
            // Lấy đối tượng file từ request
10
            $file = $request->file('file');
11
            // Lấy tên file gốc từ client
12
            $originalFilename = $file->getClientOriginalName();
13

14
            // 3. Chuẩn bị các phần của tên file
15
            $filenameWithoutExtension = pathinfo($originalFilename, PATHINFO_FILENAME); // Lấy tên file không có phần mở rộng
16
            $extension = $file->getClientOriginalExtension(); // Lấy phần mở rộng
17
            $directory = 'uploads'; // Thư mục lưu file trên disk
18
            $disk = 'public'; // Disk sẽ sử dụng (được định nghĩa trong config/filesystems.php)
19

20
            // 4. Xác định tên file duy nhất
21
            $finalFilename = $originalFilename; // Bắt đầu với tên gốc
22
            $counter = 1;
23

24
            // Kiểm tra xem file đã tồn tại chưa
25
            while (Storage::disk($disk)->exists($directory . '/' . $finalFilename)) {
26
                // Nếu tồn tại, tạo tên mới với hậu tố 1,2,3,...
27
                $finalFilename = $filenameWithoutExtension . '-' . $counter . '.' . $extension;
28
                $counter++;
29
            }
30

31
            // 5. Lưu file bằng storeAs với tên file mới
32
            $storedFilePath = $file->storeAs($directory, $finalFilename, $disk); // Trả về đường dẫn tương đối: 'uploads/ten_file_cuoi_cung.jpg'
33

34
            return "File uploaded to: " . $storedFilePath;
35
        }
36

37
        return "No file uploaded.";
38

39
    }

Kiểm tra thử: các file trùng tên sẽ được tự động thêm vào hậu tố 1,2,.. sau khi upload.

IV. Hiển thị file đã upload

Mực định, các file lưu trữ trong thư mục storage sẽ không thể truy cập trực tiếp từ trình duyệt vì lý do bảo mật. Để có thể hiển thị file đã lưu trong thư mục storage, chúng ta cần phải tạo symlink (cầu nối) bằng lệnh sau

1
php artisan storage:link

Lệnh này sẽ tạo một liên kết từ public/storage → storage/app/public, giúp bạn truy cập file qua URL như http://xxxxx.com/storage/filename.jpg.

Cập nhật lại function store, bổ sung thêm phần chuyển hướng về lại trang gốc sau khi upload file, kèm theo các thông tin cần thiết: success, stored_path, original_filename

1
 public function store(Request $request)
2
    {
3
        // Tạo biến mới để lưu đường dẫn và tên file gốc
4
        $storedFilePath = null;
5
        $originalFilename = null;
6

7
        // Kiểm tra xem request có chứa file với tên là 'file' không
8
        if ($request->hasFile('file')) {
9
            // Lấy đối tượng file từ request
10
            $file = $request->file('file');
11
            // Lấy tên file gốc từ client
12
            $originalFilename = $file->getClientOriginalName();
13

14
            // 3. Chuẩn bị các phần của tên file
15
            $filenameWithoutExtension = pathinfo($originalFilename, PATHINFO_FILENAME); // Lấy tên file không có phần mở rộng
16
            $extension = $file->getClientOriginalExtension(); // Lấy phần mở rộng
17
            $directory = 'uploads'; // Thư mục lưu file trên disk
18
            $disk = 'public'; // Disk sẽ sử dụng (được định nghĩa trong config/filesystems.php)
19

20
            // 4. Xác định tên file duy nhất
21
            $finalFilename = $originalFilename; // Bắt đầu với tên gốc
22
            $counter = 1;
23

24
            // Kiểm tra xem file đã tồn tại chưa
25
            while (Storage::disk($disk)->exists($directory . '/' . $finalFilename)) {
26
                // Nếu tồn tại, tạo tên mới với hậu tố 1,2,3,...
27
                $finalFilename = $filenameWithoutExtension . '-' . $counter . '.' . $extension;
28
                $counter++;
29
            }
30

31
            // 5. Lưu file bằng storeAs với tên file mới
32
            $storedFilePath = $file->storeAs($directory, $finalFilename, $disk); // Trả về đường dẫn tương đối: 'uploads/ten_file_cuoi_cung.jpg'
33
        }
34

35
        // Chuyển hướng về trang trước đó
36
        return back()->with('success', 'File uploaded successfully')
37
            // Gửi kèm đường dẫn file đã lưu vào session flash data
38
            ->with('stored_path', $storedFilePath)
39
            // Gửi kèm tên file gốc vào session flash data
40
            ->with('original_filename', $originalFilename);
41
    }
42
}

Cập nhật lại giao diện của upload.blade.php để hiển thị file ảnh đã upload

1
<!DOCTYPE html>
2
<html lang="en">
3

4
<head>
5
    <meta charset="UTF-8">
6
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
7
    <title>Upload File</title>
8
    <script src="https://cdn.tailwindcss.com"></script>
9
</head>
10

11
<body class="bg-gray-100 font-sans antialiased">
12
    <div class="container mx-auto mt-10 p-6 bg-white rounded-lg shadow-md max-w-md">
13
        <h1 class="text-2xl font-bold mb-6 text-center text-gray-700">Upload File</h1>
14
        <form action="{{ route("upload.store") }}" method="POST" enctype="multipart/form-data" class="space-y-4">
15
            @csrf
16
            <div>
17
                <label for="file" class="block text-sm font-medium text-gray-700 mb-1">Choose file</label>
18
                <input type="file" name="file" id="file"
19
                    class="block w-full text-sm text-gray-500
20
                              file:mr-4 file:py-2 file:px-4
21
                              file:rounded-full file:border-0
22
                              file:text-sm file:font-semibold
23
                              file:bg-blue-50 file:text-blue-700
24
                              hover:file:bg-blue-100" />
25
            </div>
26
            <button type="submit"
27
                class="w-full bg-blue-500 hover:bg-blue-700 text-white font-bold py-2 px-4 rounded focus:outline-none focus:shadow-outline">
28
                Upload
29
            </button>
30
        </form>
31
    </div>
32

33
    {{-- Display Success Message and Uploaded File Info --}}
34
    @if (session('success'))
35
        <div class="container mx-auto mt-6 p-4 bg-green-100 border border-green-400 text-green-700 rounded-lg shadow-md max-w-md">
36
            <p class="font-bold">Success!</p>
37
            <p>{{ session('success') }}</p>
38

39
            @if (session('stored_path'))
40
                <div class="mt-4">
41
                    <p class="text-sm text-gray-600">Original Filename: {{ session('original_filename', 'N/A') }}</p>
42
                    <p class="text-sm text-gray-600">Stored Path: {{ session('stored_path') }}</p>
43
                    <img src="{{ session('stored_path') }}" alt="Uploaded Image" class="mt-2 rounded max-w-full h-auto border">
44
                </div>
45
            @endif
46
        </div>
47
    @endif
48

49
</body>
50
</html>

Kiểm tra thành quả, file sau khi upload thành công sẽ được hiển thị thành công trên trình duyệt.

V. Lời kết

Trong [Phần 1] của series File Upload trong Laravel này, mình đã hướng dẫn:

Cách tạo form upload
Xử lý upload trong controller
Những lựa chọn lưu trữ file
Hiển thị file đã upload

🔗 Mã nguồn

Toàn bộ mã nguồn sử dụng trong [Phần 1] này đã được mình đẩy lên Github, các bạn nào quan tâm có thể tham khảo ở đây: https://github.com/10h30/laravel-file-upload-series/tree/part-1-basic-upload

🔜 Phần 2: Validation & Bảo mật

Sau khi đã thực hiện thành công upload file cơ bản trong Laravel, bạn có thể thấy hệ thống vẫn đang “mở cửa tự do” cho người dùng:

Cho phép upload bất kỳ định dạng nào
Không giới hạn kích thước file
Có thể tiềm ẩn rủi ro bảo mật nếu người dùng upload file độc hại

Trong [Phần 2], chúng ta sẽ tìm hiểu cách thêm validation cho file upload, đảm bảo chỉ cho phép các loại file được phép, hạn chế dung lượng và ngăn chặn các hành vi nguy hiểm từ phía người dùng.

https://thuanbui.me/file-upload-laravel-phan-2/

Happy coding!