Directory structure

On this page

Introduction
The root
The app directory
Where to put new things

Introduction

The skeleton is small on purpose: every file in it is one you will open. Your own and package plugins and route and command files are named in app.php; the core framework plugins are registered by default and the optional ones, such as the queue's, listed there too, and configuration files and migrations are found inside their configured folders.

The root

app.php             describes the application: plugins, middleware, routes
cua                 the command line: php cua <command>

routes/
  web.php           HTTP routes
  console.php       your own commands

app/
  Actions/          what the application does: classes with handle()
  Plugins/        where your services are bound

config/
  app.php           name, debug
  cache.php         store, application-specific cache directory
  database.php      which database, and where the migrations are
  log.php           where and how much to log
  server.php        address, worker count, what to watch, where the pid and log go

database/
  migrations/       changes to the tables, in order

storage/            what the application writes while it runs: logs, the SQLite file
tests/              tests that call the application without a server
.env                settings for this machine

storage/ and .env are never committed. Nothing the application needs in order to start lives in storage/.

storage/ is where the application writes: logs, the server's process id file and stats, the file cache, the local disk and a SQLite file. A relative path starting with storage/ in a setting, such as log.path, is inside it, and storage_path('database.sqlite') names a file in it from a configuration file. Move it with ->withStorage('/var/lib/shop') in app.php, or the CRAB_STORAGE environment variable, which a relative path follows from the working directory; everything the framework writes follows. See Storage elsewhere.

Everything begins in app.php:

// app.php
use App\Setup;
use Crab\App;

return App::configure(__DIR__)
    ->withSetup(Setup::class)
    ->withRouting(
        routes: 'routes/web.php',
        commands: 'routes/console.php',
        health: '/up',
    )
    ->create();

__DIR__ is the application's base path. The .env file and the config/ folder are loaded from it, and every other path is relative to it. Configuration describes each step of the chain.

The app directory

app/ is your code, under the App\ namespace. It starts with two folders:

Folder	Holds
`app/Actions/`	Classes that answer routes. See Actions.
`app/Setup.php`	Where you bind your own services, add listeners and schedule tasks. See Your application's setup.

Where to put new things

The framework does not look for folders, so these are suggestions that keep applications alike. php cua make:middleware, php cua make:command and php cua make:migration write into the folders shown.

You are adding	Put it in	Then
A route	`routes/web.php`	Nothing; it is loaded by `app.php`
An action class	`app/Actions/`	Name it in the route
Middleware	`app/Http/`	Name it on a route, a group or in `app.php`
A command	`routes/console.php`, or a class in `app/Console/`	Register it with `Command::add('area:action', YourCommand::class)` in `routes/console.php`, then `php cua area:action`
A queue job	`app/Actions/`	Push it with the queue
An event and its listeners	`app/Events/`, and the listeners in `app/Actions/`	Add the listener in `app/Setup.php`
A scheduled task	`app/Setup.php`	Declare it on the schedule
A setting	A file in `config/`, read from `.env`	`config('file.key')`
A table	`php cua make:migration create_posts_table`	`php cua migrate`
A second routes file	`routes/api.php`	Add it to `routes:` in `app.php`