README

A PHP framework for Garrett County Government, Maryland, USA applications.

The framework can be used to generate a full SSR app or as a rest API. It is primarily used internally to generate APIs. Using the available extensions, a full-fledged API with Microsoft Oauth authentication can be created with no custom code.

Getting Started

The easiest way to start is to use the framework scaffolding project to start a new api and the frontend app template to start a corresponding front end application.

Requirements

Framework package requirements from composer.json:

PHP >=8.4
PHP extensions: ext-mongodb, ext-fileinfo, ext-pdo, ext-sodium, ext-openssl
Optional: ext-zip, which gf chrome:install and gf chrome:update need

Install dependencies with Composer:

composer install

Minimum Application Contract

The framework expects these app classes/files to exist in your /app directory:

\app\app implementing \gcgov\framework\interfaces\app
\app\router implementing \gcgov\framework\interfaces\appRouter
\app\renderer implementing \gcgov\framework\interfaces\render

Controllers should implement \gcgov\framework\interfaces\controller.

Required configuration files:

/config.json — the unified configuration at the application root (merged app + environment sections, secrets and per-environment values referenced via %env(...)%)

If it is missing, the framework throws a config exception during request handling.

config.json supports Symfony-style %env(...)% environment-variable references, so secrets (Mongo URIs, client secrets, SMTP credentials) can be injected from the process environment, Docker/Kubernetes secrets, or a .env file instead of being stored in the files. Existing plain-JSON config keeps working unchanged. See readme/environment-variables.md.

System Architecture

Application File System

All apps utilizing the framework for an entire lifecycle should use this file structure.

/api
├── config.json
├── app
│   ├── app.php
│   ├── constants.php
│   ├── renderer.php
│   ├── router.php
│   ├── cli
│   │   └── index.php
│   ├── controllers
│   │   └── {controller.php}
│   └── models
│       └── {model.php}
└── www
    └── index.php

When you start with the framework scaffolding project, you'll automatically start with some extra folders and tools.

/api
│...
├── config.json                       # committed unified config; secrets/per-env values via %env(...)
├── .env.example                      # copy to .env (gitignored); holds gf db:*/env PROD_* vars too
├── www
│   │...
├── app
│   │...
├── docker
│   └── nginx
│       └── default.conf.template
├── srv
│   ├── tmp
│   │   ├── files
│   │   ├── opcache
│   │   ├── sessions
│   │   ├── soaptmp
│   │   └── tmp
│   └── jwtCertificates
├── db
│   └── local-createuser.js
├── logs
├── Dockerfile
└── docker-compose.yml

Core Files and Application Namespacing

The webserver should point requests to /www/index.php. URL rewriting should route application paths to this file.

gcgov\framework\router routes using $_SERVER['REQUEST_URI'] and $_SERVER['REQUEST_METHOD']. Rewrite rules should preserve the original request path in REQUEST_URI.

index.php

CLI requests should point to /app/cli/index.php.

app/cli/index.php

The framework will register namespace \app to the /app directory and requires three core files in the root of /app:

Components

Controllers

\app\controllers

A controller method called by the router must return one of the following supported types. It should always provide a response and never end code execution manually to ensure that the entire application lifecycle is executed.

New controller response types may be added to the framework to support new scenarios by adding the type and setting up rendering methods in \gcgov\framework\renderer

\gcgov\framework\models\controllerDataResponse
\gcgov\framework\models\controllerPagedDataResponse
\gcgov\framework\models\controllerFileResponse
\gcgov\framework\models\controllerFileBase64EncodedContentResponse
\gcgov\framework\models\controllerViewResponse

Models

\app\models

Interfaces

\app\interfaces

Exceptions

\app\exceptions

Traits

\app\traits

Services

\app\services

Routing

\app\router method getRoutes() must return an array of \gcgov\framework\models\route that maps the URL path to the controller and defines authentication requirements.

\gcgov\framework\models\route(
    string|array $httpMethod = '', 
    string $route = '', 
    string $class = '', 
    string $method = '', 
    bool $authentication = false, 
    array $requiredRoles = [], 
    bool $allowShortLivedUrlTokens=false
)

The following route will map incoming GET requests to /structure to controller \app\controllers\structure method getAll. The route requires authentication and the user must have the role Structure.Read to execute the request.

new route( 'GET', 'structure', '\app\controllers\structure', 'getAll', true, [ 'Structure.Read' ] );

When loading the app via CLI, the method will be CLI instead of a normal HTTP method. CLI routes do not support authentication.

new route( 'CLI', 'structure/cleanup', '\app\controllers\structure', 'cleanup', false );

Request Lifecycle

\www\index.php
\app\app::_before()
\app\app::__construct()
\app\router::_before()
\app\router::__construct()
\app\router::route()
\app\router::_after()
\app\renderer::_before()
\app\controllers\{route-controller}::_before()
\app\controllers\{route-controller}::__construct()
\app\controllers\{route-controller}::{route-method}()
\app\controllers\{route-controller}::_after()
\app\renderer::_after()
\app\app::_after()

