Download the PHP package solution-forest/laravel-dynamic-properties without Composer

Laravel Dynamic Properties

A dynamic property system for Laravel that allows any entity (users, companies, contacts, etc.) to have custom properties with validation, search capabilities, and optimal performance.

Requirements

• PHP: 8.3 or higher
• Laravel: 11.0 or higher
• Database: MySQL 8.0+ or SQLite 3.35+ (with JSON support)

Features

• Simple Architecture: Clean 2-table design with optional JSON caching
• Type Safety: Support for text, number, date, boolean, and select properties
• Fast Performance: < 1ms property retrieval with JSON cache, < 20ms without
• Flexible Search: Property-based filtering with multiple operators
• Easy Integration: Simple trait-based implementation
• Database Agnostic: Works with MySQL and SQLite
• Validation: Built-in property validation with custom rules

Installation

Install the package via Composer:

Publish and run the migrations:

Optionally, publish the configuration file:

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

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.

3. Set and Get Properties

✅ Only after creating property definitions can you set values:

💡 Pro Tip: Use the Artisan command to create properties interactively:

4. Search by Properties

🔍 Search works with or without property definitions, but defining properties first is strongly recommended for type safety:

⚠️ Common Pitfalls and Warnings

1. Property Definition Required for Setting Values

2. Type Safety Depends on Property Definitions

3. Validation Only Works with Property Definitions

4. Performance Impact

Advanced Usage

Property Types and Validation

Text Properties

Number Properties

Date Properties

Boolean Properties

Select Properties

Performance Optimization

JSON Column Caching

For maximum performance, add a JSON column to your existing tables:

This provides:

• < 1ms property retrieval (vs ~20ms without cache)
• Automatic synchronization when properties change
• Transparent fallback to EAV structure when cache is unavailable

Search Performance

The package automatically creates optimized indexes:

Advanced Search

Complex Queries

Text Search

Error Handling

The package provides comprehensive error handling:

Artisan Commands

The package includes helpful Artisan commands:

API Reference

HasProperties Trait

Methods

setDynamicProperty(string $name, mixed $value): void

• Sets a single property value
• Validates the value against property rules
• Updates JSON cache if available

getDynamicProperty(string $name): mixed

• Retrieves a single property value
• Returns null if property doesn't exist

setProperties(array $properties): void

• Sets multiple properties at once
• More efficient than multiple setDynamicProperty calls

getPropertiesAttribute(): array

• Returns all properties as an associative array
• Uses JSON cache when available, falls back to EAV queries

Magic Methods

__get($key): mixed

• Access properties with prop_ prefix
• Example: $user->prop_phone gets the 'phone' property

__set($key, mixed $value): void

• Set properties with prop_ prefix
• Example: $user->prop_phone = '+1234567890' sets the 'phone' property

Query Scopes

whereProperty(string $name, mixed $value, string $operator = '='): Builder

• Filter entities by a single property
• Supports operators: =, !=, <, >, <=, >=, LIKE

whereProperties(array $properties): Builder

• Filter entities by multiple properties
• Uses AND logic between properties

PropertyService

setDynamicProperty(Model $entity, string $name, mixed $value): void

• Core method for setting property values
• Handles validation and storage

setProperties(Model $entity, array $properties): void

• Set multiple properties efficiently

search(string $entityType, array $filters): Collection

• Advanced search with complex criteria
• Supports multiple operators and property types

Performance Characteristics

Single Entity Property Retrieval

Search Performance

Memory Usage

• Property definitions: ~1KB per property
• Entity properties: ~100 bytes per property value
• JSON cache: ~50% reduction in query overhead

Database Compatibility

MySQL (Recommended)

• Full JSON support with native functions
• Full-text search capabilities
• Optimal performance with all features

SQLite

• JSON stored as TEXT with JSON1 extension
• Basic text search with LIKE queries
• All core functionality supported

Configuration

Publish the config file to customize behavior:

Troubleshooting

Common Errors and Solutions

PropertyNotFoundException

Solution: Create the property definition first:

PropertyValidationException

Solution: Check property validation rules:

Inconsistent Search Results

Solution: This happens when property definition is missing. Create it:

Testing

The package includes comprehensive tests. Run them with:

Contributing

Please see CONTRIBUTING.md for details on how to contribute to this project.

License

This package is open-sourced software licensed under the MIT license.

Changelog

Please see CHANGELOG.md for recent changes.

Documentation

• Installation Guide - Detailed installation and setup instructions
• API Documentation - Complete API reference for all classes and methods
• Usage Examples - Comprehensive examples for common and advanced scenarios
• Performance Guide - Optimization strategies and performance benchmarks
• Contributing Guide - How to contribute to the project
• Changelog - Version history and changes

Credits

• All Contributors