VS Code Apache Launcher (Windows-first)

A VS Code extension concept to launch and control a local Apache web server for the current project with PHP support and smart .htaccess behavior.

Goal

Provide a fast, editor-driven local web runtime for .php and .html files directly from VS Code, without manual Apache config edits each time.

Current Product Decisions

• Platform: Windows first (v1 scope).
• Start trigger: from VS Code editor context menu (right-click in active editor), not Explorer file tree context menu.
• Allowed start file types: only .php and .html.
• Project root: workspace folder containing the active file where start was invoked.
• Host default: localhost.
• Ports: do not use 80/443; prefer development ports, starting from 55000, selecting the first free port.

Planned Features

1. Apache process control

• Start / Stop / Restart commands.
• Output channel for logs and diagnostics.
• State tracking to avoid duplicate starts.

2. Extension settings

• Apache installation path (e.g. httpd.exe).
• Base Apache config template path.
• Global .htaccess template path.
• Host and port strategy (auto/fixed).
• PHP executable / CGI path and php.ini path.

3. Dynamic runtime config

• Generate temp Apache config per workspace launch.
• DocumentRoot = active workspace/project root.
• Validate generated config (httpd -t) before launch.

4. .htaccess precedence

• If project root contains local .htaccess, use it.
• Otherwise use global fallback template/rules.
• When no local .htaccess, route / to the file from which server start was invoked.

5. PHP support

• Optional enable/disable.
• Validate configured PHP paths before start.

Suggested Roadmap

1. Scaffold extension (yo code, TypeScript).
2. Add command + menu contributions (editor context + command palette).
3. Implement settings schema.
4. Implement validators (workspace, file type, paths, port).
5. Implement port finder (55000+, first free).
6. Implement config generator + syntax check.
7. Implement process manager and logging.
8. Add integration tests for start/stop/restart and fallback logic.
9. Package (vsce package) and test in clean Windows VM.

Non-Goals for v1

• Linux/macOS support.
• Apache service integration via Windows Services.
• HTTPS certificate automation.
• Complex multi-vhost orchestration.

Development Notes

• Keep behavior explicit and deterministic per workspace.
• Favor actionable error messages (path missing, config test failed, port occupied).
• Ensure stop/restart are robust and idempotent.

Toolchain

• Runtime target: Node.js 22 LTS.
• Package manager: npm 10.x.
• Recommendation: use the .nvmrc file in this repository to align local Node version.

Installation & Usage

1. Install dependencies:

• npm install

2. Build extension:

• npm run build

3. Run extension in VS Code:

• Press F5 from this project to launch Extension Development Host.

4. Configure settings in VS Code:

• Apache Launcher: Apache Bin Path
• Apache Launcher: Apache Base Config Path
• Apache Launcher: Apache Global Htaccess Path

5. Start server:

• Open a .php or .html file.
• Right click in editor and run Start Apache Server.

6. Control server:

• Use Stop Apache Server / Restart Apache Server.
• Use Validate Setup, Open Served URL, and Reveal Runtime Config.

Settings Reference

• apache.binPath: absolute path to httpd.exe example: C:\Apache24\bin\httpd.exe
• apache.baseConfigPath: absolute path to base Apache config template example: C:\Apache24\conf\httpd.conf
• apache.globalHtaccessPath: absolute path to global fallback .htaccess template example: C:\apache-launcher\global.htaccess
• server.host: host used for server URL (default: localhost)
• server.portMode: auto or fixed (default: auto)
• server.fixedPort: fixed port for fixed mode
• server.portRangeStart: auto scan start (default: 55000)
• server.portRangeEnd: auto scan end (default: 55100)
• php.enabled: enable PHP wiring in runtime config (default: false)
• php.cgiPath: absolute path to php-cgi.exe example: C:\php\php-cgi.exe
• php.iniPath: absolute path to php.ini example: C:\php\php.ini

Architecture

flowchart TD
  A["Editor Command: Start"] --> B["Validation Layer"]
  B --> C["Port Resolution"]
  C --> D[".htaccess Resolution"]
  D --> E["Runtime Apache Config Generation"]
  E --> F["Apache Syntax Check (httpd -t)"]
  F --> G["Process Manager Start"]
  G --> H["Status Bar + Output Channel Updates"]
  I["Stop/Restart/Deactivate"] --> J["Process Manager Stop"]
  J --> K["Temporary .htaccess Cleanup"]

Troubleshooting

• Start fails with config validation error: check path settings and ensure files exist.
• Start fails with syntax check: open Apache Launcher output channel and inspect [verify] lines.
• Port unavailable: increase server.portRangeEnd or switch to fixed mode with free port.
• PHP pages not executing: verify php.enabled=true, and valid php.cgiPath / php.iniPath.
• Server appears running but URL fails: verify firewall/antivirus rules and Apache base config compatibility.

Windows Layout Examples

Example A: Apache24 + standalone PHP

• Apache: C:\Apache24\bin\httpd.exe
• Apache config: C:\Apache24\conf\httpd.conf
• Global htaccess template: C:\apache-launcher\global.htaccess
• PHP CGI: C:\php\php-cgi.exe
• PHP INI: C:\php\php.ini

Example B: XAMPP-style paths

• Apache: C:\xampp\apache\bin\httpd.exe
• Apache config: C:\xampp\apache\conf\httpd.conf
• Global htaccess template: C:\xampp\apache\conf\global.htaccess
• PHP CGI: C:\xampp\php\php-cgi.exe
• PHP INI: C:\xampp\php\php.ini

Contributor Quick Start

1. Install dependencies: npm install
2. Run static checks: npm run lint
3. Run tests: npm run test
4. Build extension: npm run build
5. Launch Extension Development Host: F5
6. Keep TODO.md up to date and commit completed work.