Skip to content

Commit ae63b8a

Browse files
ManukMinasyanManukMinasyan
committed
feat: add Laravel Boost skill for custom fields development
Add SKILL.md to enable AI-assisted development when using this package. The skill provides guidance for Filament integration, field types, feature flags, and programmatic API usage.
1 parent 10cd2ad commit ae63b8a

File tree

1 file changed

+289
-0
lines changed
  • resources/boost/skills/custom-fields-development

1 file changed

+289
-0
lines changed

‎resources/boost/skills/custom-fields-development/SKILL.md‎

Lines changed: 289 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,289 @@
1+
---
2+
name: custom-fields-development
3+
description: Adds dynamic custom fields to Eloquent models without migrations using Filament integration. Use when adding the UsesCustomFields trait to models, integrating custom fields in Filament forms/tables/infolists, configuring field types, working with field validation, or managing feature flags for conditional visibility, encryption, and multi-tenancy.
4+
---
5+
6+
# Custom Fields Development
7+
8+
## When to Use This Skill
9+
10+
Use when:
11+
- Adding custom fields capability to an Eloquent model
12+
- Integrating custom fields into Filament resources (forms, tables, infolists)
13+
- Configuring field types, validation, or visibility
14+
- Working with feature flags (encryption, multi-tenancy)
15+
- Creating CSV importers/exporters with custom field support
16+
17+
## Quick Start
18+
19+
### 1. Add Trait to Model
20+
21+
```php
22+
use Relaticle\CustomFields\Models\Concerns\UsesCustomFields;
23+
use Relaticle\CustomFields\Models\Contracts\HasCustomFields;
24+
25+
class Contact extends Model implements HasCustomFields
26+
{
27+
use UsesCustomFields;
28+
}
29+
```
30+
31+
### 2. Register Plugin in Panel
32+
33+
```php
34+
use Relaticle\CustomFields\CustomFieldsPlugin;
35+
36+
public function panel(Panel $panel): Panel
37+
{
38+
return $panel
39+
->plugins([
40+
CustomFieldsPlugin::make()
41+
->authorize(fn () => auth()->user()->isAdmin()),
42+
]);
43+
}
44+
```
45+
46+
### 3. Publish and Run Migrations
47+
48+
```bash
49+
php artisan vendor:publish --tag=custom-fields-migrations
50+
php artisan migrate
51+
```
52+
53+
## Filament Integration
54+
55+
Use the `CustomFields` facade to generate form/table/infolist components.
56+
57+
### Form Schema
58+
59+
```php
60+
use Relaticle\CustomFields\Facades\CustomFields;
61+
62+
public static function form(Form $form): Form
63+
{
64+
return $form->schema([
65+
TextInput::make('name')->required(),
66+
// Add custom fields after regular fields
67+
CustomFields::form()->forSchema($form)->build(),
68+
]);
69+
}
70+
```
71+
72+
**Builder methods:**
73+
- `forSchema(Schema $schema)` - Auto-detect model from form/infolist
74+
- `forModel(Model|string $model)` - Explicit model binding
75+
- `only(['code1', 'code2'])` - Include only specific fields
76+
- `except(['code1'])` - Exclude specific fields
77+
- `withoutSections()` - Flatten fields without section grouping
78+
79+
### Table Columns and Filters
80+
81+
```php
82+
use Relaticle\CustomFields\Facades\CustomFields;
83+
84+
public static function table(Table $table): Table
85+
{
86+
$customFields = CustomFields::table()->forModel(Contact::class);
87+
88+
return $table
89+
->columns([
90+
TextColumn::make('name'),
91+
...$customFields->columns(),
92+
])
93+
->filters([
94+
...$customFields->filters(),
95+
]);
96+
}
97+
```
98+
99+
### Infolist Entries
100+
101+
```php
102+
use Relaticle\CustomFields\Facades\CustomFields;
103+
104+
public static function infolist(Infolist $infolist): Infolist
105+
{
106+
return $infolist->schema([
107+
TextEntry::make('name'),
108+
CustomFields::infolist()->forSchema($infolist)->build(),
109+
]);
110+
}
111+
```
112+
113+
### CSV Import/Export
114+
115+
```php
116+
use Relaticle\CustomFields\Facades\CustomFields;
117+
118+
// In Importer class
119+
public function getColumns(): array
120+
{
121+
return [
122+
ImportColumn::make('name'),
123+
...CustomFields::importer()->forModel(Contact::class)->columns()->toArray(),
124+
];
125+
}
126+
127+
// In Exporter class
128+
public function getColumns(): array
129+
{
130+
return [
131+
ExportColumn::make('name'),
132+
...CustomFields::exporter()->forModel(Contact::class)->columns()->toArray(),
133+
];
134+
}
135+
```
136+
137+
## Available Field Types
138+
139+
| Type | Key | Data Storage |
140+
|------|-----|--------------|
141+
| Text | `text` | string_value |
142+
| Email | `email` | string_value |
143+
| Phone | `phone` | string_value |
144+
| Textarea | `textarea` | text_value |
145+
| Rich Editor | `rich-editor` | text_value |
146+
| Markdown | `markdown-editor` | text_value |
147+
| Link | `link` | string_value |
148+
| Number | `number` | integer_value |
149+
| Currency | `currency` | float_value |
150+
| Date | `date` | date_value |
151+
| DateTime | `datetime` | datetime_value |
152+
| Select | `select` | string_value |
153+
| Multi-Select | `multi-select` | json_value |
154+
| Checkbox | `checkbox` | boolean_value |
155+
| Checkbox List | `checkbox-list` | json_value |
156+
| Radio | `radio` | string_value |
157+
| Toggle | `toggle` | boolean_value |
158+
| Toggle Buttons | `toggle-buttons` | string_value |
159+
| Tags Input | `tags-input` | json_value |
160+
| Color Picker | `color-picker` | string_value |
161+
| File Upload | `file-upload` | json_value |
162+
163+
## Feature Flags
164+
165+
Configure in `config/custom-fields.php` using `FeatureConfigurator`:
166+
167+
```php
168+
use Relaticle\CustomFields\Enums\CustomFieldsFeature;
169+
use Relaticle\CustomFields\FeatureSystem\FeatureConfigurator;
170+
171+
'features' => FeatureConfigurator::configure()
172+
->enable(
173+
CustomFieldsFeature::FIELD_CONDITIONAL_VISIBILITY,
174+
CustomFieldsFeature::FIELD_ENCRYPTION,
175+
CustomFieldsFeature::FIELD_OPTION_COLORS,
176+
CustomFieldsFeature::UI_TABLE_COLUMNS,
177+
CustomFieldsFeature::UI_TABLE_FILTERS,
178+
)
179+
->disable(
180+
CustomFieldsFeature::SYSTEM_MULTI_TENANCY,
181+
),
182+
```
183+
184+
**Feature Categories:**
185+
186+
| Feature | Purpose |
187+
|---------|---------|
188+
| `FIELD_CONDITIONAL_VISIBILITY` | Show/hide fields based on other field values |
189+
| `FIELD_ENCRYPTION` | Encrypt sensitive field values |
190+
| `FIELD_OPTION_COLORS` | Color badges for select/checkbox options |
191+
| `UI_TABLE_COLUMNS` | Show custom fields as table columns |
192+
| `UI_TABLE_FILTERS` | Enable filtering by custom fields |
193+
| `UI_TOGGLEABLE_COLUMNS` | Allow users to toggle column visibility |
194+
| `UI_TOGGLEABLE_COLUMNS_HIDDEN_DEFAULT` | Hide toggleable columns by default |
195+
| `SYSTEM_MANAGEMENT_INTERFACE` | Admin page for managing fields |
196+
| `SYSTEM_MULTI_TENANCY` | Tenant isolation for fields |
197+
198+
## Configuration
199+
200+
### Entity Discovery
201+
202+
```php
203+
use Relaticle\CustomFields\EntitySystem\EntityConfigurator;
204+
205+
'entity_configuration' => EntityConfigurator::configure()
206+
->discover(app_path('Models'))
207+
->exclude(['User', 'Team'])
208+
->cache(enabled: true, ttl: 3600),
209+
```
210+
211+
### Field Type Control
212+
213+
```php
214+
use Relaticle\CustomFields\FieldTypeSystem\FieldTypeConfigurator;
215+
216+
'field_type_configuration' => FieldTypeConfigurator::configure()
217+
->enabled(['text', 'email', 'select', 'number'])
218+
->disabled(['file-upload'])
219+
->discover(true)
220+
->cache(enabled: true),
221+
```
222+
223+
### Custom Tenant Resolver
224+
225+
For multi-tenancy outside Filament panels:
226+
227+
```php
228+
use Relaticle\CustomFields\CustomFields;
229+
230+
// In AppServiceProvider::boot()
231+
CustomFields::resolveTenantUsing(fn () => auth()->user()?->team_id);
232+
```
233+
234+
## Programmatic Field Access
235+
236+
```php
237+
// Get all custom fields for a model
238+
$fields = $contact->customFields()->get();
239+
240+
// Get a specific field value
241+
$value = $contact->getCustomFieldValue($customField);
242+
243+
// Save a field value
244+
$contact->saveCustomFieldValue($customField, 'new value');
245+
246+
// Save multiple field values
247+
$contact->saveCustomFields([
248+
'industry' => 'Technology',
249+
'company_size' => 'Enterprise',
250+
]);
251+
```
252+
253+
## Database Schema
254+
255+
Four tables are created:
256+
257+
- `custom_field_sections` - Optional grouping of fields
258+
- `custom_fields` - Field definitions (name, code, type, validation)
259+
- `custom_field_options` - Choice options for select/checkbox fields
260+
- `custom_field_values` - Polymorphic storage of field values
261+
262+
Values are stored in type-specific columns: `string_value`, `text_value`, `integer_value`, `float_value`, `boolean_value`, `date_value`, `datetime_value`, `json_value`.
263+
264+
## Custom Models
265+
266+
Override default models for custom behavior:
267+
268+
```php
269+
use Relaticle\CustomFields\CustomFields;
270+
271+
// In AppServiceProvider::boot()
272+
CustomFields::useCustomFieldModel(MyCustomField::class);
273+
CustomFields::useValueModel(MyCustomFieldValue::class);
274+
CustomFields::useOptionModel(MyCustomFieldOption::class);
275+
CustomFields::useSectionModel(MyCustomFieldSection::class);
276+
```
277+
278+
## Register Custom Field Types
279+
280+
```php
281+
use Relaticle\CustomFields\CustomFieldsPlugin;
282+
283+
CustomFieldsPlugin::make()
284+
->registerFieldTypes([
285+
MyCustomFieldType::class,
286+
])
287+
```
288+
289+
Custom field types must extend `Relaticle\CustomFields\FieldTypeSystem\BaseFieldType`.

0 commit comments

Comments
 (0)