ServBay

Tiếng Việt

English
简体中文
繁體中文
Español
العربية
Português
Русский
日本語
Deutsch
Français
Türkçe
Italiano
हिन्दी
Bahasa Indonesia
Bahasa Melayu
Polski
Nederlands
Українська
ไทย
한국어

Tiếng Việt

English
简体中文
繁體中文
Español
العربية
Português
Русский
日本語
Deutsch
Français
Türkçe
Italiano
हिन्दी
Bahasa Indonesia
Bahasa Melayu
Polski
Nederlands
Українська
ไทย
한국어

Appearance

Biên dịch và cài đặt mô-đun PHP tùy chỉnh trong ServBay ​

ServBay là môi trường phát triển web mạnh mẽ hỗ trợ macOS và Windows, tích hợp sẵn nhiều package phục vụ nhu cầu lập trình web hiện đại. Phần mềm này cài đặt sẵn PHP, Node.js, Python, Go, Java, các hệ quản trị cơ sở dữ liệu (MySQL, PostgreSQL, MongoDB), cache (Redis), và máy chủ web (Caddy, Nginx, Apache). ServBay cho phép bạn sử dụng đồng thời nhiều phiên bản cho mỗi package, thuận tiện chuyển đổi theo nhu cầu dự án.

Dù ServBay đã bao gồm hầu hết các mô-đun PHP phổ biến, nhưng trong một số trường hợp đặc biệt bạn sẽ cần biên dịch và cài thêm mô-đun mở rộng cho PHP để tích hợp các dịch vụ hoặc chức năng cụ thể.

Bài viết này sẽ hướng dẫn chi tiết cách biên dịch và cài đặt mô-đun tùy chỉnh cho PHP trong môi trường ServBay. Các ví dụ thực tế bao gồm mô-đun xử lý ảnh imagick và driver cơ sở dữ liệu Microsoft SQL Server sqlsrv. Bạn sẽ hiểu rõ quy trình bổ sung extension vào PHP trong ServBay.

Yêu cầu tiên quyết ​

Lưu ý quan trọng

Trước khi bắt đầu biên dịch bất kỳ mô-đun PHP nào, bước bắt buộc là khởi tạo môi trường build của ServBay và thiết lập đúng biến môi trường hệ thống, theo hướng dẫn tài liệu chính thức. Đây là tiền đề để tất cả quá trình build package (bao gồm cả các mô-đun PHP) diễn ra thành công. Nếu bạn bỏ qua hoặc thực hiện không đúng, khả năng cao sẽ gặp lỗi không tìm thấy lệnh, thư viện hoặc file header.

Script khởi tạo môi trường build của ServBay sẽ thiết lập các biến môi trường cần thiết như: PATH (đến bộ công cụ nội bộ của ServBay), SERVBAY_PACKAGE_FULL_PATH (thư mục root các package ServBay) và CPU_NUMBER (số luồng biên dịch). Đây là các biến rất quan trọng quyết định việc build sau này.

Để biết chi tiết từng bước khởi tạo môi trường build ServBay, vui lòng tham khảo tài liệu: Biên dịch lại package với ServBay. Hãy đảm bảo bạn đã hiểu rõ và thực hiện đầy đủ các thiết lập cần thiết theo hướng dẫn.

Trước khi tiếp tục, hãy xác nhận bạn đã hoàn thành xong việc khởi tạo môi trường build ServBay, và các biến môi trường liên quan đã được thiết lập chính xác trong phiên dòng lệnh hiện tại.

Ý nghĩa của việc chỉ định đúng phiên bản PHP ​

Một tính năng nổi bật của ServBay là cho phép cài đặt và chạy đồng thời nhiều phiên bản PHP trên cùng một hệ thống. Nhờ thế, bạn có thể chuyển đổi linh hoạt môi trường cho từng dự án. Tuy nhiên, khi biên dịch extension cho PHP, bạn cần chỉ định chính xác phiên bản PHP muốn sử dụng. Các công cụ quan trọng chuẩn bị môi trường build và lấy cấu hình phiên bản là phpize và php-config, đều gắn liền với từng phiên bản cụ thể.

  • phpize: Script chuẩn bị môi trường build cho extension PHP, đọc file config.m4 và tạo script tiêu chuẩn configure (bước đầu trong build C/C++).
  • php-config: Script cung cấp thông tin cấu hình chi tiết cho phiên bản PHP cụ thể, bao gồm compiler flags, thư mục include, thư viện, thư mục cài đặt extension... Script configure sẽ gọi php-config để lấy thông tin chính xác phục vụ build/link extension với đúng phiên bản PHP.

