Development Tools

The Light framework provides a comprehensive suite of development tools for schema-driven application development. These tools automate the generation of models, controllers, GraphQL types, and database schemas from a single source of truth (db.json), significantly reducing boilerplate code and ensuring consistency across the application stack. The toolset includes a Symfony Console-based CLI, code generators, database management utilities, and quality assurance tools.

For runtime configuration of the application, see System Configuration. For database abstraction and model usage at runtime, see Data Layer.

CLI Tool Architecture

The Light CLI (bin/light) serves as the main entry point for all development operations. It uses Symfony Console to provide a command-based interface with standardized help, argument parsing, and error handling.

CLI Command Architecture

Sources: bin/light1-24 composer.json55

The CLI is registered in composer.json as a binary executable, making it available via ./vendor/bin/light or directly as bin/light. The application bootstraps five command classes, each implementing Symfony's Command interface:

Command Name	Command Class	Purpose	Output Target
db:install	DbInstallCommand	Install database schema from db.json	MySQL database
make:model	MakeModelCommand	Generate PHP model classes	src/Model/
make:controller	MakeControllerCommand	Generate GraphQL controllers	src/Controller/
make:input	MakeInputCommand	Generate GraphQL input types	src/Input/
make:ts	MakeTsCommand	Generate TypeScript definitions	Configurable output path

Sources: bin/light6-21

Schema-Driven Development

The db.json file serves as the canonical schema definition, describing all database tables, columns, relationships, and constraints in a structured JSON format. This single source of truth drives all code generation and database installation operations.

Schema-Driven Artifact Generation

Sources: db.json1-676

The schema format includes comprehensive metadata for each table:

• Table definition: Name, columns, data types, constraints
• Primary keys: Auto-increment columns for record identification
• Unique keys: Enforce data integrity at database level
• Indexes: Optimize query performance for frequently accessed columns
• Foreign keys: Define relationships with cascade rules

For example, the User table definition db.json2-139 includes 24 columns covering authentication (username, password), profile information (first_name, last_name, email), OAuth identifiers (microsoft, google, facebook), security features (secret for 2FA, credential for WebAuthn), and audit fields (created_time, password_dt).

For detailed schema format and structure, see Database Schema (db.json).

Command Registry and Execution

The CLI application uses Symfony Console's command registration system to make commands discoverable and executable. Each command class extends Symfony\Component\Console\Command\Command and implements the configure() and execute() methods.

Command Execution Flow

Sources: bin/light11-23

The CLI bootstrap sequence:

1. Autoloader inclusion via Composer bin/light13
2. Symfony Console Application instantiation with version metadata bin/light15
3. Command registration using addCommand() for each command class bin/light17-21
4. Application execution via run() which handles argument parsing and command routing bin/light23

Code Generation Commands

The framework provides four code generation commands that transform schema definitions into working code. Each command reads from db.json and generates syntactically correct, properly formatted code following framework conventions.

Model Generation

The make:model command generates PHP model classes that extend Light\Model, providing automatic audit logging, timestamp tracking, and GraphQL type exposure. For implementation details, see Model Generation.

Controller Generation

The make:controller command generates GraphQL controller scaffolding with CRUD mutations for create, update, and delete operations. For implementation details, see Controller Generation.

Input Type Generation

The make:input command generates GraphQL input types (DTOs) for type-safe mutation parameters. For implementation details, see Input Type Generation.

TypeScript Generation

The make:ts command generates TypeScript interfaces and types that mirror PHP models, enabling type-safe frontend development. For implementation details, see TypeScript Generation.

Database Management

The db:install command translates the JSON schema into SQL DDL statements and executes them against the configured MySQL database. It handles table creation, index creation, and foreign key constraint setup with proper ordering to satisfy dependencies.

For detailed database management operations and schema migration strategies, see Database Management.

Testing and Quality Assurance

The framework includes built-in support for automated testing and static analysis to ensure code quality.

Quality Assurance Workflow

Sources: composer.json38-45 composer.json62-64

PHPUnit Testing

The framework uses PHPUnit 9.6+ for automated testing composer.json45 A convenience script is defined in composer.json:

Tests can be executed with composer test, which runs all tests in the tests/ directory with verbose output.

PHPStan Static Analysis

PHPStan 2.0+ provides static type analysis composer.json44 It analyzes code without executing it, catching type errors, undefined methods, and other issues at development time. This is particularly important for a framework using GraphQLite's annotation-based type system, as it ensures type safety across the GraphQL API boundary.

Dependency Management

The framework's development tools have specific dependency requirements managed through Composer.

Core Dependencies

Key dependencies for development tools:

Package	Version	Purpose
symfony/console	^7.4	CLI command framework
laminas/laminas-code	^4.7	Code generation utilities
mathsgod/json-to-sql	^1.0	JSON schema to SQL conversion
mathsgod/mysql-schema-migrate	^1.0	Schema migration tool
symfony/yaml	^6.4	YAML parsing for permissions.yml

Sources: composer.json12-36

Development Dependencies

Additional tools available in development mode:

• PHPUnit composer.json45: Test framework
• PHPStan composer.json44: Static analysis
• Storage adapters: Optional packages for S3, Aliyun OSS, FTP, Hostlink composer.json41-43

These development dependencies are not required in production but enable testing and code quality enforcement during development.

External Tools

mysql-schema-migrate

The mysql-schema-migrate package composer.json35 provides advanced schema migration capabilities beyond the basic db:install command. It can:

• Compare current database schema with db.json
• Generate migration SQL for schema differences
• Apply migrations with rollback support
• Handle complex schema changes (renames, type changes)

This tool is particularly useful for managing schema evolution in production environments where dropping and recreating tables is not feasible.

json-to-sql

The json-to-sql package composer.json34 provides the core functionality for translating JSON schema definitions into SQL DDL statements. It handles:

• Data type mapping from JSON to MySQL types
• Index creation with proper naming conventions
• Foreign key constraints with cascade rules
• Character set and collation settings

This package is used internally by DbInstallCommand to generate CREATE TABLE statements from db.json.

Development Workflow

A typical development workflow using these tools follows this pattern:

Schema-Driven Development Workflow

This workflow ensures that:

1. The database schema matches the JSON definition
2. PHP models are synchronized with database tables
3. GraphQL API surface matches model structure
4. Frontend TypeScript types match backend models
5. All code passes automated tests
6. Static analysis confirms type safety

The schema-driven approach eliminates manual synchronization between layers and reduces the risk of runtime type errors. Changes to the schema propagate automatically through the entire stack when regenerating code.

Sources: bin/light1-24 composer.json55-64