Botble Plugin Development

Botble Plugin Development

Use Botble conventions first, then apply this plugin-specific workflow.

Workflow

1. Inspect nearby plugins before adding new structure.
2. Prefer Botble generators where available: php artisan cms:plugin:create, cms:make:model, cms:make:form, cms:make:table, cms:make:controller, cms:make:request, cms:make:route.
3. Create the plugin under platform/plugins/{plugin} with predictable namespaces, translations, routes, providers, migrations, and plugin.json.
4. Register admin routes through AdminHelper::registerRoutes(). Prefer implicit route model binding; use wherePrimaryKey() on custom raw-ID routes.
5. Register permissions in config/permissions.php and attach them to dashboard menu items and routes.
6. Implement activate(), deactivate(), and removed() only when lifecycle work is needed. removed() must drop all plugin tables and clean plugin settings.
7. Run syntax, formatting, and targeted tests.

Required Structure

platform/plugins/your-plugin/
  config/general.php
  config/permissions.php
  database/migrations/
  resources/lang/en/your-plugin.php
  resources/js/
  resources/sass/
  resources/views/
  public/
  routes/web.php
  routes/api.php
  src/Database/
  src/Enums/
  src/Forms/
  src/Http/Controllers/
  src/Http/Requests/
  src/Models/
  src/Providers/
  src/Repositories/
  src/Services/
  src/Tables/
  src/Widgets/
  src/Plugin.php
  vite.build.mjs
  plugin.json

Implementation Rules

• Models extend Botble\Base\Models\BaseModel.
• Use casts(): array, not a $casts property, unless local code clearly still uses the property.
• Migrations use foreignId() and include proper cascade/null behavior.
• Controllers use Botble response helpers such as withCreatedSuccessMessage() and withUpdatedSuccessMessage().
• Forms extend FormAbstract and use typed field classes with FieldOptions.
• Tables use typed column classes; use FormattedColumn for custom display.
• Use trans('plugins/{plugin}::file.key'), never __() in plugin code.
• Register SlugHelper, SeoHelper, LanguageAdvancedManager, DashboardMenu, hooks, and assets only when the plugin needs them.
• Use BaseHelper::clean() for unescaped HTML and RvMedia::getImageUrl() for media.
• Declare assets in vite.build.mjs; do not create webpack.mix.js. Run npm run production when distributable assets must be mirrored into the plugin's public/ directory.

Load References

• Read references/examples.md for model, form, table, provider, and route examples.
• Read ../botble-conventions/references/quick-reference.md for baseline Botble rules.