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

Cài Đặt PHP Extension Từ Mã Nguồn Trên Linux

Giới Thiệu​

Trong nhiều trường hợp, việc cài đặt PHP extension thông qua trình quản lý gói hệ thống (như apt trên Debian/Ubuntu hoặc yum/dnf trên CentOS/RHEL) là phương pháp được khuyến nghị. Tuy nhiên, có những lúc bạn cần cài đặt một PHP extension không có sẵn trong kho lưu trữ, cần một phiên bản cụ thể không được cung cấp, hoặc đang làm việc với các extension tùy chỉnh. Khi đó, việc biên dịch và cài đặt extension từ mã nguồn là giải pháp cần thiết.

Hướng dẫn này sẽ trang bị cho bạn kiến thức để tự tin cài đặt bất kỳ PHP extension nào từ mã nguồn trên hệ điều hành Linux.

📋 Thời gian: 20-40 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 đảm bảo các điều kiện sau:

  • Một máy chủ hoặc máy ảo chạy hệ điều hành Linux (ví dụ: Ubuntu, Debian, CentOS, RHEL).
  • Quyền truy cập sudo hoặc quyền root.
  • PHP đã được cài đặt trên hệ thống của bạn.
  • Kiến thức cơ bản về sử dụng dòng lệnh Linux.
  • Kết nối internet để tải các gói và mã nguồn.

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

Bước 1: Chuẩn bị môi trường và công cụ cần thiết​

Trước tiên, chúng ta cần cài đặt các công cụ phát triển và thư viện cần thiết để biên dịch mã nguồn.

# Đối với Debian/Ubuntu
sudo apt update
sudo apt install -y build-essential autoconf php-dev libtool pkg-config

# Đối với CentOS/RHEL/Fedora
sudo dnf install -y @development php-devel autoconf libtool pkgconfig
# Hoặc nếu dùng yum:
# sudo yum install -y @development php-devel autoconf libtool pkgconfig

Giải thích:

  • build-essential (hoặc @development): Cung cấp trình biên dịch GCC, make và các công cụ phát triển cơ bản.
  • php-dev (hoặc php-devel): Cung cấp các header và thư viện cần thiết để biên dịch các PHP extension, bao gồm công cụ phpize và php-config.
  • autoconf, libtool, pkg-config: Các công cụ hỗ trợ quá trình cấu hình và biên dịch.

Tiếp theo, xác định phiên bản PHP và vị trí của phpize và php-config.

php -v
which phpize
which php-config

💡 Tip: Nếu bạn có nhiều phiên bản PHP được cài đặt (ví dụ: PHP 7.4 và PHP 8.1), hãy đảm bảo bạn đang sử dụng phpize và php-config tương ứng với phiên bản PHP mà bạn muốn cài đặt extension cho. Ví dụ, phpize8.1 và php-config8.1.

Bước 2: Tải mã nguồn của Extension​

Bạn có thể tải mã nguồn của extension từ kho lưu trữ PECL (PHP Extension Community Library) hoặc từ GitHub/trang dự án.

Tùy chọn 1: Từ PECL (được khuyến nghị cho các extension phổ biến)​

Sử dụng công cụ pecl để tải và giải nén mã nguồn.

# Ví dụ: Tải extension 'redis'
pecl download redis
# Lệnh này sẽ tải file .tgz vào thư mục hiện tại.
# Nếu bạn muốn một phiên bản cụ thể:
# pecl download redis-5.3.7

Sau khi tải, giải nén file:

tar -xzf redis-*.tgz
cd redis-*

Tùy chọn 2: Từ GitHub hoặc trang dự án​

Nếu extension không có trên PECL hoặc bạn cần một phiên bản phát triển, hãy tải từ GitHub.

# Ví dụ: Tải mã nguồn từ GitHub
# Thay thế URL bằng URL thực tế của extension bạn muốn cài đặt
git clone https://github.com/php/php-src.git # (Ví dụ cho một extension nằm trong php-src)
# Hoặc tải file zip/tar.gz trực tiếp từ release page
# wget https://github.com/someuser/someextension/archive/refs/tags/v1.0.0.tar.gz
# tar -xzf v1.0.0.tar.gz
# cd someextension-1.0.0

