gecole / starter

dev-main 2026-09-22 17:58 UTC

Requires

• php: >=8.3

proprietary

• framework
• scaffold
• Skeleton
• starter
• bun
• unocss
• gecole

Published on Packagist.org on 2026-09-22 17:58 UTC

README

A starting point for applications built on gecole/framework: a runnable skeleton plus the gecole-new scaffolder that stamps it out.

The skeleton is a complete, working application — front controller, bootstrap, config, routes, views, controllers, providers, storage layout and the bun + UnoCSS asset pipeline — with {{PLACEHOLDER}} tokens where the project's own identity goes. Nothing is generated at runtime and nothing is interactive: the scaffolder copies files, rewrites tokens, writes .env and installs.

Use it

# in the project that should contain the new app
composer require --dev gecole/starter      # or a path repository to this package

vendor/bin/gecole-new fleet-console \
    --name="Fleet Console" \
    --namespace=Gecole\Fleet \
    --link-framework=../gecole-framework \
    --frontend                             # also run `bun install` + `bun run build`

Running it from a checkout works too, without installing anything:

php ../gecole-starter/bin/gecole-new fleet-console --link-framework=../gecole-framework

Options

Flag	Meaning
--name="My App"	application name (default: the directory name, humanised)
--namespace=App	root PHP namespace (default App; A\B and A/B are both accepted)
--package=vendor/name	Composer package name (default gecole/<directory>)
--url=http://…	application URL written to .env
--framework=^1.0	gecole/framework constraint to require
--link-framework[=PATH]	require an unreleased local checkout through a Composer path repository (default ../gecole-framework, constraint @dev)
--force	scaffold into a directory that is not empty
--no-install	skip composer install
--frontend	also run bun install and bun run build
--list-tokens	print the placeholders the skeleton files may use
-h, --help	usage

What the skeleton gives you

• The framework, booted: bootstrap/app.php → Application, public/index.php as the only exposed PHP file, public/router.php for pretty URLs with php bin/console serve, bin/console for the CLI.
• A page that proves the wiring: routing, the web session + CSRF middleware group, validation with old input and errors, a session flash and a redirect — all in HomeController, routes/web.php and resources/views.
• An API surface: routes/api.php mounted under /api with the stateless api middleware group and JSON errors, plus Api\HealthController and a validating Api\GreetController.
• An engine-based view layer: plain PHP by default, with lazily-loaded Twig, Blade, Latte and Mustache adapters selected by file suffix.
• Config (config/app.php, auth.php, database.php, ui.php) with the framework's conventions spelled out, plus app.paths overrides where the layout can move.
• SQLite by default, MySQL one env var away: the app runs before you own a database server, and php bin/console migrate works immediately.
• The frontend pipeline: bin/build.ts bundles resources/js/app.ts with bun and generates UnoCSS CSS over the PHP views, writing content-hashed files and public/assets/manifest.json (which AssetManager reads). No Vite, no PostCSS, no Node-only tooling.
• A smoke test (php tests/smoke.php) that boots the app and walks /health, /, a 419 CSRF rejection and a full form round trip.

After scaffolding

cd fleet-console
composer install                 # already done unless you passed --no-install
cp .env.example .env             # already done by the scaffolder
bun install && bun run build      # the assets (unless you passed --frontend)

php tests/smoke.php              # verify it boots
php bin/console serve            # http://127.0.0.1:8000

The generated README.md documents the layout and the next steps (accounts, database, screens, assets).

Tests

composer install
php tests/run.php                # scaffolds into throwaway directories

The cases never install anything (install => false), so the suite runs offline: they assert the file set, that every placeholder is replaced, that the namespace lands correctly in PHP and JSON, that --link-framework writes a path repository, and that scaffolding refuses a non-empty directory unless forced.