Vì vậy, khi dùng phpize, php-config hay lệnh build liên quan PHP, bạn luôn phải chỉ rõ đường dẫn đầy đủ của phiên bản PHP mục tiêu cần build extension.

Ví dụ về đường dẫn ​

Nếu bạn muốn build extension cho PHP 8.3 đã cài trong ServBay:

macOS:

  • phpize: /Applications/ServBay/package/php/8.3/current/bin/phpize
  • php-config: /Applications/ServBay/package/php/8.3/current/bin/php-config

Windows:

  • phpize: C:\ServBay\package\php\8.3\current\bin\phpize
  • php-config: C:\ServBay\package\php\8.3\current\bin\php-config

Chọn đúng phiên bản sẽ đảm bảo extension build xong tương thích chính xác với môi trường PHP mục tiêu, tránh lỗi build hoặc lỗi runtime "không tìm thấy symbol".

Tất cả ví dụ trong tài liệu này sẽ minh họa với PHP 8.3 trên ServBay. Khi thao tác, thay thế đường dẫn bằng đúng đường dẫn tới phiên bản PHP mà bạn cần build extension.

Biên dịch mô-đun imagick cho PHP ​

imagick là mô-đun rất phổ biến trên PHP, dựa trên thư viện ImageMagick, cung cấp hàng loạt chức năng xử lý ảnh chuyên sâu. Bạn có thể scaling, crop, chuyển định dạng, watermark, xử lý ảnh phức tạp... ngay trên PHP. Sau đây là các bước chi tiết để biên dịch và cài đặt imagick trên từng phiên bản PHP cụ thể trong ServBay:

Bước 1: Cài đặt thư viện phụ thuộc ImageMagick ​

Mô-đun imagick phụ thuộc vào hệ thống đã cài sẵn thư viện ImageMagick.

macOS ​

Nên cài qua hệ thống quản lý package Homebrew. Nếu chưa cài Homebrew, hãy vào trang chủ Homebrew để xem hướng dẫn.

Mở Terminal và chạy:

bash
brew install imagemagick

Windows ​

Người dùng Windows cần tải và cài thủ công ImageMagick từ trang tải ImageMagick chính thức.

Khi cài đặt, nhớ chọn phiên bản có đầy đủ thư viện phát triển, và thêm đường dẫn của thư viện vào biến môi trường hệ thống.

Bước 2: Tải mã nguồn mô-đun imagick ​

Truy cập trang PECL PECL imagick, chọn phiên bản phù hợp (nên dùng bản stable mới nhất), lấy link tải về. Ví dụ ở đây là phiên bản 3.7.0:

bash
wget https://pecl.php.net/get/imagick-3.7.0.tgz

Bước 3: Giải nén mã nguồn và chuyển vào thư mục ​

Sau khi tải xong, giải nén rồi cd vào thư mục mã nguồn:

bash
tar zxvf imagick-3.7.0.tgz
cd imagick-3.7.0

Bước 4: Chuẩn bị môi trường build (phpize) ​

Sau khi cd vào source, dùng phpize đúng phiên bản PHP mục tiêu. Ví dụ cho PHP 8.3 và đã export biến SERVBAY_PACKAGE_FULL_PATH:

bash
${SERVBAY_PACKAGE_FULL_PATH}/php/8.3/current/bin/phpize

Chạy thành công sẽ kiểm tra file config.m4 và sinh ra script configure cùng các file build cần thiết. Terminal sẽ báo “build environment ready”.

Bước 5: Cấu hình build ​

Chạy script configure vừa sinh ra để cấu hình các tùy chọn build. Dùng option --with-php-config chỉ đường dẫn tới php-config của phiên bản PHP mục tiêu:

bash
./configure --with-php-config=${SERVBAY_PACKAGE_FULL_PATH}/php/8.3/current/bin/php-config

Script sẽ kiểm tra thư viện, file header… Sinh ra file Makefile nếu mọi thứ OK. Nếu báo lỗi thường là do thiếu dependency, sai đường dẫn...

Bước 6: Biên dịch và cài đặt mô-đun ​

Cấu hình xong rồi, dùng lệnh sau để build và cài extension (biến ${CPU_NUMBER} để build đa luồng — đã được gán lúc khởi tạo môi trường build):

bash
make -j ${CPU_NUMBER}
make install

