Bu rehber, CustomBuild kullanan bir DirectAdmin sunucusunda eski (legacy) bir Phalcon 3.4 uygulamasını çalışır durumda tutmak zorunda olan sistem yöneticileri için hazırlandı. İhtiyacınız olan üç şey var: sitenizin gerçekten kullandığı PHP 7.3 için derlenmiş bir phalcon.so, CustomBuild yeniden derlemelerinden (rebuild) etkilenmeyen bir ini dosyası ve destek süresi dolmuş iki bileşenden kurtulmak için bir plan. Siteniz zaten PHP 8.x ile çalışıyorsa elle derlemeye gerek yok; DirectAdmin'e Phalcon nasıl kurulur? başlığında anlatılan CustomBuild seçeneğini kullanın.
Phalcon ve PHP uyumluluk tablosu
Phalcon bir C eklentisidir (extension); her sürüm yalnızca hedeflediği PHP sürümleriyle derlenebilir. Aşağıdaki aralıklar, cphalcon değişiklik günlüklerinden (changelog) ve her sürümün package.xml dosyasında bildirilen PHP sınırlarından alındı:| Phalcon | PHP sürümleri | Not |
|---|---|---|
| 3.4.0 – 3.4.2 | 5.5 – 7.2 | PHP 7.3 desteği henüz başlangıç düzeyindeydi; tam destek 3.4.3 ile geldi |
| 3.4.3 – 3.4.5 | 5.5 – 7.3 | 3.4.4, PHP 7.3.6 ile görülen çökmeleri (segfault) giderdi; 3.4.5 (30 Ekim 2019) son 3.x sürümüdür |
| 4.0.x – 4.1.x | 7.2 – 7.4 | Phalcon'dan önce yüklenmesi gereken ayrı bir PSR eklentisi ister; son 4.x etiketi 4.1.3'tür |
| 5.0 – 5.4 | 7.4.1 – 8.1; 5.2.0'dan itibaren 8.2 | PSR eklentisi artık gerekmez |
| 5.5 – 5.10 | 8.0 – 8.3; 5.9.0'dan itibaren 8.4 | 5.5.0 (Aralık 2023) alt sınırı PHP 8.0'a yükseltti |
| 5.11 ve sonrası | 8.1 ve üzeri (üst sınır bildirilmiyor) | Güncel seri; 5.23.0 Ekim 2026'da yayımlandı |
Kısacası PHP 7.3 için 3.4.5'i derleyin; 7.3 düzeltmelerinin tamamı bu sürümde. Hiçbir 3.x sürümü PHP 7.4 veya 8.x desteği bildirmiyor; bu yüzden PHP 7.3'ü bırakan bir uygulama Phalcon 3'ü de bırakmak zorunda.
Önkoşullar ve doğru PHP 7.3 araçları
- Root SSH erişimi, güncel bir yedek ya da anlık görüntü (snapshot) ve PHP yeniden başlatılacağı için bir bakım penceresi.
- CustomBuild ile php1_release … php9_release yuvalarından (slot) birine kurulmuş PHP 7.3.
- gcc, make, autoconf (phpize bunu ister), git ya da curl ve Phalcon 3.4 belgelerinin listelediği PCRE geliştirme başlık dosyaları.
- Bellek: build/php7/64bits/phalcon.zep.c yaklaşık 5 MB'lık tek bir C dosyasıdır; 1 GB civarında ya da daha az RAM'i olan bir VPS'te derleyici, bellek yetmediği için sonlandırılabilir. Geçici takas alanı (swap) eklemeyi Sorun giderme bölümünde bulabilirsiniz.
CustomBuild her PHP sürümünü ayrı bir dizine kurar; 7.3'ün araçları /usr/local/php73/bin altındadır. PATH'te ilk bulunan php ve phpize normalde php1_release'e aittir; o yuva 7.3 değilse eklentiyi bunlarla derlemek, aşağıda anlatılan API uyuşmazlığı hatasına yol açar. Yuvaları kontrol edin, her zaman tam yol kullanın ve sonradan karşılaştırmak için mevcut modül listesini kaydedin:
Bash:
grep -E '^php[1-9]_(release|mode)' /usr/local/directadmin/custombuild/options.conf
/usr/local/php73/bin/php -v
/usr/local/php73/bin/php-config --extension-dir
/usr/local/php73/bin/php --ini
mkdir -p /root/phalcon
/usr/local/php73/bin/php -m > /root/phalcon/php73-modules-before.txt
# derleme araçları: AlmaLinux, Rocky, CloudLinux, CentOS
yum install -y gcc make autoconf git pcre-devel
# derleme araçları: Debian, Ubuntu
apt-get install -y gcc make autoconf git libpcre3-devDerlemeden önce iki not. PHP, OpenSSL 3 desteğini resmi olarak ancak 8.1 sürümünde kazandı. Bu yüzden PHP 7.3'ün openssl eklentisi, AlmaLinux veya Rocky 9 ile Debian 12'de sistem kütüphanesi olan OpenSSL 3'e karşı ancak yamayla ya da daha eski bir OpenSSL'e bağlanarak derlenebilir. Bu rehber CustomBuild'in zaten kurduğu 7.3'ü esas alır; sunucunuz bu 7.3'ü koruyamıyor ya da yeniden derleyemiyorsa derleme araçlarıyla uğraşmak yerine geçişi planlayın. Ayrıca ./build update bu iş için gerekmez, çünkü PHP'yi değil CustomBuild'in kendisini günceller; ancak işiniz bitene kadar update_versions çalıştırmayın, PHP'yi yarı yolda yeniden derleyebilir. Bu komutlar SSH üzerinden CustomBuild update başlığında anlatılıyor.
1. Adım: v3.4.5 kaynak kodunu indirin
Bash:
cd /usr/local/src
git clone --depth 1 --branch v3.4.5 https://github.com/phalcon/cphalcon.git cphalcon-3.4.5
# git yoksa:
# curl -L -o cphalcon-3.4.5.tar.gz https://github.com/phalcon/cphalcon/archive/refs/tags/v3.4.5.tar.gz
# tar xzf cphalcon-3.4.5.tar.gz2. Adım: PHP 7.3'e karşı derleyin
Etiketteki build klasörü önceden üretilmiş C kodunu içerdiği için Zephir'e gerek yoktur. 64 bit bir sunucuda:
Bash:
cd /usr/local/src/cphalcon-3.4.5/build/php7/64bits
export CFLAGS="-mtune=native -O2 -fomit-frame-pointer"
export CPPFLAGS="-DPHALCON_RELEASE"
/usr/local/php73/bin/phpize
./configure --with-php-config=/usr/local/php73/bin/php-config --enable-phalcon
make
make install
Bash:
ls -l "$(/usr/local/php73/bin/php-config --extension-dir)/phalcon.so"
/usr/local/php73/bin/php -r 'echo ini_get("extension_dir"), PHP_EOL;'3. Adım: CustomBuild'in ezmeyeceği bir ini dosyasıyla etkinleştirin
Bu rehberin önceki sürümü php.ini'yi düzenliyor ve extension=phalcon.so satırının önündeki ";" işaretini silmenizi söylüyordu; oysa standart bir php.ini'de böyle bir satır yoktur. CustomBuild'in PHP'si /usr/local/php73/lib/php.conf.d içindeki bütün .ini dosyalarını alfabetik sırayla okur. CustomBuild bu dizinde kendi dosyalarını (belgelerine göre 10-directadmin.ini ve 50-webapps.ini) oluşturur; aynı belgeler, modül yüklemek için bu klasöre kendi dosyalarınızı ekleyebileceğinizi belirtir ve elle derlenen bir eklenti için ayrı bir 90-*.ini dosyası örneği verir. Böylece değişikliğiniz, php.ini dahil CustomBuild'in yönettiği her şeyden ayrı kalır:
Bash:
echo 'extension=phalcon.so' > /usr/local/php73/lib/php.conf.d/90-phalcon.ini
cp -p /usr/local/php73/lib/php.conf.d/90-phalcon.ini /root/phalcon/
/usr/local/php73/bin/php -m | grep -i phalcon
/usr/local/php73/bin/php -r 'echo \Phalcon\Version::get(), PHP_EOL;'4. Adım: PHP'yi çalıştıran servisi yeniden başlatın
Neyi yeniden başlatacağınız, options.conf'taki phpN_mode değerine bağlıdır:| PHP modu ve web sunucusu | Komut |
|---|---|
| php-fpm (CustomBuild varsayılanı); Apache, Nginx veya Nginx+Apache ile | systemctl restart php-fpm73 |
| LiteSpeed veya OpenLiteSpeed altında lsphp | /usr/local/lsws/bin/lswsctrl restart |
| Apache altında fastcgi (mod_fcgid) | systemctl restart httpd |
5. Adım: Web sitesinin gerçekte ne kullandığını doğrulayın
Komut satırı testi yalnızca /usr/local/php73/bin/php'nin Phalcon'u yüklediğini kanıtlar; web sitesi ise alan adına (domain) atanmış sürümle çalışır. DirectAdmin aynı anda dokuz PHP sürümüne kadar çalıştırabilir. php1_release varsayılan sürümdür ve phpMyAdmin, Roundcube gibi DirectAdmin web uygulamalarını (webapps) da o çalıştırır. Kullanıcılar alan adı başına başka bir sürümü Domain Setup sayfasındaki PHP sürüm seçiciden (PHP Version Selector) seçer; bunun için php_version_selector=1 olmalıdır (da config-get php_version_selector ile kontrol edin). Alt alan adlarının (subdomain) seçimi ayrı olabilir. Sitenin belge kök dizininde (document root) adı tahmin edilmesi zor geçici bir dosya oluşturun, örneğin pcheck-8d41.php. Uygulama Phalcon'un yaygın public/ klasörlü yapısını ve yönlendirme (rewrite) kurallarını kullanıyorsa bu dizin public_html/public/ olur:
PHP:
<?php
header('Content-Type: text/plain');
echo 'PHP: ', PHP_VERSION, ' (', PHP_SAPI, ')', PHP_EOL;
echo 'Phalcon: ', extension_loaded('phalcon') ? phpversion('phalcon') : 'NOT LOADED', PHP_EOL;
echo 'ini files: ', php_ini_scanned_files(), PHP_EOL;
?>
Bash:
cd /home/KULLANICI/domains/example.com/public_html # ya da public_html/public
chown KULLANICI:KULLANICI pcheck-8d41.php
curl -s https://example.com/pcheck-8d41.php
rm -f pcheck-8d41.phpSorun giderme
Modül API uyuşmazlığı (module API mismatch). Modül başka bir sürümün phpize veya php-config aracıyla derlenmiştir. Aşağıdaki çıktı, PHP 7.3'ün 7.4 için derlenmiş bir modülü yüklemeye çalıştığını gösterir:
Kod:
PHP Warning: PHP Startup: phalcon: Unable to initialize module
Module compiled with module API=20190902
PHP compiled with module API=20180731
These options need to matchUnable to load dynamic library 'phalcon.so' … No such file or directory. Dosya bu PHP'nin extension_dir dizininde değildir. 2. Adım'daki kontrolü tekrarlayın.
undefined symbol: …. Modül, onu yükleyen ikili dosyadan (binary) farklı PHP başlık dosyalarına karşı derlenmiştir (örneğin PATH'ten gelen bir dağıtım php-devel paketi) ya da bağımlı olduğu bir modülden önce yükleniyordur. /usr/local/php73'e karşı yeniden derleyin, 90- önekini koruyun ve php -m çıktısında PDO'nun göründüğünü kontrol edin.
Class 'Phalcon\Mvc\Model' not found. Eklenti, siteye hizmet veren PHP'de yüklü değildir. Genellikle alan adı başka bir sürümde çalışıyordur, PHP-FPM yeniden başlatılmamıştır ya da ini dosyası bir CustomBuild çalışmasından sonra kaybolmuştur. Tırnaklar ipucu verir: PHP 7.x Class 'Phalcon\Mvc\Model' not found, PHP 8.x ise Class "Phalcon\Mvc\Model" not found yazar. Yani 54 numaralı başlıktaki çift tırnaklı hata PHP 8'den geliyordu.
Cannot find autoconf. autoconf paketini kurun ve phpize'ı yeniden çalıştırın.
gcc: internal compiler error: Killed (program cc1). Derleyicinin belleği yetmemiştir. Geçici swap ekleyin, make'i yeniden çalıştırın, ardından swap'ı kaldırın:
Bash:
dd if=/dev/zero of=/swapfile-build bs=1M count=2048
chmod 600 /swapfile-build && mkswap /swapfile-build && swapon /swapfile-build
# make'i yeniden çalıştırın, ardından:
swapoff /swapfile-build && rm -f /swapfile-buildPHP 7.3.6 veya sonrasında segmentation fault (çökme). 3.4.4'ten önceki sürümlerde bu sorun vardır; 3.4.4, daha yeni bir Zephir ile derlenerek bunu giderdi. 3.4.5 kullanın.
CustomBuild yeniden derlemelerinden sonra Phalcon'u korumak
Girişte bağlantısı verilen 54 numaralı başlık tipik arızayı gösteriyor: bir CustomBuild güncellemesinden sonra Phalcon kaybolmuş ve site "Class not found" hatasıyla durmuştu. Elle yaptığınız değişikliklerin bir yeniden derlemede kaybolabileceğini varsayın ve onarımı otomatik hale getirin. Tüm 7.3.x sürümleri 20180731 modül API'sini kullanır (7.3.33 zaten son sürümdür); yani yeniden derlenen bir 7.3, derlediğiniz modülü geçersiz kılmaz ve çoğu zaman modülü yeniden kurmak ile ini dosyasını geri koymak yeterlidir. Aşağıdaki betiği /root/phalcon/reinstall-phalcon73.sh olarak kaydedin (nano kullanabilirsiniz):
Bash:
#!/bin/bash
# Eksikse CustomBuild PHP 7.3 için Phalcon 3.4.5'i yeniden kurar
PHPBIN=/usr/local/php73/bin/php
SRC=/usr/local/src/cphalcon-3.4.5/build/php7/64bits
INI=/usr/local/php73/lib/php.conf.d/90-phalcon.ini
RESTART="systemctl restart php-fpm73" # lsphp: /usr/local/lsws/bin/lswsctrl restart, fastcgi: systemctl restart httpd
CHANGED=0
[ -x "$PHPBIN" ] || exit 0
if [ ! -f "$INI" ]; then
cp -p /root/phalcon/90-phalcon.ini "$INI" && CHANGED=1
fi
if ! "$PHPBIN" -m | grep -qx phalcon; then
make -C "$SRC" install && CHANGED=1
fi
[ "$CHANGED" = 1 ] && $RESTART
if "$PHPBIN" -m | grep -qx phalcon; then echo "phalcon73: OK"; else echo "phalcon73: eksik, elle kontrol edin"; fi
exit 0
Bash:
chmod 700 /root/phalcon/reinstall-phalcon73.sh
HOOKDIR=/usr/local/directadmin/custombuild/custom/hooks/php/post
mkdir -p "$HOOKDIR"
printf '#!/bin/bash\n/bin/bash /root/phalcon/reinstall-phalcon73.sh || true\n' > "$HOOKDIR/phalcon73.sh"
chmod 755 "$HOOKDIR/phalcon73.sh"
/root/phalcon/reinstall-phalcon73.shCloudLinux alternatifi: alt-php73 ve PHP Selector
CloudLinux'ta uygulama, CustomBuild'in PHP 7.3'ü yerine CloudLinux'un kendi PHP 7.3 derlemesi olan alt-php73 ile de çalışabilir. DirectAdmin belgelerine göre PHP Selector php1_mode=lsphp gerektirir ve yalnızca DirectAdmin'in ilk PHP sürümünü (php1) kullanan alan adlarını etkiler. CloudLinux, alt-php için Phalcon paketleri de hazırlıyor: CloudLinux 7, 8 ve 9'un herkese açık depo dizinlerinde alt-php73-phalcon4 (4.1.3) paketinin yanında alt-php73-phalcon3 (Phalcon 3.4.5) da listeleniyor. Paketlenmiş bir modül yum ile kurulup güncellendiği için derlemeye girişmeden önce onu deneyin:
Bash:
yum list 'alt-php73-phalcon*'
yum install alt-php73-phalcon3
selectorctl --list-extensions --version=7.3 | grep -i phalcon
selectorctl --set-user-current=7.3 --user=KULLANICI
selectorctl --enable-user-extensions=phalcon3 --user=KULLANICI --version=7.3
selectorctl --list-user-extensions --user=KULLANICI --version=7.3
Bash:
yum install alt-php73-devel
cp -a /usr/local/src/cphalcon-3.4.5 /usr/local/src/cphalcon-3.4.5-alt73
cd /usr/local/src/cphalcon-3.4.5-alt73/build/php7/64bits
make clean; /opt/alt/php73/usr/bin/phpize --clean
export CFLAGS="-mtune=native -O2 -fomit-frame-pointer" CPPFLAGS="-DPHALCON_RELEASE"
/opt/alt/php73/usr/bin/phpize
./configure --with-php-config=/opt/alt/php73/usr/bin/php-config --enable-phalcon
make
cp -p modules/phalcon.so /opt/alt/php73/usr/lib64/php/modules/
printf 'extension=pdo.so\nextension=json.so\nextension=phalcon.so\n' > /opt/alt/php73/etc/php.d.all/phalcon.ini
cagefsctl --setup-cl-selector
selectorctl --enable-user-extensions=phalcon --user=KULLANICI --version=7.3Güvenlik: PHP 7.3'ün desteği bitti; yalıtın ve çıkışı planlayın
PHP 7.3, 6 Aralık 2021'de güvenlik güncellemesi almayı bıraktı ve son sürümü 7.3.33'tür. Ekim 2019 tarihli Phalcon 3.4.5 de son 3.x sürümüdür. Bu kurulumu geçici sayın ve sınırlandırın:- php1_release'i desteklenen bir PHP 8.x sürümünde tutun. php1 her sitenin varsayılanıdır ve web uygulamalarını çalıştırır; 7.3 yalnızca ek bir yuva olmalıdır.
- Eski uygulamaya ayrı bir DirectAdmin kullanıcısı verin; böylece PHP-FPM havuzu (pool), dosyaları ve veritabanı kimlik bilgileri ayrı kalır.
- Veritabanı kullanıcısına yalnızca uygulamanın ihtiyaç duyduğu yetkileri verin ve mümkünse yönetim adreslerini IP ile kısıtlayın.
- Canlı ortamda display_errors'ı kapalı tutun; CustomBuild'in kurabildiği ModSecurity gibi bir web uygulaması güvenlik duvarı (WAF) kullanmayı düşünün.
- Test edilmiş yedekler ve yazılı bir geri dönüş (rollback) planı bulundurun.
PHP 8.x üzerinde Phalcon 5'e geçişin ana hatları:
- Kodun kullandığı Phalcon sınıflarının ve PHP eklentilerinin envanterini çıkarın; testleri (ya da elle izlenecek bir test listesini) mevcut kurulumda çalışır hale getirin.
- Resmi rehberleri okuyun: v4'e yükseltme ve v5'e yükseltme. Arada 4.x'i canlıya almanız gerekmez, ancak v5 değişiklikleri v4'ün üzerine kuruludur. Birçok sınıfın yeri değişti: Phalcon\Di artık Phalcon\Di\Di, Phalcon\Loader artık Phalcon\Autoload\Loader, Phalcon\Validation artık Phalcon\Filter\Validation; Phalcon\Crypt ve Phalcon\Security ise Phalcon\Encryption altına taşındı.
- Desteklenen bir PHP 8.x yuvası ekleyin; örneğin da build set php3_release 8.4, ardından da build php ve da build rewrite_confs (eski DirectAdmin sürümlerinde custombuild klasöründe ./build kullanın). da build php yapılandırılmış tüm sürümleri yeniden derler; bu, kancanızı da test eder.
- Phalcon 5'i bu sürüm için ya CustomBuild ile (da build set php_phalcon yes, ardından da build php_phalcon; 54 numaralı başlıkta anlatılan yol) ya da Phalcon'un artık kullanımdan kalkan (deprecated) PECL yerine önerdiği PIE ile kurun: /usr/local/php84/bin/php pie.phar install --with-php-config=/usr/local/php84/bin/php-config phalcon/cphalcon. Güncel 5.x sürümleri PHP 8.1 veya üzerini ister; Phalcon belgeleri PIE ile derleme için en az 4 GB RAM gerektiği konusunda uyarır. CustomBuild seçeneği kurulu tüm PHP sürümlerini etkileyebilir; bu yüzden ardından 3. Adım'daki kontrolleri 7.3 yuvasında tekrarlayın ve yeni sürümün php --ini çıktısıyla Phalcon'u yalnızca bir dosyanın yüklediğini doğrulayın (PIE kendi ini dosyasını ekler).
- Bir test alt alan adında (staging) deneyin, canlı alan adını Domain Setup sayfasından değiştirin, geri dönüş için 7.3'ü kısa bir süre tutun, sonra 7.3 yuvasını, kancayı ve 90-phalcon.ini dosyasını kaldırın.
Sık sorulan sorular
Phalcon 3.4.5, PHP 7.4 veya 8.x üzerinde çalışır mı?Hiçbir 3.x sürümü bu PHP sürümlerini desteklediğini bildirmiyor. PHP 7.4'te Phalcon 4.x ya da 5.0–5.4, PHP 8.x'te 5.x gerekir; yani uygulamanın yeni sürüme taşınması (port) şarttır.
CustomBuild'in Phalcon seçeneği PHP 7.3'e 3.4.5 kurar mı?
Bunu varsaymayın. Hangi Phalcon sürümünün derleneceğine CustomBuild karar verir ve güncel 5.x sürümleri 7.3 için derlenmez. Uygulamanız tam olarak 3.4.5 istiyorsa elle derleme kontrolü sizde tutar. PHP 8.x ve Phalcon 5'e geçtiğinizde CustomBuild seçeneğine dönün.
php -m phalcon'u listeliyor ama site sınıfın bulunamadığını söylüyor. Neden?
Komut satırı ve site farklı PHP sürümleri ya da yapılandırmaları kullanıyordur. 5. Adım'daki test sayfasını çalıştırın; çoğunlukla alan adı başka bir sürümdedir ya da PHP-FPM yeniden başlatılmamıştır.
CloudLinux'ta Phalcon 3.4.5'i derlemem gerekir mi?
Genellikle hayır. CloudLinux bu sürümü alt-php73 için alt-php73-phalcon3 paketiyle sunuyor; PHP Selector'da phalcon3 adıyla etkinleştirilir. Yalnızca CloudLinux sürümünüz bu paketi sunmuyorsa kendiniz derleyin.
Her CustomBuild güncellemesinden sonra yeniden derlemem gerekir mi?
Genellikle hayır. Tüm 7.3.x derlemeleri 20180731 modül API'sini kullanır; modülü yeniden kurmak ve ini dosyasını geri koymak (betiğin yaptığı iş) çoğu zaman yeterlidir. Yalnızca API numarası ya da iş parçacığı güvenliği modu değişirse yeniden derleyin.
nano'da nasıl kaydederim?
Ctrl+O ve ardından Enter dosyayı kaydeder, Ctrl+X çıkar. Ctrl+Y ise bir sayfa yukarı kaydırır. Güncel nano sürümleri Ctrl+S ile de kaydeder.
Sonuç ve sonraki adımlar
3.4.5'i etiketinden PHP 7.3'ün kendi phpize ve php-config araçlarıyla derleyin, php.ini yerine 90-phalcon.ini ile etkinleştirin, PHP'yi gerçekten çalıştıran servisi yeniden başlatın ve doğrulamayı yalnızca komut satırından değil web sitesi üzerinden de yapın. Yeniden kurulum betiğini ve kancayı ekleyin; böylece bir CustomBuild çalışması siteyi fark edilmeden durduramaz. Ardından Phalcon 5 ve PHP 8.x geçişine bir tarih koyun ve envanterle başlayın. Bu geçiş yeni bir sunucuya taşınmayı da kapsıyorsa AIOR'un DirectAdmin barındırma hizmetine göz atabilirsiniz. Kendi kurulumunuzla ilgili soruları bu başlıkta sorabilirsiniz.This guide is for admins keeping a legacy Phalcon 3.4 application alive on a DirectAdmin server with CustomBuild. You need a phalcon.so compiled for the exact PHP 7.3 your site uses, an ini file that survives CustomBuild rebuilds, and a plan for leaving two end-of-life components behind. If the site already runs PHP 8.x, skip the manual build and use CustomBuild's own Phalcon option, as described in How to install Phalcon at DirectAdmin.
Phalcon and PHP compatibility matrix
Phalcon is a C extension, so each release builds only against the PHP versions it was written for. These ranges come from the cphalcon changelogs and from the PHP limits declared in each release's package.xml:| Phalcon | PHP versions | Notes |
|---|---|---|
| 3.4.0 – 3.4.2 | 5.5 – 7.2 | PHP 7.3 support was still only initial; full support arrived in 3.4.3 |
| 3.4.3 – 3.4.5 | 5.5 – 7.3 | 3.4.4 fixed segfaults seen with PHP 7.3.6; 3.4.5 (30 October 2019) is the last 3.x release |
| 4.0.x – 4.1.x | 7.2 – 7.4 | Needs the separate PSR extension, loaded before Phalcon; 4.1.3 is the last 4.x tag |
| 5.0 – 5.4 | 7.4.1 – 8.1, plus 8.2 from 5.2.0 | The PSR extension is no longer needed |
| 5.5 – 5.10 | 8.0 – 8.3, plus 8.4 from 5.9.0 | 5.5.0 (December 2023) raised the minimum to PHP 8.0 |
| 5.11 and later | 8.1 and newer (no upper limit declared) | Current line; 5.23.0 came out in October 2026 |
So for PHP 7.3, build 3.4.5, which contains all the 7.3 fixes. No 3.x release declares support for PHP 7.4 or 8.x, so an application that leaves PHP 7.3 also has to leave Phalcon 3.
Prerequisites and the right PHP 7.3 binaries
- Root SSH access, a fresh backup or snapshot, and a maintenance window, because PHP will be restarted.
- PHP 7.3 installed by CustomBuild in one of the php1_release … php9_release slots.
- gcc, make, autoconf (phpize needs it), git or curl, and the PCRE development headers that the Phalcon 3.4 docs list.
- Memory: build/php7/64bits/phalcon.zep.c is a single C file of about 5 MB, and on a VPS with around 1 GB of RAM or less the compiler can be killed for lack of memory. Troubleshooting shows how to add temporary swap.
CustomBuild installs each PHP version under its own prefix, so 7.3 has its own tools in /usr/local/php73/bin. The php and phpize found first in your PATH normally belong to php1_release, and unless that slot is 7.3, building with them causes the API mismatch error described below. Check the slots, always use full paths, and save the current module list for later comparison:
Bash:
grep -E '^php[1-9]_(release|mode)' /usr/local/directadmin/custombuild/options.conf
/usr/local/php73/bin/php -v
/usr/local/php73/bin/php-config --extension-dir
/usr/local/php73/bin/php --ini
mkdir -p /root/phalcon
/usr/local/php73/bin/php -m > /root/phalcon/php73-modules-before.txt
# build tools on AlmaLinux, Rocky, CloudLinux, CentOS
yum install -y gcc make autoconf git pcre-devel
# build tools on Debian, Ubuntu
apt-get install -y gcc make autoconf git libpcre3-devTwo notes before you build. Upstream PHP added OpenSSL 3 support only in 8.1, so PHP 7.3's openssl extension does not compile against OpenSSL 3, the system library on AlmaLinux or Rocky 9 and Debian 12, unless the build is patched or linked to an older OpenSSL. This guide assumes the 7.3 that CustomBuild already installed; if your server cannot keep or rebuild that 7.3, plan the migration instead of fighting the toolchain. And ./build update is not needed here, since it refreshes CustomBuild itself, not PHP, but hold off on update_versions until you finish, because it can rebuild PHP midway. Running CustomBuild update via SSH explains these commands.
Step 1: Get the v3.4.5 source
Bash:
cd /usr/local/src
git clone --depth 1 --branch v3.4.5 https://github.com/phalcon/cphalcon.git cphalcon-3.4.5
# without git:
# curl -L -o cphalcon-3.4.5.tar.gz https://github.com/phalcon/cphalcon/archive/refs/tags/v3.4.5.tar.gz
# tar xzf cphalcon-3.4.5.tar.gzStep 2: Compile against PHP 7.3
The build folder already contains generated C code, so you don't need Zephir. On a 64-bit server:
Bash:
cd /usr/local/src/cphalcon-3.4.5/build/php7/64bits
export CFLAGS="-mtune=native -O2 -fomit-frame-pointer"
export CPPFLAGS="-DPHALCON_RELEASE"
/usr/local/php73/bin/phpize
./configure --with-php-config=/usr/local/php73/bin/php-config --enable-phalcon
make
make install
Bash:
ls -l "$(/usr/local/php73/bin/php-config --extension-dir)/phalcon.so"
/usr/local/php73/bin/php -r 'echo ini_get("extension_dir"), PHP_EOL;'Step 3: Enable it in an ini file CustomBuild won't overwrite
The earlier version of this guide edited php.ini and told you to remove a ";" in front of extension=phalcon.so, but a stock php.ini has no such line. CustomBuild's PHP reads every .ini file in /usr/local/php73/lib/php.conf.d in alphabetical order. CustomBuild creates its own files there (10-directadmin.ini and 50-webapps.ini, according to its documentation), and the same documentation says you can add your own files to load modules; its example for a hand-built extension uses a separate 90-*.ini file. That keeps your change apart from everything CustomBuild manages, php.ini included:
Bash:
echo 'extension=phalcon.so' > /usr/local/php73/lib/php.conf.d/90-phalcon.ini
cp -p /usr/local/php73/lib/php.conf.d/90-phalcon.ini /root/phalcon/
/usr/local/php73/bin/php -m | grep -i phalcon
/usr/local/php73/bin/php -r 'echo \Phalcon\Version::get(), PHP_EOL;'Step 4: Restart the service that runs PHP
What to restart depends on the phpN_mode value in options.conf:| PHP mode and web server | Command |
|---|---|
| php-fpm (CustomBuild's default) with Apache, Nginx or Nginx+Apache | systemctl restart php-fpm73 |
| lsphp under LiteSpeed or OpenLiteSpeed | /usr/local/lsws/bin/lswsctrl restart |
| fastcgi (mod_fcgid) under Apache | systemctl restart httpd |
Step 5: Verify what the website actually uses
The CLI test only proves that /usr/local/php73/bin/php loads Phalcon. The website runs on whatever version its domain is assigned. DirectAdmin can run up to nine PHP versions. php1_release is the default and also runs DirectAdmin's webapps, such as phpMyAdmin and Roundcube. Users choose another version per domain with the PHP version selector on the Domain Setup page, which requires php_version_selector=1 (check it with da config-get php_version_selector). Subdomains can have their own selection. Create a temporary file with a hard-to-guess name, such as pcheck-8d41.php, in the site's document root. If the app uses Phalcon's usual public/ folder with rewrite rules, that is public_html/public/:
PHP:
<?php
header('Content-Type: text/plain');
echo 'PHP: ', PHP_VERSION, ' (', PHP_SAPI, ')', PHP_EOL;
echo 'Phalcon: ', extension_loaded('phalcon') ? phpversion('phalcon') : 'NOT LOADED', PHP_EOL;
echo 'ini files: ', php_ini_scanned_files(), PHP_EOL;
?>
Bash:
cd /home/USER/domains/example.com/public_html # or public_html/public
chown USER:USER pcheck-8d41.php
curl -s https://example.com/pcheck-8d41.php
rm -f pcheck-8d41.phpTroubleshooting
Module API mismatch. The module was built with another version's phpize or php-config. This output means PHP 7.3 tried to load a module built for 7.4:
Kod:
PHP Warning: PHP Startup: phalcon: Unable to initialize module
Module compiled with module API=20190902
PHP compiled with module API=20180731
These options need to matchUnable to load dynamic library 'phalcon.so' … No such file or directory. The file is not in this PHP's extension_dir. Repeat the check from Step 2.
undefined symbol: …. The module was compiled against other PHP headers than the binary that loads it (for example a distribution php-devel package found in PATH), or it loads before a module it depends on. Rebuild against /usr/local/php73, keep the 90- prefix, and check that php -m lists PDO.
Class 'Phalcon\Mvc\Model' not found. The extension is not loaded in the PHP that serves the site. Usually the domain runs another version, PHP-FPM was not restarted, or the ini file vanished after a CustomBuild run. The quotes are a clue: PHP 7.x prints Class 'Phalcon\Mvc\Model' not found, while PHP 8.x prints Class "Phalcon\Mvc\Model" not found. The double-quoted error in thread 54 therefore came from PHP 8.
Cannot find autoconf. Install autoconf and run phpize again.
gcc: internal compiler error: Killed (program cc1). The compiler ran out of memory. Add temporary swap, run make again, then remove it:
Bash:
dd if=/dev/zero of=/swapfile-build bs=1M count=2048
chmod 600 /swapfile-build && mkswap /swapfile-build && swapon /swapfile-build
# run make again, then:
swapoff /swapfile-build && rm -f /swapfile-buildSegfaults on PHP 7.3.6 or later. Releases before 3.4.4 have this problem; 3.4.4 fixed it by building with a newer Zephir. Use 3.4.5.
Keeping Phalcon after CustomBuild rebuilds
Thread 54, linked at the top, shows the typical failure: after a CustomBuild update, Phalcon was gone and the site stopped with "Class not found". Assume that hand-made changes can vanish in a rebuild, and automate the repair. Every 7.3.x release uses module API 20180731, and 7.3.33 is the last one anyway, so a rebuilt 7.3 does not invalidate the module you compiled; reinstalling it and restoring the ini file are usually enough. Save this as /root/phalcon/reinstall-phalcon73.sh (nano is fine):
Bash:
#!/bin/bash
# Reinstall Phalcon 3.4.5 for CustomBuild PHP 7.3 when it is missing
PHPBIN=/usr/local/php73/bin/php
SRC=/usr/local/src/cphalcon-3.4.5/build/php7/64bits
INI=/usr/local/php73/lib/php.conf.d/90-phalcon.ini
RESTART="systemctl restart php-fpm73" # lsphp: /usr/local/lsws/bin/lswsctrl restart, fastcgi: systemctl restart httpd
CHANGED=0
[ -x "$PHPBIN" ] || exit 0
if [ ! -f "$INI" ]; then
cp -p /root/phalcon/90-phalcon.ini "$INI" && CHANGED=1
fi
if ! "$PHPBIN" -m | grep -qx phalcon; then
make -C "$SRC" install && CHANGED=1
fi
[ "$CHANGED" = 1 ] && $RESTART
if "$PHPBIN" -m | grep -qx phalcon; then echo "phalcon73: OK"; else echo "phalcon73: MISSING, check by hand"; fi
exit 0
Bash:
chmod 700 /root/phalcon/reinstall-phalcon73.sh
HOOKDIR=/usr/local/directadmin/custombuild/custom/hooks/php/post
mkdir -p "$HOOKDIR"
printf '#!/bin/bash\n/bin/bash /root/phalcon/reinstall-phalcon73.sh || true\n' > "$HOOKDIR/phalcon73.sh"
chmod 755 "$HOOKDIR/phalcon73.sh"
/root/phalcon/reinstall-phalcon73.shCloudLinux alternative: alt-php73 and PHP Selector
On CloudLinux the app can run on alt-php73, CloudLinux's own PHP 7.3 build, instead of CustomBuild's. DirectAdmin's documentation says PHP Selector needs php1_mode=lsphp and only affects domains that use the first DirectAdmin PHP version (php1). CloudLinux also packages Phalcon for alt-php: the public repository indexes for CloudLinux 7, 8 and 9 list alt-php73-phalcon3 (Phalcon 3.4.5) next to alt-php73-phalcon4 (4.1.3). A packaged module installs and updates through yum, so try it before compiling anything:
Bash:
yum list 'alt-php73-phalcon*'
yum install alt-php73-phalcon3
selectorctl --list-extensions --version=7.3 | grep -i phalcon
selectorctl --set-user-current=7.3 --user=USER
selectorctl --enable-user-extensions=phalcon3 --user=USER --version=7.3
selectorctl --list-user-extensions --user=USER --version=7.3
Bash:
yum install alt-php73-devel
cp -a /usr/local/src/cphalcon-3.4.5 /usr/local/src/cphalcon-3.4.5-alt73
cd /usr/local/src/cphalcon-3.4.5-alt73/build/php7/64bits
make clean; /opt/alt/php73/usr/bin/phpize --clean
export CFLAGS="-mtune=native -O2 -fomit-frame-pointer" CPPFLAGS="-DPHALCON_RELEASE"
/opt/alt/php73/usr/bin/phpize
./configure --with-php-config=/opt/alt/php73/usr/bin/php-config --enable-phalcon
make
cp -p modules/phalcon.so /opt/alt/php73/usr/lib64/php/modules/
printf 'extension=pdo.so\nextension=json.so\nextension=phalcon.so\n' > /opt/alt/php73/etc/php.d.all/phalcon.ini
cagefsctl --setup-cl-selector
selectorctl --enable-user-extensions=phalcon --user=USER --version=7.3Security: PHP 7.3 is end-of-life, so isolate it and plan the exit
PHP 7.3 stopped receiving security fixes on 6 December 2021, and 7.3.33 is its last release. Phalcon 3.4.5, from October 2019, is the last 3.x release. Treat the setup as temporary and contain it:- Keep php1_release on a supported PHP 8.x. php1 is every site's default and runs the webapps, so 7.3 should only be an extra slot.
- Give the legacy app its own DirectAdmin user, so its PHP-FPM pool, files and database credentials stay separate.
- Grant its database user only the privileges the app needs, and restrict admin URLs by IP where you can.
- Keep display_errors off in production and consider a web application firewall such as ModSecurity, which CustomBuild can install.
- Keep tested backups and a written rollback plan.
The move to Phalcon 5 on PHP 8.x, in outline:
- Inventory the Phalcon classes and PHP extensions the code uses, and get tests (or a manual test checklist) running on the current setup.
- Read the official guides for upgrading to v4 and upgrading to v5. You don't have to deploy 4.x in between, but v5 builds on the v4 changes. Many classes moved: Phalcon\Di is now Phalcon\Di\Di, Phalcon\Loader is Phalcon\Autoload\Loader, Phalcon\Validation is Phalcon\Filter\Validation, and Phalcon\Crypt and Phalcon\Security moved under Phalcon\Encryption.
- Add a supported PHP 8.x slot, for example da build set php3_release 8.4, then da build php and da build rewrite_confs (on older DirectAdmin, use ./build in the custombuild folder). da build php rebuilds every configured version, which also tests your hook.
- Install Phalcon 5 for that version, either through CustomBuild (da build set php_phalcon yes, then da build php_phalcon, the route thread 54 describes) or with PIE, which Phalcon now recommends over the deprecated PECL: /usr/local/php84/bin/php pie.phar install --with-php-config=/usr/local/php84/bin/php-config phalcon/cphalcon. Current 5.x releases need PHP 8.1 or newer, and Phalcon's docs warn that a PIE build needs at least 4 GB of RAM. CustomBuild's option may act on every installed PHP version, so repeat the Step 3 checks on the 7.3 slot afterwards, and check the new version's php --ini so that only one file loads Phalcon (PIE adds its own ini file).
- Test on a staging subdomain, switch the production domain on the Domain Setup page, keep 7.3 briefly for rollback, and then remove the 7.3 slot, the hook and 90-phalcon.ini.
FAQ
Can Phalcon 3.4.5 run on PHP 7.4 or 8.x?No 3.x release declares support for them. On PHP 7.4 you need Phalcon 4.x or 5.0 to 5.4, and on PHP 8.x Phalcon 5.x, so the application has to be ported.
Will CustomBuild's Phalcon option give me 3.4.5 on PHP 7.3?
Don't assume so. CustomBuild picks the Phalcon release it builds, and current 5.x releases don't compile for 7.3. If the app needs exactly 3.4.5, the manual build keeps you in control. Switch to CustomBuild's option once you are on PHP 8.x and Phalcon 5.
php -m lists phalcon, but the site says the class is not found. Why?
The CLI and the site are using different PHP versions or configurations. Run the test page from Step 5. Usually the domain is on another version, or PHP-FPM was not restarted.
Do I have to compile Phalcon 3.4.5 on CloudLinux?
Usually not. CloudLinux packages it for alt-php73 as alt-php73-phalcon3, which you enable as phalcon3 in PHP Selector. Compile it yourself only if your CloudLinux release does not offer that package.
Do I have to recompile after every CustomBuild update?
Usually not. Every 7.3.x build uses module API 20180731, so reinstalling the module and restoring the ini file (which the script does) is normally enough. Recompile only if the API number or the thread-safety mode changes.
How do I save in nano?
Ctrl+O and then Enter saves the file, and Ctrl+X exits. Ctrl+Y scrolls up a page. Recent nano versions also save with Ctrl+S.
Conclusion and next steps
Build 3.4.5 from its tag with PHP 7.3's own phpize and php-config, enable it in 90-phalcon.ini rather than php.ini, restart the service that really runs PHP, and verify through the website, not only the CLI. Add the re-install script and the hook, so a CustomBuild run cannot take the site down unnoticed. Then put a date on the Phalcon 5 and PHP 8.x migration and start with the inventory. If that migration includes moving to a new server, AIOR offers DirectAdmin hosting. Questions about a specific setup are welcome in this thread.
Son düzenleyen:
