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 fileconfig.m4
và tạo script tiêu chuẩnconfigure
(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... Scriptconfigure
sẽ gọiphp-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
1
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
1
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
1
2
2
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
1
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
1
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
1
2
2
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
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
1
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
1
2
3
2
3
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:
- Truy cập Microsoft ODBC Driver for SQL Server
- Chọn đúng phiên bản cho hệ thống của bạn
- Sau khi cài, xác nhận driver khả dụng trong hệ thống
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
1
2
2
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.
1
2
3
4
2
3
4
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
1
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
1
2
3
2
3
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
1
2
2
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
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
1
2
2
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ếnLDFLAGS
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
.
- Với
- Đá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.
- Hỏi: Fail khi chạy
make
hoặcmake 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.
- Đáp: Có thể do nhiều nguyên nhân:
- Hỏi: Đã sinh file
.so
bỏ đúng vào thư mục extension, đã enable bên.ini
, nhưng chạyphp -m
hoặcphpinfo()
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ạngextension=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
trongphp.ini
đã trỏ đúng tới thư mục ServBay extension. Có thể xác thực qua lệnhphp-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.
- Đáp:
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ớ:
- 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 đó.
- 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. - 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. - Bật extension đúng cách: Sửa file
.ini
trong thư mục conf.d, thêm dòngextension=ten_mo_dun.so
để enable extension. - 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.