Controller Generation

Purpose and Scope

This document describes the make:controller command, which generates GraphQL controller boilerplate code from the database schema defined in db.json. The command creates controller classes with standard CRUD operations (Query, Create, Update, Delete) decorated with GraphQLite annotations and RBAC permission checks.

For information about model generation, see Model Generation. For input validation type generation, see Input Type Generation. For TypeScript type generation, see TypeScript Generation.

Command Overview

The make:controller command is registered in the Light CLI tool and generates GraphQL controller classes with pre-configured query and mutation methods based on database table definitions.

Command Registration:

The CLI tool at bin/light1-24 registers the MakeControllerCommand as one of five code generation commands:

bin/light
├── DbInstallCommand
├── MakeControllerCommand ← Controller generation
├── MakeModelCommand
├── MakeInputCommand
└── MakeTsCommand

Sources: bin/light1-24

Generated Controller Architecture

The controller generator produces classes that integrate with the GraphQL API layer, RBAC security system, and data persistence layer.

System Integration Flow

Sources: bin/light1-24 db.json1-676

Command Usage

Basic Command Syntax

The command reads the corresponding table definition from db.json and generates a controller class with the following naming convention:

• Input: Table name from db.json (e.g., User, Role, Config)
• Output: Controller class file (e.g., UserController.php, RoleController.php, ConfigController.php)

Example: Generating User Controller

Given the User table definition in db.json1-139:

This generates a UserController class based on the User table's structure, which includes columns like user_id, username, password, email, etc.

Sources: bin/light1-24 db.json1-139

Generated Controller Structure

Controllers generated by make:controller follow a consistent pattern aligned with the GraphQL API architecture described in the system overview.

Standard Methods Generated

Sources: db.json1-676

Controller Method Patterns

Each generated controller includes these standard methods:

Method	GraphQL Type	Permission Pattern	Input Parameters	Return Type
get{TableName}()	@Query	model.{table}:read	Primary key from db.json	Model instance
create{TableName}()	@Mutation	model.{table}:write	{TableName}Input object	Created model instance
update{TableName}()	@Mutation	model.{table}:write	Primary key + {TableName}Input	Updated model instance
delete{TableName}()	@Mutation	model.{table}:delete	Primary key from db.json	Boolean success flag

Sources: db.json1-676

Permission Integration

Generated controllers automatically integrate with the RBAC system through @Right annotations, following the permission discovery mechanism described in the system architecture.

Permission Naming Convention

Permission Format:

• Pattern: model.{lowercase_table_name}:{operation}
• Operations: read, write, delete
• Example for User table: model.user:read, model.user:write, model.user:delete

Sources: db.json1-676

Integration with Schema Definition

The controller generator analyzes the table definition in db.json to determine the appropriate data types, required fields, and primary key structure.

Schema-to-Controller Mapping

Example Mappings:

For the User table db.json1-139:

• Primary Key: user_id (int, unsigned) → getUserId(int $user_id) parameter
• Nullable Columns: phone, addr1, expiry_date → Optional fields in Input type
• Required Columns: username, join_date, status → Required fields in Input type
• Foreign Keys: Referenced by UserRole, UserLog → Navigation properties available

Sources: db.json1-139

GraphQL Schema Registration

Generated controllers are automatically discovered by the GraphQLite schema factory through annotation scanning, as described in the GraphQL API architecture.

Controller-to-Schema Flow

Discovery Process:

1. Schema factory scans configured namespaces for controller classes
2. Identifies methods decorated with @Query or @Mutation annotations
3. Extracts @Right and @Logged metadata for security enforcement
4. Registers field resolvers in the GraphQL schema
5. Auto-wires controller constructor dependencies via DI container

Sources: bin/light1-24

Example Table-to-Controller Generation

Using the Config table db.json233-263 as an example:

Input Schema

Generated Controller Methods

Method	Signature	GraphQL Operation	Permission
getConfig()	getConfig(int $config_id): ?Config	query { getConfig(config_id: 1) }	model.config:read
createConfig()	createConfig(ConfigInput $input): Config	mutation { createConfig(input: {...}) }	model.config:write
updateConfig()	updateConfig(int $config_id, ConfigInput $input): Config	mutation { updateConfig(config_id: 1, input: {...}) }	model.config:write
deleteConfig()	deleteConfig(int $config_id): bool	mutation { deleteConfig(config_id: 1) }	model.config:delete

Sources: db.json233-263

Relationship to Model Generation

Controllers generated by make:controller depend on corresponding model classes generated by make:model (see Model Generation).

Controller-Model Dependency

Generation Dependencies:

1. Model Class must be generated first (provides data persistence layer)
2. Input Class should be generated (provides validation structure)
3. Controller Class references both Model and Input types

Sources: db.json1-676

Customization and Extension

Generated controllers serve as boilerplate starting points. Developers can extend them with custom business logic while maintaining the GraphQL integration and security annotations.

Common Customization Patterns

Customization Type	Implementation	Example Use Case
Additional Queries	Add @Query methods	List operations, search, filtering
Custom Mutations	Add @Mutation methods	Complex updates, bulk operations
Business Logic	Override/extend methods	Validation rules, state transitions
Permission Refinement	Modify @Right values	Fine-grained access control
Field-Level Security	Add @Right to fields	Column-level permissions
Event Handlers	Dispatch custom events	Notifications, integrations

Note: Generated controllers inherit automatic audit trail functionality from Light\Model EventLog table in db.json338-418 including created_by, updated_by, and revision snapshots.

Sources: db.json338-418

Integration with CLI Workflow

The controller generation command is typically used as part of a complete code generation workflow:

Recommended Workflow:

1. Define schema in db.json
2. Run db:install to create database tables
3. Run make:model to generate model classes
4. Run make:input to generate validation types
5. Run make:controller to generate GraphQL controllers
6. Run make:ts to generate frontend types
7. Customize generated code as needed

Sources: bin/light1-24 db.json1-676