Language Migration / ARTICLE

Building a Repeatable PHP-to-Java Migration Engine with Kiro

AWS outlines a PHP-to-Java migration engine built on Kiro skill files, a dependency-free discovery scanner, and a parity-first eight-phase pipeline that runs interactively or at portfolio scale.

A dependency-free scanner that reads tokens, not code

Moving a mature PHP application to Java brings stronger type safety, broader library support, and more predictable scaling. But business rules in Laravel, Symfony, or Doctrine code often live inside Eloquent traits or XML mapping files, so a structurally similar Java port can compile cleanly and still behave differently. AWS’s published engine turns migration into a measurable, repeatable process using Kiro, an AI IDE that pairs an agent with a codebase. The core is a shared methodology, a mechanical discovery scanner, and an eight-phase workflow. The original PHP application is treated as the specification; the Java port is not declared correct until a parity harness verifies it.

The scanner, discover-models.php, is a single-file, dependency-free PHP command-line tool. It does not execute target code; it reads source text as tokens, so it runs even if dependencies are not installed. Each scan applies three strategies: Eloquent model discovery by walking the class inheritance chain to Illuminate\Database\Eloquent\Model, Doctrine attribute detection via #[ORM\Entity], and ORM XML mapping from external *.orm.xml files. The output is a JSON manifest. A models[] array records every field, cast, relationship, and visibility rule. A flags[] array appears on each entry. The scanner flags ambiguity rather than guessing: a $fillable list built from a runtime expression becomes a plain-English flag in the human review queue.

The parity harness comes before Java code

The first four phases concentrate human judgment. Phase 0 runs the scanner and assembles the inventory. Phase 1 builds the parity harness before any Java is written, replaying request/response pairs against the PHP original and the Java port. The harness must pass on working PHP and fail when breakage is deliberately injected; a harness that misses injected breakage is not trusted. Phase 2 seeds RULEBOOK.md and GAP_INVENTORY.md. Phase 3 stress-tests the rulebook against representative files before committing it across the application. Phases 4 through 8 are mostly self-driving loops. Phase 4 scaffolds a compiling Spring Boot project. Phase 5 translates the data model into JPA entities from the manifest. Phase 6 translates the I/O layer: routes become controllers, middleware becomes filters, validation becomes annotated data transfer objects. Phase 7 converts business logic in batches. Phase 8 proves parity against the harness and cuts over. Two principles govern the loop. The PHP code is the specification: the port is done when the referee agrees, or each mismatch is logged as an approved change. The second principle is to fix the loop, not the code—amend the rulebook and regenerate rather than hand-patching.

One skill layer, two execution modes

The methodology lives in versioned Markdown skill files: php-to-java-migration encodes the eight-phase workflow, and php-model-discovery encodes the scanner workflow. Kiro runs the skills interactively in the editor with explicit approval gates. The developer reviews the discovery manifest, approves the rulebook, and signs off on each phase before the next begins. AWS Transform, an agentic AI service for large-scale migration, now integrates natively with Kiro. The same skill files can be handed to AWS Transform, whose agents execute the identical methodology autonomously at portfolio scale, with review at the checkpoints the skill defines. Both paths read the same files, so every rulebook fix made in Kiro improves the next AWS Transform run, and vice versa. The methodology auto-detects Laravel, Symfony, CodeIgniter, and plain PHP; adding a framework only requires a detection row and a references/ to Spring guide.

A candid Laravel-to-Spring Boot slice

The laravel-eloquent-sample project is a bounded, read-only slice. Only the Book, Chapter, Page, and User models are migrated to Spring Boot 3.4.1 on Java 21 with Maven and an in-memory H2 database. The mappings are mechanical and traceable: a PHP namespace becomes a Java package, an Eloquent model becomes a JPA @Entity, hasMany becomes @OneToMany, belongsTo becomes @ManyToOne, and Eloquent query scopes become Spring Data repository methods. Serialization follows the manifest: Page’s $hidden list includes html, markdown, and text, so those fields carry @JsonIgnore; Book’s description deliberately does not. The spec states that only 4 of 37 models were ported and, crucially, that the parity harness was never built for this slice—calling it “the single biggest gap.” Documenting the shortfall is part of the design.

To run the engine, clone the sample repository and open its root as a Kiro workspace. The .kiro/ directory contains the shared skills and steering files. Fetch the PHP source into the project’s source-php/ folder, with README-pinned commits to reproduce the baseline. Ask Kiro to migrate the application; the skill activates automatically, runs the scanner first, generates a fresh spec under .kiro/specs/, and walks through approval gates. No AWS resources are provisioned by the engine itself.

END
Feedback