Accelerating PHP to Express.js Migrations with AI: A Repeatable Pattern

Migrating legacy systems, such as moving from a PHP backend to Node.js/Express.js, presents significant challenges. These projects often involve understanding complex existing logic, rewriting features, and maintaining service continuity. This post outlines a repeatable, AI-assisted pattern to streamline this process, based on experiences from a recent migration project.

We will demonstrate this pattern using a common and critical feature: User Authentication (Login, Registration, Profiles).

Core Migration Strategy:

The approach focuses on abstracting requirements away from the legacy implementation, designing a modern API, leveraging AI for initial code generation, and then rigorously testing and integrating.

Legacy PHP -> Define Requirements -> Design API -> Generate Backend (AI-Assisted) -> Test API -> Generate Frontend (AI-Assisted) -> Integrate -> Complete

Prerequisites:

Before starting the migration for a specific feature, ensure you have:

  1. Clear Functional Requirements: Document what the feature must accomplish, independent of the old PHP implementation.
  2. Defined Database Schema: Have the target database schema (e.g., PostgreSQL, MySQL) designed and ready.
  3. UI Designs: Have UI mockups (e.g., Figma) for the corresponding frontend components.

Feature Migration Example: User Authentication

Let's apply the pattern to user registration, login, and profile management.

Step 1: Define Functional Requirements

Goal: Document the essential business logic and user interactions for the feature.

Action:

  1. List core user actions (e.g., Register, Login, View Profile, Update Profile).
  2. For each action, specify: Required inputs, validation rules, processing steps, expected success outputs, and potential error conditions.
  • Example (Login):
    • Input: Email, Password.
    • Processing: Validate input formats. Verify user existence in the database. Compare provided password hash with stored hash. Generate a JWT upon successful verification.
    • Success Output: 200 OK status with a JWT Token.
    • Error Outputs: 400 Bad Request (invalid input format), 401 Unauthorized (invalid credentials).

AI Assistance (Conceptual - for understanding legacy code):
If needed, use an AI chat assistant to help decipher complex legacy code:

Act as a senior software engineer. Analyze the provided PHP code [or description] for user login. Extract the core functional requirements: inputs, validation steps, success output (data returned), and failure scenarios/error conditions. Focus on the business logic, not the specific PHP implementation.

Step 2: Design the API Contract

Goal: Define how the new Express.js service will communicate with clients (e.g., the frontend).

Action: Specify RESTful endpoints including HTTP methods, URL paths, request body structures (JSON), and expected response formats (JSON, status codes).

  • Example API Endpoints:
    • POST /api/auth/register (Body: { email, password }) -> 201 Created { userId } or error.
    • POST /api/auth/login (Body: { email, password }) -> 200 OK { token } or error.
    • GET /api/users/me (Requires Authorization: Bearer ) -> 200 OK { userId, email, name, ... } or error.
    • PUT /api/users/me (Requires Authorization: Bearer , Body: { name, ... }) -> 200 OK { updatedProfile } or error.

(Conceptual Flow): [Client Application] <- (HTTP Request/Response) -> [Express.js API Service]

Step 3: Generate Backend Logic with AI Assistance

Goal: Use AI code generation tools to create the initial Express.js routes, controllers, and service logic based on the API design.

Action: Provide a detailed prompt to your chosen AI code generation tool (e.g., Codeium, Windsurf).

AI Prompt Example (Login Endpoint):

Act as a full-stack Node.js developer. Generate an Express.js API endpoint implementation for user login based on the following specifications:

**1. API Contract:**
   - Method: POST
   - Path: /api/auth/login
   - Request Body: JSON object with 'email' (string, valid email format) and 'password' (string, min 8 chars).
   - Success Response (200 OK): JSON object with 'token' (string, JWT).
   - Error Response (400 Bad Request): JSON { message: "Invalid input format" }
   - Error Response (401 Unauthorized): JSON { message: "Invalid email or password" }

**2. Technology Stack:**
   - Framework: Express.js 4.x
   - Language: JavaScript (ES6+) [or specify TypeScript]
   - Database: PostgreSQL
   - ORM: Prisma (Ensure Prisma Client is imported and used)
   - Authentication: JWT (using 'jsonwebtoken' library)
   - Password Hashing: bcrypt (using 'bcryptjs' library)

