What happened
This is from migrating an e-commerce site running on Amazon Linux 2 (PHP 8.2) to Amazon Linux 2023 (PHP 8.3). I moved the code and the database, started httpd, opened the top page — and got a 500 Internal Server Error. Nothing in the application log. Only Apache's error_log had this:
/var/www/app/html/.htaccess: Invalid command 'php_value', perhaps misspelled or defined by a module not included in the server configuration The culprit was a block that had been sitting in the old server's .htaccess for years:
php_value upload_max_filesize 500M php_value post_max_size 512M The cause — AL2023's httpd has no mod_php
php_value and php_flag are mod_php directives. On AL2, httpd shipped with mod_php built in, so they worked. The standard setup on AL2023 is php-fpm + proxy_fcgi with the event MPM — the mod_php module simply does not exist.
When Apache finds a directive it cannot parse in .htaccess, it returns 500 for every request to that directory. So this isn't "the PHP settings silently stop applying" — not a single page renders. When a migration changes how the runtime executes, config files living inside the app directory are where the teeth come out.
The fix — relocate where the settings live
1. Neutralize .htaccess with IfModule
I wanted to keep compatibility with the old server, so instead of deleting the php_value lines I wrapped them:
# .htaccess after the fix <IfModule mod_php.c> php_value upload_max_filesize 500M php_value post_max_size 512M </IfModule> Where mod_php exists, the block still applies; where it doesn't, Apache skips it entirely. The same file can be deployed to both generations of servers during the transition.
2. Move the same values into php.ini
Everything that used to live in .htaccess went into /etc/php.d/99-app.ini:
; /etc/php.d/99-app.ini memory_limit = 512M post_max_size = 512M upload_max_filesize = 500M max_execution_time = 0 opcache.memory_consumption = 256 opcache.max_accelerated_files = 20000 With php-fpm, a systemctl reload php-fpm picks these up.
3. Derive pm.max_children from available memory
The default value will swap a small instance to death. Assuming memory_limit 512M, I used 4 children for 512 MB of RAM and 8 for 1 GB.
; /etc/php-fpm.d/www.conf pm.max_children = 8 4. Diff the extension list against the old server's php -m
AL2023's default set is missing zip and exif. I captured php -m on the old server, diffed it against the new one, and installed only the gap (dnf install php8.3-zip, etc.). Skip this comparison and the features that break are the ones you rarely touch — like the admin panel's CSV upload — weeks later.
5. Regenerate caches as the web user
Running cache warmup or assets:install as root creates root-owned cache files, which become your next 500. Everything went through sudo -u apache php bin/console ....
Side quests along the way
- Lightsail's
Default SSH keyis per-region. The same pem happened to open the new instance only because it was in the same region. - If rsync's source includes root-only files (sessions, etc.), use
--rsync-path="sudo rsync". - A default vhost in
ssl.confwithout a ServerName logscertificate does NOT include an IDon every start. Harmless, but it pollutes log monitoring, so I filled it in.
Results
- Response times: 0.17–0.43s → 0.12–0.48s (HTTP/2 + event MPM)
- OpenSSL 1.0.2k → 3.5.8
- Support runway extended: OS until 2028-03, PHP 8.3 until 2027-12
- Vendor directory rebuilt via
composer installfrom acomposer.lockalready validated in dev (13 installs / 102 upgrades, 46 seconds)
Takeaway
Ninety percent of a runtime migration is a table: where does the old server read each setting, and where does the new server expect it to be written? php.ini values, .htaccess values, the module list, vhosts, cron — build the table first, and the migration script is just a translation of that table.
My migration script failed three times in dev while it got polished, then passed on the first try in production. That, I think, is exactly what dev environments are for.