Test Before Publish

Test changes to your PHP site locally before uploading them to your hosting provider.

Open your project in VS Code, choose your PHP and MySQL versions, and start a Docker environment with Apache or Nginx. Inspect your database, preview test emails, and follow PHP errors directly from your development workflow.

Who is it for?

Developers maintaining existing PHP websites who want a convenient local environment before deploying changes — including projects hosted on shared hosting.

Quick start

Prerequisite: Docker Desktop must be installed and running.

Access the commands: Right-click your project folder in the VS Code Explorer and choose a Test Before Publish: ... action. You can also run these commands from the Command Palette. In a multi-folder workspace, the right-click actions apply to the folder you selected.

1. Open your PHP project folder in VS Code.
2. Run Test Before Publish: Configure to choose your PHP version, web server, and MySQL version.
3. Run Test Before Publish: Start.
4. Run Test Before Publish: Open in Browser to view your site.
5. When you are done, run Test Before Publish: Stop.

Your database persists between restarts. Use Test Before Publish: Reset Database only when you want to delete the local test database contents and start again.

What you get

• PHP and MySQL versions configurable per project.
• Apache or Nginx with PHP-FPM.
• Automatic detection of the project directory and document root.
• A suggested PHP version based on composer.json, when detected.
• Automatic SQL import into a fresh database.
• Adminer to inspect your test database.
• Mailpit to preview emails sent through the configured local mail transport.
• Live container logs, including PHP errors and warnings.
• Support for existing projects using MySQL localhost connections.
• Separate Docker Compose projects and database volumes for different workspaces.
• Support for multi-folder VS Code workspaces.
• Optional integration to pause compatible FTP upload-on-save settings during testing.

Free and licensed features

The free version includes PHP/MySQL environments, Apache or Nginx, Mailpit, and live logs, with one active Test Before Publish project at a time.

A license unlocks:

• Multiple active projects for working on several sites at once.
• Share Link for sharing a temporary public preview of your local site.

Use Test Before Publish: Enter License Key to activate your license. The key is checked offline, on your machine, and works on every computer you use it on (see the license for details). It is valid for every release of the major version you purchased (for example, all 1.x releases).

€29 excluding VAT — one-time payment. The license does not expire for the purchased major version. Updates within that major version and 12 months of email support from the purchase date are included. Future major versions may be sold separately; upgrading is optional.

View license details and availability · Informations en français

See the License tab of this extension (LICENSE.md in the package) for the full software license terms. The support period does not limit any mandatory rights under applicable law.

Feedback

Did your project run successfully? If something blocked you, describe your operating system, PHP version, the steps you followed, and the error you encountered.

Please remove passwords and other sensitive information before sharing logs or configuration.

Send feedback or support requests to support@propublisher.be.

Visit proPublisher for our applications and developer tools.

Commands

Project detection and generated configuration

The extension detects the actual project directory, including when the folder opened in VS Code is a parent of the site directory — for example, a workspace containing marketplace/public/index.php.

It also detects the document root, using public/ when present, and suggests a PHP version from composer.json when possible.

The generated docker-compose.yml is stored in .testbefore/. Do not edit that generated file manually: use Test Before Publish: Reconfigure to change the selected versions or web server.

Additional settings described below belong in .testbefore/config.json. The JSON examples show individual settings to merge into your existing configuration, rather than complete replacement files.

Multiple projects and workspace folders

Each workspace uses a Docker Compose project name derived from its path, keeping its containers and database volumes separate from those of other projects.

In a multi-folder workspace:

• Right-click a folder in the VS Code Explorer and select a Test Before Publish: ... command to act on that folder.
• When running a command from the Command Palette, select the target folder if prompted.
• Each project has its own configuration and containers.
• The status bar shows the running project (or the number of running projects) and, separately, any active share link.

The free version allows one active project at a time. Running multiple projects simultaneously requires a license.

MySQL compatibility

Existing connections using localhost

The MySQL socket directory, /var/run/mysqld, is shared between the MySQL and PHP containers. The extension preconfigures pdo_mysql.default_socket and mysqli.default_socket.

This supports PHP code that connects to MySQL using host=localhost, rather than reading a DB_HOST environment variable, without requiring a change to that host setting. Database credentials and the database name still need to match your local environment.

SQL mode

MySQL starts with an empty, permissive sql_mode by default. This disables modes such as ONLY_FULL_GROUP_BY and STRICT_TRANS_TABLES, which can help with existing sites written for permissive hosting environments.

To use a different mode, set db.sqlMode in .testbefore/config.json. For example, merge this setting into the existing db object:

{
  "db": {
    "sqlMode": "STRICT_TRANS_TABLES,ONLY_FULL_GROUP_BY"
  }
}

Choose settings appropriate to the environment you want to test against. A permissive local configuration may behave differently from a stricter production database.

Database persistence, imports, and reset

MySQL data is stored in a named Docker volume and survives normal environment stops and restarts.

The extension automatically imports .sql files found in:

• The project root.
• db/.
• database/.
• sql/.

Import runs only when initializing an empty database, using the official MySQL image's docker-entrypoint-initdb.d mechanism. Restarting an existing database does not import the files again.

Test Before Publish: Reset Database deletes the local test database contents and starts with a fresh database. The discovered SQL files are then imported again.

Inspecting the database with Adminer

Adminer is available on the configured adminer port, which defaults to 8081:

http://localhost:8081

The Server field is prefilled with db, the Docker Compose database service name. Do not use localhost in Adminer: that would refer to the Adminer container itself.

