Laravel Custom Properties Laravel Package

Technical Evaluation

Architecture Fit

• Modularity: The package enables dynamic, schema-less properties for Eloquent models, aligning with Laravel’s convention-over-configuration philosophy. Ideal for use cases requiring flexible attribute storage (e.g., user preferences, metadata, or extensible APIs).
• Database Agnosticism: Leverages Laravel’s JSON column support (PostgreSQL, MySQL 5.7+, SQLite), ensuring broad compatibility without vendor lock-in.
• ORM Integration: Seamlessly integrates with Eloquent’s lifecycle (e.g., saving, retrieved), reducing boilerplate for custom attribute logic.
• Tradeoffs:
  • Schema Rigidity: Requires a custom_properties JSON column, which may complicate migrations or schema evolution.
  • Query Limitations: JSON columns restrict indexing/searching capabilities compared to dedicated columns.

Integration Feasibility

• High for Laravel 8+: Explicit support for Laravel 8 (and backward to 7) ensures compatibility with modern Laravel stacks. Minimal friction for teams already using Eloquent.
• Low for Legacy Systems: Laravel 6 or earlier may require additional testing or polyfills (e.g., for JSON column handling or Facade changes).
• Dependency Risks:
  • None Critical: The package has no external dependencies beyond Laravel core.
  • Internal: Potential conflicts if the application overrides Eloquent’s attributes or casts behavior.

Technical Risk

• Minimal:
  • Backward Compatibility: The package’s last release (2020) predates Laravel 9/10, but its core functionality (JSON storage + trait-based extension) remains stable.
  • Performance: JSON serialization/deserialization adds negligible overhead for typical use cases (microbenchmarking recommended for high-throughput systems).
• Mitigable Risks:
  • Schema Changes: Adding the custom_properties column may require downtime or careful migration sequencing.
  • Data Corruption: Improper handling of JSON serialization (e.g., circular references) could corrupt stored data. The package lacks explicit safeguards here.
• Key Questions:
  1. How does the package handle circular references or deeply nested data in JSON serialization?
  2. Are there race conditions when multiple processes update custom_properties concurrently?
  3. Does the package support partial updates (e.g., PATCH requests) for nested JSON structures?
  4. What’s the failure mode if the JSON column is corrupted or malformed?

Integration Approach

Stack Fit

• Laravel 8+: Optimal fit. Leverages:
  • Eloquent’s improved JSON casting (Laravel 8+).
  • Symfony 5.4’s JsonSerializable for consistent serialization.
  • Laravel’s service container for trait resolution.
• Laravel 7/6: Functional but may require:
  • Manual JSON column handling (e.g., DB::raw for queries).
  • Polyfills for L8-specific Facade methods (e.g., Str::of()).
• Non-Laravel: Not applicable; tightly coupled to Eloquent’s model lifecycle.

Migration Path

1. Assessment:
   • Audit existing models to identify candidates for dynamic properties (e.g., User, Product).
   • Verify database support for JSON columns (e.g., MySQL 5.7+).
2. Schema Migration:

   Schema::table('users', function (Blueprint $table) {
       $table->json('custom_properties')->nullable()->after('updated_at');
   });
   

   • Rollback Plan: Add a custom_properties_text column as a fallback for non-JSON databases.
3. Model Integration:

   use LaTevaWeb\CustomProperties\HasCustomProperties;
   
   class User extends Model {
       use HasCustomProperties;
       protected $casts = [
           'custom_properties' => 'array', // Optional: Auto-cast JSON to array
       ];
   }
   

4. Testing:
   • Validate CRUD operations with dynamic properties.
   • Test edge cases: empty JSON, large payloads, concurrent writes.

Compatibility

• Backward: Limited. The package assumes Laravel 7+ features (e.g., JSON column support). Laravel 6 may need:
  • Custom JSON handling (e.g., json_encode/json_decode shims).
  • Manual trait resolution if using older PHP versions.
• Forward: High. The trait pattern is stable; future Laravel versions will likely maintain Eloquent compatibility.

Sequencing

1. Pilot Phase:
   • Apply to a non-critical model (e.g., LogEntry) to test performance and edge cases.
   • Monitor database load during JSON serialization.
2. Gradual Rollout:
   • Start with read-heavy models (e.g., Product metadata).
   • Phase in write-heavy models (e.g., User preferences) after validating concurrency.
3. Deprecation:
   • Plan to replace static columns with dynamic properties where applicable (e.g., is_premium → custom_properties['subscription']['tier']).

Operational Impact

Maintenance

• Reduced:
  • Eliminates need for manual attribute management (e.g., addColumn migrations).
  • Centralized logic in the trait reduces duplication across models.
• Ongoing:
  • Schema Management: Monitor JSON column bloat (e.g., log size growth).
  • Backup/Restore: Ensure JSON data integrity during database backups.
  • Deprecation: Track Laravel’s JSON column deprecations (e.g., in favor of jsonb in PostgreSQL).

Support

• Proactive Measures:
  • Document common use cases (e.g., "How to migrate static columns to dynamic properties").
  • Create a runbook for JSON corruption scenarios (e.g., ALTER TABLE ... ALTER COLUMN custom_properties TYPE jsonb USING custom_properties::jsonb).
• Escalation Path:
  • For package bugs: Open issues with:
    • Laravel version.
    • PHP version.
    • Reproducible steps (e.g., "Setting a circular reference crashes serialization").
  • For Laravel-specific issues: Engage the Laravel core team if the package relies on undocumented behavior.

Scaling

• Performance:
  • Reads: Minimal impact; JSON casting happens once per query.
  • Writes: Concurrency risks if multiple processes update custom_properties simultaneously. Mitigate with:
    • Database-level locks (e.g., SELECT ... FOR UPDATE).
    • Application-level retries for failed saves.
• Database:
  • JSON columns may increase storage usage. Consider:
    • Compression for large payloads (e.g., pg_lzcompress in PostgreSQL).
    • Partitioning if custom_properties grows unbounded.

Failure Modes

Ramp-Up

• For Developers:
  • Training: Focus on:
    • When to use dynamic properties vs. static columns.
    • Serialization pitfalls (e.g., non-JSON-serializable objects).
    • Performance implications of nested JSON.
  • Documentation: Add examples for:
    • Querying dynamic properties (e.g., whereJsonContains).
    • Migrating legacy data to JSON format.
• For QA:
  • Test plans should include:
    • Edge cases: empty JSON, null values, malformed data.
    • Concurrency: simulate race conditions.
    • Serialization: validate with complex PHP objects (e.g., DateTime, Collection).
• Onboarding Time:
  • Low: 1–2 hours for basic usage.
  • High: 1–2 days for advanced patterns (e.g., nested updates, validation).