Lệnh make install sẽ copy file extension vào thư mục chuẩn của PHP extension:

  • macOS: /Applications/ServBay/package/php/8.3/current/lib/php/extensions/no-debug-non-zts-YYYYMMDD/
  • Windows: C:\ServBay\package\php\8.3\current\lib\php\extensions\no-debug-non-zts-YYYYMMDD\

Đường dẫn cụ thể sẽ tùy phiên bản PHP và config build.

Bước 7: Kích hoạt extension ​

Cài xong file extension, cần bật nó trong file cấu hình PHP. ServBay hỗ trợ bật qua giao diện đồ họa:

  • Mở ứng dụng ServBay
  • Menu bên trái chọn Ngôn ngữ - PHP - PHP 8.3
  • Trang bên phải chuyển sang tab PHP, kéo xuống cuối, ở mục "Tham số bổ sung" thêm dòng: extension=imagick.so
  • Nhấn Lưu để ServBay tự động restart PHP và nạp extension mới

Biên dịch và thêm mô-đun cho PHP

Bước 8: Xác thực extension đã được nạp ​

Sau khi bật extension, cần restart package PHP trong ServBay để cấu hình mới có hiệu lực. Có thể làm qua giao diện quản lý ServBay, hoặc dùng dòng lệnh ServBay (xem tài liệu ServBay để lấy lệnh).

Sau khi restart, kiểm tra extension đã được nạp bằng:

bash
${SERVBAY_PACKAGE_FULL_PATH}/php/8.3/current/bin/php -m | grep imagick

Sử dụng chính PHP của ServBay, version tương ứng. Tham số -m liệt kê danh sách extension đã nạp. Nếu thành công sẽ hiện imagick trong kết quả.

Cách kiểm tra chi tiết hơn: tạo file PHP (ví dụ info.php) chứa <?php phpinfo(); ?> ở thư mục gốc của web:

  • macOS: /Applications/ServBay/www
  • Windows: C:\ServBay\www

Truy cập qua trình duyệt: http://localhost/info.php hoặc tên miền bạn khai báo trên ServBay. Tìm mục "imagick" trong page output để xác nhận extension đã enable và xem thông tin cấu hình, version...

Biên dịch mô-đun sqlsrv/pdo_sqlsrv cho PHP ​

sqlsrv và pdo_sqlsrv là hai extension chính thức giúp PHP kết nối SQL Server. Chúng dựa trên driver ODBC do Microsoft cung cấp. Nếu cần kết nối PHP trong ServBay tới SQL Server, bạn cần biên dịch và cài chúng. Sau đây là hướng dẫn chi tiết:

Chú ý: Các yêu cầu tiên quyết cực kỳ quan trọng

Trước khi build extension sqlsrv, phải cài đặt driver SQL Server ODBC của Microsoft và các công cụ liên quan. Các package này không đi kèm ServBay, bạn cần tự cài.

macOS ​

Nên dùng Homebrew để cài dependency. Nếu chưa có Homebrew, cài theo hướng dẫn trang chủ.

Lệnh cài driver ODBC và công cụ qua Homebrew như sau. Có thể bạn sẽ cần xác nhận EULA (set biến HOMEBREW_ACCEPT_EULA=Y):

bash
brew tap microsoft/mssql-release https://github.com/Microsoft/homebrew-mssql-release
brew update
HOMEBREW_ACCEPT_EULA=Y brew install msodbcsql18 mssql-tools18

Thư viện thường nằm tại /opt/homebrew/ (cho Mac chip Apple Silicon) hoặc /usr/local/ (cho Intel Mac). Chú ý khi dẫn đường biên dịch.

Windows ​

Tải và cài đặt từ Microsoft chính thức:

Hãy đảm bảo các dependency đã được cài hoàn chỉnh trước khi build extension.

Mẹo nhỏ

sqlsrv và pdo_sqlsrv là hai extension độc lập, cần build riêng. Các bước đều giống nhau, hướng dẫn dưới lấy sqlsrv làm ví dụ.

Bước 1: Cài driver và tool ODBC của Microsoft ​

(Như đã trình bày ở trên, bạn cần cài sẵn msodbcsql18 và mssql-tools18 qua Homebrew.)

Bước 2: Tải source mô-đun sqlsrv ​

Truy cập PECL để lấy source: PECL sqlsrv. Ví dụ version 5.12.0:

bash
wget https://pecl.php.net/get/sqlsrv-5.12.0.tgz  # sqlsrv
wget https://pecl.php.net/get/pdo_sqlsrv-5.12.0.tgz  # pdo_sqlsrv

