Screenshot published in the phpboy project's official README. Image source: phpboy project on GitHub.

phpboy

GAME BOY EMULATOR

phpboy

PHPBoy — a Game Boy Color emulator implemented in modern PHP (targeting PHP 8.4+). It provides a working CLI terminal frontend, an experimental WebAssembly browser frontend, and a work-in-progress SDL2 native frontend. The core claims full GBC support with DMG backward compatibility and successful Blargg CPU test coverage.

Jump to download ↓Jump to setup guide ↓

Screenshot published in the phpboy project's official README. Image source: phpboy project on GitHub.

Game BoyPRIMARY SYSTEM

2020sPROJECT BEGAN

Open sourcePROJECT MODEL

WHY IT MATTERS

Why PHPBoy matters

PHPBoy is notable because it implements cycle-accurate Game Boy/Color subsystems in PHP (using modern language features and PHP JIT where available). It’s primarily a development / research project that demonstrates a language-unusual approach to emulator design and provides multiple frontends (CLI, WASM, SDL2) for different environments.

BEST FOR

Best uses

Running and testing Game Boy / Game Boy Color homebrew and test ROMs in a readable, well-documented PHP codebase; reproducing and studying emulation techniques; experimenting with a browser-playable PHP build via WebAssembly; running the CLI frontend for lightweight local play and verification.

Gameplay from Tetris on Game Boy.

The people behind phpboy

History and status

Primary source material for this profile is the project repository. The GitHub repository shows active development (commits, issues, and a development roadmap). The README documents a working CLI frontend and GBC features; the author reports passing Blargg CPU instruction tests and partial progress on other test suites. The browser/WebAssembly frontend is available but noted as slower and with audio still work-in-progress. SDL2 native frontend and some test-suite coverage (Mooneye / acid tests) are marked as in-progress. Development and testing are driven from a Docker-based workflow and Makefile targets. Project is hosted publicly on GitHub and is actively maintained (issues and recent commits present at the repository).

What phpboy supports

Nintendo Game Boy Color (primary target)
Original Game Boy (DMG compatibility mode)
Memory Bank Controllers: reported MBC1, MBC3, MBC5 support (as implemented in repo)
Frontends: CLI terminal (primary), WebAssembly (browser), SDL2 (WIP)

Download and availability

OFFICIAL DOWNLOADS

Get phpboy

Official releases and source are distributed through the project's GitHub repository and releases page. The repository includes Makefile targets and a Docker-based build/test workflow for obtaining a runnable build.

Get phpboy ↗

DOCUMENTATION

Official documentation

Read the official configuration, compatibility, and troubleshooting material before changing advanced options.

Read official documentation ↗

Broken or missing download? Emulator projects move and official links sometimes change. Please contact Retro Replay so the source can be verified and updated.

phpboy setup guide

Setup note: This setup guide follows the project's documented workflow (Makefile + Docker) and the README. It focuses on getting the CLI frontend running, building the WASM frontend, and notes platform-specific requirements reported by the author.

1) Clone the official repository: git clone https://github.com/eddmann/phpboy.git && cd phpboy. Use the official repo as the source of truth for build steps and the Makefile targets.
2) Prerequisites: Install Docker and Docker Compose (used by the repository's Makefile). Install Make. If you plan to use local audio in CLI mode, install SoX (Linux: apt-get install sox; macOS: brew install sox). For native builds you will need the platform's SDL2 development libraries (SDL2 frontend is WIP and may require manual adjustments).
3) Build the development environment: Run make setup to build the Docker image the project uses for development and testing. This target prepares a consistent PHP 8.4 environment used for subsequent commands.
4) Install PHP dependencies: Run make install (executes Composer within the Docker environment) to fetch vendor libraries required by the emulator core and frontends.
5) Run the CLI frontend (recommended first step): Use the Makefile-run targets described in the README. Example: make run ROM=path/to/game.gb (or .gbc). The CLI frontend is the primary, fully working frontend per the repo. The README documents that PHP JIT produces much higher framerates; start without JIT (make run-no-jit) to confirm baseline behavior before enabling JIT.
6) Running tests and verification: Run make test to execute the PHPUnit tests included in the repository. The project documents passing Blargg CPU instruction tests; the repository includes a cgb-test-summary and other test artifacts (inspect tests/ and docs/ in the repo for details).
7) Browser / WebAssembly frontend: Build the WASM distribution with make build-wasm and serve it locally with make serve-wasm (serves on port 8080 per README). The browser frontend uses php-wasm; the repo notes the WASM build currently suffers performance and audio limitations.
8) Native SDL2 desktop (WIP): The SDL2 frontend is marked work-in-progress. The README and codebase contain the necessary build targets and references, but expect manual dependency installation (SDL2 dev headers/libraries) and possible code changes as the frontend is not yet feature-complete.

Software reminder: The repository does not include commercial ROMs, firmware, or BIOS files. Use only legally obtained ROMs or public-domain/test ROMs when running the emulator. Follow the project license (MIT) for reuse of source code.