> 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/01-introduction.md). # 1. Introduction ## What problem this solves Laravel is a strong runtime. Eloquent, Blade, queues, validation, and Sanctum stay. The pain is not the framework. The pain is how a typical app spreads one business entity across many files. For a single `Product` you often end up with: ``` app/Models/Product.php database/migrations/xxxx_create_products_table.php app/Http/Controllers/ProductController.php app/Http/Requests/StoreProductRequest.php app/Http/Requests/UpdateProductRequest.php app/Policies/ProductPolicy.php app/Http/Resources/ProductResource.php routes/api.php app/Jobs/... app/Mail/... app/Events/... app/Listeners/... ``` That is ten or more files for one noun. Rename a column: migration, model, FormRequest, API Resource, maybe the policy. Add a filter: controller, scope, routes. An assistant asked to add `featured` must align a pile of files that all describe the same thing differently. LaraBoom cuts the files you write. You describe the entity once: fields and PHP 8 attributes. The package runtime does schema sync, JSON CRUD at `/api/{resource}`, filters, gates, and side effects. Laravel stays. You are not rewriting Laravel. You stop cloning Laravel folder trees for every feature. ## Core idea **Resource** - data and JSON API. Fields define columns and validation. Attributes define migrate, allow, scope, hooks, job, mail, broadcast. **Path** - web pages. Methods with `#[Get]` / `#[Post]` return Blade, redirects, forms. Middleware aliases from `App::through()`. Host **App** extends `Boom`: middleware, view share, schedule, custom `php boom` commands. Reference in the repo: * `apps/app/Resources/Demo.php` * `apps/app/Routes/Demo.php` * `apps/app/App.php` * [`../agents.md`](https://github.com/VladimirKostikov/LaraBoom/tree/main/docs/agents.md) ## Comparison with plain Laravel | Task | Laravel | LaraBoom | | --------------------- | ----------------------------- | ------------------------------------------- | | Table | migration | `fields()` + `#[Migrate]` + `php boom sync` | | Rename column | new migration + string hunt | `Text('title')->was('name')` then sync | | CRUD API | controller + routes | `/api/{resource}` automatically | | Validation | FormRequest | field rules + `#[Check]` | | Permissions | Policy + Gate | `#[Allow]` | | List with filters | scope + query params by hand | `->filter()`, `->sort()`, `#[Filter]` | | Eager load | `with()` in the controller | `#[With('category')]` | | Soft delete | trait + migration | `#[Migrate(softDeletes: true)]` | | Pages | `routes/web.php` + controller | Path + `#[Get]` / `#[Post]` | | Rate limit | middleware on a group | `#[Throttle(60, 1)]` | | Transaction | `DB::transaction` | `#[Atomic]` | | Job / Mail | separate classes | methods with `#[Job]` / `#[Mail]` | | Event / listener | Event + Listener | `fire(...)` + `#[On('evt')]` | | Middleware on a route | group in routes | `only:` + `App::through()` | Eloquent, Blade, Sanctum, the queue, the cache, and the validator stay your tools. ## Tokens and AI assistants What you pay for with an assistant is mostly **input context and output diff**, not prompt wording. In Laravel a feature change often pulls many files into context. In LaraBoom the same change usually fits in a Resource and, if needed, a Path. In practice: 1. Fewer files in context (often 1-2 instead of 6-10). 2. Smaller diffs and less review noise. 3. One style reference: `Demo`, not scattered Laravel habits. 4. Prompts do not need "add FormRequest, Policy, migration, apiResource". The runtime already owns that scaffold. 5. The same win for humans: the repo is easier to read. Token meters just make the cost visible. Rough scale for a medium feature (field + filter + gate + optional job): | | Laravel | LaraBoom | | --------------- | ------------------- | ---------------------------- | | Files touched | 5-10 | 1-2 | | Context | large | small | | Typical mistake | drift between files | wrong attribute on one class | ## Two HTTP worlds 1. JSON API always under `/api`. CRUD and custom Resource actions. 2. Web through Path. Blade, sessions, redirects, forms. One Resource can feed both worlds. A Path injects the Resource and calls `query()`. ## Resource in a nutshell ```php #[Migrate(softDeletes: true)] #[Allow('index', true)] #[Allow('store', 'auth')] final class Product extends Resource { public function fields(): array { return [ Text('title', needed: true, max: 255)->sort()->filter(), Money('price')->sort()->filter(), ]; } } ``` After `php boom sync` the `products` table appears. After boot you get: * `GET /api/products` * `POST /api/products` * `GET /api/products/{id}` * `PUT|PATCH /api/products/{id}` * `DELETE /api/products/{id}` Resource and table name: plural snake of the class name. Class `Demo` gives resource `demos`. Gate: `demos.{action}`. ## Path in a nutshell ```php final class Shop extends Path { #[Get('/', name: 'shop.home')] public function home(): mixed { return view('shop.home'); } } ``` Views live in `{host}/web/views`. Public entry point: `{host}/web/index.php`. ## Host::boot The host does not use standard `bootstrap/app.php`. The package boots Laravel through `LaraBoom\Host::boot($basePath)`. * HTTP goes through `web/index.php` * CLI: the `boom` file in the host root and commands `php boom ...` ## Why the shape is like this 1. Attributes over class hierarchies. Do not invent Policy / FormRequest / Job trees just because stock Laravel looks that way. 2. Logic next to the Resource or Path (`Resources/X/Service.php` when a method grows), not in a shared `app/Services`. 3. No Laravel-clone folders in the host as the place you write features. Jobs and Mail start as entity methods. 4. Schema from code. A column comes from a field. Rename with `->was('old')`. 5. Demo is the source of truth for attribute APIs: `apps/app/Resources/Demo.php`. ## Versions and requirements * PHP `^8.3` * Laravel `^13` * MySQL 8.4 in the Docker stack (tests often use SQLite `:memory:`) The `laraboom/core` package is wired as a path repository: * from `apps`: `"url": "../packages/laraboom"` * from `demos/*`: `"url": "../../packages/laraboom"` ## How this documentation is organized Chapters go from zero to practice: installation and host, data and schema, HTTP, side effects and CLI, tests and demos. Source of truth for the text: `docs/ru/`. Other locales are translations. Edit Russian first. --- # 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/01-introduction.md?ask=&goal= ``` `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.