README

Imarc’s Laravel starter for single-page applications. It wires together a session-first API (Laravel Sanctum), a Vue 3 front end (Vite), an admin panel (Filament), and roles/permissions (Spatie)—plus API docs, an HTTP client collection, tests, and team conventions—so new projects begin from a consistent baseline instead of an empty laravel new.

Install it as a new project:

composer create-project imarc/spa-treatment

The Composer post-create-project-cmd script generates an application key, ensures a SQLite file exists at database/database.sqlite, and runs migrations when possible. Configure your database and environment in .env (see Configuration) before relying on a fresh install in production or on a team database.

Requirements

Tool	Notes
PHP	`^8.3` (see `composer.json`)
Composer	For PHP dependencies and scripts
Node.js + npm	For Vite, Vue, and front-end tooling
Database	Matches `.env` (example uses MariaDB/MySQL; tests use SQLite in-memory)

Quick start

After composer create-project (or cloning this repo):

composer install
cp .env.example .env   # skipped if .env already exists
php artisan key:generate # skipped if key already set by create-project
php artisan migrate
npm install
npm run dev

In another terminal, serve the app if you are not using a full stack (e.g. Laravel Herd, Valet, or Docker):

php artisan serve

For an all-in-one local stack (server, queue, logs, Vite), use:

composer dev

Running with Imarc Ops

Imarc Ops is a Docker-based local development environment aimed at PHP projects: shared services (MariaDB, Redis, Mailhog, and others), HTTPS with local certs, and projects under $HOME/Sites served at https://{project-directory}.imarc.io by default. Install and usage are covered in the Ops README.

Project hints in `.env`

.env.example includes OPS_PROJECT_BACKEND (for example apache-php84) so Ops selects the right PHP/Apache stack. Adjust APP_URL, SANCTUM_STATEFUL_DOMAINS, and DB_* to match your Ops hostname and the MariaDB database you use (hostname is typically mariadb from inside containers—see Ops docs for connecting apps to shared services).

Artisan through Ops

With Ops, MariaDB and other services run in Docker. Your app’s PHP process must run in the same environment where .env (for example DB_HOST=mariadb) resolves correctly.

Use ops artisan, not php artisan, for any Artisan command that touches the database—migrations, seeders, db:*, queue:* when using the database driver, php artisan test against the real dev DB, and anything else that opens a DB connection. Running php artisan on the host can point at the wrong network or fail to reach the containerized database.

ops artisan <command>

Examples: ops artisan migrate, ops artisan db:seed, ops artisan tinker.

Commands that never touch the database may still work from the host with php artisan. This project’s phpunit.xml uses an in-memory SQLite database for PHPUnit, so php artisan test on the host often works without Ops; use ops artisan test if you need the runner (or DB) inside the app container.

`ops-commands.sh` helpers

This repo ships ops-commands.sh with shell helpers you can load from the project root:

source ops-commands.sh

Helper	What it does
`ops-install`	Ensures `.env` and `phpunit.xml` exist, creates a MariaDB database named from the Ops project (`ops project name`, with `-` → `_`), runs `composer install`, `npm install`, `npm run filament:build`, `npm run build`, symlinks `public/storage` if missing, then `ops artisan key:generate` and `ops artisan migrate:fresh --seed`.
`ops-artisan`	Wrapper around `ops shell php ./artisan`—useful if you prefer that execution path instead of `ops artisan`.
`ops-reset`	Runs `ops artisan migrate:fresh --seed` to wipe and reseed the database.

Load the file once per shell session (or add source to your profile for this project). ops-install is destructive to local data the first time you run it in an existing database because it uses migrate:fresh --seed.

What’s included

Laravel Sanctum (SPA / cookie sessions)

First-party SPA authentication uses stateful Sanctum: session cookies and CSRF, not bearer tokens for the default API surface described in openapi.yml.
bootstrap/app.php enables statefulApi() so API routes participate in the SPA cookie session.
Configure SANCTUM_STATEFUL_DOMAINS in .env so the browser origin (and tools like Bruno) match your app host—required for CSRF and session auth to work across your dev and production domains.

Filament admin panel

Default panel is mounted at /admin (App\Providers\Filament\AdminPanelProvider).
User management is scaffolded under app/Filament/Resources/Users/.
Only users with the admin role may access the panel (User::canAccessPanel).
stechstudio/filament-impersonate is included for user impersonation from the admin UI (configure per package docs as needed).

Roles and permissions (Spatie)

spatie/laravel-permission is installed and migrated.
Custom App\Models\Role defines constants such as admin and editor; seeders populate roles, permissions, and a starter user (see database/seeders/).
Gate::before in AppServiceProvider grants admins full authorization while keeping policy-based checks elsewhere—see AGENTS.md for the intended pattern.

imarc/fort

imarc/fort (“Safe API filtering & sorting for Laravel”) is required so list endpoints can share consistent, safe query filtering and sorting conventions as the API grows.

Vite and Vue 3

