OpenParable
Skip to content
← Back to skills

Model

Development
model

Model is an Agent Skill for development published in the JaguarJack/catch-admin repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Generate Eloquent model for CatchAdmin module with full CatchModel features.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/JaguarJack/catch-admin/blob/HEAD/.claude/skills/03-model/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/model, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

Step 3: Generate Model

创建 Eloquent 模型,继承 Catch\Base\CatchModel。

File Location

modules/{Module}/Models/{Model}.php

Complete Template

<?php

namespace Modules\{Module}\Models;

use Catch\Base\CatchModel as Model;
use Catch\Enums\Status;
use Illuminate\Database\Eloquent\Casts\Attribute;
use Illuminate\Database\Eloquent\Relations\BelongsTo;
use Illuminate\Database\Eloquent\Relations\BelongsToMany;
use Illuminate\Database\Eloquent\Relations\HasMany;

class {Model} extends Model
{
    protected $table = '{table}';

    protected $fillable = [
        'id',
        // business fields
        'creator_id',
        'created_at',
        'updated_at',
        'deleted_at',
    ];

    /**
     * 搜索字段配置
     * Operators: like, =, in, between
     */
    public array $searchable = [
        'name' => 'like',
        'status' => '=',
        'category_id' => '=',
    ];

    /**
     * 列表查询字段
     */
    protected array $fields = [
        'id', 'name', 'status', 'created_at'
    ];

    /**
     * 表单提交字段
     */
    protected array $form = [
        'name', 'status'
    ];

    /**
     * 表单关联同步 (多对多)
     */
    protected array $formRelations = ['roles', 'tags'];

    /**
     * 排序字段
     */
    protected string $sortField = 'sort';

    /**
     * 降序排序
     */
    protected bool $sortDesc = true;

    /**
     * 树形结构 (parent_id)
     */
    protected string $parentIdColumn = 'parent_id';

    /**
     * 是否返回树形结构
     */
    protected bool $asTree = false;

    // Relationships
    public function category(): BelongsTo
    {
        return $this->belongsTo(Category::class, 'category_id');
    }
}

CatchModel 核心属性

属性类型默认值说明
$fillablearray[]可填充字段
$searchablearray[]搜索字段及操作符
$fieldsarray['*']列表查询字段
$formarray[]表单提交字段
$formRelationsarray[]表单关联同步
$sortFieldstring''排序字段
$sortDescbooltrue是否降序
$parentIdColumnstring'parent_id'父级字段
$asTreeboolfalse返回树形结构
$isPaginatebooltrue是否分页
$dataRangeboolfalse数据权限
$isFillCreatorIdbooltrue自动填充创建人

CatchModel CRUD 方法

列表查询

// 基础列表 (自动分页、搜索、排序)
$this->model->getList();

// 自定义查询条件
$this->model->setBeforeGetList(function ($query) {
    return $query->where('type', 1);
})->getList();

// 禁用分页
$this->model->disablePaginate()->getList();

// 返回树形结构
$this->model->asTree()->getList();

创建记录

// 创建并返回 ID
$this->model->storeBy($data);

// 创建新实例
$this->model->createBy($data);

更新记录

// 更新单条
$this->model->updateBy($id, $data);

// 批量更新
$this->model->batchUpdate('id', [1, 2, 3], [
    'status' => [1, 2, 1],
]);

删除记录

// 软删除
$this->model->deleteBy($id);

// 强制删除
$this->model->deleteBy($id, force: true);

// 批量删除
$this->model->deletesBy('1,2,3');
$this->model->deletesBy([1, 2, 3]);

其他操作

// 查询单条
$this->model->firstBy($id);
$this->model->firstBy($value, 'field');

// 切换状态
$this->model->toggleBy($id);
$this->model->toggleBy($id, 'is_active');

// 恢复软删除
$this->model->restoreBy($id);
$this->model->restoreBy('1,2,3');

搜索操作符

public array $searchable = [
    'name' => 'like',      // LIKE '%value%'
    'title' => '%like',    // LIKE '%value'
    'code' => 'like%',     // LIKE 'value%'
    'status' => '=',       // = value
    'type' => 'in',        // IN (values)
    'created_at' => 'between', // BETWEEN start AND end
    'price' => '>',        // > value
    'stock' => '>=',       // >= value
];

关联关系

BelongsTo (多对一)

public function category(): BelongsTo
{
    return $this->belongsTo(Category::class, 'category_id');
}

public function creator(): BelongsTo
{
    return $this->belongsTo(\Modules\User\Models\User::class, 'creator_id');
}

HasMany (一对多)

public function items(): HasMany
{
    return $this->hasMany(OrderItem::class, 'order_id');
}

BelongsToMany (多对多)

// 需要在 $formRelations 中声明才能自动同步
protected array $formRelations = ['roles', 'tags'];

public function roles(): BelongsToMany
{
    return $this->belongsToMany(
        Role::class,
        'user_has_roles',  // pivot table
        'user_id',
        'role_id'
    );
}

public function tags(): BelongsToMany
{
    return $this->belongsToMany(Tag::class, 'product_tags');
}

树形关系 (自关联)

protected string $parentIdColumn = 'parent_id';

public function parent(): BelongsTo
{
    return $this->belongsTo(self::class, 'parent_id');
}

public function children(): HasMany
{
    return $this->hasMany(self::class, 'parent_id');
}

属性访问器 & 修改器

use Illuminate\Database\Eloquent\Casts\Attribute;

// 密码加密
protected function password(): Attribute
{
    return new Attribute(
        set: fn ($value) => bcrypt($value),
    );
}

// 状态标签
protected function statusLabel(): Attribute
{
    return new Attribute(
        get: fn () => $this->status == 1 ? '启用' : '禁用',
    );
}

// JSON 字段
protected function options(): Attribute
{
    return new Attribute(
        get: fn ($value) => json_decode($value, true) ?? [],
        set: fn ($value) => json_encode($value),
    );
}

状态枚举

use Catch\Enums\Status;

public function isEnabled(): bool
{
    return Status::Enable->assert($this->status);
}

public function isDisabled(): bool
{
    return Status::Disable->assert($this->status);
}

重写方法

自定义更新逻辑

public function updateBy($id, array $data): mixed
{
    // 密码为空时不更新
    if (empty($data['password'])) {
        unset($data['password']);
    }

    return parent::updateBy($id, $data);
}

自定义删除逻辑

public function deleteBy($id, bool $force = false, bool $softForce = false): ?bool
{
    return $this->transaction(function () use ($id) {
        // 删除关联数据
        $this->items()->where('order_id', $id)->delete();
        
        return parent::deleteBy($id);
    });
}

查询作用域

use Illuminate\Database\Eloquent\Builder;

public function scopeActive(Builder $query): Builder
{
    return $query->where('status', 1);
}

public function scopeOfType(Builder $query, int $type): Builder
{
    return $query->where('type', $type);
}

// 使用
Model::active()->ofType(1)->get();

关联预加载

// 在模型中定义默认预加载
protected $with = ['category'];

// 在控制器中
public function show($id): mixed
{
    return $this->model
        ->with(['category', 'tags'])
        ->firstBy($id);
}

外键字段自动检测规则

字段名关联方法关联模型
category_idcategory()Category::class
user_iduser()User::class
department_iddepartment()Departments::class
parent_idparent()self::class