PHMATE - PHP Built-in Server Manager

PHMATE is a lightweight command-line utility that simplifies management of PHP's built-in web server for local development. It streamlines server startup, configuration, and monitoring with sensible defaults and multiple profile support.

Features

• Server Management: Start, stop, restart, and check status of PHP's built-in web server
• Interactive Wizard: Configure server settings via a guided setup with phmate wizard
• Multiple Profiles: Create and manage different server configurations with the --profile option
• Document Root-based Configuration: Configuration files stored in each project's document root for isolation
• Multiple Concurrent Servers: Run multiple PHP servers simultaneously in different projects
• Custom PHP Settings: Specify PHP binary path and custom php.ini files
• Router Script Support: Use custom PHP router script files with auto-detection
• Auto-Router Detection: Automatically detects and uses router.php in document root if present
• Configurable Host/Port: Run servers on custom hostnames and ports
• Robust Error Handling: Comprehensive error checking, validation, and detailed logs
• Logging: Detailed logs with configurable verbosity levels (DEBUG, INFO, WARNING, ERROR)
• Status Monitoring: View running server status including uptime and process information
• Project Isolation: Each project maintains its own configuration and server state

Requirements

• Bash: Version 4.0 or higher
• PHP: Version 8.0 or higher with built-in web server support
• Standard Unix Tools: ps, kill, netstat/ss (optional for port checking)

Installation

Quick Install

1. Download the script:

   curl -o phmate.sh https://raw.githubusercontent.com/dlzi/phmate/main/phmate.sh

2. Make it executable:

   chmod +x phmate.sh

3. Optionally, move to a directory in your PATH:

   sudo mv phmate.sh /usr/local/bin/phmate

Using Makefile

If you've cloned the repository, you can use the provided Makefile for a complete installation including documentation and bash completion:

git clone https://github.com/dlzi/phmate.git
cd phmate
make install

This will install PHMATE to /usr/local/bin/phmate by default. To install to a different location:

make install PREFIX=~/.local

To uninstall PHMATE when installed with the Makefile:

make uninstall

Using install.sh Script

The repository includes an installation script that properly installs all components including documentation and bash completion:

git clone https://github.com/dlzi/phmate.git
cd phmate
./install.sh

You can customize the installation directories by setting environment variables:

PREFIX=~/.local ./install.sh

To uninstall PHMATE when installed with the install script:

./uninstall.sh

Package Installation

Arch Linux (and derivatives)

For Arch Linux and derivatives (Manjaro, EndeavourOS, etc.), a PKGBUILD is provided:

git clone https://github.com/dlzi/phmate.git
cd phmate/packages/arch
makepkg -si

Verification

Verify installation:

phmate version

Usage

PHMATE uses the syntax: phmate COMMAND [OPTIONS] [<hostname>:<port>]

Commands

• Server Control:
  • phmate start [<hostname>:<port>] [options]: Start the PHP server
  • phmate stop: Stop the running server
  • phmate restart [options]: Restart the server
  • phmate status: Check server status
  • phmate list: List available profiles in current document root
  • phmate wizard: Interactively configure server settings
  • phmate config: Display current configuration
  • phmate help: Show help information
  • phmate version: Display version information

Options

• --docroot=<path>: Set document root directory (default: current directory)
• --php=<path>: Specify PHP binary path
• --php-ini=<path>: Use custom PHP ini file
• --profile=<name>: Use specific configuration profile (default: default)
• --router=<file>: Set router script (file path)
• --debug: Enable debug logging (sets LOG_LEVEL=DEBUG)

Auto-Router Detection

PHMATE automatically detects and uses a router.php file in the document root directory if:

• No explicit --router option is provided
• A router.php file exists in the document root

This feature makes it convenient for projects that follow the common convention of using router.php as the main routing script.

Precedence: Explicit --router option always takes precedence over auto-detection.

Examples

• Start a server on the default host/port (localhost:8000):

  phmate start

• Start a server on a specific host and port:

  phmate start localhost:8080

• Use a custom PHP router script (explicit):

  phmate start --router=custom_router.php

• Start server with auto-detection of router.php:

  phmate start --docroot=/path/to/www
  # Will automatically use /path/to/www/router.php if it exists

• Start server with a specific document root:

  phmate start --docroot=/path/to/www

• Use a specific PHP version:

  phmate start --php=/usr/bin/php8.1

• Use a custom PHP ini file:

  phmate start --php-ini=/etc/php/8.1/php.ini

• Create and use a named configuration profile:

  phmate start --profile=dev

• List available profiles in current project:

  phmate list

• Check server status:

  phmate status

