GraphQL API

Purpose and Scope

This document describes the GraphQL API layer in the Light framework, which provides the primary programmatic interface for client applications. The GraphQL API uses a code-first approach powered by the GraphQLite library, generating the schema automatically from PHP annotations and attributes.

This page covers:

• Schema generation and the type system
• Available queries and mutations through root entry points
• Authorization enforcement via annotations
• Request processing pipeline

For details on specific controllers and their operations, see Controllers. For authentication flow details, see Authentication Architecture. For the overall request lifecycle including middleware, see Request Lifecycle.

---

Architecture Overview

The Light framework implements a code-first GraphQL API where the schema is automatically generated from PHP class annotations rather than being defined in GraphQL SDL files. This approach provides type safety, IDE support, and keeps API definitions co-located with implementation code.

Core GraphQL Components

Sources: src/App.php121-130 src/App.php529-530

The SchemaFactory is initialized during application bootstrap and configured with:

• Namespace scanning for type discovery
• Custom type mappers for database models
• Authentication and authorization services
• Caching configuration based on dev/prod mode

---

Schema Generation Process

Initialization and Configuration

The GraphQL schema is generated during application initialization through a multi-step process:

Sources: src/App.php121-127 src/App.php529-530

The schema factory setup occurs in the Light\App constructor:

Configuration Step	Code Reference	Purpose
Create GraphQL Server	src/App.php121	Initializes with cache lifetime (15s dev, 0s prod)
Get Cache Instance	src/App.php123	PSR-16 cache for schema storage
Get Schema Factory	src/App.php124	GraphQLite factory instance
Add Namespace	src/App.php125	Scan "Light" namespace for types
Add Type Mapper	src/App.php126	Custom mapper for Light\Db models
Set Auth Services	src/App.php529-530	Inject authentication context

---

Annotation-Based Type System

The GraphQL schema is defined using PHP attributes (annotations) on classes and methods:

Sources: src/Type/App.php28 src/Type/App.php32-36 src/Type/App.php186-194

Example from Light\Type\App showing annotation usage:

Annotation	Usage	Location
#[Type]	Declares the class as a GraphQL type	src/Type/App.php28
#[Field]	Exposes a method as a GraphQL field	src/Type/App.php32
#[Logged]	Requires user to be authenticated	src/Type/App.php33
#[Right("permission")]	Requires specific permission	src/Type/App.php343
#[Autowire]	Injects dependency from container	src/Type/App.php191
#[InjectUser]	Injects authenticated user	src/Type/App.php461

---

Schema Caching Strategy

The framework employs different caching strategies based on environment mode:

Environment	Cache Lifetime	Schema Regeneration	Code Reference
Development (mode != "prod")	15 seconds	Every 15s or on cache miss	src/App.php113
Production (mode == "prod")	0 seconds (indefinite)	Only on cache clear	src/App.php111

The cache lifetime is determined during initialization:

if ($this->mode === "prod") {
 $defaultLifetime = 0; // Cache indefinitely
} else {
 $defaultLifetime = 15; // Re-scan every 15 seconds
}

Sources: src/App.php104-119

---

Root Query Type: Light\Type\App

The primary GraphQL entry point is the Light\Type\App class, which serves as the root query type exposing system-level queries and configuration access.

System Query Fields

Sources: src/Type/App.php28-544

Authentication and User Context Queries

Field	Return Type	Authentication	Authorization	Purpose
getAuth	Auth	No	None	Returns authentication status and OAuth configuration
isLogged	Boolean	No	None	Checks if current user is authenticated and has base roles
getMenus	[Menu]	Yes (@Logged)	None	Returns menu structure filtered by user permissions
getPermissions	[String]	Yes (@Logged)	None	Lists all permissions discovered in the system

Sources: src/Type/App.php93-96 src/Type/App.php331-337 src/Type/App.php197-202 src/Type/App.php186-194

The getMenus field implements hierarchical permission filtering:

Filter Logic:
1. Iterate through menu tree
2. For each menu item with "permission" property:
 - If permission starts with "#", check role membership
 - Otherwise, check if any user role has the permission via RBAC
3. Recursively filter children
4. Remove parent items with no accessible children

Sources: src/Type/App.php204-261

---

Configuration and Feature Queries

Field	Return Type	Authentication	Authorization	Purpose
getVersion	String	No	None	Returns Light framework version from composer
isDevMode	Boolean	No	None	Checks if Config.mode != "prod"
isTwoFactorAuthentication	Boolean	No	None	Checks if 2FA is enabled in config
isWebAuthnEnabled	Boolean	No	None	Checks if WebAuthn/FIDO2 is enabled
hasBioAuth	Boolean	No	None	Checks if webauthn-lib is installed
getCompany	String	No	None	Returns company name from config (default: "HostLink")
getCompanyLogo	String?	No	None	Returns company logo URL from config

Sources: src/Type/App.php109-112 src/Type/App.php181-184 src/Type/App.php175-178 src/Type/App.php288-291 src/Type/App.php168-172 src/Type/App.php301-304 src/Type/App.php313-316

These queries are typically used during application bootstrap on the frontend to configure the UI.

