Skip to content
This repository


Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

Run legacy environments like CGI and PHP under any rack server.

branch: master

Proxy off to PHP better.

The preserve_host option on rack-rewrite seems a bit off. I would assume it
would mean it keeps the hostname requested. But instead it replaces it with
the internal hostname (the host we proxy to). There is a ticket related to
this (jaswope/rack-reverse-proxy#11).

In addition, even if it pulled from the right host it also doesn't include
the port. There is also already a ticket for this

To resolve this I simply avoiding using the preserve host option. This allows
the original host to pass on through to PHP (it doesn't seem to need to be
explicitly set, PHP already know it).

Both of these option (wrong host and missing port) cause some PHP scripts,
like Wordpress, who are trying to redirect to a canonical URL to get caught
in an infinate loop.

I am also now stripping out the index.php from the PATH_INFO before proxying
off. The PHP webserver has it's own built-in method of looking for the
index.php. So we add it for detecting the PHP handler should be called but
then remove it to let PHP do things it's own way. This helps for script like
Wordpress that try to direct to a canoncial URL. It prevent it from bouncing
between index.php and the root directory. It may be slightly incorrect for
cases where the user explicitly chose to pull up the index.php script. But
in the real world I don't know where that would cause a problem and making
this change solves a real world problem for Wordpress.

Finally, I am passing on the HTTP_X_FORWARDED_FOR header. Although not
standardized it is fairly widely and provide a way for the script to determine
the IP address of the real browser since REMOTE_ADDR will be set to the
proxy server.
latest commit 52cd23ff83
Eric Anderson authored
Octocat-spinner-32 bin Get rid of deprecation warning. August 11, 2011
Octocat-spinner-32 lib Proxy off to PHP better. January 20, 2014
Octocat-spinner-32 share Add generic support for index rewriting. November 12, 2013
Octocat-spinner-32 test Add generic support for index rewriting. November 12, 2013
Octocat-spinner-32 .gitignore Refactoring packaging. November 09, 2013
Octocat-spinner-32 Gemfile Refactoring packaging. November 09, 2013
Octocat-spinner-32 README.rdoc Fix typo November 12, 2013
Octocat-spinner-32 Rakefile Switch to PHP's built-in server. November 12, 2013
Octocat-spinner-32 rack-legacy.gemspec Proxy off to PHP better. January 20, 2014


Rack Legacy tries to provide interaction with legacy environments like PHP and CGI while still getting the Rack portability so you don't need a full Apache/lighttpd stack.

This software is currently BETA quality. Use at your own risk.


The PRIMARY use case is while developing an application where Ruby is being used but there are also some legacy PHP or CGI that is running along-side your Ruby. This middleware allows you to do that development without the full Apache stack.

When you take the application to a production environment you can either leave this middleware in or use a full Apache stack to get more battle tested performance and security.



gem install rack-legacy

Generic Rack Integration

Put the following in your rack stack:

require 'rack-legacy'
use Rack::Legacy::Php, 'public'

Rails Usage

In your Gemfile

gem 'rack-legacy'

In your application.rb:

config.middleware.insert_before \
  ActionDispatch::Static, Rack::Legacy::Php, Rails.public_path

Rails < 3 is not well supported. This is because Rack::Static (later turned into ActionDispatch::Static) is not in the Rails stack but instead processed in the stack that loads Rails prior to Rails running. This means you cannot insert any middleware before it. This software previously had some hacks to work around this but with the release of Rails 3 the hacks where not necessary and therefore removed.

If you still need to use rack-legacy on a Rails 2 app see version 0.1.5.

Legacy Modules

The above configuration just adds PHP support to your stack. That is just one of currently three modules available. The current modules are:


Provides support for executing any standard CGI script. It is important that script has the executable bit set.


Provides support for executing PHP scripts.


Provides support for running “index.php”, “index.cgi” or “index.html” when just a directory is specified in the request. You will want to install this module before the CGI or PHP ones.

An example rackup file that enables all modules (plus exception reporting and static file delivery) is:

require 'rack/showexceptions'
require 'rack-legacy'

use Rack::ShowExceptions
use Rack::Legacy::Index
use Rack::Legacy::Php
use Rack::Legacy::Cgi
run Dir.getwd


Got a project that is nothing but PHP or CGI? Run `rack_legacy` in the website root directory and it will start serving the files. It just executes the above example rackup file.


This is free and unencumbered software released into the public domain.


This gem was developed by Eric Anderson ( partially via work done under Red Tusk Studios ( and Southern Web Group (

Something went wrong with that request. Please try again.