bagisto-package-development

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Package Development in Bagisto

Bagisto包开发

A Bagisto package is a self-contained Laravel module under

packages/Webkul/<Name>/

with its own models, controllers, routes, views, migrations and providers. All 41 core packages follow one shape — copy the closest existing package rather than scaffolding a generic Laravel one.

Bagisto包是位于

packages/Webkul/<Name>/

下的独立Laravel模块，拥有自己的模型、控制器、路由、视图、迁移和提供者。所有41个核心包都遵循统一的结构——复制最接近的现有包，而不是搭建通用的Laravel模块。

Reference files — load only what the current task needs

参考文件——仅加载当前任务所需的文件

File	Load when
core.md	Creating a package — directory layout, `composer.json` , providers, Concord registration
data-layer.md	Migrations, models, contracts, proxies, repositories
ui.md	Routes, controllers, Blade views
features.md	Admin menus, ACL, system configuration

文件	加载时机
core.md	创建包时——目录结构、 `composer.json` 、提供者、Concord注册
data-layer.md	涉及迁移、模型、契约、代理、仓库时
ui.md	涉及路由、控制器、Blade视图时
features.md	涉及后台菜单、ACL、系统配置时

The shape of a package

包的结构

packages/Webkul/<Name>/src/
├── Config/           # system.php, admin-menu.php, acl.php
├── Contracts/        # one interface per model
├── Database/         # Migrations/, Seeders/, Factories/
├── DataGrids/        # admin listings
├── Http/Controllers/ # separate Admin/ and Shop/
├── Models/           # Eloquent models + Proxy classes
├── Providers/        # <Name>ServiceProvider + ModuleServiceProvider
├── Repositories/     # all database access
├── Resources/        # views/, lang/{22 locales}/, assets/
└── Routes/           # admin-routes.php, shop-routes.php

packages/Webkul/<Name>/src/
├── Config/           # system.php, admin-menu.php, acl.php
├── Contracts/        # 每个模型对应一个接口
├── Database/         # Migrations/, Seeders/, Factories/
├── DataGrids/        # 后台列表
├── Http/Controllers/ # 分为Admin/和Shop/目录
├── Models/           # Eloquent模型 + 代理类
├── Providers/        # <Name>ServiceProvider + ModuleServiceProvider
├── Repositories/     # 所有数据库操作
├── Resources/        # views/, lang/{22 locales}/, assets/
└── Routes/           # admin-routes.php, shop-routes.php

The rules that are not negotiable

不可协商的规则

Dual registration. Every package registers twice: its main
```
ServiceProvider
```
in
```
bootstrap/providers.php
```
, and its
```
ModuleServiceProvider
```
in
```
config/concord.php
```
. Miss either and the package half-loads in a way that is hard to diagnose. See core.md.
Three-part models. Every entity is a Contract, a Model implementing it, and a Proxy. Repositories return the Contract from
```
model()
```
, and cross-package type hints use the Proxy — that is what makes a model replaceable without editing core. See data-layer.md.
Docblocks, member order, comments, the repository rule and translations are owned by the bagisto-coding-standards
skill. They apply to every Bagisto file, not only to a package, and they are the most common review rejection.
Fix what you touch. A pre-existing violation in a file you edit is yours: scan the whole class's member order and docblocks, not just your own lines.

双重注册：每个包需要注册两次：主
```
ServiceProvider
```
注册到
```
bootstrap/providers.php
```
，
```
ModuleServiceProvider
```
注册到
```
config/concord.php
```
。任何一个遗漏都会导致包加载不完全，且难以排查问题。详情请见core.md。
三段式模型：每个实体包含Contract、实现Contract的Model以及Proxy。仓库从
```
model()
```
方法返回Contract，跨包类型提示使用Proxy——这正是无需修改核心代码即可替换模型的关键。详情请见data-layer.md。
文档块、成员顺序、注释、仓库规则和翻译由**
```
bagisto-coding-standards
```
**技能负责。这些规则适用于所有Bagisto文件，不仅限于包，也是代码审查中最常见的拒绝原因。
修改触及的内容：如果你编辑的文件中存在预先存在的违规问题，你需要修复它：检查整个类的成员顺序和文档块，而不仅仅是你修改的行。