• Stop the server:

  phmate stop

• Restart the server:

  phmate restart

• Configure interactively:

  phmate wizard

Multiple Concurrent Servers

PHMATE now supports running multiple servers simultaneously:

# Start server in project 1
cd /path/to/project1
phmate start localhost:8000 --profile=main

# Start server in project 2  
cd /path/to/project2
phmate start localhost:8001 --profile=staging

# Start another profile in project 1
cd /path/to/project1
phmate start localhost:8002 --profile=dev

Each server maintains its own configuration, logs, and process state.

Configuration

Document Root-based Storage

Starting with version 1.2.0, PHMATE stores configuration files in the document root directory:

• Configuration Directory: <docroot>/.phmate/
• Profile Configuration: <docroot>/.phmate/config_<profile>
• PID Files: <docroot>/.phmate/phmate_<profile>.pid
• Log Files: <docroot>/.phmate/phmate_<profile>.log
• Global Fallback: ${HOME}/.config/phmate/ (customize with PHMATE_CONFIG_DIR)

Benefits of Document Root Storage

1. Project Isolation: Each project has its own server configuration
2. Multiple Servers: Run different projects simultaneously without conflicts
3. Portable Configuration: Configuration travels with the project
4. Team Collaboration: Share project-specific server settings with team members
5. Version Control: Optionally commit .phmate directory for consistent team setup

Environment Variables

• PHMATE_CONFIG_DIR: Override default global configuration directory
• LOG_LEVEL: Set logging verbosity (DEBUG, INFO, WARNING, ERROR)

Profile Behavior

• All Profiles: Configuration settings are now saved to disk in the document root
• Project-specific: Each project maintains its own set of profiles
• Persistence: Settings persist between sessions within each project
• Isolation: Profiles in different projects are completely independent

Configuration Files Structure

your-project/
├── .phmate/
│   ├── config_default      # Default profile configuration
│   ├── config_dev          # Development profile configuration
│   ├── config_staging      # Staging profile configuration
│   ├── phmate_default.pid  # Default profile PID file
│   ├── phmate_dev.pid      # Development profile PID file
│   ├── phmate_default.log  # Default profile log file
│   └── phmate_dev.log      # Development profile log file
├── index.php
├── router.php              # Auto-detected if present
└── ... (your project files)

Using Router Scripts

Custom Router Scripts

A custom PHP router script allows you to handle HTTP requests in specific ways, such as routing requests to a single entry point or serving static files directly. Here's a simple example:

<?php
// router.php
if (preg_match('/\.(?:png|jpg|jpeg|gif|css|js)$/', $_SERVER["REQUEST_URI"])) {
    return false; // Serve the requested file as-is
} else {
    include_once 'index.php'; // Route all other requests to index.php
}

Router Script Usage

1. Auto-Detection: Place a router.php file in your document root and start the server:

   phmate start
   # Automatically detects and uses ./router.php

2. Explicit Router: Specify a custom router script:

   phmate start --router=custom_router.php

3. Different Document Root: Auto-detection works with custom document roots:

   phmate start --docroot=/var/www/html
   # Will use /var/www/html/router.php if it exists

Troubleshooting

• Port Already in Use: Use phmate stop to stop any existing server, or specify a different port
• Permission Denied: Ensure the script is executable (chmod +x phmate.sh)
• PHP Not Found: Specify PHP path with --php=/path/to/php
• PHP Version Too Old: Update to PHP 8.0+ or install compatible version
• Log File Access: Check that the document root directory is writable for .phmate directory creation
• Router Script Issues: Ensure router.php has correct PHP syntax and is readable
• Configuration Conflicts: Use different profiles (--profile=name) for different server configurations
• Multiple Servers: Check phmate list to see all running profiles in current project
• Detailed Errors: Use --debug flag for verbose logging

Check logs for more information:

• Project logs: <docroot>/.phmate/phmate_<profile>.log
• Global fallback: ${HOME}/.config/phmate/phmate.log

Migration from Previous Versions

If you're upgrading from a version prior to 1.2.0:

1. Existing configurations in ~/.config/phmate/ will continue to work as a fallback
2. New configurations will be created in document root directories
3. Manual migration: Copy old configs to new locations if desired:

   # Example migration
   mkdir -p /path/to/project/.phmate
   cp ~/.config/phmate/config_default /path/to/project/.phmate/

Environment Variables

• PHMATE_CONFIG_DIR: Override default global configuration directory
• LOG_LEVEL: Set logging verbosity (DEBUG, INFO, WARNING, ERROR)

License

PHMATE is released under the MIT License.

Author

Developed by Daniel Zilli.