Code Generation

Purpose and Scope

This document provides an overview of the Light framework's code generation capabilities. Code generation in Light automatically produces PHP model classes, GraphQL controllers, input validation types, and TypeScript definitions from a single source of truth: the db.json database schema file. This approach accelerates development by eliminating boilerplate code and ensuring consistency between the database schema, backend models, and frontend types.

For detailed command documentation, see the following child pages:

• Model generation: 9.3.1
• Controller generation: 9.3.2
• Input type generation: 9.3.3
• TypeScript generation: 9.3.4

For database installation and schema management, see 9.2.

---

Schema-Driven Development

The Light framework implements a schema-first development model where all database table definitions are declared in db.json1-676 This JSON file serves as the single source of truth for the application's data structure and drives multiple code generation processes.

db.json Structure

The db.json1-676 file contains an array of table definitions. Each table object specifies:

Property	Description	Example
name	Table name (PascalCase)	"User", "EventLog"
columns	Array of column definitions	See column structure below
primary_key	Array of primary key column names	["user_id"]
unique_keys	Array of unique constraint definitions	[{"name": "username", "columns": ["username"]}]
keys	Array of index definitions	[{"name": "user_id", "columns": ["user_id"]}]
foreign_keys	Array of foreign key constraints	See foreign key structure below

Column Definition Structure:

Foreign Key Structure:

The schema defines 12 core tables including User db.json3-139 Role db.json141-178 UserRole db.json180-231 Config db.json233-263 UserLog db.json265-336 EventLog db.json338-418 MailLog db.json420-475 Permission db.json477-499 SystemValue db.json501-549 Translate db.json551-605 and CustomField db.json607-675

Sources: db.json1-676

---

CLI Tool Architecture

The Light CLI tool is implemented as a Symfony Console application located at bin/light1-24 This executable script registers all code generation commands and provides a unified interface for development operations.

CLI Tool Initialization

CLI Initialization Flow:

1. Autoloading: bin/light13 loads Composer's autoloader
2. Application Creation: bin/light15 instantiates a Symfony Console Application with name "Light CLI" and version "1.0.0"
3. Command Registration: bin/light17-21 adds five commands to the application
4. Execution: bin/light23 runs the application, which parses command-line arguments and dispatches to the appropriate command

Sources: bin/light1-24

---

Code Generation Workflow

The following diagram illustrates how db.json flows through the CLI tool to generate various code artifacts:

Typical Development Workflow:

1. Define Schema: Edit db.json1-676 to add/modify table definitions
2. Install Database: Run bin/light db:install to create/update database tables
3. Generate Models: Run bin/light make:model <TableName> to create PHP model classes
4. Generate Controllers: Run bin/light make:controller <TableName> to create GraphQL controllers with CRUD operations
5. Generate Inputs: Run bin/light make:input <TableName> to create input validation types
6. Generate TypeScript: Run bin/light make:ts to create TypeScript definitions for frontend use

Sources: bin/light17-21 db.json1-676

---

Available Generation Commands

The CLI tool provides five commands for code generation and database management. Each command reads from db.json1-676 and generates specific artifacts.

Command Overview Table

Command	Class	Purpose	Output
db:install	Light\Command\DbInstallCommand	Install/update database schema from db.json	MySQL tables with columns, keys, and constraints
make:model	Light\Command\MakeModelCommand	Generate PHP model class for a table	src/Model/<TableName>.php extending Light\Model
make:controller	Light\Command\MakeControllerCommand	Generate GraphQL controller with CRUD operations	src/Controller/<TableName>Controller.php with @Query and @Mutation annotations
make:input	Light\Command\MakeInputCommand	Generate input validation type for GraphQL mutations	src/Input/<TableName>Input.php with validation rules
make:ts	Light\Command\MakeTsCommand	Generate TypeScript type definitions from models	TypeScript .d.ts files for frontend type safety

Command Registration

The CLI tool registers all commands during initialization bin/light17-21:

Each command class implements Symfony Console's Command interface and provides command-specific logic for parsing db.json and generating code.

Sources: bin/light6-11 bin/light17-21

---

Generated Code Architecture

The following diagram shows how generated code artifacts integrate with the Light framework's runtime components:

Integration Points:

1. Models: Generated model classes extend Light\Model, inheriting automatic audit trails, event logging, and database abstraction capabilities
2. Controllers: Generated controllers use GraphQLite annotations (@Type, @Query, @Mutation) to expose GraphQL API endpoints
3. Input Types: Generated input classes provide validation rules and type safety for GraphQL mutation arguments
4. TypeScript: Generated TypeScript definitions provide compile-time type checking for frontend applications consuming the GraphQL API
5. Database: All generated code ultimately interacts with MySQL tables created by the db:install command

Sources: db.json1-676

---

Benefits of Schema-Driven Code Generation

Benefit	Description
Single Source of Truth	db.json defines the schema once; all code artifacts are generated from it, eliminating inconsistencies
Reduced Boilerplate	Eliminates manual writing of repetitive model properties, GraphQL types, and TypeScript interfaces
Type Safety	Generated TypeScript definitions ensure frontend code matches backend models at compile time
Rapid Prototyping	New tables can be added to db.json and have full CRUD operations generated in seconds
Consistency	All generated code follows the same patterns and conventions, making the codebase easier to maintain
Audit Trail Integration	Generated models automatically inherit audit capabilities from Light\Model without manual implementation
GraphQL Schema Sync	Controllers and inputs are always aligned with the database schema, preventing runtime errors

---

Usage Example

To add a new Product table to the system:

1. Add table definition to db.json:

2. Run generation commands:

3. Result: The system now has:

   • A Product table in MySQL
   • A Product.php model class in src/Model/
   • A ProductController.php with CRUD operations in src/Controller/
   • A ProductInput.php validation type in src/Input/
   • A Product.d.ts TypeScript interface

For detailed command usage and options, see the child pages 9.3.1, 9.3.2, 9.3.3, and 9.3.4.

Sources: bin/light17-21 db.json1-676