How to Migrate a PHP Application to Python (Django/Flask)

TL;DR

• Bottom line: Migrate incrementally using the strangler fig pattern — run PHP and Python side-by-side behind a reverse proxy, converting one route/module at a time, starting with the API layer and working inward to models and templates. [src6]
• Key tool/command: django-admin startproject myapp && python manage.py startapp core (Django) or pip install flask && flask run (Flask) or pip install fastapi uvicorn && uvicorn main:app (FastAPI)
• Watch out for: Trying to do a big-bang rewrite — the #1 cause of failed migrations. Always migrate incrementally. [src6]
• Works with: Django 5.2 LTS (Python 3.10-3.13, recommended for migrations) or Django 6.0 (Python 3.12-3.14), Flask 3.1.x, FastAPI 0.115+ (latest 0.136.x), PHP 8.1-8.5 as source [src9]

Constraints

• Never attempt a big-bang rewrite of a production PHP app — use the strangler fig pattern to migrate incrementally, or risk project failure (60-70% of full rewrites are abandoned or severely delayed). [src6]
• Set managed = False on all Django models generated via inspectdb until you are ready for Django to own the database schema — otherwise makemigrations will attempt to recreate or alter existing PHP tables. [src1]
• Both PHP and Python backends must share the same JWT secret during the transition period — mismatched secrets cause silent authentication failures across the proxy boundary. [src4]
• Django 5.2 LTS requires PostgreSQL 14+; if your PHP app runs MySQL, plan a database migration step or use django.db.backends.mysql. [src7]
• Django 6.0 (Dec 2025) dropped Python 3.10/3.11 (requires 3.12+), removed cx_Oracle, and made custom ORM expression as_sql() params return tuples (not lists). For a migration target, prefer the 5.2 LTS line (supported through April 2028) unless you control the Python runtime. [src9]
• Laravel bcrypt hashes use $2y$ prefix; Django defaults to PBKDF2 — add BCryptSHA256PasswordHasher to PASSWORD_HASHERS or all existing users will fail to authenticate. [src4]

Quick Reference

Decision Tree

Full script: decision-tree.txt (38 lines)

START: Should I migrate my PHP app to Python?
+-- Is your PHP app actively maintained and working well?
|   +-- YES -> Consider staying with PHP. Migration has real cost. Only proceed if
|   |          there's a strategic reason (team skills, ecosystem needs, ML/AI integration).
|   +-- NO v
+-- Do you need ML/AI, data science, or scientific computing?
|   +-- YES -> Migrate to Python. Python's ecosystem is unmatched here. [src8]
|   +-- NO v
+-- Is the codebase > 100K lines of PHP?
|   +-- YES -> Use Strangler Fig pattern. Run both side-by-side. -> See Step 4 [src6]
|   +-- NO v
+-- Do you need a full-featured admin, ORM, auth out of the box?
|   +-- YES -> Choose Django -> See Code Example 1 [src4]
|   +-- NO v
+-- Need a lightweight microservice or API?
|   +-- YES -> Choose Flask or FastAPI -> See Code Example 2 [src2, src8]
|   +-- NO v
+-- DEFAULT -> Django (batteries-included is safer for most migrations) [src3]

Framework choice:
+-- Need admin panel, user management, ORM, forms? -> Django [src4]
+-- Need maximum flexibility, minimal overhead? -> Flask [src2]
+-- Need async-first, high-performance API, auto-docs? -> FastAPI [src8]
+-- Migrating from Laravel specifically? -> Django (closest conceptual match) [src3]

Decision Logic

Agent-ready if/then rules for picking the migration target and strategy. Each rule maps a concrete situation to a recommendation.

If the codebase is a production app over 100K lines

→ Use the strangler fig pattern: run PHP and Python behind a reverse proxy and convert one route/module at a time; never attempt a big-bang rewrite (60-70% fail). [src6]

If you need a batteries-included framework (admin, ORM, auth, forms)

→ Choose Django, and target Django 5.2 LTS (supported through April 2028) rather than 6.0 unless you fully control the Python 3.12+ runtime. [src4, src7, src9]

If you need an async-first, API-only service with auto-generated OpenAPI docs

