Bagisto Agent Skills: Bagisto development

---
name: bagisto-coding-standards
description: Use when writing, changing or reviewing any Bagisto PHP or Blade — the conventions this codebase holds to, covering Laravel idiom, code style, comments and docblocks, database access, Blade, security and localization. Trigger phrases include "standards", "conventions", "code style", "docblock", "comments", "repository pattern", "blade", "component", "binding", "event", "migration", "security", "XSS", "authorization", "escaping", "is this safe", "best practice".
license: MIT
---

# Coding Standards

The canonical rules for all Bagisto code, in one place, so a change to a
DataGrid, a payment class or a theme is held to the same bar as a change to a
package.

**Pint decides the mechanical questions.** Run `vendor/bin/pint` and trust it for
spacing, import order, trailing commas and the rest. What follows is what Pint
cannot see — and what a reviewer will otherwise send back.

## Reference files

| File | Load when |
|---|---|
| [code-style.md](code-style.md) | Writing any PHP — multi-clause conditions, class member order |
| [comments.md](comments.md) | Any comment or docblock, in any language |
| [laravel.md](laravel.md) | Framework idiom — events, migrations, config, helpers, validation, queues |
| [data-access.md](data-access.md) | Reading or writing the database — the repository rule and its one exception |
| [database-compatibility.md](database-compatibility.md) | Any query, migration or raw SQL — MySQL, MariaDB and PostgreSQL all have to pass |
| [security.md](security.md) | Output, input, uploads, SQL, secrets, payments |
| [security-authorization.md](security-authorization.md) | Routes, permissions, guards, one user's access to another's data |
| [blade.md](blade.md) | Any `.blade.php` — namespaces, `:` versus `::`, components, page skeleton |
| [blade-formatting.md](blade-formatting.md) | Indentation, attribute layout, `@props` alignment, recipes |
| [localization.md](localization.md) | Any user-facing string, or a `Resources/lang/` change |

The PHP rules apply inside an `@php` block too, which Pint cannot reach.

## The rules in one screen

- **Every method and property carries a docblock**, whatever its visibility. The
  description is a capitalised sentence ending in a full stop, and it is **at most
  two lines**. Type information belongs in the signature; add `@param`/`@return`
  only for what a native type cannot express.
- **Class members run constants → properties → constructor → public →
  protected → private**, each visibility one contiguous block. A helper called
  by a public method still lives in the protected block at the bottom.
- **A condition with more than one clause goes multiline**, the boolean operator
  leading each line. Single-clause conditions stay inline. The rule keys off the
  number of clauses, not the line length.