php-proxy-app is a drop-in web proxy you install into the document root

A project, not a package you require into an application

php-proxy-app is a deployable web application that sits on top of the php-proxy library. The distinction between the two matters, because the README is explicit that installing it through composer require would do you no good. It is a project, so it is meant to be dropped straight into the public directory of a web server, with its own index.php at the front and its own configuration file.

The intended users are people who want a proxy running on infrastructure they control, typically on a server in a different country from the site they need to reach, or behind a network that blocks certain domains. The project description calls it a web proxy ready to be installed on your server, and the repository keeps a live demo instance at unblockvideos.com.

The whole surface is small by design. The top level of the repository holds index.php, config.php, a templates directory, a plugins directory, a composer.json and a setup.txt file. There is no framework, no build step and no client bundle.

Rewriting pages rather than tunnelling traffic

The mechanism is page rewriting. The proxy fetches a target page on the server's side and rewrites the links and resources inside it so that the browser keeps talking to the proxy rather than to the origin. That is why a homepage with images, stylesheets and links can be browsed through the proxy at all, and it is also the source of the project's central limitation.

The README states plainly that pages which are too script heavy or have too many dynamic parts may not work, and calls this a known limitation of web proxies. A page whose content is assembled by JavaScript after load has nothing in the initial HTML for the proxy to rewrite, so the browser requests the missing pieces from the origin directly and the browser sees the blocked address. The README answers that case by pointing at an actual proxy server, since a server that routes the browser HTTP requests through the network path does not depend on rewriting at all.

That is the key difference between the two categories the project names in its own headings: a web proxy rewrites what the browser downloads, a proxy server moves the traffic itself.

Installing into the document root with composer create-project

Since this is a project, the install command creates a directory rather than adding a dependency. The version constraint pins the 4.0 line:

composer create-project athlon1600/php-proxy-app:"^4.0" /var/www/

That command writes the application into /var/www/, which is the public directory of a typical Linux web server. Nothing else is required for the basic case, because config.php ships with sensible defaults and is loaded into the global Config class.

For local work the repository ships a Makefile with a serve target that starts PHP's built in server:

php -S localhost:9000

There is also an actions target that runs the build workflow locally with act. The README also names a setup.txt file at the root, which is worth reading before a first deployment even though the README itself does not explain its contents.

A single container image with two published ports

Docker is the path the README lists first. It assumes Docker is already installed, and the installation it points at is the convenience script:

curl -sSL https://get.docker.com/ | sh

The run command publishes two ports, 8080 for HTTP and 8443 for HTTPS:

docker run -d -p 8080:80 -p 8443:443 dwaaan/php-proxy

The image is published under the dwaaan namespace rather than the Athlon1600 one, and the README credits a separate PHP-Proxy-Docker project for it. The container name for the image is dwaaan/php-proxy, and mapping host 8080 onto container port 80 means the proxy is reachable at localhost:8080 immediately after the container starts.

One deployment detail is easy to miss and worth knowing: the proxy is a PHP application, so the container needs its own web server in front of the PHP code, which is why the image exposes ports 80 and 443 rather than a PHP port.

Plugins are plain PHP files loaded from a folder

The extension mechanism is filesystem based. The README explains that PHP-Proxy provides many of its own native plugins, and that users are free to write custom plugins which are then automatically loaded from the plugins directory. The reference example given is plugins/TestPlugin.php, which is the file to read first if you plan to write one.

Automatic loading from a directory is convenient for a small deployment, where dropping a file in place is faster than any configuration change. It also means the plugin folder is part of the trust boundary of the installation, since anything placed there runs. A deployment that lets other people write to that directory should be treated accordingly.

The templates directory holds the views, and the README admits the naming is historical, saying it should have been called views but was kept as templates for legacy reasons. Both directories are ordinary folders in the project root, which makes the file layout easy to inspect before you put anything in front of it.

composer update is the real upgrade path

The README makes a point about how this project changes. The application itself rarely changes, and most of the movement comes from its requirement packages, php-proxy above all. The suggested routine is to run a composer update from time to time so the proxy always uses the latest versions of those dependencies.

composer update

That is a sensible arrangement for a deployment that tracks upstream rather than vendoring. It also means the code you install and the code that runs a month later can differ, so pinning is worth considering in any environment where you care about repeatability.

On dates, the v4.0.0 tag was published on 2026-06-04, and the last push to the repository was on 2026-06-04 as well. Before that the release history jumps back to v3.0 in 2015 and v2.0 in 2015, so the jump from v3 to v4 came with a long gap in tagged releases. The repository is not archived. The licence is MIT, which leaves most deployment questions about the licence simple, although any specific compliance question belongs with your own counsel.

Where a real proxy server is the better answer

The alternative the project itself recommends is an actual proxy server, listed at proxynova.com as a starting point for proxy software. The difference in approach is one layer. A proxy server accepts the browser connection and forwards the requests onward at the network level, so the browser believes it is talking to the origin and every script, request and API call behaves normally. The web proxy in this repository sits in the middle of the HTML, rewriting it, which means anything that runs after the initial page load escapes the rewrite.

There is a cost to the server approach and a cost to the rewrite approach. A proxy server needs a reachable address that the browser is configured to use, which in practice means a browser or operating system setting, and it forwards traffic that you may not want to forward. The web proxy needs nothing from the browser and can be used by anyone who has the URL, which is exactly why it is the shape people reach for when they want to give someone else access through their own server.

For a single static page or a simple site, the rewrite approach is quick. For anything interactive, it is the wrong tool, and the README says so.

Editorial conclusion

php-proxy-app fits a self hosted setup where one server should relay a handful of otherwise blocked pages, and installing it takes one composer create-project into the document root plus a docker run command if you would rather containerise it. It is the wrong tool for sites that rely on client side JavaScript, and for anyone who needs a full tunnel rather than page rewriting. Before deploying, install it with composer create-project athlon1600/php-proxy-app:"^4.0" /var/www/, read config.php and the TestPlugin.php example, and check that the pages you care about are static enough to survive the rewrite.

Frequently asked questions

Official sources

1. Athlon1600/php-proxy-app on GitHub
2. License: MIT
3. Project website
4. README
5. Releases