Biên dịch và cài đặt module PHP tùy chỉnh trong ServBay (macOS)

ServBay là một môi trường phát triển Web local mạnh mẽ dành riêng cho macOS, tích hợp sẵn nhiều gói phần mềm để phục vụ nhu cầu phát triển Web hiện đại. Ứng dụng này cài sẵn PHP, Node.js, Python, Go, Java, các hệ quản trị cơ sở dữ liệu (như MySQL, PostgreSQL, MongoDB), bộ nhớ đệm (Redis) và các máy chủ Web như Caddy, Nginx, Apache. ServBay hỗ trợ đa phiên bản cho từng phần mềm, giúp bạn dễ dàng chuyển đổi môi trường tùy theo yêu cầu dự án.

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

Bài viết này sẽ hướng dẫn chi tiết cách biên dịch và cài đặt các module tùy chỉnh cho phiên bản PHP bạn đang sử dụng trong môi trường ServBay. Chúng tôi sẽ lấy ví dụ với module xử lý ảnh phổ biến imagick và module driver kết nối Microsoft SQL Server sqlsrv để minh họa quy trình, hỗ trợ bạn bổ sung chức năng cho PHP trong ServBay một cách dễ dàng.

Điều kiện tiên quyết

Lưu ý quan trọng

Trước khi tiến hành biên dịch bất kỳ module PHP nào, bước cực kỳ quan trọng là khởi tạo môi trường biên dịch và cài đặt biến môi trường hệ thống đúng theo hướng dẫn chính thức từ ServBay. Đây là nền tảng để bạn biên dịch thành công các gói phần mềm (bao gồm cả module PHP) trên ServBay. Nếu bỏ qua hoặc thực hiện chưa đầy đủ bước này, rất có thể quá trình biên dịch sau đó sẽ thất bại với các lỗi như không tìm thấy lệnh, thư viện hoặc file header.

Script khởi tạo môi trường biên dịch của ServBay sẽ thiết lập các biến môi trường cần thiết, ví dụ như PATH (trỏ tới công cụ build nội bộ của ServBay), SERVBAY_PACKAGE_FULL_PATH (đường dẫn gốc đến các gói phần mềm của ServBay), và CPU_NUMBER (số lõi CPU dùng để biên dịch song song). Những biến này cực kỳ quan trọng khi thực hiện các lệnh biên dịch tiếp theo.

Vui lòng tham khảo hướng dẫn chi tiết về khởi tạo môi trường tại: Biên dịch lại gói phần mềm với ServBay. Hãy chắc chắn rằng bạn đã hiểu rõ và thực hiện đầy đủ mọi bước theo chỉ dẫn trong tài liệu đó.

Trước khi tiếp tục biên dịch module, hãy đảm bảo bạn đã khởi tạo thành công môi trường biên dịch của ServBay và các biến môi trường liên quan đã được thiết lập đúng trong phiên làm việc terminal hiện tại.

Tại sao cần chỉ định phiên bản PHP

Một điểm mạnh lớn của ServBay là hỗ trợ cài đặt và vận hành nhiều phiên bản PHP song song trên cùng một hệ thống. Nhờ đó, lập trình viên có thể chuyển đổi môi trường PHP linh hoạt, phù hợp với từng dự án. Tuy nhiên, khi biên dịch module PHP, bạn phải chắc chắn thao tác trên đúng phiên bản PHP mong muốn. Các công cụ thiết yếu như phpize và php-config đều gắn liền với từng phiên bản PHP cụ thể.

• phpize: Script để chuẩn bị môi trường build module mở rộng cho PHP. Nó đọc file config.m4 và tạo script configure tiêu chuẩn - bước đầu tiên khi biên dịch phần mềm C/C++.
• php-config: Script cung cấp cấu hình chi tiết của bản cài PHP cụ thể, như cờ compile, đường dẫn file header, thư viện, thư mục cài đặt extension,... Script configure sẽ sử dụng php-config để lấy các thông tin này, bảo đảm module build ra tương thích với đúng phiên bản PHP đó.

Vì vậy, khi sử dụng phpize, php-config hoặc các lệnh liên quan tới build PHP, tuyệt đối phải chỉ rõ đường dẫn đầy đủ tới phiên bản PHP bạn muốn biên dịch module cho nó. Ví dụ, để build module cho PHP 8.3 cài đặt bởi ServBay, hãy dùng /Applications/ServBay/package/php/8.3/current/bin/phpize và /Applications/ServBay/package/php/8.3/current/bin/php-config. Việc này giúp module bạn build ra chạy đúng với môi trường PHP, tránh các lỗi không tương thích, thiếu biểu tượng, hoặc lỗi khi chạy.

