---
title: "Рекомендуемый формат ресурса"
description: "Командный стиль Resource, разделение Form, Table и Infolist и границы авторизации"
canonical_url: "https://frame.qubeek.io/ru/developers/resources/patterns"
---
# Рекомендуемый формат ресурса

> Командный стиль Resource, разделение Form, Table и Infolist и границы авторизации

Используйте этот формат при создании и ревью ресурсов в команде. Это рекомендация по организации кода, а не дополнительное требование Frame. Небольшому ресурсу достаточно `fields()`; выносите схемы, когда таблица, форма и просмотр начинают различаться.

Примеры рассчитаны на API с `Frame\Laravel\Schemas\Form`, `Table` и `Infolist`. Проверьте наличие этих классов в установленном пакете: версия в checkout сама по себе не подтверждает состав опубликованного релиза.

## Минимальный ресурс

Для примера нужна таблица `posts` с первичным ключом `id`, строкой `title`, nullable-текстом `body` и timestamps. Миграцию создайте и примените средствами своего Laravel-приложения.

```php [app/Models/Post.php]
<?php

declare(strict_types=1);

namespace App\Models;

use Illuminate\Database\Eloquent\Model;

final class Post extends Model
{
    protected $guarded = [];
}
```

Ресурс описывает административный интерфейс модели. Не путайте его с Laravel `JsonResource`, который преобразует ответы API.

```php [app/Frame/Resources/PostResource.php]
<?php

declare(strict_types=1);

namespace App\Frame\Resources;

use App\Models\Post;
use Frame\Laravel\Fields\ID;
use Frame\Laravel\Fields\Text;
use Frame\Laravel\Fields\Textarea;
use Frame\Laravel\Resources\Resource;

final class PostResource extends Resource
{
    public static string $model = Post::class;

    public static string $title = 'title';

    public static function label(): string
    {
        return __('Публикации');
    }

    public function fields(): array
    {
        return [
            ID::make('id'),

            Text::make('title', 'Заголовок')
                ->required()
                ->rules(['string', 'max:255']),

            Textarea::make('body', 'Текст')->nullable(),
        ];
    }
}
```

