PHPackages                             mathsgod/light - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. mathsgod/light

ActiveLibrary[Utility & Helpers](/categories/utility)

mathsgod/light
==============

A lightweight PHP GraphQL framework

1.40.2(yesterday)03381[1 PRs](https://github.com/mathsgod/light/pulls)MITPHPPHP >=8.3CI passing

Since Dec 27Pushed 4d ago1 watchersCompare

[ Source](https://github.com/mathsgod/light)[ Packagist](https://packagist.org/packages/mathsgod/light)[ RSS](/packages/mathsgod-light/feed)WikiDiscussions main Synced today

READMEChangelog (10)Dependencies (230)Versions (103)Used By (0)

[![Ask DeepWiki](https://camo.githubusercontent.com/0f5ae213ac378635adeb5d7f13cef055ad2f7d9a47b36de7b1c67dbe09f609ca/68747470733a2f2f6465657077696b692e636f6d2f62616467652e737667)](https://deepwiki.com/mathsgod/light)

light
=====

[](#light)

A lightweight PHP 8.3+ GraphQL backend framework for building admin/CMS applications. Exposes a GraphQL API (plus a few REST endpoints for file serving) backed by a custom ORM ([mathsgod/light-db](https://github.com/mathsgod/light-db)), RBAC, and a PSR-15 middleware pipeline.

The companion frontend module is [`nuxt-light`](https://github.com/hostlink/nuxt-light) — a Nuxt 4 module using Quasar UI.

---

Requirements
------------

[](#requirements)

- PHP >= 8.3
- Composer
- MySQL / MariaDB (or any Laminas DB-supported database)

---

Installation
------------

[](#installation)

```
composer install
```

---

Configuration
-------------

[](#configuration)

All configuration is read from a `.env` file in the project root.

### Database

[](#database)

```
DATABASE_HOSTNAME=
DATABASE_DATABASE=
DATABASE_USERNAME=
DATABASE_PASSWORD=
DATABASE_PORT=
DATABASE_CHARSET=
```

### JWT Secret

[](#jwt-secret)

A random string used to sign JWT access/refresh tokens.

```
JWT_SECRET=
```

### Timezone

[](#timezone)

```
TZ=Asia/Hong_Kong
```

### Google Sign-In (optional)

[](#google-sign-in-optional)

Install the Google API client:

```
composer require google/apiclient
```

Then set:

```
GOOGLE_CLIENT_ID=
```

### Other optional settings

[](#other-optional-settings)

```
API_PREFIX=       # URL prefix for the GraphQL endpoint
CORS=             # Allowed CORS origin domain
```

---

Development Server
------------------

[](#development-server)

```
# Linux / macOS
sh run.sh

# Windows
run.bat
```

Both start `php -S 0.0.0.0:8888 router.php`.

---

Database Schema
---------------

[](#database-schema)

Initialize the database schema (defined in `db.json`):

```
php bin/light db:install
```

---

CLI Scaffolding
---------------

[](#cli-scaffolding)

```
php bin/light make:controller Name   # Generate a GraphQL controller
php bin/light make:model Name        # Generate an ORM model
php bin/light make:input Name        # Generate a GraphQL input type
php bin/light make:ts                # Generate TypeScript definitions from the schema
```

---

Architecture
------------

[](#architecture)

```
index.php → Light\App::run()
  → Middleware pipeline (CORS, JWT auth, file upload)
  → Router:
      GET  /fs/{protocol}/{path}   — Flysystem file serving
      GET  /drive/{index}/{path}   — Drive/storage access
      POST /refresh_token          — JWT token refresh
      *                            — GraphQL execution

```

**Schema generation** is annotation-driven via [TheCodingMachine/GraphQLite](https://graphqlite.thecodingmachine.io/). Controllers in `src/Controller/` declare queries and mutations using PHP 8 attributes (`#[Query]`, `#[Mutation]`, `#[Type]`, etc.).

**ORM** — models live in `src/Model/` and extend `Light\Model`. The schema is defined in `db.json`. `save()` and `delete()` auto-populate audit fields (`created_time`, `updated_time`, `created_by`, `updated_by`) and write to `EventLog`.

**RBAC** — role → permission mappings bootstrap from `permissions.yml`; menus bootstrap from `menus.yml`. The `Administrators` role always has `*` (wildcard) permission.

**File storage** — file operations go through `Light\Drive` (Flysystem MountManager). Supported adapters: Local, AWS S3, Aliyun OSS, Hostlink.

---

Directory Layout
----------------

[](#directory-layout)

PathPurpose`src/Controller/`GraphQL controllers (queries & mutations)`src/Model/`ORM models, extend `Light\Model``src/Input/`GraphQL input types for mutations`src/Type/`GraphQL output types`src/Command/`Symfony Console CLI commands`src/Auth/`JWT auth & authorization logic`src/Drive/`Flysystem drive abstraction`function/`Global helper functions (auto-loaded)`pages/`Optional plain-PHP pages (return JSON)`db.json`Database schema definition`menus.yml`Hierarchical menu definitions`permissions.yml`Role → permission bootstrap mappings---

Authentication Flow
-------------------

[](#authentication-flow)

1. Login via GraphQL mutation → returns `access_token` (short-lived JWT) + `refresh_token`
2. Subsequent requests send `Authorization: Bearer `
3. Token refresh: `POST /refresh_token`
4. Optional 2FA (TOTP) and WebAuthn supported via `src/Security/`

---

Testing
-------

[](#testing)

```
./vendor/bin/phpunit --no-coverage                          # Run all tests
./vendor/bin/phpunit --no-coverage tests/SomeTest.php       # Single test file
./vendor/bin/phpunit --no-coverage --filter testMethodName  # Single test method
./vendor/bin/phpstan analyse src/                           # Static analysis
```

Tests require a real DB connection (integration tests). Each test wraps in a DB transaction and rolls back in `tearDown()`.

---

License
-------

[](#license)

MIT

###  Health Score

53

—

FairBetter than 96% of packages

Maintenance100

Actively maintained with recent releases

Popularity16

Limited adoption so far

Community8

Small or concentrated contributor base

Maturity74

Established project with proven stability

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~9 days

Recently: every ~0 days

Total

102

Last Release

1d ago

PHP version history (2 changes)1.20.0PHP >=8.1

1.37.0PHP >=8.3

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/18732337?v=4)[Raymond](/maintainers/mathsgod)[@mathsgod](https://github.com/mathsgod)

---

Top Contributors

[![mathsgod](https://avatars.githubusercontent.com/u/18732337?v=4)](https://github.com/mathsgod "mathsgod (618 commits)")

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Type Coverage Yes

### Embed Badge

![Health badge](/badges/mathsgod-light/health.svg)

```
[![Health](https://phpackages.com/badges/mathsgod-light/health.svg)](https://phpackages.com/packages/mathsgod-light)
```

###  Alternatives

[shopware/core

Shopware platform is the core for all Shopware ecommerce products.

585.6M574](/packages/shopware-core)[craftcms/cms

Craft CMS

3.6k3.6M3.1k](/packages/craftcms-cms)[chameleon-system/chameleon-base

The Chameleon System core.

1028.6k5](/packages/chameleon-system-chameleon-base)[shopware/platform

The Shopware e-commerce core

3.4k1.5M3](/packages/shopware-platform)[open-dxp/opendxp

Content & Product Management Framework (CMS/PIM)

9421.6k61](/packages/open-dxp-opendxp)[pimcore/pimcore

Content & Product Management Framework (CMS/PIM/E-Commerce)

3.8k3.8M508](/packages/pimcore-pimcore)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)