Tất cả các ví dụ trong tài liệu này sẽ dùng PHP 8.3 trong ServBay để minh họa. Khi thao tác thực tế, hãy thay đổi đường dẫn theo phiên bản PHP bạn cần build module.

Biên dịch module PHP imagick

Module imagick là một extension phổ biến cho PHP, dựa trên thư viện dòng lệnh ImageMagick, đem đến hàng loạt chức năng xử lý ảnh. Với imagick, bạn có thể thao tác như thu nhỏ, cắt, chuyển đổi định dạng, thêm watermark, ghép ảnh,... trong PHP một cách dễ dàng. Dưới đây là các bước chi tiết để biên dịch và cài đặt module imagick cho phiên bản PHP cụ thể trong ServBay:

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

Module imagick phụ thuộc vào thư viện ImageMagick trên hệ thống. Trên macOS, nên cài qua Homebrew. Nếu chưa cài Homebrew, hãy truy cập Trang chủ Homebrew để hướng dẫn cài đặt.

Mở Terminal và chạy lệnh sau để cài ImageMagick cùng các thư viện phát triển:

brew install imagemagick

Bước 2: Tải mã nguồn module imagick

Tiếp theo, cần tải mã nguồn module imagick từ trang PECL chính thức. Vào Trang PECL imagick để chọn phiên bản mong muốn (thường chọn bản stable mới nhất), lấy link tải về. Ví dụ dưới đây sử dụng phiên bản 3.7.0:

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, sử dụng lệnh tar để giải nén và dùng cd chuyển vào thư mục mã nguồn vừa giải nén:

tar zxvf imagick-3.7.0.tgz
cd imagick-3.7.0

Bước 4: Chuẩn bị môi trường biên dịch (sử dụng phpize)

Sau khi vào thư mục mã nguồn, hãy dùng phpize tương ứng đúng phiên bản PHP cần build. Như đã trình bày, nhớ sử dụng đường dẫn đầy đủ tới phpize của PHP mục tiêu. Ví dụ, muốn build cho PHP 8.3 và đã đặt biến SERVBAY_PACKAGE_FULL_PATH:

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

Chạy lệnh xong, nó sẽ kiểm tra file config.m4 trong mã nguồn và sinh ra script configure cùng các file cần thiết để build. Kết quả sẽ báo quá trình chuẩn bị môi trường đã sẵn sàng.

Bước 5: Cấu hình các tuỳ chọn biên dịch

Chạy script configure vừa sinh ra để thiết lập tùy chọn build module. Bắt buộc phải chỉ định tham số --with-php-config trỏ tới đường dẫn php-config của phiên bản PHP mục tiêu, để đảm bảo lấy đúng cấu hình môi trường build.

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

Script configure sẽ kiểm tra, tìm kiếm thư viện ImageMagick và file header phụ thuộc, đồng thời dựa trên thông tin PHP nhận được sinh ra file Makefile. Nếu gặp lỗi, nguyên nhân thường do thiếu thư viện phụ thuộc hoặc trỏ sai đường dẫn.

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

Sau khi tạo thành công Makefile, đã có thể tiến hành biên dịch. Dùng lệnh make để build, sau đó dùng make install để copy file module vào thư mục extension của PHP. Biến ${CPU_NUMBER} (đặt ở bước khởi tạo môi trường ServBay) giúp chỉ định số tiến trình biên dịch song song để tăng tốc.

make -j ${CPU_NUMBER}
make install

Lệnh make install sẽ tự động copy file imagick.so sau build vào thư mục extension chuẩn tương ứng với PHP version trong ServBay (ví dụ /Applications/ServBay/package/php/8.3/current/lib/php/extensions/no-debug-non-zts-YYYYMMDD/, đường dẫn cụ thể tùy theo PHP).

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

Sau khi cài file module, cần bật extension trong file cấu hình của PHP phiên bản mong muốn. ServBay cung cấp giao diện đồ họa để thao tác việc này.

