PHP Legacy Refactor AI

Modernize your legacy PHP codebase with AI-powered analysis and refactoring - 100% local, 100% private.

A CLI tool that uses local AI models (via Ollama) to analyze PHP code, detect deprecated functions, security issues, and automatically generate PHPUnit tests and documentation. All processing happens on your machine - no data is sent to external servers.

Why This Tool?

• Privacy First: Your code never leaves your machine. Uses Ollama for 100% local AI processing.
• Legacy Code Support: Specifically designed to help modernize PHP 5.x/7.x code to PHP 8.x standards.
• Automated Testing: Generate PHPUnit test skeletons automatically.
• Documentation: Auto-generate DocBlocks and OpenAPI specs.
• Open Source: Free to use, modify, and contribute.

Features

• Analyze: Detect deprecated functions, old syntax, missing type hints, and security issues
• Test: Generate PHPUnit test files automatically
• Docs: Generate DocBlock comments or OpenAPI specifications

Requirements

• Node.js 18+
• Ollama running locally
• PHP 8.1+ and Composer (for running generated tests)

Installation

Quick Install (recommended)

# Install globally from npm
npm install -g php-legacy-refactor-ai

# Now you can use it anywhere
php-refactor analyze ./src

Or run directly without installing:

npx php-legacy-refactor-ai analyze ./src

From Source (for contributors)

# Clone the repository
git clone https://github.com/mary2501/php-legacy-refactor-ai.git
cd php-legacy-refactor-ai

# Install dependencies and build
npm install
npm run build

# Link globally
npm link

Setup Ollama

Installation

macOS:

brew install ollama

Linux:

curl -fsSL https://ollama.ai/install.sh | sh

Windows: Download the installer from ollama.ai/download

Start Ollama

# Start the server
ollama serve

# Pull a model (in another terminal)
ollama pull llama3

Usage

Analyze PHP Code

Scan files for deprecations and get improvement suggestions:

# Analyze a directory
npx php-refactor analyze ./src --php-version 8.3

# Analyze a single file
npx php-refactor analyze ./src/UserService.php -o report.md

# Use a different model
npx php-refactor analyze ./src --model codellama

Output: Markdown report with:

• Table of issues (line, problem, suggestion)
• Refactored code examples
• Security recommendations

Note: The --php-version flag affects suggestions. For example, --php-version 5 won't suggest return types (added in PHP 7.0).

Generate PHPUnit Tests

Create test skeletons for PHP classes:

# Generate tests for all classes in a directory
npx php-refactor test ./src -o ./tests

# Generate tests for a single class
npx php-refactor test ./src/UserService.php -o ./tests

Output: PHPUnit test files with:

• Test methods for each public method
• Data providers for edge cases
• setUp/tearDown boilerplate

Generate Documentation

DocBlock Comments

# Add DocBlocks to PHP files
npx php-refactor docs ./src --format docblock

# Output to specific directory
npx php-refactor docs ./src --format docblock -o ./documented

Output: PHP files with comprehensive DocBlock comments.

OpenAPI Specification

# Generate OpenAPI from controllers
npx php-refactor docs ./src/Controllers --format openapi -o api.yaml

Output: OpenAPI 3.0.3 YAML specification.

Options

| Option | Description | Default | |--------|-------------|---------| | --php-version <version> | Target PHP version | 8.3 | | -o, --output <path> | Output file/directory | varies | | --model <model> | Ollama model to use | llama3 | | -f, --format <format> | Docs format: docblock or openapi | docblock |

Recommended Models

All models run 100% locally on your machine. No data is sent to external servers.

Available Models

| Model | Size | Speed | Best For | |-------|------|-------|----------| | llama3 | 4.7GB | Fast | Simple analysis, small files | | llama3:70b | 40GB | Slow | Better quality, needs 64GB+ RAM | | codellama | 3.8GB | Fast | Code analysis, refactoring | | codellama:13b | 7.4GB | Medium | Better code understanding | | deepseek-coder | 776MB | Fast | Code-focused, lightweight | | deepseek-coder:6.7b | 3.8GB | Medium | Better code analysis | | qwen2.5-coder | 4.7GB | Fast | Modern code model | | mistral | 4.1GB | Fast | General purpose |