⚠️ Cảnh báo: Luôn kiểm tra tính tương thích của extension với phiên bản PHP của bạn trước khi tải mã nguồn.

Bước 3: Biên dịch Extension​

Đây là bước cốt lõi để tạo ra file .so (shared object) của extension.

# Đảm bảo bạn đang ở trong thư mục mã nguồn của extension
# Ví dụ: cd redis-*

# 1. Chuẩn bị môi trường biên dịch
phpize

phpize sẽ quét thư mục hiện tại và tạo ra các file cần thiết cho quá trình cấu hình và biên dịch (như configure).

# 2. Cấu hình biên dịch
# Sử dụng --with-php-config nếu bạn có nhiều phiên bản PHP hoặc muốn chỉ định rõ
./configure --with-php-config=/usr/bin/php-config8.1 # Thay đổi đường dẫn nếu cần
# Hoặc đơn giản hơn nếu php-config mặc định là đúng phiên bản:
# ./configure

# 3. Biên dịch mã nguồn
make

# 4. Cài đặt extension vào thư mục extensions của PHP
sudo make install

Sau khi sudo make install hoàn tất, bạn sẽ thấy một thông báo cho biết file .so đã được cài đặt vào đâu. Ví dụ: Installing shared extensions: /usr/lib/php/20210902/ (đường dẫn này có thể khác tùy thuộc vào phiên bản PHP và hệ điều hành).

Bước 4: Kích hoạt Extension​

Sau khi biên dịch và cài đặt, bạn cần thông báo cho PHP biết về extension mới bằng cách chỉnh sửa file php.ini.

  1. Tìm file php.ini: PHP có thể sử dụng nhiều file php.ini khác nhau tùy thuộc vào ngữ cảnh (CLI, FPM, Apache, Nginx).

    php --ini

    Lệnh này sẽ hiển thị các file php.ini đang được tải. Bạn thường cần chỉnh sửa file cho CLI và file cho web server (ví dụ: /etc/php/8.1/fpm/php.ini cho PHP-FPM hoặc /etc/php/8.1/apache2/php.ini cho Apache).

  2. Thêm dòng kích hoạt extension: Mở file php.ini tương ứng bằng trình soạn thảo văn bản yêu thích của bạn (ví dụ: nano hoặc vi).

    # Ví dụ với PHP 8.1 FPM trên Ubuntu
    sudo nano /etc/php/8.1/fpm/php.ini

    Thêm dòng sau vào cuối file hoặc trong phần Dynamic Extensions:

    extension=redis.so

    ⚠️ Quan trọng: Đảm bảo tên file .so khớp chính xác với tên mà make install đã tạo ra (ví dụ: redis.so, mongodb.so).

  3. Khởi động lại dịch vụ PHP/Web Server: Để các thay đổi có hiệu lực, bạn cần khởi động lại dịch vụ PHP-FPM hoặc web server (Apache/Nginx).

    # Đối với PHP-FPM (ví dụ: PHP 8.1)
    sudo systemctl restart php8.1-fpm

    # Đối với Apache
    sudo systemctl restart apache2

    # Đối với Nginx (chỉ cần khởi động lại PHP-FPM, Nginx không cần)
    # sudo systemctl restart nginx

Bước 5: Kiểm tra cài đặt​