• Mở ứng dụng ServBay
• Từ menu bên trái, chọn Ngôn ngữ - PHP - PHP 8.3
• Ở trang bên phải, chọn tab PHP, cuộn xuống cuối, nhập extension=imagick.so vào phần “Tham số bổ sung”
• Nhấn Lưu, PHP sẽ tự động khởi động lại và đọc cấu hình module mới

Bước 8: Kiểm tra module đã được nạp

Sau khi kích hoạt, cần khởi động lại package PHP trong ServBay để cấu hình mới có hiệu lực. Bạn có thể dùng giao diện quản lý ServBay, tìm đúng package PHP rồi bấm nút khởi động lại; hoặc sử dụng công cụ dòng lệnh ServBay (cụ thể xin tham khảo tài liệu ServBay).

Sau khi restart PHP, kiểm tra module imagick đã được nạp hay chưa với lệnh sau:

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

Lệnh này đảm bảo bạn gọi đúng binary PHP của ServBay phiên bản mong muốn. Tham số -m liệt kê toàn bộ module PHP đang hoạt động. Nếu module đã nạp, dòng imagick sẽ hiển thị trong kết quả.

Một cách kiểm tra chi tiết hơn là tạo một file PHP trong thư mục gốc web (mặc định /Applications/ServBay/www), đặt tên như info.php và có nội dung <?php phpinfo(); ?>. Sau đó, mở trình duyệt truy cập http://localhost/info.php hoặc domain đã cấu hình trên ServBay. Trên trang phpinfo(), tìm kiếm từ khoá "imagick" để xem module đã bật, cấu hình và phiên bản.

Biên dịch module PHP sqlsrv/pdo_sqlsrv

Module sqlsrv và pdo_sqlsrv là extension PHP chính thức cho phép kết nối, thao tác database Microsoft SQL Server. Module này dùng driver ODBC của Microsoft. Nếu bạn cần kết nối SQL Server trong môi trường PHP của ServBay, hãy làm theo các bước dưới đây để biên dịch và cài đặt hai module này.

Lưu ý: Điều kiện tiên quyết quan trọng

Để compile và cài đặt sqlsrv trên macOS, bạn bắt buộc phải cài đặt trước driver ODBC SQL Server (msodbcsql18) và công cụ dòng lệnh (mssql-tools18) do Microsoft cung cấp. Những gói này không có sẵn trong ServBay, bạn phải tự cài thủ công.

Khuyến khích sử dụng Homebrew để cài đặt. Nếu chưa có Homebrew, truy cập Trang chủ Homebrew để cài.

Cách cài đặt driver Microsoft ODBC và công cụ qua Homebrew như sau. Lưu ý có thể bạn cần đồng ý điều khoản (qua biến môi trường HOMEBREW_ACCEPT_EULA=Y).

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

Hãy đảm bảo các phụ thuộc này đã cài xong trước khi compile module. Thông thường, chúng sẽ nằm tại /opt/homebrew/ (Apple Silicon Mac) hoặc /usr/local/ (Intel Mac). Khi biên dịch cần chỉ ra các đường dẫn này chính xác.

Lưu ý

sqlsrv và pdo_sqlsrv là hai module riêng biệt, cần biên dịch riêng, nhưng các bước thực hiện tương tự nhau, dưới đây minh hoạ với sqlsrv.

Bước 1: Cài driver ODBC và công cụ Microsoft

(Như trên, đây là bước bắt buộc, hãy cài msodbcsql18 và mssql-tools18 bằng Homebrew.)

Bước 2: Tải mã nguồn module sqlsrv

Từ trang PECL chính thức, tải mã nguồn hai module sqlsrv và pdo_sqlsrv. Vào Trang PECL sqlsrv để lấy phiên bản mong muốn. Ví dụ bài viết dùng bản 5.12.0:

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 mã nguồn và chuyển vào thư mục

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

tar zxvf sqlsrv-5.12.0.tgz
cd sqlsrv-5.12.0

# Đối với pdo_sqlsrv cũng tương tự, các bước sau đây sẽ chỉ làm ví dụ với sqlsrv

Bước 4: Chuẩn bị môi trường biên dịch (sử dụng phpize)

Vào thư mục mã nguồn, sử dụng phpize đúng phiên bản PHP. Giả sử bạn cần build cho PHP 8.3 và đã thiết lập SERVBAY_PACKAGE_FULL_PATH:

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

Bước 5: Cấu hình tuỳ chọn build (bao gồm đường dẫn phụ thuộc)