---

Data Listing Queries

The Light\Type\App class provides several list queries that support filtering and sorting:

Field	Return Type	Required Permission	Filter Support	Sort Support
listUser	Light\Db\Query	user.list	Yes	Yes
listConfig	Light\Db\Query	config.list	Yes	Yes
listEventLog	Light\Db\Query	eventlog.list	Yes	Yes
listMailLog	Light\Db\Query	maillog.list	Yes	Yes
listUserLog	Light\Db\Query	userlog.list	Yes	Yes
listPermission	Light\Db\Query	permission.list	Yes	Yes
listSystemValue	Light\Db\Query	systemvalue.list	Yes	Yes

Sources: src/Type/App.php460-473 src/Type/App.php442-451 src/Type/App.php422-439 src/Type/App.php412-420 src/Type/App.php522-532 src/Type/App.php534-543 src/Type/App.php510-520

All list queries return Light\Db\Query objects which support:

• Filter expressions: $filters = ["username" => ["contains" => "john"]]
• Sort specifications: $sort = "created_time DESC"
• Lazy evaluation and pagination

The listUser query includes special logic to prevent non-administrators from listing administrators:

if (!$user->is("Administrators")) {
 $q->where("user_id NOT IN (SELECT user_id FROM UserRole WHERE role = 'Administrators')");
}

Sources: src/Type/App.php466-470

---

File System Access Queries

Field	Return Type	Authentication	Parameters	Purpose
fs	Filesystem	Yes (@Logged)	None	Returns filesystem operations interface
getDrive	Drive	Yes (@Logged)	index: Int = 0	Returns specific drive by index
getDrives	[Drive]	Yes (@Logged)	None	Returns all configured drives
getDriveTypes	[String]	Yes (@Logged)	None	Lists available storage backend types
listFileSystem	mixed	No	None	Lists filesystem configurations (requires filesystem.list permission)

Sources: src/Type/App.php32-37 src/Type/App.php386-393 src/Type/App.php395-409 src/Type/App.php362-384 src/Type/App.php500-508

The getDriveTypes field dynamically discovers available storage backends by checking installed composer packages:

Storage Type	Required Package	Check Location
local	Always available	N/A
s3	league/flysystem-aws-s3-v3	src/Type/App.php372-374
hostlink	hostlink/hostlink-storage-adapter	src/Type/App.php376-378
aliyun-oss	alphasnow/aliyun-oss-flysystem	src/Type/App.php380-382

---

Controller-Based Mutations

While Light\Type\App provides the root query type, mutations are primarily organized in controller classes within the Light\Controller namespace. Each controller focuses on a specific domain.

Controller Registration

Controllers are registered in the dependency injection container during Light\App initialization:

Sources: src/App.php75-97

The registration code shows all controllers added to the container:

Controller Class	Domain	Registration Line
AuthController	Authentication	src/App.php77
AppController	Configuration	src/App.php75
FileSystemController	File operations	src/App.php93
RevisionController	Audit trail	src/App.php94
UserController	User management	src/App.php78
RoleController	Role management	src/App.php79
ConfigController	Config updates	src/App.php83
PermissionController	Permissions	src/App.php82
WebAuthnController	Biometric auth	src/App.php90
TranslateController	Internationalization	src/App.php89
CustomFieldController	Dynamic schema	src/App.php97

For detailed documentation of each controller's operations, see:

• Authentication mutations: AuthController
• Configuration mutations: AppController
• File operations: FileSystemController
• Revision restoration: RevisionController

---

Authorization Enforcement

The GraphQL API integrates authorization at multiple levels using annotations and the RBAC system.

Authorization Annotation Hierarchy

Sources: src/App.php529-530

Authentication Check: @Logged

The @Logged annotation requires a user to be authenticated before accessing a field:

#[Field]
#[Logged]
public function getMenus(#[InjectUser()] User $user, #[Autowire] LightApp $app)
{
 return $this->filterMenus($app->getMenus(), $app->getRbac(), $user->getRoles());
}

Sources: src/Type/App.php197-202

When @Logged is present:

1. GraphQLite checks the AuthenticationService (which is Auth\Service)
2. Calls isLogged() method
3. If false, throws authentication error before method execution
4. If true, proceeds to execute method (and checks @Right if present)

---

Permission Check: @Right

The @Right annotation requires specific permissions checked through the RBAC system:

#[Field]
#[Logged]
#[Right("user.list")]
public function listUser(#[InjectUser] \Light\Model\User $user, $filters = [], ?string $sort = "")
{
 // Implementation
}

Sources: src/Type/App.php460-473

When @Right("permission") is present:

1. GraphQLite checks the AuthorizationService (which is Auth\Service)
2. Calls isAllowed("permission") method
3. Auth\Service delegates to Rbac system to check user's roles
4. Permission is checked against role hierarchy and user-specific permissions
5. If denied, throws authorization error
6. If allowed, method executes

Permission Discovery

The framework discovers all permissions at runtime by scanning for @Right annotations:

Sources: src/App.php392-472

The permission discovery process:

Step	Code Reference	Purpose
Scan Controllers	src/App.php395-403	Find @Right in Light\Controller\*
Scan Models	src/App.php405-413	Find @Right in Light\Model\*
Scan Types	src/App.php425-433	Find @Right in Light\Type\*
Scan Database	src/App.php415-423	Find @Right in Light\Database\*
Scan Custom Namespaces	src/App.php435-451	Find @Right in custom Controller/Model namespaces
Extract Menu Permissions	src/App.php453-455	Get permissions from menu definitions
Add RBAC Permissions	src/App.php458-460	Include permissions from RBAC system
Filter Role Markers	src/App.php463-465	Remove permissions starting with "#"

This comprehensive discovery ensures the system has a complete inventory of all permissions for management and UI display purposes.

---

Request Processing Flow

End-to-End GraphQL Request

Sources: src/App.php500-537 src/App.php154-170 src/App.php567-579

Query Execution Steps

Phase	Method	Responsibilities	Code Reference
1. Request Preprocessing	App::process()	Parse body, handle uploads, initialize auth	src/App.php500-537
2. Auth Context Setup	new Auth\Service()	Extract JWT, validate, load user	src/App.php526
3. Factory Configuration	setAuthenticationService()	Inject auth into GraphQLite	src/App.php529-530
4. Schema Creation	Factory::createSchema()	Load from cache or generate	src/App.php577
5. Query Execution	GraphQL::executeQuery()	Parse and execute GraphQL	src/App.php578
6. Authorization Checks	Before resolver	Check @Logged and @Right	N/A (handled by GraphQLite)
7. Resolver Invocation	Controller method	Execute business logic	Varies by resolver
8. Response Formatting	App::handle()	Format result, add debug info if dev	src/App.php154-170

Request Body Parsing

The framework handles two types of GraphQL request bodies:

// Standard GraphQL POST
{
 "query": "query { app { isLogged } }",
 "variables": { ... }
}

// Multipart upload (for file uploads)
Content-Type: multipart/form-data
operations: {"query": "mutation($file: Upload!) { ... }", "variables": {...}}
map: {"0": ["variables.file"]}
0: [file data]

The body parsing logic:

Step	Code	Purpose
Check parsed body	src/App.php508-511	If not parsed by middleware, decode JSON manually
Process uploads	src/App.php513-514	Use UploadMiddleware to handle multipart uploads
Extract query & variables	src/App.php573-574	Parse from request body

Sources: src/App.php508-514 src/App.php567-574

---

Response Format

Standard Response Structure

GraphQL responses follow the standard format:

Debug Mode Enhancement

When in development mode (Config.mode != "prod"), responses include additional debug information:

Debug Flag	Included Information	Code Reference
INCLUDE_DEBUG_MESSAGE	Detailed error messages	src/App.php161
INCLUDE_TRACE	Stack traces for errors	src/App.php161
JSON_UNESCAPED_UNICODE	Preserve Unicode characters	src/App.php161-163

The debug flag logic:

if ($this->isDevMode()) {
 return new JsonResponse(
 $result->toArray(DebugFlag::INCLUDE_DEBUG_MESSAGE | DebugFlag::INCLUDE_TRACE),
 200,
 [],
 JsonResponse::DEFAULT_JSON_FLAGS | JSON_UNESCAPED_UNICODE
 );
}

Sources: src/App.php160-164

This ensures sensitive error details (like stack traces and internal paths) are not exposed in production environments while providing helpful debugging information during development.

---

Type Mapping and Custom Scalars

The GraphQL schema generation includes custom type mappers to bridge between PHP types and GraphQL types, particularly for database models.

Type Mapper Factory Registration

Sources: src/App.php126

The type mapper factory is registered during app initialization:

$this->factory->addTypeMapperFactory(new \Light\Db\GraphQLite\Mappers\TypeMapperFactory);

This allows database models extending Light\Db\Model to be automatically exposed as GraphQL types without manual schema definition, maintaining synchronization between database schema and GraphQL schema.

Common Output Types

Several fields use special output type declarations:

Output Type	Usage	Purpose	Example Field
mixed	Dynamic/untyped	For configuration objects with varying structure	src/Type/App.php39 generate2FASecret
[mixed]	Array of dynamic	For flexible arrays	src/Type/App.php58 getCustomFieldSchema
[String]	String array	For list of strings	src/Type/App.php82 getCustomFieldModels

These type declarations provide flexibility for fields that don't conform to strict GraphQL object types while maintaining type safety where possible.

---

Summary

The Light framework's GraphQL API provides a comprehensive, type-safe interface through:

1. Code-first schema generation using GraphQLite annotations, eliminating schema/code drift
2. Automatic type discovery from the Light namespace and custom namespaces
3. Integrated authorization via @Logged and @Right annotations enforced before resolver execution
4. Flexible querying through Light\Type\App providing system queries and configuration
5. Domain-organized mutations through specialized controller classes
6. Environment-aware behavior with debug information in development and optimized caching in production
7. Permission discovery enabling dynamic UI generation based on user capabilities

The architecture ensures security is enforced at the GraphQL field level, provides comprehensive audit capabilities, and maintains a clear separation between API surface and implementation while keeping them synchronized through annotations.