Sau khi kích hoạt và khởi động lại, hãy xác minh rằng extension đã được tải thành công.

  1. Kiểm tra qua CLI:

    php -m | grep redis
    # Nếu extension được tải, bạn sẽ thấy tên extension được liệt kê (ví dụ: redis)

  2. Kiểm tra chi tiết qua CLI:

    php -i | grep "redis support"
    # Hoặc để xem toàn bộ thông tin về extension
    php --ri redis

  3. Kiểm tra qua phpinfo() (cho môi trường web): Tạo một file info.php trong thư mục gốc của web server của bạn với nội dung:

    <?php phpinfo(); ?>

    Truy cập file này qua trình duyệt (ví dụ: http://your_domain_or_ip/info.php). Tìm kiếm tên extension của bạn trên trang phpinfo(). Nếu bạn thấy một phần dành riêng cho extension đó, nghĩa là nó đã được cài đặt và kích hoạt thành công. ✅ Success: Sau khi xác nhận, hãy nhớ xóa file info.php để tránh rủi ro bảo mật.

Troubleshooting​

  • Lỗi: "Cannot find phpize/php-config" hoặc "phpize: command not found"

    • Nguyên nhân: Gói php-dev (hoặc php-devel) chưa được cài đặt hoặc không đúng phiên bản.
    • Giải pháp: Quay lại Bước 1 và đảm bảo đã cài đặt gói php-dev tương ứng với phiên bản PHP của bạn. Ví dụ: sudo apt install php8.1-dev. Kiểm tra lại đường dẫn bằng which phpize.

  • Lỗi: Lỗi biên dịch (make thất bại)

    • Nguyên nhân: Thiếu các thư viện phụ thuộc cụ thể mà extension yêu cầu, hoặc phiên bản PHP không tương thích với mã nguồn extension.
    • Giải pháp: Đọc kỹ thông báo lỗi. Thông thường, nó sẽ chỉ ra thư viện hoặc header file nào bị thiếu (ví dụ: libmemcached-dev, libssl-dev). Cài đặt các gói *-dev (hoặc *-devel) tương ứng. Đảm bảo phiên bản extension tương thích với phiên bản PHP của bạn.

  • Lỗi: Extension không tải sau khi kích hoạt và khởi động lại dịch vụ

    • Nguyên nhân:
      1. Chỉnh sửa sai file php.ini.
      2. Đường dẫn đến file .so không chính xác trong php.ini.
      3. Tên file .so sai (ví dụ: extension=redis.so thay vì extension=redis.so).
      4. Quyền hạn không đúng cho file .so.
    • Giải pháp:
      1. Sử dụng php --ini để kiểm tra các file php.ini đang được tải và đảm bảo bạn đã chỉnh sửa đúng file cho môi trường web server (FPM/Apache).
      2. Kiểm tra lại đường dẫn mà sudo make install đã cài đặt file .so vào. Đôi khi, bạn cần chỉ định đường dẫn đầy đủ trong php.ini: extension=/usr/lib/php/20210902/redis.so.
      3. Kiểm tra lại chính tả tên extension.
      4. Đảm bảo file .so có quyền đọc cho người dùng chạy PHP (thường là www-data hoặc apache).

  • Lỗi: "PHP Warning: Unknown: Failed loading extension_name.so"

    • Nguyên nhân: File .so bị hỏng, không tương thích với phiên bản PHP, hoặc không tìm thấy tại đường dẫn được chỉ định.
    • Giải pháp: Kiểm tra lại đường dẫn trong php.ini. Đảm bảo bạn đã biên dịch extension với phpize và php-config của đúng phiên bản PHP đang chạy. Thử biên dịch lại từ đầu.

Kết Luận​

Cài đặt PHP extension thủ công từ mã nguồn là một kỹ năng quan trọng, đặc biệt khi bạn cần tính linh hoạt hoặc làm việc với các extension chuyên biệt. Mặc dù quá trình này đòi hỏi sự chú ý đến từng bước, nhưng nó cho phép bạn kiểm soát hoàn toàn môi trường PHP của mình.

Best Practices:

  • Ưu tiên trình quản lý gói: Luôn cố gắng sử dụng trình quản lý gói hệ thống trước (ví dụ: sudo apt install php-redis) nếu extension có sẵn, vì nó đơn giản và dễ quản lý hơn.
  • Kiểm tra tương thích: Luôn xác nhận phiên bản PHP của bạn tương thích với phiên bản extension mà bạn định cài đặt.
  • Ghi lại các bước: Ghi lại các lệnh và cấu hình bạn đã thực hiện, đặc biệt là khi cài đặt nhiều extension hoặc trên nhiều máy chủ. Điều này hữu ích cho việc bảo trì và gỡ lỗi sau này.
  • Sao lưu php.ini: Luôn sao lưu file php.ini trước khi thực hiện bất kỳ thay đổi nào.
  • Kiểm tra kỹ lưỡng: Sau khi cài đặt, luôn kiểm tra kỹ lưỡng bằng php -m hoặc phpinfo() để đảm bảo extension hoạt động như mong đợi.