Chạy script configure để cấu hình. Do sqlsrv phụ thuộc nhiều vào driver ODBC của Microsoft cài qua Homebrew và unixODBC, trước khi chạy ./configure, bạn cần set các biến môi trường LDFLAGS và CPPFLAGS để báo cho script biết đường dẫn thư viện và header. Đồng thời vẫn phải chỉ định --with-php-config đúng đường dẫn PHP.

Lưu ý thay đổi đường dẫn Homebrew tương ứng với máy của bạn (/usr/local cho Intel; /opt/homebrew cho Apple Silicon). Ví dụ sau giả định dùng /opt/homebrew:

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 để chắc chắn mọi file header được tìm thấy
./configure --with-php-config=${SERVBAY_PACKAGE_FULL_PATH}/php/8.3/current/bin/php-config

• LDFLAGS: Chỉ định đường dẫn tìm kiếm file thư viện cho trình liên kết, -L/opt/homebrew/lib là nơi Homebrew cài thư viện.
• CPPFLAGS: Chỉ định đường dẫn tìm kiếm file header cho trình tiền xử lý C/C++, bổ sung cả đường dẫn unixODBC và thư viện tổng quát. ${CPPFLAGS} và ${LDFLAGS} giúp giữ lại tham số từ ServBay nếu có.

Bước 6: Biên dịch và cài module

Sau khi sinh thành công Makefile, dùng lệnh dưới đây để biên dịch và cài đặt vào thư mục extension của PHP:

make -j ${CPU_NUMBER}
make install

make install sẽ copy file sqlsrv.so và pdo_sqlsrv.so (nếu build cả hai) vào thư mục extension tiêu chuẩn của PHP theo cấu hình ServBay.

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

Sau khi đã cài module, cần bật nó trong file cấu hình của PHP. ServBay cung cấp giao diện để thực hiện:

• Mở ứng dụng ServBay
• Từ menu trái vào Ngôn ngữ - PHP - PHP 8.3
• Ở trang phải, mở tab PHP, kéo xuống cuối phần “Tham số bổ sung”, điền extension=sqlsrv.so và extension=pdo_sqlsrv.so
• Nhấn Lưu, PHP sẽ tự động restart và nạp module mới

Bước 8: Kiểm tra module đã nạp

Khi đã bật module, hãy restart lại package PHP trong ServBay để cấu hình mới có hiệu lực.

Sau khi restart PHP, kiểm tra module sqlsrv (và pdo_sqlsrv) đã nạp thành công chưa:

${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 module đã nạp, kết quả sẽ xuất hiện sqlsrv và pdo_sqlsrv như mong muốn. Ngoài ra, bạn cũng có thể dùng phpinfo() để xác nhận chi tiết trạng thái các module.

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

• Hỏi: Bị lỗi "Cannot find autoconf" hoặc tương tự khi biên dịch?
  • Đáp: Hầu như chắc chắn là bạn chưa khởi tạo môi trường compile của ServBay đúng cách. Quay lại phần “Điều kiện tiên quyết” ở đầu tài liệu này và kiểm tra lại theo hướng dẫn Biên dịch lại gói phần mềm với ServBay, bảo đảm các công cụ build (autoconf, automake, libtool,...) đã cài xong và trỏ đúng qua biến môi trường. Thường chỉ cần chạy lại script khởi tạo và mở lại terminal là sửa được lỗi này.
• Hỏi: Script configure báo lỗi không tìm thấy thư viện hay file header?
  • Đáp: Module đang thiếu file thư viện hệ thống hoặc file header (hoặc có rồi nhưng không tìm thấy).
    • Với imagick, đảm bảo đã cài đủ thư viện phát triển ImageMagick: brew install imagemagick.
    • Với sqlsrv, phải chắc chắn đã cài đủ ODBC Driver và mssql-tools bằng Homebrew, đồng thời cấu hình đúng biến môi trường LDFLAGS, CPPFLAGS để trỏ đường dẫn thư viện, header (ví dụ /opt/homebrew/lib, /opt/homebrew/opt/unixodbc/include).
    • Kiểm tra môi trường compile của ServBay đã nhận đủ đường dẫn Homebrew (nếu cài phụ thuộc qua Homebrew), hoặc bổ sung bằng tay thư mục bin của Homebrew vào biến PATH trong môi trường build của ServBay.
• Hỏi: Lỗi khi chạy make hoặc make install?
  • Đáp: Có thể do nhiều nguyên nhân:
    • Thiếu phụ thuộc: Kiểm tra kỹ log lỗi, thường nó báo thiếu file/thư viện nào, hãy cài tương ứng.
    • Tham số cấu hình sai: Quay lại bước configure, kiểm tra kỹ tham số truyền vào, nhất là đường dẫn --with-php-config.
    • Quyền hạn: Lệnh make install cần chép file vào thư mục extension của ServBay. Nếu chưa đủ quyền (do chưa khởi tạo đúng môi trường, chưa set quyền), có thể thử sudo make install (nhưng cẩn trọng, chỉ làm khi hiểu rõ rủi ro).
    • Mã nguồn hỏng: Kiểm tra lại file mã nguồn module đã tải về chưa bị lỗi hoặc thiếu file.
• Hỏi: Đã có file .so ở thư mục extension, file .ini cũng đã bật, nhưng php -m hoặc phpinfo() không thấy module?
  • Đáp:
    • Nguyên nhân phổ biến nhất: Chưa restart lại package PHP của ServBay sau khi thay cấu hình. Hãy chắc chắn bạn đã restart hoàn toàn package PHP mong muốn. Mỗi web server (Caddy/Nginx/Apache) restart riêng không đủ, phải restart package PHP.
    • Lỗi sai cú pháp file .ini: Kiểm tra kỹ file .ini viết đúng dạng extension=ten_module.so.
    • Đường dẫn extension sai: Rà soát thiết lập extension_dir trong php.ini phải chính xác tới thư mục extension mặc định của ServBay cho phiên bản PHP đó. make install sẽ chép dựa theo kết quả của lệnh php-config --extension-dir, có thể dùng lệnh này để xác nhận.
    • File module lỗi hoặc không tương thích PHP: Rebuild lại, kiểm tra quá trình không có báo lỗi, mã nguồn phải đúng bản tương thích PHP đang dùng. Xem log PHP của ServBay (nằm trong thư mục logs của ServBay) có lỗi gì khi load module.

Tổng kết

Làm theo từng bước hướng dẫn chi tiết ở bài viết này, bạn hoàn toàn có thể tự biên dịch và cài đặt thành công các module PHP tùy chỉnh như imagick, sqlsrv vào môi trường phát triển local trên macOS với ServBay. Những điểm then chốt:

1. Khởi tạo môi trường build của ServBay thật chuẩn xác và đầy đủ: Nền tảng cho mọi thao tác biên dịch về sau.
2. Chỉ định và sử dụng đúng đường dẫn phiên bản PHP: Khi dùng phpize và php-config, luôn trỏ đúng tới bản PHP mình nhắm tới trong ServBay.
3. Xử lý đủ mọi phụ thuộc ngoài: Tùy mỗi module, hãy cài trước thư viện hoặc công cụ hệ thống cần thiết (ImageMagick, ODBC Driver,...) và truyền đúng path và biến môi trường (LDFLAGS, CPPFLAGS) ở bước ./configure.
4. Kích hoạt module chuẩn: Trong thư mục conf.d của PHP phiên bản đích, tạo/sửa file .ini với dòng extension=ten_module.so để load module.
5. Luôn restart package PHP của ServBay: Để các module đã cài và cấu hình mới có hiệu lực.

ServBay là môi trường phát triển local mạnh mẽ, hỗ trợ tối đa nhu cầu phát triển của bạn với khả năng tích hợp nhiều công nghệ ngoài PHP như MySQL, PostgreSQL, MongoDB, Redis, Caddy, Nginx, Apache, Node.js, Python, Go, Java, .NET, Ruby, Rust,... cùng nhiều tính năng bổ sung như xin chứng chỉ SSL thật qua ACME, cấu hình CORS nhanh, backup tự động (từ cài đặt, project, database, chứng chỉ SSL), reset mật khẩu root database, cấp phát CA nội bộ cho phát triển HTTPS,... giúp tối ưu quy trình làm việc và phát triển chuyên nghiệp.

Hy vọng hướng dẫn này giúp bạn chủ động bổ sung các tính năng cần thiết cho môi trường PHP trên ServBay và phát triển Web hiệu quả hơn. Nếu gặp vướng mắc, bạn có thể tra cứu thêm tài liệu chính thức hoặc tìm sự hỗ trợ từ cộng đồng ServBay.