→ Choose FastAPI (0.115+, latest 0.136.x); it outperforms Flask/Django for I/O-bound APIs but ships no admin/ORM/templates. [src8]

If you need a minimal, flexible microservice without Django's conventions

→ Choose Flask 3.1.x with Flask-SQLAlchemy and Flask-Migrate; add flask-wtf for CSRF. [src2]

If your PHP app stores Laravel bcrypt ($2y$) password hashes

→ Add BCryptSHA256PasswordHasher to PASSWORD_HASHERS and install bcrypt before pointing Python at the users table, or every login fails. [src4]

If the PHP app runs MySQL and you want Django on PostgreSQL

→ Keep Django on MySQL via django.db.backends.mysql during transition, or run a dedicated data-migration step first; do not switch the database engine and the framework in the same cutover. [src1, src7]

If the PHP app is small, stable, well-maintained, and has no ML/AI need

→ Do not migrate; the maintenance cost is lower than the migration cost. Revisit only if team skills or ecosystem needs change. [src5, src6]

Step-by-Step Guide

1. Audit the PHP codebase and map dependencies

Catalog every route, model, middleware, job, and third-party integration in your PHP app. Create a spreadsheet mapping each PHP component to its Python equivalent. Identify shared infrastructure (databases, caches, queues) that both systems must access during the transition. [src6]

# List all routes in Laravel
php artisan route:list --json > routes_inventory.json

# Count models, controllers, middleware
find app/Models -name "*.php" | wc -l
find app/Http/Controllers -name "*.php" | wc -l
find app/Http/Middleware -name "*.php" | wc -l

# List Composer dependencies and check for Python equivalents
composer show --format=json > php_dependencies.json

# Estimate lines of code
find app/ -name "*.php" -exec cat {} + | wc -l

Verify: Review routes_inventory.json — every route must have a planned Python equivalent before proceeding.

2. Set up the Python project alongside PHP

Create the Django or Flask project in a separate directory. Both apps will run simultaneously, sharing the same database. Use a reverse proxy (Nginx, Caddy, or Cloudflare) to route traffic to the appropriate backend. [src4]

# Django setup (recommended for most migrations)
python -m venv venv
source venv/bin/activate  # Linux/macOS
# venv\Scripts\activate   # Windows
pip install django==5.2.* djangorestframework psycopg[binary] python-dotenv
django-admin startproject myproject .
python manage.py startapp core

# Flask setup (alternative — lightweight)
pip install flask flask-sqlalchemy flask-migrate python-dotenv
mkdir -p app/{models,routes,templates}

# FastAPI setup (alternative — async-first APIs)
pip install fastapi uvicorn[standard] sqlalchemy python-dotenv
mkdir -p app/{models,routes}

# Django: myproject/settings.py — connect to existing PHP database
import os
from dotenv import load_dotenv
load_dotenv()

DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.postgresql',
        'NAME': os.environ.get('DB_NAME'),
        'USER': os.environ.get('DB_USER'),
        'PASSWORD': os.environ.get('DB_PASSWORD'),
        'HOST': os.environ.get('DB_HOST', 'localhost'),
        'PORT': os.environ.get('DB_PORT', '5432'),
    }
}

Verify: python manage.py check → System check identified no issues.

3. Introspect and generate models from the existing database

Django can reverse-engineer your existing PHP database schema into Python models. This avoids rewriting schema definitions manually and ensures your Python app reads the same tables. [src1]

# Generate models from existing database
python manage.py inspectdb > core/models_generated.py

# Review and clean up the generated models, then move to models.py
# Key: set managed = False initially to prevent Django from altering tables

# core/models.py — cleaned up from inspectdb output
from django.db import models

class User(models.Model):
    name = models.CharField(max_length=255)
    email = models.EmailField(unique=True)
    password = models.CharField(max_length=255)  # Laravel bcrypt hash
    created_at = models.DateTimeField(auto_now_add=True)
    updated_at = models.DateTimeField(auto_now=True)

    class Meta:
        db_table = 'users'      # Match existing PHP table name
        managed = False          # Don't let Django alter this table yet

Verify: python manage.py shell -c "from core.models import User; print(User.objects.count())" — should return the same count as your PHP database.

4. Migrate routes incrementally using the strangler fig pattern

