Skip to content

Commit d403607

Browse files
Abhishek5SharmaAbhishek5Sharma
committed
update readme
1 parent a81bbd6 commit d403607

1 file changed

Lines changed: 298 additions & 0 deletions

File tree

‎README.md‎

Lines changed: 298 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,298 @@
1+
# Laravel Data Fields Package
2+
3+
A Laravel package for managing dynamic data fields and data sets with polymorphic relationships. This package allows you to attach custom fields and organized field sets to any Eloquent model.
4+
5+
## Features
6+
7+
- **Dynamic Data Fields**: Attach custom fields to any model
8+
- **Data Sets**: Organize fields into logical groups
9+
- **Polymorphic Relations**: Works with any Eloquent model
10+
- **Field Validation**: Built-in validation support
11+
- **Configurable Models**: Override default models
12+
- **Migration Support**: Database migrations included
13+
14+
## Installation
15+
16+
### 1. Install via Composer
17+
18+
```bash
19+
composer require ssntpl/data-fields
20+
```
21+
22+
### 2. Publish Configuration (Optional)
23+
24+
```bash
25+
php artisan vendor:publish --tag=data-fields-config
26+
```
27+
28+
### 3. Register Service Provider (Laravel < 5.5)
29+
30+
For Laravel versions before 5.5, add the service provider to `config/app.php`:
31+
32+
```php
33+
'providers' => [
34+
// Other providers...
35+
Ssntpl\DataFields\DataFieldsServiceProvider::class,
36+
],
37+
```
38+
39+
### 4. Publish and Run Migrations
40+
41+
```bash
42+
php artisan vendor:publish --tag=data-fields-migrations
43+
php artisan migrate
44+
```
45+
46+
## Configuration
47+
48+
The package publishes a configuration file to `config/data-fields.php`:
49+
50+
```php
51+
<?php
52+
return [
53+
'data_set_model' => \Ssntpl\DataFields\Models\DataSet::class,
54+
'data_field_model' => \Ssntpl\DataFields\Models\DataField::class,
55+
];
56+
```
57+
58+
## Usage
59+
60+
### 1. Add Traits to Your Models
61+
62+
#### For Data Fields Only
63+
```php
64+
use Ssntpl\DataFields\Traits\HasDataFields;
65+
66+
class User extends Model
67+
{
68+
use HasDataFields;
69+
}
70+
```
71+
72+
#### For Data Sets (includes Data Fields)
73+
```php
74+
use Ssntpl\DataFields\Traits\HasDataSets;
75+
76+
class Product extends Model
77+
{
78+
use HasDataSets;
79+
}
80+
```
81+
82+
### 2. Working with Data Fields
83+
84+
#### Create Data Fields
85+
```php
86+
$user = User::find(1);
87+
88+
// Create a simple field
89+
$user->fields()->create([
90+
'key' => 'phone_number',
91+
'value' => '+1234567890',
92+
'type' => 'text',
93+
'description' => 'User phone number'
94+
]);
95+
96+
// Create field with validation
97+
$user->fields()->create([
98+
'key' => 'age',
99+
'value' => '25',
100+
'type' => 'number',
101+
'validations' => ['required', 'numeric', 'min:18'],
102+
'sort_order' => 1
103+
]);
104+
```
105+
106+
#### Retrieve Data Fields
107+
```php
108+
// Get all fields for a model
109+
$fields = $user->fields;
110+
111+
// Get specific field by key
112+
$phoneField = $user->fields()->where('key', 'phone_number')->first();
113+
114+
// Get field value
115+
$phoneNumber = $phoneField->value;
116+
```
117+
118+
### 3. Working with Data Sets
119+
120+
#### Create Data Sets
121+
```php
122+
$product = Product::find(1);
123+
124+
// Create a data set
125+
$specifications = $product->data_sets()->create([
126+
'name' => 'Product Specifications',
127+
'type' => 'specifications',
128+
'sort_order' => 1
129+
]);
130+
131+
// Add fields to the data set
132+
$specifications->fields()->create([
133+
'key' => 'weight',
134+
'value' => '2.5kg',
135+
'type' => 'text',
136+
'description' => 'Product weight'
137+
]);
138+
139+
$specifications->fields()->create([
140+
'key' => 'dimensions',
141+
'value' => '30x20x10cm',
142+
'type' => 'text',
143+
'description' => 'Product dimensions'
144+
]);
145+
```
146+
147+
#### Retrieve Data Sets
148+
```php
149+
// Get all data sets
150+
$dataSets = $product->data_sets;
151+
152+
// Get specific data set by type
153+
$specs = $product->data_sets()->where('type', 'specifications')->first();
154+
155+
// Get fields within a data set
156+
$specFields = $specs->fields;
157+
```
158+
159+
### 4. Field Types and Validation
160+
161+
The package supports various field types:
162+
163+
```php
164+
// Text field
165+
$field = $model->fields()->create([
166+
'key' => 'description',
167+
'value' => 'Sample description',
168+
'type' => 'text'
169+
]);
170+
171+
// Number field with validation
172+
$field = $model->fields()->create([
173+
'key' => 'price',
174+
'value' => '99.99',
175+
'type' => 'number',
176+
'validations' => ['required', 'numeric', 'min:0']
177+
]);
178+
179+
// Date field
180+
$field = $model->fields()->create([
181+
'key' => 'expiry_date',
182+
'value' => '2024-12-31',
183+
'type' => 'date',
184+
'validations' => ['required', 'date', 'after:today']
185+
]);
186+
```
187+
188+
### 5. Duplication
189+
190+
Both DataField and DataSet models support duplication:
191+
192+
```php
193+
// Duplicate a data field
194+
$originalField = DataField::find(1);
195+
$duplicatedField = $originalField->duplicate();
196+
197+
// Duplicate a data set (includes all its fields)
198+
$originalSet = DataSet::find(1);
199+
$duplicatedSet = $originalSet->duplicate();
200+
```
201+
202+
### 6. Custom Models
203+
204+
You can extend the base models to add custom functionality:
205+
206+
```php
207+
// Custom DataField model
208+
class CustomDataField extends \Ssntpl\DataFields\Models\DataField
209+
{
210+
protected $fillable = ['custom_attribute'];
211+
212+
// Add custom methods
213+
public function getFormattedValue()
214+
{
215+
return strtoupper($this->value);
216+
}
217+
}
218+
219+
// Custom DataSet model
220+
class CustomDataSet extends \Ssntpl\DataFields\Models\DataSet
221+
{
222+
protected $extraFillable = ['custom_field'];
223+
224+
public function getFillable()
225+
{
226+
return array_merge(parent::getFillable(), $this->extraFillable ?? []);
227+
}
228+
}
229+
```
230+
231+
Update your configuration:
232+
233+
```php
234+
// config/data-fields.php
235+
return [
236+
'data_set_model' => App\Models\CustomDataSet::class,
237+
'data_field_model' => App\Models\CustomDataField::class,
238+
];
239+
```
240+
241+
## Database Schema
242+
243+
### Data Fields Table
244+
- `id` - Primary key
245+
- `owner_id` - Polymorphic relation ID
246+
- `owner_type` - Polymorphic relation type
247+
- `description` - Field description
248+
- `key` - Field identifier
249+
- `value` - Field value
250+
- `type` - Field type (text, number, date, etc.)
251+
- `validations` - JSON validation rules
252+
- `sort_order` - Display order
253+
- `meta_data` - Additional metadata
254+
255+
### Data Sets Table
256+
- `id` - Primary key
257+
- `owner_id` - Polymorphic relation ID
258+
- `owner_type` - Polymorphic relation type
259+
- `name` - Data set name
260+
- `type` - Data set type/category
261+
- `sort_order` - Display order
262+
- `meta_data` - Additional metadata
263+
264+
## API Reference
265+
266+
### HasDataFields Trait
267+
- `fields()` - Morphed relationship to data fields
268+
269+
### HasDataSets Trait
270+
- `data_sets()` - Morphed relationship to data sets
271+
- Includes `HasDataFields` trait
272+
273+
### DataField Model
274+
- `owner()` - Polymorphic relationship to owner model
275+
- `duplicate()` - Create a copy of the field
276+
- `delete()` - Delete field and related data
277+
278+
### DataSet Model
279+
- `owner()` - Polymorphic relationship to owner model
280+
- `fields()` - Relationship to associated fields
281+
- `duplicate()` - Create a copy of the set and all fields
282+
- `delete()` - Delete set and all associated fields
283+
284+
## Requirements
285+
286+
- PHP 7.4+
287+
- Laravel 8.0+
288+
289+
## Support
290+
291+
- **Issues**: [GitHub Issues](https://github.com/ssntpl/data-fields/issues)
292+
- **Source**: [GitHub Repository](https://github.com/ssntpl/data-fields)
293+
294+
## Author
295+
296+
**Abhishek Sharma**
297+
- Email: abhishek.sharma@ssntpl.in
298+
- Website: [https://ssntpl.com](https://ssntpl.com)

0 commit comments

Comments
 (0)