Sửa lỗi PHP Fatal error: Call to undefined function imagecreatetruecolor() - Thiếu GD Extension

Vấn đề

Có lẽ bạn đang cố gắng xử lý một hình ảnh—chẳng hạn như thay đổi kích thước ảnh đại diện, tạo mã captcha hoặc tạo ảnh thu nhỏ (thumbnail)—thì tập lệnh của bạn gặp lỗi và dừng đột ngột với thông báo sau:

PHP Fatal error: Uncaught Error: Call to undefined function imagecreatetruecolor()

Điều này xảy ra do imagecreatetruecolor() là một phần của tiện ích mở rộng (extension) GD (Graphics Draw). Nếu tiện ích này chưa được cài đặt hoặc chưa được kích hoạt trong tệp php.ini, PHP sẽ không nhận diện được hàm này. Đây là một vấn đề phổ biến trên các máy chủ mới thiết lập hoặc khi chuyển sang phiên bản PHP mới mà các tiện ích mở rộng không được chuyển sang một cách tự động.

Nguyên nhân gốc rễ

Thư viện GD là yêu cầu bắt buộc đối với hầu hết các thư viện xử lý hình ảnh trong PHP (như Intervention Image hoặc Imagine). Theo mặc định, nhiều bản phân phối Linux và các hình ảnh Docker tối giản không bao gồm GD để giữ cho việc cài đặt nhẹ nhàng hơn. Nếu không có tiện ích mở rộng GD, bất kỳ lệnh gọi nào tới imagecreatetruecolor(), imagecreatefromjpeg(), hoặc imagepng() đều sẽ thất bại.

Cách khắc phục cho Ubuntu / Debian

Trên các hệ thống dựa trên Debian, bạn cần cài đặt gói GD cụ thể cho phiên bản PHP của mình. Hãy thay thế 8.x bằng phiên bản hiện tại của bạn (ví dụ: 7.4, 8.1, 8.2, 8.3).

# Cập nhật danh sách gói
sudo apt update

# Cài đặt tiện ích mở rộng GD (ví dụ cho PHP 8.2)
sudo apt install php8.2-gd

Sau khi cài đặt, hãy khởi động lại máy chủ web hoặc tiến trình PHP-FPM để áp dụng các thay đổi:

# Nếu sử dụng Apache
sudo systemctl restart apache2

# Nếu sử dụng Nginx với PHP-FPM
sudo systemctl restart php8.2-fpm

Cách khắc phục cho CentOS / RHEL / AlmaLinux

Đối với các hệ thống dựa trên RHEL sử dụng trình quản lý gói yum hoặc dnf:

# Cài đặt tiện ích mở rộng GD
sudo dnf install php-gd

# Khởi động lại PHP-FPM
sudo systemctl restart php-fpm

Cách khắc phục cho Docker (PHP-FPM Images)

Nếu bạn đang sử dụng các hình ảnh Docker PHP chính thức, việc chỉ sử dụng apt install bên trong container là không đủ vì tiện ích mở rộng cần phải được cấu hình và kích hoạt trong môi trường PHP. Hãy sử dụng tập lệnh hỗ trợ docker-php-ext-install.

Thêm nội dung này vào Dockerfile của bạn:

FROM php:8.2-fpm

# Cài đặt các thư viện phụ thuộc cho GD
RUN apt-get update && apt-get install -y \
    libpng-dev \
    libjpeg-dev \
    libfreetype6-dev

# Cấu hình và cài đặt GD
RUN docker-php-ext-configure gd --with-freetype --with-jpeg \
    && docker-php-ext-install gd

Lưu ý: Các phiên bản PHP hiện đại (7.4+) yêu cầu các cờ --with-freetype và --with-jpeg trong quá trình cấu hình nếu bạn cần hỗ trợ cho các định dạng cụ thể đó.

Cách khắc phục cho Windows (XAMPP / WAMP)

Nếu bạn đang phát triển cục bộ trên Windows, tiện ích mở rộng GD thường đã được bao gồm sẵn nhưng bị vô hiệu hóa theo mặc định.

• Tìm tệp php.ini của bạn (Trong XAMPP, nó thường nằm ở C:\xampp\php\php.ini).
• Mở tệp bằng trình soạn thảo văn bản và tìm kiếm dòng extension=gd.
• Xóa dấu chấm phẩy (;) ở đầu dòng để bỏ chú thích:

;extension=gd --> chuyển thành --> extension=gd

  
  - Lưu tệp và khởi động lại dịch vụ Apache thông qua XAMPP/WAMP Control Panel.

## Kiểm tra kết quả
Sau khi đã khởi động lại máy chủ, bạn nên kiểm tra xem tiện ích mở rộng đã hoạt động hay chưa. Bạn có thể thực hiện việc này thông qua dòng lệnh hoặc một tập lệnh web.

### Cách 1: Dòng lệnh (CLI)
Chạy lệnh sau để xem "gd" có xuất hiện trong danh sách các module đã tải hay không:

php -m | grep -i gd

Nếu kết quả trả về là `gd`, tiện ích mở rộng đã được tải thành công cho CLI.

### Cách 2: PHP Info
Tạo một tệp tạm thời có tên `info.php` trong thư mục web của bạn với nội dung sau:

Truy cập tệp này qua trình duyệt (ví dụ: `http://localhost/info.php`) và tìm kiếm phần "gd". Nó sẽ hiển thị "GD Support => enabled".

## Phòng ngừa và các phương pháp tốt nhất
Để tránh lỗi này trong tương lai, đặc biệt là khi triển khai lên môi trường production, hãy tuân thủ các phương pháp sau:

  - **Kiểm tra các phụ thuộc Composer:** Nếu bạn sử dụng một thư viện như `intervention/image`, hãy đảm bảo nó được liệt kê trong tệp `composer.json` của bạn. Bạn cũng có thể yêu cầu tiện ích mở rộng một cách rõ ràng trong `composer.json` để lệnh `composer install` sẽ thất bại nếu thiếu tiện ích mở rộng:
    ```
"require": {
    "ext-gd": "*"
}

• Sự đồng nhất giữa các môi trường: Đảm bảo môi trường phát triển cục bộ của bạn (XAMPP/Docker) khớp với các tiện ích mở rộng PHP trên máy chủ production.
• Cung cấp hạ tầng tự động: Sử dụng các tập lệnh (Ansible, Docker, hoặc Bash) để thiết lập máy chủ sao cho các tiện ích mở rộng bắt buộc như gd, mbstring, và pdo luôn được cài đặt theo mặc định.