Default local credentials, configurable in .testbefore/config.json:

Previewing test emails with Mailpit

Mailpit captures messages routed through the local test mail configuration so you can inspect them in a browser.

Its web interface is available on the configured mailpit port, which defaults to 8025:

http://localhost:8025

Native PHP mail()

PHP's native mail() function is automatically redirected to Mailpit through msmtp in the generated environment.

SMTP libraries

For PHPMailer, Symfony Mailer, or another SMTP library, configure the application to use:

If your application reads mail settings from environment variables, you can provide overrides:

{
  "envOverrides": {
    "MAIL_HOST": "mailpit",
    "MAIL_PORT": "1025"
  }
}

Use the variable names expected by your application and adjust any additional mail settings it requires. SMTP connections still configured to use an external mail provider, and messages sent through external email APIs, are not automatically intercepted by this setup.

Live logs

While the environment is running, container logs are streamed to the Test Before Publish output channel in VS Code. This includes PHP errors and warnings emitted in the container logs.

Environment variable overrides

An existing .env file may contain production values such as APP_URL or SITE_URL that cause incorrect redirects or asset paths locally.

Use envOverrides in .testbefore/config.json to inject local values into the web/PHP container without editing the project's .env file:

{
  "envOverrides": {
    "APP_URL": "http://localhost:8090"
  }
}

Replace the URL and port with those of your local environment. The overrides are injected alongside the environment's DB_* variables. Your application must read and honor the supplied environment variables.

Run Test Before Publish: Start again after changing these settings.

Existing projects with hard-coded paths

Some sites use absolute production paths in PHP require or include statements. Others expect their URLs and assets to live under a fixed prefix such as /monsite/public/.

The extraMounts setting mounts the project at additional paths inside the container:

{
  "extraMounts": [
    "/var/www/html/domains/exemple.com/www/monsite",
    "/var/www/html/public/monsite"
  ]
}

These are examples: use the paths required by your own project.

Absolute PHP include paths

Choose the additional mount point so that the file referenced by require or include resolves to its matching location inside the mounted project.

For example, if the application expects /domains/exemple.com/www/monsite/vendor/autoload.php and your project contains vendor/autoload.php, mount the project at /domains/exemple.com/www/monsite.

Preserve any prefix actually present in the path reported by PHP, including /var/www/html if applicable.

Fixed URL prefixes

For a project using public as its document root and expecting URLs starting with /monsite/, the documented additional mount is:

/var/www/html/public/monsite

The mount contains the whole project, including its public/ directory; do not append another public to that mount path.

Use an additional mount rather than relying on a symbolic link created under /var/www/html during image build: the runtime project mount hides the image's original contents at that location.

Run Test Before Publish: Start again after changing extraMounts.

Pausing automatic uploads during testing

The extension can temporarily disable a compatible tool's boolean setting in a workspace JSON file. This is useful for pausing FTP/SFTP upload-on-save while testing changes locally.

For example:

{
  "pauseDuringTest": [
    {
      "file": ".vscode/ftp-sync.json",
      "key": "uploadOnSave"
    }
  ]
}

Behavior:

1. Start saves the existing value and sets the specified key to false.
2. Stop restores the saved value.
3. If VS Code closes without Stop, the next Start detects the pending state, restores the saved value, and then pauses the setting again for the new test session.

This integration applies to the configured file and setting. It does not automatically pause every deployment extension or upload mechanism.

Excluding generated files from uploads and Git

If .vscode/ftp-sync.json exists, the extension adds .testbefore/** to its ignore array when needed. This is checked during both Configure and Start.

For another compatible tool or configuration file, use ensureIgnored:

{
  "ensureIgnored": [
    {
      "file": ".vscode/mon-outil.json",
      "key": "ignore",
      "value": ".testbefore/**"
    }
  ]
}

Unlike pauseDuringTest, this is a persistent configuration change: the ignore entry is not removed when testing stops. The upload tool must honor the configured ignore setting.

When a .git entry is present in the project, the extension also adds .testbefore/ to .gitignore, creating that file if needed. This is checked during Configure and Start. As with any Git ignore rule, this does not untrack files already committed to the repository.

Sharing a temporary preview link

Requires a license and a local installation of cloudflared.

Run Test Before Publish: Share Link (start) to open a Cloudflare tunnel to your environment's web port. The extension offers to copy the generated public URL:

https://xxxx.trycloudflare.com

No Cloudflare account is required for this sharing mode.

On Windows, you can install cloudflared with:

winget install --id Cloudflare.cloudflared

Run Test Before Publish: Share Link (stop) to close the tunnel. The extension also stops sharing when you stop the environment or close VS Code during normal operation.

Keep in mind:

• The URL is public while the tunnel is running. Anyone who knows it can access the site.
• The tunnel targets only the web port, not the separate Adminer, Mailpit, or MySQL ports. Content exposed by your web application remains accessible through the shared site.
• A new random URL is generated each time sharing starts.
• Your local environment must remain running for the preview to work.

Windows prerequisite troubleshooting

Docker Desktop must be installed and running. When using its WSL2 backend on Windows, the required Windows features must also be enabled.

If Docker Desktop reports Virtualization support not detected, and virtualization is already enabled in your BIOS/UEFI settings, open PowerShell as Administrator and run:

dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart
dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart

Restart Windows. Then open a normal PowerShell session and run:

wsl --update
wsl --set-default-version 2

Start Docker Desktop again before launching your test environment.