Command line: gf

The framework ships a multiplatform command line tool at vendor/bin/gf (Windows: vendor\bin\gf.bat). Run gf with no arguments to list every available command. Highlights:

gf cli /structure/cleanup        # run a CLI route (replaces app/cli/{env}.bat)
gf cli /structure/cleanup --debug# run with Xdebug (replaces local-debug.bat)
gf cli:list                      # list the app's CLI routes
gf cert:generate-auth            # JWT signing keys (replaces create-jwt-keys.ps1)
gf db:run db/script.js           # run a mongosh script with config-managed credentials
gf env                           # validate config.json resolves against this environment
gf env --list                    # every variable config.json references, and which are set
gf env --init                    # write/extend the .env skeleton from config.json
gf init --title="My API"         # bootstrap a scaffolded app (replaces setup.ps1)
gf migrate                       # convert a v6 application to the v7 layout
gf user:create --email=… --roles=…  # create the account you sign in as (the first user)

Removed in v7: deploy (a Release is an immutable image pinned by digest — see ADR 0002), db:restore (it required production credentials on every workstation), and setup (replaced by the non-interactive init). The framework no longer ships the PowerShell scripts scripts/setup.ps1 and scripts/create-jwt-keys.ps1. Use gf init and gf cert:generate-auth.

Tab completion is available for bash/zsh/fish (gf completion --help) and PowerShell (gf completion:powershell), including dynamic completion of the app's CLI route names. Apps and plugins can add their own gf commands via a cli\commandProvider class.

See readme/gf.md for the full reference and the migration guide, and readme/local-development.md for what an application needs in order to run on a development computer.

