> For the complete documentation index, see [llms.txt](https://vladimirkostikov.gitbook.io/laraboom/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://vladimirkostikov.gitbook.io/laraboom/getting-started/03-host.md).

# 3. Host and App

A host is a runnable application built on `laraboom/core`. In the monorepo the hosts are `apps`, `demos/shop`, `demos/blog`.

## Host directory map

```
apps/
  app/
    App.php              # extends Boom: through, share, Run, Every
    Resources/           # data entities
    Routes/              # Path classes (pages and form actions)
  web/
    index.php            # HTTP entry, Host::boot
    views/               # Blade
    css/ js/             # static files
  boom                   # CLI entry
  system/                # runtime: cache, logs, compiled views
  storage/               # public and private application files
  composer.json
  tests/
  .env
```

There is no `routes/web.php`. No `app/Http/Controllers`. No host `database/migrations` for Resource fields. The schema comes from `fields()`.

## Entry points

### HTTP

`web/index.php` boots the application through `LaraBoom\Host::boot` and hands the request to the Laravel kernel.

The web server document root is always `{host}/web`.

### CLI

```bash
php boom help
php boom doctor
```

The `boom` file sits in the host root. Commands are handled by `LaraBoom\Console\BoomKernel`. There are aliases. `key` is `key:generate`, `tinker` is `shell`.

## The App class

Every host declares `App\App extends LaraBoom\Definition\Boom`.

An example from `apps/app/App.php`:

```php
namespace App;

use App\Resources\Demo;
use LaraBoom\Attributes\Every;
use LaraBoom\Attributes\Run;
use LaraBoom\Definition\Boom;
use function LaraBoom\Author\note;

final class App extends Boom
{
    public function through(): array
    {
        return [
            'auth' => 'auth',
            'guest' => 'guest',
        ];
    }

    public function share(): array
    {
        return [
            'app' => config('app.name', 'LaraBoom'),
            'demo_name' => 'LaraBoom Demo',
            'user' => fn () => auth()->user(),
        ];
    }

    #[Every('hourly')]
    public function pulseDemos(): void
    {
        $active = app(Demo::class)->query()->where('status', 'active')->count();
        note('demo.hourly', ['active' => $active]);
    }

    #[Run('demo:pulse', about: 'Count active demo rows')]
    public function pulse(): string
    {
        $active = app(Demo::class)->query()->where('status', 'active')->count();
        $total = app(Demo::class)->query()->count();

        return "demos_active={$active} demos_total={$total}";
    }
}
```

### through() and middleware aliases

The key is a short name. The value is a Laravel middleware alias or a class.

On a Path and on custom Resource routes:

```php
#[Get('/account', name: 'demo.account', only: 'auth')]
```

`only: 'auth'` is resolved through `through()`. You can pass an array. Look at the current Path in Demo.

### share() for Blade and boom()

Values from `share()` are available in all Blade templates (a View composer) and through the `boom('demo_name')` helper.

Closures are evaluated lazily. That is how `user` works in the example.

### exceptions() if you want it

The base `Boom` lets you configure `Illuminate\Foundation\Configuration\Exceptions`. Override it when you need custom render or report.

## Discovery

On boot `LaraBoomServiceProvider`:

1. scans `app/Resources` for Resources
2. scans `app/Routes` for Paths
3. registers Gates from `#[Allow]`
4. attaches the `/api/{resource}` CRUD
5. registers Path routes
6. wires up `#[Run]` and `#[Every]` from App and the entities

Class names follow PSR-4. The `App\` namespace maps to the `app/` directory.

## Host composer

The key parts of `apps/composer.json`:

```json
{
  "name": "laraboom/apps",
  "repositories": [
    {
      "type": "path",
      "url": "../packages/laraboom",
      "options": { "symlink": true }
    }
  ],
  "require": {
    "php": "^8.3",
    "laravel/framework": "^13.8",
    "laraboom/core": "@dev"
  },
  "autoload": {
    "psr-4": { "App\\": "app/" }
  },
  "scripts": {
    "setup": [
      "composer install",
      "@php -r \"file_exists('.env') || copy('.env.example', '.env');\"",
      "@php boom install --fresh"
    ],
    "test": "phpunit"
  }
}
```

The package auto registers `LaraBoomServiceProvider` through Composer extra.

## Runtime directories

`system/` is the framework service storage (cache, logs, compiled views). Do not put author code there.

`storage/public` and `storage/private` hold user files. `Upload` fields usually write to the `public` disk.

## Host environment variables

The minimum is the same as Laravel. You need `APP_KEY`, `APP_URL`, the `DB_*` block, `MAIL_*`, the queue. The exact keys live in the `.env.example` of the specific host.

Remember the difference in `DB_HOST` between Docker and the Mac. See [installation](/laraboom/getting-started/02-installation.md).

## Mini checklist for a new host

1. Copy the skeleton from `demos/blog` or `apps`.
2. Fix the `composer.json` path to the package.
3. Write `app/App.php` with `through()` and `share()`.
4. Add at least one Resource with `#[Migrate]` and one Path with `#[Get('/')]`.
5. Run `composer setup`, open `/`, hit `/api/{resource}`.

Next up is [Resources](/laraboom/data-model/04-resources.md).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://vladimirkostikov.gitbook.io/laraboom/getting-started/03-host.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.