Перед доступом пользователей настройте [авторизацию ресурса](https://frame.qubeek.io/ru/developers/resources/authorization). Этот пример не задаёт Policy и не ограничивает доступ по владельцу.

### Порядок внутри класса

Держите одинаковый порядок, чтобы при ревью быстро находить нужный участок:

1. Модель, заголовок записи и остальные статические свойства; ссылки на классы схем — рядом.
2. Идентичность и представление раздела: `name()`, если действительно нужен override, затем `label()` и `icon()`.
3. Запросы: `indexQuery()` и при необходимости `searchableQuery()`.
4. Поля: обязательный `fields()`, затем контекстные `fieldsFor*()`.
5. `actions(FrameRequest $request): Actions`, `cards(FrameRequest $request): array`, `lenses(FrameRequest $request): array`, если они нужны.
6. Переопределения доступа и lifecycle-хуки, затем `protected setUp(Options $options): void` и приватные помощники.

Не добавляйте пустые переопределения ради этого списка. `fields()` возвращает массив полей и `Panel`, а не коллекцию и не объект Form. Для правил полей договоритесь использовать массив: `->rules(['string', 'max:255'])`.

### Имя, подпись и идентификатор

Разделяйте четыре значения:

<table>
<thead>
  <tr>
    <th>
      Значение
    </th>
    
    <th>
      Пример
    </th>
    
    <th>
      Назначение
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        $model
      </code>
    </td>
    
    <td>
      <code>
        Post::class
      </code>
    </td>
    
    <td>
      Eloquent-модель
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        name()
      </code>
    </td>
    
    <td>
      <code>
        posts
      </code>
    </td>
    
    <td>
      Машинный ключ зарегистрированного ресурса; по умолчанию выводится из имени класса
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        label()
      </code>
    </td>
    
    <td>
      <code>
        Публикации
      </code>
    </td>
    
    <td>
      Подпись раздела в интерфейсе
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        $title
      </code>
      
       / <code>
        getTitle()
      </code>
    </td>
    
    <td>
      <code>
        title
      </code>
      
       / значение заголовка
    </td>
    
    <td>
      Название конкретной записи, в том числе в выборе связей
    </td>
  </tr>
</tbody>
</table>

Первичный ключ берётся из модели; `ID::make('id')` соответствует стандартному ключу примера. `$title` не меняет первичный ключ. Для перевода раздела меняйте `label()`, а не `name()`: смена машинного ключа затрагивает маршруты и ссылки на ресурс. У полей первый аргумент — атрибут или имя отношения, второй у обычных полей — подпись. У [отношений](https://frame.qubeek.io/ru/developers/fields/relationships) второй аргумент занят классом ресурса.

## Запросы и eager loading

Добавляйте условия к `parent::indexQuery()`, а не начинайте новый несвязанный запрос. Например, после добавления колонки `is_published` можно ограничить этот раздел опубликованными записями:

```php [app/Frame/Resources/PostResource.php]
use Illuminate\Database\Eloquent\Builder;
use Illuminate\Database\Eloquent\Relations\Relation;

public static function indexQuery(): Builder|Relation
{
    return parent::indexQuery()->where('is_published', true);
}
```

Это фрагмент для существующего класса. Не добавляйте `withoutGlobalScopes()` в такой override как способ «починить» выборку. При этом не рассчитывайте на автоматическое сохранение всех model scopes: текущий `QueriesResources::createIndexQuery()` сам снимает global scopes, а запрос через отношение строится отдельной веткой. Явное условие `where()` и model global scope — разные механизмы.

После определения Eloquent-отношения `author()` добавьте `public static array $with = ['author'];`, если заголовки или вычисляемые поля читают автора. `HasOne`/`BelongsTo` также добавляют eager loading в своём query callback, а `HasMany` — `withCount()`. Это не обещает отсутствия N+1 в произвольном `resolveUsing()` или в собственном запросе.

`indexQuery()` не является универсальным tenant-фильтром для всех endpoint. Настройте tenancy в приложении и отдельно проверьте список, просмотр, поиск связей, изменение и создание через родителя. `viewAny()` также не добавляет SQL-условие владельца.

По умолчанию `searchableQuery()` вызывает `indexQuery()`. Если выборка зависит от текущего пользователя, определите отдельно, какие записи должен получать индексатор без HTTP-пользователя. Не переносите пользовательский фильтр в глобальный индекс без проверки этого сценария.

## Когда выносить классы схем

Переносите один контекст за раз. Формат ниже заменяет минимальный ресурс и добавляет три отдельных файла. В модели и таблице остаются те же `id`, `title` и nullable `body`.

```php [app/Frame/Resources/PostResource.php]
<?php

declare(strict_types=1);

namespace App\Frame\Resources;

use App\Frame\Schemas\PostForm;
use App\Frame\Schemas\PostInfolist;
use App\Frame\Schemas\PostTable;
use App\Models\Post;
use Frame\Laravel\Fields\ID;
use Frame\Laravel\Fields\Text;
use Frame\Laravel\Fields\Textarea;
use Frame\Laravel\Resources\Resource;

final class PostResource extends Resource
{
    public static string $model = Post::class;

    public static string $title = 'title';

    public static ?string $form = PostForm::class;

    public static ?string $table = PostTable::class;

    public static ?string $infolist = PostInfolist::class;

    public static function label(): string
    {
        return __('Публикации');
    }

    public function fields(): array
    {
        return [
            ID::make('id'),
            Text::make('title', 'Заголовок')
                ->required()
                ->rules(['string', 'max:255']),
            Textarea::make('body', 'Текст')->nullable(),
        ];
    }
}
```

`Resource::fields(): array` — абстрактный метод. Он обязателен и при трёх объявленных схемах. Сохраняйте в нём осмысленный базовый набор: он нужен не только как запасной интерфейс. В текущей реализации `getGlobalFields()` собирает поля из legacy-методов ресурса, не из классов схем. Отношения, используемые сервером через `viaRelationship`, оставляйте доступными базовому набору ресурса, а не только классам схем.

### Form

Схема формы определяет поля создания и изменения, а также их серверную валидацию. В отличие от `Resource::fields()`, её `fields()` принимает `FrameRequest`.

```php [app/Frame/Schemas/PostForm.php]
<?php

declare(strict_types=1);

namespace App\Frame\Schemas;

use Frame\Laravel\Fields\Text;
use Frame\Laravel\Fields\Textarea;
use Frame\Laravel\Http\Requests\FrameRequest;
use Frame\Laravel\Schemas\Form;

final class PostForm extends Form
{
    public function fields(FrameRequest $request): array
    {
        return [
            Text::make('title', 'Заголовок')
                ->required()
                ->rules(['string', 'max:255']),

            Textarea::make('body', 'Текст')->nullable(),
        ];
    }
}
```

Для различий создания и изменения переопределяйте методы схемы с точными сигнатурами `public function fieldsForCreate(FrameRequest $request): array` и `public function fieldsForUpdate(FrameRequest $request): array`. По умолчанию оба вызывают `$this->fields($request)`. Правила уникальности при изменении должны учитывать текущую модель; не копируйте `unique` создания без исключения редактируемой записи.

Дополнительный API Form:

<table>
<thead>
  <tr>
    <th>
      Метод
    </th>
    
    <th>
      Контракт
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        public function layout(): FormLayout
      </code>
    </td>
    
    <td>
      Enum <code>
        Frame\Laravel\Enums\FormLayout
      </code>
      
      ; по умолчанию <code>
        STACKED
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        public function rules(FrameRequest $request): array
      </code>
    </td>
    
    <td>
      Правила уровня формы: имя поля → массив правил
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        public function messages(FrameRequest $request): array
      </code>
    </td>
    
    <td>
      Сообщения: ключ <code>
        field.rule
      </code>
      
       → строка
    </td>
  </tr>
</tbody>
</table>

`rules()` формы дополняет правила полей при создании и изменении. Это другой API, чем fluent-вызов `rules()` у поля. Раскладка, панели и wizard описаны в разделе [Формы](https://frame.qubeek.io/ru/developers/resources/forms).

### Table

Вынесите колонки списка отдельно от редактируемых полей. Не добавляйте правила ввода в Table в расчёте на валидацию формы.

```php [app/Frame/Schemas/PostTable.php]
<?php

declare(strict_types=1);

namespace App\Frame\Schemas;

use Frame\Laravel\Fields\ID;
use Frame\Laravel\Fields\Text;
use Frame\Laravel\Http\Requests\FrameRequest;
use Frame\Laravel\Schemas\Table;

final class PostTable extends Table
{
    public function fields(FrameRequest $request): array
    {
        return [
            ID::make('id'),
            Text::make('title', 'Заголовок')->sortable(),
        ];
    }
}
```

### Infolist

Вынесите состав страницы просмотра. Infolist не заменяет Policy и не запрещает изменение через другой endpoint.

```php [app/Frame/Schemas/PostInfolist.php]
<?php

declare(strict_types=1);

namespace App\Frame\Schemas;

use Frame\Laravel\Fields\Panel;
use Frame\Laravel\Fields\Text;
use Frame\Laravel\Fields\Textarea;
use Frame\Laravel\Http\Requests\FrameRequest;
use Frame\Laravel\Schemas\Infolist;

final class PostInfolist extends Infolist
{
    public function fields(FrameRequest $request): array
    {
        return [
            Panel::make('Публикация', [
                Text::make('title', 'Заголовок'),
                Textarea::make('body', 'Текст'),
            ]),
        ];
    }
}
```

### Постепенный переход

Каждое статическое свойство независимо. Необъявленное свойство или значение `null` оставляет legacy-путь:

<table>
<thead>
  <tr>
    <th>
      Контекст
    </th>
    
    <th>
      При объявленной схеме
    </th>
    
    <th>
      Без схемы
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      Создание
    </td>
    
    <td>
      <code>
        Form::fieldsForCreate($request)
      </code>
    </td>
    
    <td>
      <code>
        Resource::fieldsForCreate()
      </code>
      
       либо <code>
        fields()
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      Изменение
    </td>
    
    <td>
      <code>
        Form::fieldsForUpdate($request)
      </code>
    </td>
    
    <td>
      <code>
        Resource::fieldsForUpdate()
      </code>
      
       либо <code>
        fields()
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      Список
    </td>
    
    <td>
      <code>
        Table::fields($request)
      </code>
    </td>
    
    <td>
      <code>
        Resource::fieldsForIndex()
      </code>
      
       либо <code>
        fields()
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      Просмотр
    </td>
    
    <td>
      <code>
        Infolist::fields($request)
      </code>
    </td>
    
    <td>
      <code>
        Resource::fieldsForDetail()
      </code>
      
       либо <code>
        fields()
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      Экспорт
    </td>
    
    <td>
      Отдельного <code>
        $export
      </code>
      
      -класса здесь нет
    </td>
    
    <td>
      <code>
        Resource::fieldsForExport()
      </code>
      
       либо <code>
        fields()
      </code>
    </td>
  </tr>
</tbody>
</table>

Пустой массив из схемы не запускает fallback. В legacy-selector есть особенность: `fieldsForDetail()` проверяется раньше `fieldsForCreate()` / `fieldsForUpdate()`. Запрос формы, который одновременно является `ResourceDetailRequest`, может попасть в `fieldsForDetail()`, если он определён. Для объявленного Form приоритет другой: сначала создание/изменение, затем detail. Проверьте и показ формы, и POST, если оставляете несколько legacy-наборов.

Пользовательская Lens, в отличие от DefaultLens, переопределяет набор полей. При миграции проверьте её отдельно. Legacy-методы `fieldsFor*()` оставляйте вызываемыми без обязательных аргументов: `getGlobalFields()` обращается к ним без request.

## Обязательность и nullable

У поля `required()` и `rules()` участвуют в серверных правилах и сериализации формы. Сигнатуры: `required(bool|callable $callback = true)` и `rules(callable|array|string ...$rules)`. И массив, и `->rules('required')` поддерживаются; массив — выбранный здесь командный стиль.

`required()` вычисляет обязательность для запроса. В ответе формы есть `required`, `readonly`, `nullable` и, для поддерживаемых правил, `validation`. Сервер остаётся источником решения: клиент не исполняет безопасно все Laravel Rule и callback.

`nullable()` задаёт метаданные поля, но не меняет nullable-колонку в БД. Сборщик `getRules()` отдельно добавляет `required` или `nullable` на основании `isRequired()`. Согласуйте миграцию, модель и правила; одного `->nullable()` недостаточно для снятия ограничения `NOT NULL`.

Создание валидирует набор полей формы. При update текущий request выбирает для полевых правил только ключи, присутствующие во входных данных; правила уровня Form добавляются отдельно. Поэтому обязательность на создании не является обещанием запрета любого частичного update. Если сценарии различаются, задайте их через `fieldsForCreate()` / `fieldsForUpdate()` и проверьте оба запроса.

## Опции, действия и права

Опции интерфейса настраивайте в `setUp()`, а не в конструкторе. Frame сначала создаёт defaults в `initializeResourceOptions()`, затем вызывает `setUp($options)`. Не рассчитывайте, что `$this->options` уже заполнено в произвольном экземпляре ресурса или в `fields()`.

```php [app/Frame/Resources/PostResource.php]
use Frame\Laravel\Options\Options;

protected function setUp(Options $options): void
{
    $options->pagination->perPage(25);
}
```

Действия определяйте методом `public function actions(FrameRequest $request): Actions` с импортом `Frame\Laravel\Options\Actions`. Если override возвращает новый `Actions::make()`, он заменяет набор родителя, включая стандартные действия. Не копируйте пустой набор из read-only журнала в обычный CRUD-ресурс. Обработчик действия должен проверять допустимость своей операции на сервере; наличие кнопки не выдаёт право на запись.

Policy задаёт права на модель, Resource координирует запросы и операции, схемы описывают поля. `hideOnIndex()`, скрытая навигация, Infolist и карточка просмотра не заменяют авторизацию. Не добавляйте вымышленный `Resource::resourceCard()`: состав просмотра задаёт `$infolist`, а карточки дашборда подключаются через отдельный API [просмотра записи](https://frame.qubeek.io/ru/developers/resources/infolist).

Ресурс журнала событий из optional-модуля — специализированный пример: он запрещает создание, изменение и удаление и убирает действия. Это не универсальная заготовка. Без Policy Frame сохраняет штатное поведение no-policy; этот формат не вводит strict-default. Настройте ограничения явно по странице [Авторизация ресурса](https://frame.qubeek.io/ru/developers/resources/authorization).

## Генератор и проверка перед ревью

Базовая команда создаёт ресурс из стаба; классы схем из примера создайте отдельно:

```shell
php artisan frame:resource PostResource
```

В текущем `CreateResourceCommand` есть булев флаг `--m`, который выводит модель из имени ресурса. Не считайте его параметром `--model=...` или генератором Form/Table/Infolist. Проверьте получившиеся `$model` и `$title`; пользовательский `stubs/Resource.stub` в приложении может заменить пакетный шаблон.

Перед ревью проверьте:

- `fields(): array` есть, даже если все три схемы объявлены; импорты схем соответствуют файлам.
- Имя отношения совпадает с Eloquent-методом, второй аргумент поля — класс Resource, а не модель.
- Создание и изменение валидируют нужные поля, включая пустые значения и частичный update.
- Запросы не полагаются на скрытую кнопку или на автоматическое tenant/global-scope ограничение всех веток.
- Запреты Policy и read-only проверены прямыми серверными запросами; успешный рендер схемы этого не доказывает.

## Что дальше

- [Отношения](https://frame.qubeek.io/ru/developers/fields/relationships) — сопоставьте Eloquent-методы, ресурсы и контекст родителя.
- [Авторизация ресурса](https://frame.qubeek.io/ru/developers/resources/authorization) — настройте Policy без изменения no-policy default.
- [Метрики](https://frame.qubeek.io/ru/developers/functions/metrics) — подключите показатели без переноса их реализации в Resource.
- [Пользовательские поля](https://frame.qubeek.io/ru/developers/fields/custom) — расширьте типы полей.
- [Slug](https://frame.qubeek.io/ru/developers/fields/slug) — настройте адрес записи по отдельному руководству.


## Sitemap

See the full [sitemap](https://frame.qubeek.io/sitemap.md) for all pages.