Start with low-traffic, read-only API endpoints. Configure your reverse proxy to route specific paths to the Python backend while everything else continues going to PHP. The rhythm is: proxy, extract, validate, repeat. [src6]

# Nginx config: route /api/v2/* to Django, everything else to PHP
upstream php_backend {
    server 127.0.0.1:8080;
}
upstream django_backend {
    server 127.0.0.1:8000;
}

server {
    listen 80;

    # New Python endpoints
    location /api/v2/ {
        proxy_pass http://django_backend;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }

    # Everything else stays on PHP
    location / {
        proxy_pass http://php_backend;
        proxy_set_header Host $host;
    }
}

Verify: curl -s http://localhost/api/v2/health | jq . → {"status": "ok", "backend": "django"}

5. Convert authentication and session handling

Authentication is the critical bridge between PHP and Python. Both systems must validate the same user sessions during the transition period. The simplest approach is token-based auth (JWT) shared between both backends. [src4]

# Django: shared JWT authentication between PHP and Python
# pip install djangorestframework-simplejwt
from datetime import timedelta

# myproject/settings.py
REST_FRAMEWORK = {
    'DEFAULT_AUTHENTICATION_CLASSES': [
        'rest_framework_simplejwt.authentication.JWTAuthentication',
    ],
}

SIMPLE_JWT = {
    'ALGORITHM': 'HS256',
    'SIGNING_KEY': os.environ.get('JWT_SECRET'),  # Same secret as PHP
    'AUTH_HEADER_TYPES': ('Bearer',),
    'ACCESS_TOKEN_LIFETIME': timedelta(minutes=60),
}

# Handle Laravel's bcrypt $2y$ password hashes
PASSWORD_HASHERS = [
    'django.contrib.auth.hashers.BCryptSHA256PasswordHasher',
    'django.contrib.auth.hashers.PBKDF2PasswordHasher',
]

// PHP side: generate JWT tokens compatible with Django
// composer require firebase/php-jwt
use Firebase\JWT\JWT;

$payload = [
    'user_id' => $user->id,
    'exp' => time() + 3600,
    'iat' => time(),
];
$token = JWT::encode($payload, env('JWT_SECRET'), 'HS256');

Verify: Generate a token from PHP, validate it in Django: python manage.py shell -c "from rest_framework_simplejwt.tokens import UntypedToken; UntypedToken('TOKEN_HERE')"

6. Migrate templates and frontend layer

Convert Blade/Twig templates to Django templates or Jinja2. If you are building an API-first architecture, this step may be replaced by serving a JavaScript frontend (React, Vue) that calls your new Python API. [src3, src4]

<!-- PHP Blade template -->
@extends('layouts.app')
@section('content')
    <h1>{{ $user->name }}</h1>
    @foreach($posts as $post)
        <article>{{ $post->title }}</article>
    @endforeach
@endsection

<!-- Django template equivalent -->
{% extends "layouts/base.html" %}
{% block content %}
    <h1>{{ user.name }}</h1>
    {% for post in posts %}
        <article>{{ post.title }}</article>
    {% endfor %}
{% endblock %}

Verify: Compare HTML output of both templates — diff <(curl -s php-app/users/1) <(curl -s django-app/users/1) should show minimal structural differences.

7. Decommission PHP routes and clean up

Once all routes are migrated and tested, remove the reverse proxy split, point all traffic to Python, and retire the PHP codebase. Run a parallel period of at least 2-4 weeks with monitoring before full cutover. [src6]

# Run Django test suite
python manage.py test --verbosity=2

# Check for any remaining PHP route references
grep -r "php_backend" /etc/nginx/conf.d/

# Monitor error rates after cutover
# Set up alerting on 5xx responses for the first 2 weeks

# Verify all traffic goes through Python
python manage.py shell -c "from django.contrib.auth.models import User; print(f'Total users: {User.objects.count()}')"

Verify: php artisan route:list should be empty or the PHP app should be fully stopped. All traffic goes through Python.

Code Examples

Django: REST API with Model and Serializer

Full script: django-rest-api-with-model-and-serializer.py (54 lines)

# Input:  HTTP GET /api/v2/products/?category=electronics&limit=10
# Output: JSON array of product objects with pagination
# core/models.py
from django.db import models
class Product(models.Model):
    name = models.CharField(max_length=255)
    slug = models.SlugField(unique=True)
    category = models.CharField(max_length=100, db_index=True)
    price = models.DecimalField(max_digits=10, decimal_places=2)
    is_active = models.BooleanField(default=True)
    class Meta:
        db_table = 'products'   # Match existing PHP table
        ordering = ['-created_at']
# ... (see full script)

Flask: Equivalent REST API

Full script: flask-equivalent-rest-api.py (50 lines)

# Input:  HTTP GET /api/v2/products/?category=electronics&limit=10
# Output: JSON array of product objects with pagination
# app.py
from flask import Flask, request, jsonify
from flask_sqlalchemy import SQLAlchemy
import os

app = Flask(__name__)
app.config['SQLALCHEMY_DATABASE_URI'] = os.environ.get('DATABASE_URL')
db = SQLAlchemy(app)
# ... (see full script)

FastAPI: High-Performance Async API

# Input:  HTTP GET /api/v2/products/?category=electronics&limit=10
# Output: JSON array of product objects with auto-generated OpenAPI docs
# main.py
from fastapi import FastAPI, Query
from sqlalchemy.ext.asyncio import create_async_engine, AsyncSession
from pydantic import BaseModel
from typing import Optional
import os

app = FastAPI(title="Migrated API", version="2.0")

class ProductResponse(BaseModel):
    id: int
    name: str
    slug: str
    category: str
    price: float
    is_active: bool

    class Config:
        from_attributes = True  # Replaces orm_mode in Pydantic v2

@app.get("/api/v2/products/", response_model=list[ProductResponse])
async def list_products(
    category: Optional[str] = None,
    limit: int = Query(default=20, le=100),
    page: int = Query(default=1, ge=1),
):
    """List products — auto-documented at /docs."""
    # SQLAlchemy async query against existing PHP database
    query = select(Product).where(Product.is_active == True)
    if category:
        query = query.where(Product.category == category)
    query = query.offset((page - 1) * limit).limit(limit)
    async with AsyncSession(engine) as session:
        result = await session.execute(query)
        return result.scalars().all()

Database Migration Script: Verify Data Integrity

Full script: database-migration-script-verify-data-integrity.py (33 lines)

# Input:  Existing PHP/MySQL database and new Django/PostgreSQL setup
# Output: Comparison report of record counts and data integrity
# scripts/verify_migration.py
"""
Cross-database verification script.
# ... (see full script)

Anti-Patterns

Wrong: Big-bang rewrite (rewriting everything at once)

# BAD — Attempting to rewrite the entire PHP app from scratch
# This is the "Second System Effect" — takes months/years, often fails

# "Let's just rewrite the whole thing in Django over the next 6 months"
# Meanwhile: PHP app gets zero maintenance, bugs pile up,
# business features are frozen, team morale drops

# Result: 60-70% of big-bang rewrites are abandoned or significantly
# delayed (industry experience) [src6]

Correct: Strangler fig pattern (incremental migration)

# GOOD — Migrate one module at a time, both systems run in parallel
# Start with the lowest-risk, highest-value endpoint

# Week 1-2: Migrate /api/v2/health and /api/v2/products (read-only)
# Week 3-4: Migrate /api/v2/users (read-only)
# Week 5-8: Migrate write operations for products
# Week 9-12: Migrate authentication
# ...continue until PHP serves zero routes [src6]

Wrong: Direct SQL queries instead of ORM

# BAD — Bringing PHP habits into Python
from django.db import connection

def get_active_users():
    with connection.cursor() as cursor:
        cursor.execute("SELECT * FROM users WHERE active = 1")
        return cursor.fetchall()  # Returns raw tuples, no model instances

Correct: Use the Django ORM properly

# GOOD — Use Django ORM querysets for type safety, SQL injection prevention,
# and lazy evaluation [src1]
from core.models import User

def get_active_users():
    return User.objects.filter(active=True).select_related('profile')
    # Returns model instances, supports chaining, auto-escapes values

Wrong: Copying PHP's $GLOBALS / global state pattern

# BAD — Using global variables like PHP superglobals
_current_user = None  # Module-level mutable state

def login(user_id):
    global _current_user
    _current_user = User.objects.get(id=user_id)

def get_dashboard():
    # Relies on global state — breaks in multi-threaded/async contexts
    return render(f"Welcome {_current_user.name}")

Correct: Use request context and dependency injection

# GOOD — Django/Flask handle request state through the request object [src2, src4]
# Django
from django.contrib.auth.decorators import login_required

@login_required
def get_dashboard(request):
    # request.user is thread-safe, scoped to this request
    return render(request, 'dashboard.html', {'user': request.user})

# Flask
from flask_login import login_required, current_user

@app.route('/dashboard')
@login_required
def get_dashboard():
    return render_template('dashboard.html', user=current_user)

# FastAPI
from fastapi import Depends
from .auth import get_current_user

@app.get('/dashboard')
async def get_dashboard(user: User = Depends(get_current_user)):
    return {"message": f"Welcome {user.name}"}

Wrong: Mixing PHP naming conventions in Python code

# BAD — Using camelCase and PHP naming patterns in Python
class UserController:  # Python uses "View" not "Controller" in Django
    def getUserById(self, userId):  # camelCase is not Pythonic
        $user = User.objects.get(id=userId)  # $ prefix doesn't exist in Python
        return $user

Correct: Follow Python/Django conventions (PEP 8)

# GOOD — snake_case, Django naming conventions [src3, src5]
class UserDetailView(generics.RetrieveAPIView):  # "View" in Django
    def get_queryset(self):  # snake_case methods
        user_id = self.kwargs['pk']  # No $ prefix
        return User.objects.filter(id=user_id)

Wrong: Ignoring Python's package structure

# BAD — Flat file structure like a PHP project
# myproject/
#   models.py          (all models in one file)
#   views.py           (all views in one file)
#   urls.py            (500+ routes in one file)

Correct: Use Django apps for modular organization

# GOOD — Django app-per-domain pattern [src1, src4]
# myproject/
#   users/
#     models.py, views.py, urls.py, serializers.py, tests.py
#   products/
#     models.py, views.py, urls.py, serializers.py, tests.py
#   orders/
#     models.py, views.py, urls.py, serializers.py, tests.py

# myproject/urls.py
from django.urls import path, include

urlpatterns = [
    path('api/v2/users/', include('users.urls')),
    path('api/v2/products/', include('products.urls')),
    path('api/v2/orders/', include('orders.urls')),
]

Wrong: Not pinning dependencies during migration

# BAD — Unpinned requirements allow breaking changes mid-migration
# requirements.txt
django
djangorestframework
psycopg2

Correct: Pin all dependency versions

# GOOD — Pinned requirements ensure reproducible builds [src5]
# requirements.txt
django==5.2.1
djangorestframework==3.15.2
psycopg[binary]==3.2.4
python-dotenv==1.0.1

# Or better: use pyproject.toml with uv/poetry for lockfile support

Common Pitfalls

• PHP arrays are not Python lists: PHP arrays serve as both indexed arrays and associative arrays (dicts). In Python, use list for ordered sequences and dict for key-value pairs. Mixing them up causes TypeError exceptions. Fix: audit every $array usage and decide if it maps to list or dict. [src5]
• Forgetting managed = False on introspected models: When using inspectdb to generate models from an existing database, Django defaults to managed = True, which means makemigrations will try to recreate or alter existing tables. Fix: set managed = False in the model's Meta class until you are ready to let Django own the schema. [src1]
• Password hash incompatibility: Laravel uses bcrypt with a $2y$ prefix while Django uses PBKDF2 by default. If you point Django at an existing users table, authentication will fail. Fix: add 'django.contrib.auth.hashers.BCryptSHA256PasswordHasher' to PASSWORD_HASHERS in settings.py and install bcrypt. [src4]
• Session format mismatch during transition: PHP serializes sessions differently from Django. Users will be logged out when traffic switches between backends. Fix: use token-based auth (JWT) shared between both backends during the transition, or implement a shared session store in Redis. [src4, src6]
• NULL vs None semantics: PHP's null, "", 0, false, and [] are all falsy. Python's None is distinct from "", 0, False, and []. Porting if (!$value) to if not value may produce different behavior. Fix: be explicit — use if value is None when checking for null specifically. [src5]
• Missing CSRF protection: Laravel includes CSRF tokens automatically via @csrf in Blade. Django also enforces CSRF but requires {% csrf_token %} in templates and proper middleware configuration. Flask requires flask-wtf for CSRF. Forgetting this causes 403 errors on all POST requests. Fix: ensure django.middleware.csrf.CsrfViewMiddleware is in MIDDLEWARE and templates include {% csrf_token %}. [src1, src2]
• Timezone handling differences: PHP uses date_default_timezone_set() globally. Django has USE_TZ = True in settings and stores everything in UTC by default, converting on display. Migrating datetime columns without timezone awareness leads to shifted timestamps. Fix: set USE_TZ = True, ensure database columns are timezone-aware, and audit all date comparisons. [src1]
• Deployment model mismatch: PHP runs on cheap shared hosting with Apache/mod_php. Python requires WSGI/ASGI servers (Gunicorn, Uvicorn), process managers, and typically container-based deployment. Fix: budget for infrastructure changes and consider containerization (Docker) early in the migration planning. [src8]

Diagnostic Commands

# Check Django project configuration for production readiness
python manage.py check --deploy

# Verify database connectivity
python manage.py dbshell

# Introspect existing PHP database schema into Django models
python manage.py inspectdb > models_generated.py

# Compare model definitions vs actual database
python manage.py showmigrations

# Run Django development server
python manage.py runserver 0.0.0.0:8000

# List all registered URL routes in Django (requires django-extensions)
python manage.py show_urls

# Check Flask routes
flask routes

# Verify Python/pip environment
python --version && pip list --format=columns

# Test database connection from Python
python -c "import psycopg; conn = psycopg.connect('dbname=mydb user=myuser'); print('Connected'); conn.close()"

# Compare record counts between PHP and Python databases
php artisan tinker --execute="echo App\Models\User::count();"
python manage.py shell -c "from core.models import User; print(User.objects.count())"

# Verify bcrypt password compatibility
python -c "import bcrypt; print(bcrypt.checkpw(b'testpassword', b'\$2y\$10\$HASH_FROM_PHP'))"

# Check Django 5.2 compatibility with current database
python manage.py migrate --check

Version History & Compatibility

When to Use / When Not to Use

Important Caveats

• Django and Laravel are conceptually similar (both batteries-included MVC frameworks), but the terminology is inverted: Laravel's "Controller" is Django's "View", and Laravel's "View" (Blade) is Django's "Template". This causes significant confusion during migration. [src3]
• Automated code translation tools (like Ispirer or AI-based converters) can handle syntax conversion but cannot replicate framework-specific patterns, middleware chains, or business logic. Budget 30-40% of migration time for manual review and refactoring.
• PHP's loose typing means many implicit type coercions happen silently. Python is strongly typed at runtime — migrated code will throw TypeError exceptions where PHP silently coerced. Add type hints and run mypy early in the migration. [src5]
• Database migration is often the hardest part. If your PHP app uses MySQL-specific features (e.g., ENUM columns, spatial queries, full-text indexes), verify Django/PostgreSQL equivalents exist before committing to the migration. [src1]
• Hosting costs and deployment patterns change significantly. PHP runs on cheap shared hosting with Apache/mod_php. Python requires WSGI/ASGI servers (Gunicorn, Uvicorn), process managers, and typically a container-based deployment. Budget for infrastructure changes.
• FastAPI is gaining significant traction (20% adoption in 2025 surveys) and is the strongest option for async API-only migrations. However, it lacks Django's built-in admin, ORM, and template system — evaluate your needs carefully. [src8]
• Django 5.2 LTS composite primary key support cannot be retrofitted to existing models with single PKs — plan table structures before migration if you need composite keys. [src7]
• Django 6.0 (Dec 2025) is the newest line but is not an LTS. It drops Python 3.10/3.11, removes cx_Oracle, requires custom ORM expression as_sql() methods to return params as tuples (not lists), and makes DEFAULT_AUTO_FIELD default to BigAutoField. For a migration where you want a long, stable target, pick Django 5.2 LTS; choose 6.0 only if you want its built-in CSP, template partials, or the new background-tasks framework and control the Python 3.12+ runtime. [src9]