Bước 3: Giải nén và chuyển vào thư mục mã nguồn ​

bash
tar zxvf sqlsrv-5.12.0.tgz
cd sqlsrv-5.12.0

# Với pdo_sqlsrv cũng làm tương tự, các bước bên dưới dùng sqlsrv minh họa.

Bước 4: Chuẩn bị môi trường build (phpize) ​

Sau khi vào thư mục mã nguồn, chạy đúng phpize của PHP bạn muốn build (ví dụ PHP 8.3):

bash
${SERVBAY_PACKAGE_FULL_PATH}/php/8.3/current/bin/phpize

Bước 5: Cấu hình build (khai báo đường dẫn dependency) ​

Chạy script configure, chú ý phải set environment LDFLAGS và CPPFLAGS để chỉ đường dẫn tìm thư viện và header. Điều này giúp script tìm được các file cần thiết. Vẫn dùng option --with-php-config để chỉ PHP version muốn build extension.

Tùy hệ máy bạn (Intel hoặc Apple Silicon — /usr/local hoặc /opt/homebrew), chỉnh lại đường dẫn tương ứng. Ví dụ Homebrew tại /opt/homebrew:

bash
export LDFLAGS="-L/opt/homebrew/lib ${LDFLAGS}"
export CPPFLAGS="-I/opt/homebrew/opt/unixodbc/include -I/opt/homebrew/include ${CPPFLAGS}" # Thêm /opt/homebrew/include để đảm bảo tìm được tất cả header
./configure --with-php-config=${SERVBAY_PACKAGE_FULL_PATH}/php/8.3/current/bin/php-config
  • LDFLAGS: Đường dẫn cho trình link thư viện. -L/opt/homebrew/lib thường là nơi Homebrew cài đặt thư viện.
  • CPPFLAGS: Đường dẫn cho trình tiền xử lý C/C++. -I/opt/homebrew/opt/unixodbc/include chỉ tới file header của unixODBC. -I/opt/homebrew/include thêm khả năng nhận đầy đủ các file header cần thiết. ${CPPFLAGS} và ${LDFLAGS} giữ lại các design của môi trường build ServBay.

Bước 6: Biên dịch và cài đặt ​

Sau khi cấu hình xong, chạy:

bash
make -j ${CPU_NUMBER}
make install

Lệnh install sẽ tự copy các file sqlsrv.so và pdo_sqlsrv.so (nếu build cả hai) vào thư mục extension đúng của ServBay.

Bước 7: Kích hoạt extension ​

Mở giao diện ServBay để enable extension:

  • Mở ứng dụng ServBay
  • Menu trái điều hướng tới Ngôn ngữ - PHP - PHP 8.3
  • Trang phải chuyển sang tab PHP, kéo xuống cuối cùng ở "Tham số bổ sung", nhập: extension=sqlsrv.so và extension=pdo_sqlsrv.so
  • Nhấn Lưu, PHP sẽ tự restart và đọc mô-đun vừa thêm

Biên dịch và thêm mô-đun cho PHP

Bước 8: Xác thực extension đã được nạp ​

Sau khi bật extension, bắt buộc phải restart package PHP để nhận cấu hình mới.

Sau đó kiểm tra việc nạp extension bằng:

bash
${SERVBAY_PACKAGE_FULL_PATH}/php/8.3/current/bin/php -m | grep sqlsrv
${SERVBAY_PACKAGE_FULL_PATH}/php/8.3/current/bin/php -m | grep pdo_sqlsrv

Nếu thành công, kết quả sẽ hiện ra sqlsrv và pdo_sqlsrv. Bạn có thể kiểm tra chi tiết qua phpinfo() tương tự như với imagick.