The legacy per-app entry (> app/cli/{env}.bat {url-path}, local-debug.bat for XDebug) keeps working, but new apps should use gf. The scripts/*.ps1 files shipped with the framework are deprecated in favor of gf init and gf cert:generate-auth.

Framework Services

Formatting

Sanitize file name: \gcgov\framework\services\formatting::fileName( string $fileName, string $replacementForIllegalChars = '-', bool $forceLowerCase = true ): string
Sanitize Excel tab name: \gcgov\framework\services\formatting::xlsxTabName( string $tabName, string $replacementForIllegalChars = ' ', bool $forceLowerCase = false ) : string
Format DateInterval to human readable string: \gcgov\framework\services\formatting::getDateIntervalHumanText( \DateInterval $interval ) : string

GUID

Create a GUID \gcgov\framework\services\guid::create()

HTTP

Get status text for HTTP code \gcgov\framework\services\http::statusText( int $code )

Logging

\gcgov\framework\services\log writes each record where logging.destination in config.json says:

stderr, the default: one JSON object per line on standard error. A container's output is its log.
file: a line appended to /logs/{channel}.log. An application still hosted on IIS sets this.
both: stderr and the file.

The database layer's log follows the same setting. It writes a record for each database operation, and only while the first database in mongoDatabases sets logging to true.

Debug \gcgov\framework\services\log::debug( string $channel, string $message, array $context = [] )
Info \gcgov\framework\services\log::info( string $channel, string $message, array $context = [] )
Notice \gcgov\framework\services\log::notice( string $channel, string $message, array $context = [] )
Warning \gcgov\framework\services\log::warning( string $channel, string $message, array $context = [] )
Error \gcgov\framework\services\log::error( string $channel, string $message, array $context = [] )
Critical \gcgov\framework\services\log::critical( string $channel, string $message, array $context = [] )
Alert \gcgov\framework\services\log::alert( string $channel, string $message, array $context = [] )
Emergency \gcgov\framework\services\log::emergency( string $channel, string $message, array $context = [] )

JWT Auth & Certificates

\gcgov\framework\services\jwtAuth\jwtAuth() provides all JWT authentication mechanisms. Explore the Oauth Server Service and Microsoft Auth Token Exchange extensions before rolling a new solution for authentication.

Microsoft Services

Deprecated - use https://github.com/andrewsauder/microsoftServices instead

MongoDB

Comprehensive database modeling system \gcgov\framework\services\mongodb.

Use this service by defining classes in \app\models that extend \gcgov\framework\services\mongodb\model (top-level collection documents) or \gcgov\framework\services\mongodb\embeddable (nested documents that are not stored as their own collection).

How Models Work

The Mongo model stack is layered like this:

embeddable handles BSON and JSON serialization/deserialization, typemaps, _meta, and validation helpers.
dispatcher handles embedded-model propagation (insert/update/delete in parent collections) and cascade deletion behavior.
factory provides static data access and persistence APIs.
model is the base class your top-level collection models extend.

Every class extending \gcgov\framework\services\mongodb\model must define a public $_id field of type \MongoDB\BSON\ObjectId.

By default, a model's collection name is the class name. You can override this and user-facing names with constants:

final class inspection extends \gcgov\framework\services\mongodb\model {
    const _COLLECTION = 'inspection';
    const _HUMAN = 'inspection';
    const _HUMAN_PLURAL = 'inspections';

    public \MongoDB\BSON\ObjectId $_id;
}

Core Model APIs (Static)

Available through any model class (for example \app\models\inspection):

Read: countDocuments, getAll, getPagedResponse, getOne, getOneBy
Write: save, saveMany
Delete: delete, deleteMany, deleteManyBy
Analytics: aggregation

Save and delete operations are transaction-aware. If you do not pass a \MongoDB\Driver\Session, the service opens and manages one for the operation.

Serialization, Typemaps, and `_meta`

embeddable provides the serialization pipeline used by all models and embedded documents:

BSON typemaps are generated from typed properties so Mongo results hydrate into your model classes.
Date handling maps Mongo UTCDateTime values to PHP DateTimeImmutable during read.
_meta is managed automatically and can include field labels, UI state, validation state, and DB operation results.
Property and class attributes control behavior such as #[includeMeta], #[excludeBsonSerialize], #[excludeBsonUnserialize], #[excludeJsonDeserialize], and #[redact(...)].

Embedded Model Dispatch and Cascading

When saving a model, dispatcher can automatically propagate changes to embedded copies in other collections:

_insertEmbedded pushes newly saved models into configured parent arrays.
_updateEmbedded updates embedded copies by matching _id.
_deleteEmbedded removes embedded copies when the source model is deleted.
_deleteCascade recursively deletes related models marked with cascade attributes.

This behavior is driven by typemap + attribute metadata, enabling denormalized Mongo document patterns while keeping embedded data synchronized.

Additional Features Provided by the Mongo Service

#[autoIncrement] support for generated counters (including grouped/formatting scenarios).
_beforeSave and _afterSave lifecycle hooks on models.
Optional auditing/diff logging when enabled in environment config.
Validation integration via updateValidationState() using Symfony validation attributes.

For full reference, configuration options, attributes, and detailed examples, see:

MongoDB Service

PDODB

Initiate PDO connections using SQL connection details in config.json (sqlDatabases). It is only a small wrapper around the native PDO class.

Read user connection: new gcgov\framework\services\pdodb\pdodb(true, $databaseName)

Write user connection: new gcgov\framework\services\pdodb\pdodb(false, $databaseName)

Extensions

Extensions add service or app level functionality to the app that registers them. Extensions may expose new endpoints.

Framework Services ship inside the framework. Enable one by adding its block to the services section of config.json — presence enables it, and the block's contents are its settings.

"services": {
  "auth":          { "provider": "oauth" },   // or "msFront"
  "userCrud":      { },
  "documentation": { }
}

Authentication services.auth — one service, two providers.
- provider: "oauth" — full OAuth server: password, third-party and authorization-code grants, MFA. GET /auth/out signs out one session: it revokes the refresh token issued with the caller's access token, and the user's other devices stay signed in.
- provider: "msFront" — exchange a Microsoft token the front end already holds for an app JWT.
- Either way you get /.well-known/jwks.json, /auth/fileToken, and a JWT guard over every authentication: true route.
User CRUD services.userCrud — /user CRUD over the resolved user model.
Open API Documentation services.documentation — GET /documentation.yaml.
Cron Monitor — not a Framework Service; construct \gcgov\framework\services\cronMonitor\cronMonitor directly and set cronMonitor.url.

The separately published gcgov/framework-service-* packages remain available for v6 applications. The framework conflicts with them, so a v7 application cannot install both.

gcgov / framework

Package info

Security

Statistics

README

Getting Started

Requirements

Minimum Application Contract

System Architecture

Application File System

Core Files and Application Namespacing

Components

Controllers

Models

Interfaces

Exceptions

Traits

Services

Routing

Request Lifecycle

Command line: gf

Framework Services

Formatting

GUID

HTTP

Logging

JWT Auth & Certificates

Microsoft Services

MongoDB

How Models Work

Core Model APIs (Static)

Serialization, Typemaps, and `_meta`

Embedded Model Dispatch and Cascading

Additional Features Provided by the Mongo Service

PDODB

Extensions

gcgov / framework

Package info

Security

Statistics

README

Getting Started

Requirements

Minimum Application Contract

System Architecture

Application File System

Core Files and Application Namespacing

Components

Controllers

Models

Interfaces

Exceptions

Traits

Services

Routing

Request Lifecycle

Command line: gf

Framework Services

Formatting

GUID

HTTP

Logging

JWT Auth & Certificates

Microsoft Services

MongoDB

How Models Work

Core Model APIs (Static)

Serialization, Typemaps, and _meta

Embedded Model Dispatch and Cascading

Additional Features Provided by the Mongo Service

PDODB

Extensions

Serialization, Typemaps, and `_meta`