**3. Logic:**
   - Validate incoming request body for presence and format of email/password. Return 400 if invalid.
   - Query the PostgreSQL database via Prisma to find the user by 'email'.
   - If user not found, return 401.
   - If user found, compare the provided 'password' with the stored hashed password using bcrypt.compare().
   - If passwords don't match, return 401.
   - If passwords match, generate a JWT containing the user ID (e.g., { userId: user.id }). Use process.env.JWT_SECRET for the secret key and set an appropriate expiration (e.g., '1h').
   - Return 200 OK with the JWT: { token: generatedToken }.
   - Include basic try/catch blocks for database or JWT operations.

**4. Code Structure:**
   - Use Express Router.
   - Define a controller function (e.g., `loginUser`).
   - Include necessary imports (express, bcryptjs, jsonwebtoken, PrismaClient).

**5. Output:** Provide the complete code snippet for the route definition and associated controller function(s), with comments explaining key logic.

Important: AI-generated code is a starting point. Thoroughly review, debug, and refine the code. Implement comprehensive error handling, add security measures (e.g., input sanitization, rate limiting), and ensure it fully meets requirements and integrates correctly with your database schema.

Step 4: Test the API Thoroughly

Goal: Verify the backend service functions correctly in isolation before integrating it with the frontend.

Action: Use an API testing tool like Postman to test every endpoint defined in Step 2.

  • Test Scenarios:
    • Valid Inputs: Verify expected success responses and data.
    • Input Validation: Test invalid formats, missing fields, etc., ensure correct error responses (e.g., 400).
    • Authentication/Authorization Logic: Test incorrect credentials, missing/invalid tokens for protected routes (expect 401/403), correct data return with valid tokens.
    • Edge Cases: Test any known boundary conditions.
  • Iteration: If tests fail, debug the Express.js code (Step 3) and re-test until all endpoints behave as expected.

Step 5: Generate Frontend Components with AI Assistance

Goal: Create the basic UI structure based on your Figma designs using AI UI generation tools.

Action: Provide designs and requirements to a UI generation tool (e.g., v0.dev).

AI Prompt Example (Login Form - v0.dev Style):

Create a user login form component using React and Tailwind CSS, based on the provided Figma design [tool typically takes image/link input].

**Required Elements:**
- Form title: "Login"
- Labeled input field for Email (type="email").
- Labeled input field for Password (type="password").
- Submit button labeled "Log In".
- An area below the form to display potential error messages (initially hidden).

**Styling:**
- Apply Tailwind CSS utility classes.
- Match the layout, spacing, and typography from the Figma design.
- Ensure responsiveness.

**Basic Interaction Structure:**
- The component should manage state for email and password inputs.
- The submit button should trigger a submission handler function (to be implemented).
- The error display area should be capable of rendering text.

Refinement: Review the generated UI code. Use the tool's features or manually edit the code to match the design precisely and ensure accessibility.

Step 6: Integrate Frontend and Backend

Goal: Connect the generated frontend UI components to the tested Express.js API endpoints.

Action: Implement the client-side logic within your frontend framework (React, Vue, etc.).

  • API Calls: Use fetch or axios to interact with your API:
    • Send POST /api/auth/login request on form submission.
    • Send GET /api/users/me request (with Authorization header) when needed.
  • State Management: Handle UI updates based on API responses (loading states, error messages). Store authentication tokens securely (e.g., in state management or secure storage). Manage conditional rendering based on authentication status.
  • End-to-End Testing: Test the complete user flow through the UI to ensure seamless interaction between frontend and backend.

(Conceptual Flow): [Frontend Component (React)] <- (State Updates / API Calls) -> [Express.js API Service]

Applying the Pattern to Your Code

To migrate a specific feature from your PHP application:

  1. Analyze Your PHP Feature: Understand its purpose, data dependencies, database interactions, and core business logic.
  2. Abstract Requirements: Document the feature's essential inputs, outputs, and rules (Step 1), independent of the PHP implementation details. This is critical.
  3. Follow the Pattern: Apply Steps 2 through 6 to design, build, test, and integrate the new Express.js service and corresponding frontend components for that specific feature.
  4. Avoid Direct Translation: Do not attempt a line-by-line translation from PHP to Node.js. Instead, re-architect the feature using modern Node.js practices based on the abstracted requirements.

Conclusion:

While legacy migrations are complex, a structured approach combined with AI assistance can significantly accelerate the process. By focusing on clear requirements and API design before implementation, and using AI tools for initial code generation (followed by essential human review and refinement), development teams can migrate features from PHP to Express.js more efficiently and effectively. This pattern breaks the migration down into manageable, repeatable steps.