Analyze Yii2 Project Workflow

Purpose

Comprehensive workflow for analyzing legacy Yii2 projects to extract business logic, understand architecture, and plan modernization.

When to Use

✅ User provides Yii2 codebase for analysis
✅ Planning Yii2 → NestJS/Modern framework migration
✅ Need to understand undocumented Yii2 project
✅ Extracting business requirements from Yii2 code
✅ Technical debt assessment of Yii2 application

Prerequisites

Infrastructure Check

codecompass health

Verify:

✅ Weaviate running (localhost:8081)
✅ Ollama running (localhost:11434)
✅ PostgreSQL running (localhost:5433)

Project Requirements

Yii2 project directory accessible
vendor/ directory present (run composer install if missing)
Read permissions on all files

Step-by-Step Workflow

Phase 1: Initial Scan (Quick Overview)

Step 1.1: Run Yii2 Analyzer

codecompass analyze:yii2 <path-to-yii2-project>

What this does:

Scans directory structure
Detects Yii2 version
Identifies conventions (controllers, models, views)
Extracts routing patterns
Maps database migrations

Expected output:

Framework version
Directory structure validation
Controller/Model counts
Migration history

Step 1.2: Validate Results Check for:

❌ Missing vendor/ → Run composer install
❌ Old Yii2 version (<2.0.40) → Check compatibility notes in docs/YII2_QUICK_REFERENCE.md
❌ Non-standard structure → May need manual configuration

Phase 2: Business Capability Extraction

Step 2.1: Extract Controllers → Capabilities

# Analyzer automatically extracts business capabilities from controllers

What this maps:

Controller → Business Capability
├── UserController → User Management
├── OrderController → Order Processing
├── PaymentController → Payment Handling
└── ReportController → Reporting & Analytics

Step 2.2: Extract Models → Domain Entities Identifies:

ActiveRecord models → Database entities
Validation rules → Business rules
Relationships → Domain model connections

Step 2.3: Extract Migrations → Data Model Evolution Traces:

Schema changes over time
Business logic embedded in migrations
Data transformation patterns

Phase 3: Dependency Analysis

Step 3.1: Analyze Class Dependencies Uses: AstAnalyzerService for PHP parsing

Maps:

Tight coupling (classes depending on many others)
Circular dependencies (refactoring red flags)
Inheritance hierarchies
Service dependencies

Step 3.2: Identify Core vs Supporting Logic Categorizes:

Core Domain: Business-critical logic (preserve carefully)
Supporting: Infrastructure, utilities (can be replaced)
Generic: Framework boilerplate (discard in migration)

Phase 4: Requirements Extraction

Step 4.1: Run Requirements Extractor

codecompass requirements:extract --project-id <yii2-project-id>

Extracts:

Validation rules from models → Business constraints
Controller actions → Use cases
RBAC rules (if present) → Authorization requirements
Database constraints → Data integrity rules

Step 4.2: Generate Documentation Outputs:

Business capability map (Markdown)
Domain model diagram (Mermaid)
Use case catalog
Data dictionary

Phase 5: Semantic Indexing (Optional but Recommended)

Step 5.1: Index Codebase

codecompass batch:index <path-to-yii2-project>

Why:

Enables semantic search for "business logic for payment processing"
Cross-file pattern discovery
Similar code detection
Natural language queries

Step 5.2: Verify Indexing

curl http://localhost:8081/v1/schema
# Check for CodeContext or AtlasCode collection

Step 5.3: Test Semantic Search

codecompass search:semantic "validation rules for customer registration"

Should return: User model validators, controller logic, related code

Phase 6: Migration Planning

Step 6.1: Identify Migration Complexity Assess:

Low complexity: CRUD operations, standard patterns
Medium complexity: Custom workflows, business rules
High complexity: Legacy integrations, undocumented logic

Step 6.2: Prioritize by Business Value Map:

