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

$3

``bash


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:

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

$3

`bash


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

$3

macOS:
`bash
brew install ollama
`

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

Windows:
Download the installer from ollama.ai/download

$3

`bash


Start the server

ollama serve

Pull a model (in another terminal)

ollama pull llama3
`

Usage

$3

Scan files for deprecations and get improvement suggestions:

`bash


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).

$3

Create test skeletons for PHP classes:

`bash


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

$3

#### DocBlock Comments

`bash


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

`bash


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 | Target PHP version | 8.3 |
| -o, --output | Output file/directory | varies |
| --model | Ollama model to use | llama3 |
| -f, --format | Docs format: docblock or openapi | docblock |

Recommended Models

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

$3

| 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 |

$3

`bash


Install the model you want to use

ollama pull codellama
ollama pull deepseek-coder
ollama pull qwen2.5-coder

List installed models

ollama list
`

$3

- 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)

$3

`bash


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
`

$3

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

$3

`markdown


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

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.

$3

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

$3

- 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

$3

`bash
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