Chuyển tới nội dung chính

Khắc Phục Lỗi PHP Không Tải Extension Trên Linux

Giới Thiệu​

PHP extensions (phần mở rộng) là các thư viện động giúp mở rộng chức năng cốt lõi của PHP, cho phép ứng dụng của bạn tương tác với cơ sở dữ liệu (MySQLi, PDO), xử lý hình ảnh (GD), mã hóa dữ liệu (OpenSSL), quản lý bộ nhớ đệm (Redis, Memcached) và nhiều tác vụ chuyên biệt khác. Khi một extension không được tải đúng cách, các ứng dụng PHP phụ thuộc vào nó sẽ gặp lỗi, thường là Fatal error: Uncaught Error: Call to undefined function....

Bài viết này sẽ hướng dẫn bạn các bước chi tiết để chẩn đoán và khắc phục lỗi PHP không load extension trên môi trường Linux, giúp đảm bảo các ứng dụng PHP của bạn hoạt động trơn tru.

📋 Thời gian: 20 phút | Độ khó: Trung bình

Yêu Cầu​

Để thực hiện theo hướng dẫn này, bạn cần:

  • Quyền truy cập root hoặc sudo trên hệ thống Linux của bạn.
  • Hiểu biết cơ bản về cách sử dụng terminal và các lệnh Linux.
  • PHP đã được cài đặt trên hệ thống.
  • Biết tên của extension PHP mà bạn muốn kiểm tra hoặc kích hoạt.

Các Bước Thực Hiện​

Bước 1: Kiểm tra cấu hình PHP hiện tại​

Trước tiên, chúng ta cần xác định PHP đang sử dụng file cấu hình nào và những extension nào đang được tải. Điều này giúp chúng ta biết được file php.ini cần chỉnh sửa và trạng thái hiện tại của các extension.

# Lệnh này hiển thị đường dẫn đến file php.ini chính đang được tải
php -i | grep "Loaded Configuration File"

# Lệnh này liệt kê tất cả các file .ini bổ sung mà PHP đang quét
php --ini

# Lệnh này liệt kê tất cả các extension đã được tải
php -m

💡 Mẹo: Ghi lại đường dẫn của "Loaded Configuration File" và thư mục extension_dir (tìm bằng php -i | grep "extension_dir"). Đây là những thông tin quan trọng cho các bước sau.

Bước 2: Xác định vị trí file .so của extension​

Mỗi extension PHP là một file thư viện động có đuôi .so (shared object). Để PHP có thể tải extension, file .so này phải tồn tại trong thư mục extension_dir hoặc một đường dẫn cụ thể mà bạn chỉ định.

# Ví dụ: Kiểm tra xem extension 'mbstring.so' có tồn tại không
# Thay thế 'X.Y' bằng phiên bản PHP của bạn, ví dụ: 8.1, 7.4
sudo find /usr/lib/php/X.Y/ -name "mbstring.so"
sudo find /usr/lib/php/ -name "mbstring.so" # Tìm trong tất cả các phiên bản PHP

# Nếu bạn biết chính xác extension_dir, hãy kiểm tra trực tiếp
# Ví dụ: /usr/lib/php/20210902
ls -l /usr/lib/php/20210902/mbstring.so

Nếu file .so không được tìm thấy, bạn có thể cần phải cài đặt extension đó.

# Ví dụ cài đặt extension mbstring trên Ubuntu/Debian
sudo apt update
sudo apt install phpX.Y-mbstring # Thay X.Y bằng phiên bản PHP của bạn, ví dụ: php8.1-mbstring

# Ví dụ cài đặt extension gd trên CentOS/RHEL
sudo dnf install php-gd # Hoặc yum install php-gd

Bước 3: Chỉnh sửa file php.ini​

Sau khi xác định được file php.ini đang được sử dụng và vị trí của file .so, bạn cần chỉnh sửa php.ini để kích hoạt extension.

⚠️ Quan trọng: PHP có thể có nhiều file php.ini cho các môi trường khác nhau (CLI, FPM, Apache). Đảm bảo bạn chỉnh sửa đúng file php.ini cho môi trường mà ứng dụng của bạn đang chạy. Ví dụ:

  • /etc/php/X.Y/cli/php.ini (cho các script chạy từ dòng lệnh)
  • /etc/php/X.Y/fpm/php.ini (cho PHP-FPM, thường dùng với Nginx)
  • /etc/php/X.Y/apache2/php.ini (cho Apache)

Mở file php.ini bằng trình soạn thảo văn bản (ví dụ: nano hoặc vim):

sudo nano /etc/php/X.Y/fpm/php.ini # Thay X.Y và đường dẫn phù hợp

Tìm dòng extension_dir. Đảm bảo nó trỏ đến thư mục chứa các file .so của bạn.

; Ví dụ cấu hình extension_dir
extension_dir = "/usr/lib/php/20210902" ; Đảm bảo đường dẫn này chính xác

Tiếp theo, tìm dòng extension=extension_name.so và bỏ dấu chấm phẩy (;) ở đầu dòng để kích hoạt nó. Nếu dòng đó không tồn tại, hãy thêm vào cuối phần Dynamic Extensions.

; Ví dụ kích hoạt extension mbstring
extension=mbstring.so