Installing Models

# Install the model you want to use
ollama pull codellama
ollama pull deepseek-coder
ollama pull qwen2.5-coder

# List installed models
ollama list

Model Recommendations

• Small files (< 200 lines): llama3 or codellama
• Large files / complex code: codellama:13b or deepseek-coder:6.7b
• Best for PHP refactoring: codellama or qwen2.5-coder
• Limited RAM (< 8GB): deepseek-coder (smallest)

Usage with Different Models

# Use codellama for analysis
npx php-refactor analyze ./src --model codellama

# Use deepseek for test generation
npx php-refactor test ./src/User.php --model deepseek-coder

# Use qwen for documentation
npx php-refactor docs ./src --model qwen2.5-coder

Limitations of Local Models

Local AI models have some limitations compared to cloud-based solutions:

• Large files: Models may struggle with files over 300-500 lines. Try splitting large files or analyzing them individually.
• Complex code: Deeply nested or complex logic may result in incomplete analysis.
• Format issues: Sometimes models generate descriptions instead of structured output (tables, code). The tool will warn you when this happens and suggest trying a different model.
• Inconsistent results: Running the same command twice may produce different results.
• Language confusion: Some models may occasionally convert PHP to Python or other languages.

Tips for better results:

• Use code-specific models (codellama, qwen2.5-coder) instead of general-purpose ones
• For large projects, analyze files one at a time
• If a model fails, try a different one
• Larger model variants (e.g., codellama:13b) usually produce better results but require more RAM

Example Output

Analysis Report

# Analysis Report: UserService.php

## Issues Found

| Line | Category | Issue | Suggestion |
|------|----------|-------|------------|
| 15 | Deprecated | `mysql_connect()` | Use PDO with prepared statements |
| 23 | Syntax | `array()` | Use short array syntax `[]` |
| 45 | Type Safety | No return type | Add `: bool` return type |

## Refactored Code

<?php
class UserService
{
    public function __construct(
        private readonly PDO $db
    ) {}

    public function findById(int $id): ?User
    {
        // ...
    }
}

Project Structure

php-legacy-refactor-ai/
├── bin/cli.ts           # CLI entry point
├── src/
│   ├── index.ts         # Main exports
│   ├── scanner.ts       # PHP file scanner
│   ├── ollama.ts        # Ollama API client
│   └── commands/
│       ├── analyze.ts   # Analyze command
│       ├── test.ts      # Test generation
│       └── docs.ts      # Documentation
├── prompts/             # AI system prompts (customizable)
├── examples/            # Example PHP files for testing
├── dist/                # Compiled JavaScript (generated)
├── tsconfig.json        # TypeScript config
├── package.json         # Node.js dependencies
└── composer.json        # PHP dependencies (PHPUnit)

Contributing

Contributions are welcome! Whether it's bug fixes, new features, or documentation improvements.

How to Contribute

1. Fork the repository
2. Clone your fork: git clone https://github.com/mary2501/php-legacy-refactor-ai.git
3. Create a branch: git checkout -b feature/my-new-feature
4. Make changes and test them
5. Commit: git commit -m "Add my new feature"
6. Push: git push origin feature/my-new-feature
7. Open a Pull Request

Ideas for Contributions

• Support for additional AI providers (OpenAI, Anthropic, etc.)
• Better prompts for more accurate analysis
• Support for other PHP testing frameworks (Pest)
• Web UI for easier usage
• VS Code extension
• Additional output formats (JSON, HTML reports)
• Improved PHP parsing for better class detection
• Support for analyzing entire directories recursively
• Caching to avoid re-analyzing unchanged files

Development Setup

git clone https://github.com/mary2501/php-legacy-refactor-ai.git
cd php-legacy-refactor-ai
npm install
npm run dev  # Watch mode for development

Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions

If you find this tool useful, please consider giving it a ⭐ on GitHub!

License

MIT License - see LICENSE file for details.

"AI can write the tests, but only you can explain to your PM why it still takes another week." 😄

Made with ❤️ for the PHP community