Business Capability → Migration Priority
├── Core Revenue Generating → HIGH (do first, carefully)
├── Customer-Facing → MEDIUM (visible impact)
└── Internal Tools → LOW (can defer)

Step 6.3: Generate Migration Roadmap Structure:

Infrastructure setup (NestJS, TypeORM, etc.)
Domain models (migrate ActiveRecords → TypeORM entities)
Core business logic (preserve carefully)
API layer (REST/GraphQL endpoints)
Background jobs (if using Yii2 queue)
Testing & validation

Common Patterns to Look For

Yii2 Controller Patterns

// CRUD pattern
public function actionIndex() // → LIST endpoint
public function actionView($id) // → GET/:id endpoint
public function actionCreate() // → POST endpoint
public function actionUpdate($id) // → PUT/:id endpoint
public function actionDelete($id) // → DELETE/:id endpoint

Maps to NestJS:

@Controller('users')
export class UsersController {
  @Get() findAll()
  @Get(':id') findOne()
  @Post() create()
  @Put(':id') update()
  @Delete(':id') remove()
}

Yii2 Model Patterns

// Validation rules
public function rules() {
  return [
    [['email'], 'required'],
    [['email'], 'email'],
  ];
}

Maps to NestJS DTO:

export class CreateUserDto {
  @IsNotEmpty()
  @IsEmail()
  email: string;
}

Yii2 Database Patterns

// ActiveRecord query
$users = User::find()
  ->where(['status' => User::STATUS_ACTIVE])
  ->orderBy('created_at DESC')
  ->all();

Maps to TypeORM:

const users = await this.userRepository.find({
  where: { status: UserStatus.ACTIVE },
  order: { createdAt: 'DESC' },
});

Output Artifacts

1. Architecture Diagram (Mermaid)

graph TD
  Controller[Controllers] --> Service[Business Logic]
  Service --> Model[ActiveRecord Models]
  Model --> DB[(Database)]
  Controller --> View[Views]

2. Business Capability Map

## Core Capabilities
- User Management (UserController, User model)
- Order Processing (OrderController, Order/OrderItem models)
- Payment Handling (PaymentController, Payment model)

## Supporting Capabilities
- Reporting (ReportController)
- Notifications (EmailService)

3. Migration Checklist

Common Issues & Solutions

Issue 1: Cannot find controllers

Symptom: Analyzer reports 0 controllers Cause: Non-standard directory structure Solution: Check @app alias configuration in Yii2, adjust paths

Issue 2: Missing database schema

Symptom: Cannot extract models properly Cause: Database not accessible or migrations not run Solution: Ensure database connection configured, run pending migrations

Issue 3: Circular dependencies detected

Symptom: Dependency graph shows circular references Meaning: Code smell - tight coupling between modules Action: Plan refactoring to break cycles during migration

Issue 4: Undocumented business rules

Symptom: Complex logic in controllers with no comments Action:

Use semantic search to find similar patterns
Interview original developers if available
Write tests to capture behavior before migration
Document assumptions in requirements docs

Best Practices

✅ Do

Run full analysis before planning migration
Extract ALL business rules (even implicit ones)
Document assumptions and unknowns
Test semantic search to validate indexing
Create comprehensive capability map
Prioritize by business value, not technical ease

❌ Don't

Skip dependency analysis (will bite you later)
Assume standard Yii2 patterns everywhere
Ignore validation rules (they're business requirements!)
Start coding before understanding full architecture
Migrate everything at once (strangler fig pattern instead)

Related Skills

extract-requirements.md - For detailed requirements extraction
semantic-search.md - For code exploration
software-architect.md - For architecture perspective

Related Modules

From .ai/capabilities.json:

yii2-analyzer - Main analysis module
ast-analyzer - PHP parsing
database-analyzer - Schema extraction
requirements - Business rules extraction
business-analyzer - Capability mapping

Remember: The goal is not just to understand the code, but to preserve the business knowledge embedded in it.

analyze-yii2-project