; Ví dụ kích hoạt extension pdo_mysql
extension=pdo_mysql.so

Lưu file và thoát khỏi trình soạn thảo.

Bước 4: Khởi động lại dịch vụ Web Server/PHP-FPM​

Để các thay đổi trong php.ini có hiệu lực, bạn cần khởi động lại dịch vụ web server hoặc PHP-FPM.

# Nếu bạn dùng PHP-FPM với Nginx hoặc Apache
sudo systemctl restart phpX.Y-fpm # Thay X.Y bằng phiên bản PHP của bạn, ví dụ: php8.1-fpm

# Nếu bạn dùng Apache với mod_php
sudo systemctl restart apache2

# Nếu bạn dùng Nginx
sudo systemctl restart nginx

Bước 5: Kiểm tra lại​

Sau khi khởi động lại dịch vụ, hãy kiểm tra lại xem extension đã được tải thành công chưa.

# Kiểm tra từ dòng lệnh
php -m | grep "mbstring" # Thay "mbstring" bằng tên extension của bạn

# Kiểm tra qua web server
# Tạo một file info.php trong thư mục gốc của web server (ví dụ: /var/www/html/info.php)
# Với nội dung:
# <?php phpinfo(); ?>
# Sau đó truy cập http://your_domain_or_ip/info.php trên trình duyệt của bạn.
# Tìm kiếm tên extension (ví dụ: "mbstring") trên trang phpinfo để xác nhận nó đã được kích hoạt.

✅ Nếu bạn thấy tên extension xuất hiện trong danh sách php -m hoặc trên trang phpinfo(), thì extension đã được tải thành công!

Troubleshooting​

Lỗi thường gặp 1: PHP Warning: PHP Startup: Unable to load dynamic library 'extension_name.so' (or module 'extension_name')​

  • Nguyên nhân:
    • Đường dẫn đến file .so trong php.ini không chính xác hoặc file không tồn tại.
    • Phiên bản extension không tương thích với phiên bản PHP hiện tại.
    • Thiếu các thư viện phụ thuộc của extension.
  • Cách xử lý:
    1. ⚠️ Kiểm tra lại Bước 2 và Bước 3. Đảm bảo extension_dir và tên file .so là chính xác.
    2. Kiểm tra xem bạn đã cài đặt đúng phiên bản extension cho phiên bản PHP của mình chưa (ví dụ: php8.1-gd chứ không phải php7.4-gd).
    3. Kiểm tra log của web server hoặc PHP-FPM để tìm thêm thông tin chi tiết về lỗi (ví dụ: /var/log/apache2/error.log, /var/log/nginx/error.log, /var/log/phpX.Y-fpm.log).

Lỗi thường gặp 2: Extension đã được bật trong php.ini nhưng vẫn không hoạt động trên trình duyệt​

  • Nguyên nhân: Bạn đã chỉnh sửa sai file php.ini. Có thể bạn chỉ chỉnh sửa php.ini cho CLI mà quên chỉnh sửa cho FPM/Apache.
  • Cách xử lý:
    1. 💡 Quay lại Bước 1 và dùng php --ini để xem tất cả các file .ini đang được tải.
    2. Kiểm tra lại output của php -i | grep "Loaded Configuration File" từ trình duyệt (qua info.php) để xác định chính xác file php.ini mà web server đang sử dụng.
    3. Thực hiện Bước 3 và Bước 4 trên đúng file php.ini và khởi động lại đúng dịch vụ.

Lỗi thường gặp 3: Không thể cài đặt extension hoặc lỗi khi biên dịch từ mã nguồn​

  • Nguyên nhân: Thiếu các gói phát triển (development packages) hoặc thư viện phụ thuộc.
  • Cách xử lý:
    1. Đảm bảo bạn đã cài đặt gói php-dev (trên Debian/Ubuntu) hoặc php-devel (trên CentOS/RHEL). 
      sudo apt install phpX.Y-dev # Debian/Ubuntu
      sudo dnf install php-devel # CentOS/RHEL
    2. Cài đặt các thư viện phụ thuộc cụ thể cho extension đó. Ví dụ, để cài đặt pdo_pgsql, bạn có thể cần libpq-dev. 
      sudo apt install libpq-dev # Debian/Ubuntu
    3. Tham khảo tài liệu chính thức của extension hoặc tìm kiếm lỗi cụ thể trên mạng để tìm các gói phụ thuộc cần thiết.

Kết Luận​

Việc khắc phục lỗi PHP không load extension thường xoay quanh việc kiểm tra đúng file cấu hình php.ini, đảm bảo file .so của extension tồn tại ở đúng vị trí và khởi động lại dịch vụ PHP/web server. Bằng cách làm theo các bước được mô tả ở trên, bạn có thể tự tin chẩn đoán và giải quyết hầu hết các vấn đề liên quan đến việc tải extension PHP.

Best practices:

  • Luôn kiểm tra log lỗi của PHP và web server để có thêm thông tin chi tiết.
  • Chỉ kích hoạt những extension thực sự cần thiết để tối ưu hiệu suất và bảo mật.
  • Khi có nhiều phiên bản PHP, hãy luôn cẩn thận để chỉnh sửa đúng file php.ini cho phiên bản và môi trường mong muốn.