PHP Handler Mapping

Learning Focus

By the end of this lesson you will know how to map .php files to an lsphp external application so PHP scripts execute correctly.

What Handler Mapping Does

Script handler mapping tells OpenLiteSpeed: "When a request matches this file extension, process it using this external application." Without a handler mapping for .php, PHP files would be served as plain text downloads instead of being executed.

Setting Up a PHP Handler

In WebAdmin

1. Navigate to Server Configuration → Script Handler (for server-wide) or Virtual Hosts → Script Handler (per site)
2. Click Add
3. Set:
   • Suffix: php
   • Handler Type: LiteSpeed SAPI
   • Handler Name: lsphp84 (or your external app name)
4. Save and Graceful Restart

Verifying the Handler

# Test PHP execution
echo '<?php phpinfo(); ?>' > /var/www/example.com/public/test.php
curl http://localhost/test.php | head -20

# If you see HTML output with PHP info, the handler is working
# If the file downloads instead, the handler mapping is missing

# Clean up
rm /var/www/example.com/public/test.php

Result	Meaning	Fix
PHP output renders	✅ Handler working	No action needed
File downloads	❌ No handler	Add .php handler mapping
503 error	❌ External app failed	Check lsphp external app config

Key Takeaways

• Without a handler mapping, PHP files are served as downloads, not executed.
• Map the .php suffix to your lsphp external application in the script handler settings.
• Verify with a test PHP file after any handler change.

What's Next

• Continue to Multiple PHP Versions for running different PHP versions per site.