Vite drives the asset pipeline; the main SPA entry is resources/js/index.js (Vue 3 app mounted on the Blade shell).
Vue Router, Pinia, and @pinia/colada are included for routing and data layers.
Tailwind CSS v4 (via @tailwindcss/vite), Sass, ESLint, Stylelint, Prettier, and Vitest are present for styling and quality gates.
Imarc libraries @imarc/pronto and @imarc/vitrine are wired in package.json / vite.config.js for internal UI and dev tooling patterns.

The catch-all routes/web.php route returns the SPA shell view so client-side routing can own navigation.

OpenAPI (`openapi.yml`)

openapi.yml at the repository root describes the SPA Treatment API (OpenAPI 3). It documents session-based auth expectations and paths such as /api/auth/login and /api/auth/current-user.
Treat it as the contract for consumers: when you add or change endpoints, update this file (and tests) in the same change.

Bruno collection (`bruno/`)

A Bruno collection lives under bruno/, with opencollection.yml defining shared behavior (for example Referer handling for Sanctum stateful domains and CSRF cookie bootstrap).
Environment variables (for example host) should match your local or staging base URL so cookies and CSRF flow match the SPA.

Test suite

PHPUnit is configured via phpunit.xml with tests/Unit and tests/Feature, using an in-memory SQLite database and isolated env defaults for fast, repeatable runs.
Run the suite with:
```
php artisan test
```
or composer test (clears config cache first).
Vitest is available through Vite for front-end unit tests (vite.config.js includes a test block); add npm scripts as your team standardizes JS testing.

`AGENTS.md` (conventions for people and AI)

AGENTS.md is the canonical guide for workflows, structure, naming, API parity with the SPA, and quality checks (Pint, Psalm, tests, lint). Human contributors and coding agents should follow it so generated code matches project expectations.

Other notable dependencies

sentry/sentry-laravel — error monitoring (configure DSN and environment in .env when you enable Sentry).
Laravel Tinker, Collision, Pail, Pint, Psalm (with Laravel plugin) — debugging, style, and static analysis in development.

Configuration highlights

Copy .env.example to .env and adjust at least:

Variable	Purpose
`APP_URL`	Must match how users reach the app (affects URL generation and Sanctum).
`DB_*`	Database connection for migrations and the app.
`SESSION_DRIVER`	Example uses `database`; ensure the sessions table exists if you keep it.
`SANCTUM_STATEFUL_DOMAINS`	Comma-separated hosts that may receive Sanctum SPA cookies (include ports for local dev).
`VITE_APP_NAME`	Passed to the front end for display/branding.

For Filament assets in production, build the dedicated Vite config when needed:

npm run filament:build

Useful Composer scripts

Script	What it does
`composer setup`	Install deps, ensure `.env`, key, migrate, npm install, production `npm run build`
`composer dev`	Concurrently runs `php artisan serve`, queue worker, `pail`, and `npm run dev`
`composer test`	Clears config cache and runs `php artisan test`
`composer pint`	Laravel Pint (code style)
`composer psalm`	Psalm static analysis

Repository layout (orientation)

Area	Location
HTTP API routes	`routes/api.php`
Web / SPA shell	`routes/web.php`, `resources/views/index.blade.php`
Vue app	`resources/js/`
Styles	`resources/styles/`, `resources/css/`
Filament	`app/Filament/`, `app/Providers/Filament/`
Models & policies	`app/Models/`, `app/Policies/`
API contract	`openapi.yml`
Bruno requests	`bruno/`
PHPUnit tests	`tests/`

Imarc Ops–specific helpers live in ops-commands.sh (see Running with Imarc Ops).

Quality checklist (before you merge)

From AGENTS.md, the usual bar is:

composer pint
composer psalm
php artisan test
Front-end lint/build as your package.json scripts define (align scripts with AGENTS.md over time)

License

This starter is released under the MIT license (see composer.json).

Laravel itself is open-source software under the MIT license; see laravel.com for framework documentation.

imarc / spa-treatment

Maintainers

Package info

Statistics

Security

README

Requirements

Quick start

Running with Imarc Ops

Project hints in `.env`

Artisan through Ops

`ops-commands.sh` helpers

What’s included

Laravel Sanctum (SPA / cookie sessions)

Filament admin panel

Roles and permissions (Spatie)

imarc/fort

Vite and Vue 3

OpenAPI (`openapi.yml`)

Bruno collection (`bruno/`)

Test suite

`AGENTS.md` (conventions for people and AI)

Other notable dependencies

Configuration highlights

Useful Composer scripts

Repository layout (orientation)

Quality checklist (before you merge)

License

imarc / spa-treatment

Maintainers

Package info

Statistics

Security

README

Requirements

Quick start

Running with Imarc Ops

Project hints in .env

Artisan through Ops

ops-commands.sh helpers

What’s included

Laravel Sanctum (SPA / cookie sessions)

Filament admin panel

Roles and permissions (Spatie)

imarc/fort

Vite and Vue 3

OpenAPI (openapi.yml)

Bruno collection (bruno/)

Test suite

AGENTS.md (conventions for people and AI)

Other notable dependencies

Configuration highlights

Useful Composer scripts

Repository layout (orientation)

Quality checklist (before you merge)

License

Project hints in `.env`

`ops-commands.sh` helpers

OpenAPI (`openapi.yml`)

Bruno collection (`bruno/`)

`AGENTS.md` (conventions for people and AI)