Câu hỏi thường gặp (FAQ) ​

  • Hỏi: Biên dịch báo lỗi "Cannot find autoconf" hoặc lỗi tương tự?
    • Đáp: Gần như chắc chắn do chưa khởi tạo chính xác môi trường build ServBay. Quay lại phần "Yêu cầu tiên quyết" đầu bài, kiểm tra kỹ và làm đúng theo tài liệu Biên dịch lại package với ServBay. Đảm bảo các tool như autoconf, automake, libtool đã cài và các biến môi trường đã thiết lập. Mở terminal mới sau khi chạy script khởi tạo để mọi biến có hiệu lực.
  • Hỏi: Chạy script configure bị fail, báo không tìm library hoặc file header?
    • Đáp: Thường là do thiếu library/hay header file cần thiết hoặc đã cài nhưng không đúng đường dẫn.
      • Với imagick: Kiểm tra đã cài ImageMagick development library (brew install imagemagick).
      • Với sqlsrv: Bắt buộc phải cài driver ODBC Microsoft (msodbcsql18), mssql-tools18 qua Homebrew như phần tiên quyết. Ngoài ra, phải đảm bảo khi chạy ./configure, các biến LDFLAGS và CPPFLAGS đã chỉ đúng các thư mục thư viện/header (/opt/homebrew/lib, /opt/homebrew/opt/unixodbc/include).
      • Kiểm tra trong biến môi trường build ServBay có thêm được path của Homebrew chưa (nếu dependency cài qua Homebrew). Nếu thiếu cần add thủ công vào PATH.
  • Hỏi: Fail khi chạy make hoặc make install?
    • Đáp: Có thể do nhiều nguyên nhân:
      • Thiếu dependency build: Xem kỹ output lỗi, để biết thiếu file/thư viện nào rồi cài hoặc chỉnh đường dẫn cho đúng.
      • Sai cấu hình: Quay lại bước cấu hình, nhất là option --with-php-config phải đúng phiên bản PHP ServBay.
      • Lỗi quyền truy cập: Nếu thư mục cài thiếu quyền ghi, có thể thử sudo make install (chú ý, cần hiểu kỹ nguy cơ liên quan tới quyền).
      • Lỗi source: Kiểm tra lại mã nguồn tải về có bị hỏng hay không.
  • Hỏi: Đã sinh file .so bỏ đúng vào thư mục extension, đã enable bên .ini, nhưng chạy php -m hoặc phpinfo() lại không thấy extension?
    • Đáp:
      • Nguyên nhân phổ biến nhất: Chưa restart PHP package trong ServBay. Cần phải restart hoàn toàn PHP package của phiên bản bạn cài, chỉ reload trang web hoặc reset web server là không đủ.
      • Sai cú pháp file .ini: Kiểm tra dòng cấu hình dạng extension=modulename.so có bị lỗi chính tả hoặc format.
      • Sai đường dẫn thư mục extension: Kiểm tra thông số extension_dir trong php.ini đã trỏ đúng tới thư mục ServBay extension. Có thể xác thực qua lệnh php-config --extension-dir.
      • File extension bị lỗi hoặc không tương thích với PHP: Biên dịch lại từ đầu, kiểm tra source và PHP version, xem error log trong thư mục logs của ServBay.

Tổng kết ​

Theo hướng dẫn trên, bạn có thể biên dịch và cài đặt thành công các extension PHP tùy chỉnh như imagick và sqlsrv trên môi trường phát triển local ServBay. Các điểm cần ghi nhớ:

  1. Khởi tạo môi trường build ServBay đúng cách: Đây là tiền đề cho mọi thao tác build sau đó.
  2. Chỉ định chính xác phiên bản PHP: Khi dùng phpize và php-config, luôn dùng đường dẫn đầy đủ tới phiên bản cần build.
  3. Xử lý dependency chuẩn: Cài đủ mọi thư viện và công cụ yêu cầu, đưa vào biến môi trường (LDFLAGS, CPPFLAGS) hoặc option cấu hình khi chạy ./configure để script tìm đủ dependency.
  4. Bật extension đúng cách: Sửa file .ini trong thư mục conf.d, thêm dòng extension=ten_mo_dun.so để enable extension.
  5. Restart package PHP trong ServBay: Đảm bảo extension mới được nạp và hoạt động.

ServBay cung cấp một môi trường phát triển local linh hoạt hỗ trợ đa dạng các nhu cầu lập trình. Ngoài các mô-đun PHP, ServBay cũng tích hợp MySQL, PostgreSQL, MongoDB, Redis, Caddy, Nginx, Apache, Node.js, Python, Go, Java, .NET, Ruby, Rust..., cùng nhiều tiện ích như tự đăng ký SSL thật qua ACME, cài đặt nhanh CORS, tự động backup dữ liệu (bao gồm cài đặt, website, database, chứng chỉ SSL), reset mật khẩu root database, ServBay User CA và ServBay Public CA cho hỗ trợ HTTPS local...

Với hướng dẫn này, bạn sẽ dễ dàng bổ sung tính năng vào PHP và nâng cao hiệu quả phát triển web trên ServBay. Nếu gặp vấn đề ngoài nội dung trên, hãy tham khảo thêm tài liệu chính thức hoặc cộng đồng ServBay để được hỗ trợ nhanh chóng.