wip

Author: lam0819

INSTALLATION.md

@@ -16,9 +16,9 @@ This guide provides detailed instructions for installing and configuring the Lar
 
 ### System Requirements
 
-- **PHP**: 8.1 or higher
-- **Laravel**: 9.0 or higher
-- **Database**: MySQL 5.7+, PostgreSQL 12+, or SQLite 3.35+
+- **PHP**: 8.3 or higher
+- **Laravel**: 11.0 or higher
+- **Database**: MySQL 8.1+, PostgreSQL 12+, or SQLite 3.35+
 
 ### PHP Extensions
 
@@ -565,9 +565,48 @@ rm -rf database/migrations/*_create_entity_properties_table.php
 
 After successful installation:
 
+> **⚠️ IMPORTANT**: Before using dynamic properties, you must create property definitions first!
+
+### Quick Start
+
+1. **Create your first properties**:
+```bash
+# Interactive property creation
+php artisan properties:create
+```
+
+Or programmatically:
+```php
+use SolutionForest\LaravelDynamicProperties\Models\Property;
+
+Property::create([
+    'name' => 'phone',
+    'label' => 'Phone Number', 
+    'type' => 'text'
+]);
+```
+
+2. **Add the trait to your models**:
+```php
+use SolutionForest\LaravelDynamicProperties\Traits\HasProperties;
+
+class User extends Model 
+{
+    use HasProperties;
+}
+```
+
+3. **Start using properties**:
+```php
+$user = User::find(1);
+$user->setDynamicProperty('phone', '+1234567890'); // ✅ Works
+```
+
+### Additional Resources
+
 1. **Read the [Usage Examples](docs/EXAMPLES.md)** for common use cases
-2. **Review the [API Documentation](docs/API.md)** for detailed method references
+2. **Review the [API Documentation](docs/API.md)** for detailed method references  
 3. **Check the [Performance Guide](docs/PERFORMANCE.md)** for optimization strategies
 4. **Set up monitoring** for production environments
 
-The package is now ready to use! Start by adding the `HasProperties` trait to your models and creating your first properties.
+> **💡 Remember**: Always create Property definitions before setting values to avoid `PropertyNotFoundException`!

README.md

@@ -65,6 +65,8 @@ php artisan vendor:publish --provider="SolutionForest\LaravelDynamicProperties\D
 
 ## Quick Start
 
+> **⚠️ IMPORTANT**: You must create Property definitions before setting property values. Attempting to set a property that doesn't have a definition will throw a `PropertyNotFoundException`.
+
 ### 1. Add the Trait to Your Models
 
 ```php
@@ -85,8 +87,10 @@ class User extends Model
 
 ### 2. Create Properties
 
+**⚠️ REQUIRED STEP**: Before setting any property values, you must first create the property definitions. This ensures type safety, validation, and optimal performance.
+
 ```php
-use YourVendor\DynamicProperties\Models\Property;
+use SolutionForest\LaravelDynamicProperties\Models\Property;
 
 // Create a text property
 Property::create([
@@ -118,14 +122,19 @@ Property::create([
 
 ### 3. Set and Get Properties
 
+**✅ Only after creating property definitions can you set values:**
+
 ```php
 $user = User::find(1);
 
-// Set properties
+// ✅ This works - property 'phone' was defined above
 $user->setDynamicProperty('phone', '+1234567890');
 $user->setDynamicProperty('age', 25);
 $user->setDynamicProperty('status', 'active');
 
+// ❌ This will throw PropertyNotFoundException
+$user->setDynamicProperty('undefined_property', 'value');
+
 // Or use magic methods
 $user->prop_phone = '+1234567890';
 $user->prop_age = 25;
@@ -143,20 +152,80 @@ $user->setProperties([
 ]);
 ```
 
+> **💡 Pro Tip**: Use the Artisan command to create properties interactively:
+> ```bash
+> php artisan properties:create
+> ```
+
 ### 4. Search by Properties
 
+**🔍 Search works with or without property definitions, but defining properties first is strongly recommended for type safety:**
+
 ```php
-// Find users by single property
+// ✅ RECOMMENDED: Search with defined properties (uses correct column types)
 $activeUsers = User::whereProperty('status', 'active')->get();
 $youngUsers = User::whereProperty('age', '<', 30)->get();
 
+// ⚠️ FALLBACK: Search undefined properties (uses value-based type detection)
+$results = User::whereProperty('undefined_prop', 'some_value')->get();
+
 // Find users by multiple properties
 $users = User::whereProperties([
     'status' => 'active',
     'age' => 25
 ])->get();
 ```
 
+## ⚠️ Common Pitfalls and Warnings
+
+### 1. Property Definition Required for Setting Values
+```php
+// ❌ WRONG - Will throw PropertyNotFoundException
+$user->setDynamicProperty('new_field', 'value'); // Property 'new_field' doesn't exist
+
+// ✅ CORRECT - Create property definition first
+Property::create([
+    'name' => 'new_field',
+    'label' => 'New Field',
+    'type' => 'text'
+]);
+$user->setDynamicProperty('new_field', 'value'); // Now it works
+```
+
+### 2. Type Safety Depends on Property Definitions
+```php
+// ✅ With property definition - Type safe
+Property::create(['name' => 'score', 'type' => 'number']);
+$users = User::whereProperty('score', '>', 80); // Uses number_value column correctly
+
+// ⚠️ Without property definition - Fallback behavior
+$users = User::whereProperty('undefined_score', '>', 80); // Uses value-based type detection
+```
+
+### 3. Validation Only Works with Property Definitions
+```php
+// ✅ With validation rules
+Property::create([
+    'name' => 'email',
+    'type' => 'text',
+    'validation' => ['email', 'required']
+]);
+$user->setDynamicProperty('email', 'invalid-email'); // Throws PropertyValidationException
+
+// ❌ Without property definition - No validation possible
+// (Would throw PropertyNotFoundException before validation could occur)
+```
+
+### 4. Performance Impact
+```php
+// ✅ FAST - Uses correct column and indexes
+Property::create(['name' => 'department', 'type' => 'text']);
+$users = User::whereProperty('department', 'engineering'); // Optimized query
+
+// ⚠️ SLOWER - Uses fallback type detection
+$users = User::whereProperty('undefined_dept', 'engineering'); // Less optimal
+```
+
 ## Advanced Usage
 
 ### Property Types and Validation
@@ -449,6 +518,45 @@ return [
 ];
 ```
 
+## Troubleshooting
+
+### Common Errors and Solutions
+
+#### `PropertyNotFoundException`
+```php
+// Error: "Property 'phone' not found"
+$user->setDynamicProperty('phone', '+1234567890');
+```
+**Solution**: Create the property definition first:
+```php
+Property::create(['name' => 'phone', 'type' => 'text']);
+$user->setDynamicProperty('phone', '+1234567890'); // Now works
+```
+
+#### `PropertyValidationException`
+```php
+// Error: "Validation failed for property 'age'"
+$user->setDynamicProperty('age', -5);
+```
+**Solution**: Check property validation rules:
+```php
+$property = Property::where('name', 'age')->first();
+var_dump($property->validation); // See what rules are defined
+$user->setDynamicProperty('age', 25); // Use valid value
+```
+
+#### Inconsistent Search Results
+```php
+// Getting different results for the same logical query
+$users1 = User::whereProperty('level', '>', 5)->get();   // 10 results
+$users2 = User::whereProperty('level', '>', '5')->get(); // 3 results
+```
+**Solution**: This happens when property definition is missing. Create it:
+```php
+Property::create(['name' => 'level', 'type' => 'number']);
+// Now both queries will return the same results
+```
+
 ## Testing
 
 The package includes comprehensive tests. Run them with:

docs/API.md

@@ -1,5 +1,7 @@
 # API Documentation
 
+> **⚠️ IMPORTANT**: Property definitions must be created before setting property values. All `setDynamicProperty` methods will throw `PropertyNotFoundException` if the property doesn't exist. Search methods (`whereProperty`) will work but fall back to less optimal type detection without property definitions.
+
 ## Table of Contents
 
 - [Models](#models)
@@ -14,6 +16,37 @@
 - [Facades](#facades)
 - [Artisan Commands](#artisan-commands)
 
+## Getting Started
+
+### Property Definition Requirement
+
+**All dynamic property operations require property definitions to exist first.** Here's what happens in each scenario:
+
+| Operation | With Property Definition | Without Property Definition |
+|-----------|-------------------------|----------------------------|
+| `setDynamicProperty()` | ✅ Works with validation | ❌ Throws `PropertyNotFoundException` |
+| `setProperties()` | ✅ Works with validation | ❌ Throws `PropertyNotFoundException` |
+| `whereProperty()` | ✅ Optimal performance, type-safe | ⚠️ Works but uses fallback type detection |
+| `getDynamicProperty()` | ✅ Returns typed value | ✅ Returns value if exists |
+
+### Quick Setup Checklist
+
+1. **Create property definitions**:
+```php
+Property::create(['name' => 'phone', 'type' => 'text']);
+Property::create(['name' => 'age', 'type' => 'number']);
+```
+
+2. **Add trait to your models**:
+```php
+class User extends Model { use HasProperties; }
+```
+
+3. **Start using properties**:
+```php
+$user->setDynamicProperty('phone', '+1234567890');
+```
+
 ## Models
 
 ### Property Model
@@ -159,7 +192,13 @@ class User extends Model
 
 Sets a single property value with validation.
 
+> **⚠️ REQUIREMENT**: The property must exist in the `properties` table before calling this method.
+
 ```php
+// First create the property definition
+Property::create(['name' => 'phone', 'type' => 'text']);
+
+// Then set the value
 $user->setDynamicProperty('phone', '+1234567890');
 ```
 
@@ -192,7 +231,15 @@ $phone = $user->getDynamicProperty('phone');
 
 Sets multiple properties at once.
 
+> **⚠️ REQUIREMENT**: All properties must exist in the `properties` table before calling this method.
+
 ```php
+// Ensure all properties are defined first
+Property::create(['name' => 'phone', 'type' => 'text']);
+Property::create(['name' => 'age', 'type' => 'number']);
+Property::create(['name' => 'active', 'type' => 'boolean']);
+
+// Then set multiple values
 $user->setProperties([
     'phone' => '+1234567890',
     'age' => 25,
@@ -293,9 +340,18 @@ $entityProperties = $user->entityProperties;
 
 Filter entities by a single property value.
 
+> **💡 BEST PRACTICE**: While this method works without property definitions (using fallback type detection), defining properties first ensures optimal performance and type safety.
+
 ```php
+// ✅ RECOMMENDED: With property definition
+Property::create(['name' => 'active', 'type' => 'boolean']);
+Property::create(['name' => 'age', 'type' => 'number']);
+
 $activeUsers = User::whereProperty('active', true)->get();
 $youngUsers = User::whereProperty('age', '<', 30)->get();
+
+// ⚠️ WORKS BUT NOT OPTIMAL: Without property definition
+$results = User::whereProperty('undefined_prop', 'value')->get(); // Uses fallback logic
 ```
 
 **Parameters:**
@@ -372,8 +428,15 @@ Core service for managing dynamic properties.
 
 Sets a property value for an entity.
 
+> **⚠️ REQUIREMENT**: The property must exist in the `properties` table before calling this method.
+
 ```php
 $propertyService = app(PropertyService::class);
+
+// First ensure property exists
+Property::create(['name' => 'phone', 'type' => 'text']);
+
+// Then set the value
 $propertyService->setDynamicProperty($user, 'phone', '+1234567890');
 ```