Phpcore Laravel Package

Getting Started

Minimal Setup

1. Installation: Add to your Laravel project via Composer:

   composer require splash/phpcore
   

2. Basic Object Structure: Create a class extending Splash\Core\Models\AbstractObject with IntelParserTrait:

   namespace App\Splash\Objects;
   
   use Splash\Core\Models\AbstractObject;
   use Splash\Core\Models\Objects\IntelParserTrait;
   
   class Customer extends AbstractObject
   {
       use IntelParserTrait;
   
       protected static string $name = "Customer";
       protected static string $description = "Customer records";
       protected static string $ico = "fa-user";
     }
   

3. First Use Case: Define fields and CRUD operations in traits:

   // app/Splash/Objects/Customer/CrudTrait.php
   trait CrudTrait
   {
       public function load(string $id): ?CustomerEntity
       {
           return Customer::find($id);
       }
   
       public function create(): CustomerEntity
       {
           return new CustomerEntity();
       }
   }
   

Where to Look First

• Documentation: Start with objects/overview.md for core concepts
• Examples: Study the CRUD examples for implementation patterns
• Field Definitions: Review fields.md for field type configurations

Implementation Patterns

Core Workflow

1. Object Definition: Extend AbstractObject with traits

   class Product extends AbstractObject
   {
       use IntelParserTrait;
       use Product\CrudTrait;
       use Product\FieldDefinitionsTrait;
   }
   

2. Field Management:

   • Define fields in buildFields() using fluent API

   protected function buildFields(): void
   {
       $this->fieldsFactory()->create(SplFields::VARCHAR)
           ->identifier('sku')
           ->name('SKU')
           ->isRequired();
   }
   

3. CRUD Implementation:

   • Implement required methods (load, create, update, delete)
   • Use $this->needUpdate() to track changes

4. Data Synchronization:

   • Field getters/setters automatically mapped via IntelParserTrait
   • Use SimpleFieldsTrait for basic properties

Integration Tips

• Laravel Eloquent: Bridge Splash objects with Eloquent models:

  public function load(string $id): ?Product
  {
      return Product::query()->find($id);
  }
  

• Field Validation: Leverage Splash's validation system:

  $this->fieldsFactory()->create(SplFields::EMAIL)
      ->identifier('email')
      ->isRequired()
      ->isUnique();
  

• Complex Fields: Use helpers for:

  • Prices: SplFields::PRICE
  • Images: SplFields::IMAGE
  • Files: SplFields::FILE

• Pagination: Implement objectsList() with metadata:

  return [
      'items' => $products->toArray(),
      'meta' => [
          'total' => $products->total(),
          'current' => $products->count()
      ]
  ];
  

Common Patterns

1. Field Processing:

   protected function getCoreFields(int $key, string $fieldName): void
   {
       switch ($fieldName) {
           case 'name': $this->out[$fieldName] = $this->object->name; break;
           case 'price': $this->out[$fieldName] = $this->object->price->value; break;
       }
       unset($this->in[$key]);
   }
   

2. Change Tracking:

   protected function setCoreFields(string $fieldName, $value): void
   {
       if ($this->object->{$fieldName} !== $value) {
           $this->object->{$fieldName} = $value;
           $this->needUpdate();
       }
       unset($this->in[$fieldName]);
   }
   

3. List Fields:

   protected function getOrderLines(int $key): void
   {
       $this->out['order_lines'] = $this->object->orderLines->map(function($line) {
           return [
               'product_id' => $line->product_id,
               'quantity' => $line->quantity
           ];
       });
       unset($this->in[$key]);
   }
   

Gotchas and Tips

Common Pitfalls

1. Field Processing Order:

   • Always call unset($this->in[$key]) after processing a field
   • Missing this causes fields to be reprocessed

2. Change Detection:

   • Forgetting to call $this->needUpdate() when modifying objects
   • Causes unnecessary database writes when $needed is always false

3. Identifier Handling:

   • getObjectIdentifier() must return null for new objects
   • Returning invalid IDs breaks synchronization

4. Type Mismatches:

   • Splash expects specific field types (e.g., PRICE vs DOUBLE)
   • Improper type handling causes serialization errors

5. Pagination Requirements:

   • objectsList() must include meta with total and current
   • Missing metadata breaks client-side pagination

Debugging Tips

1. Enable Logging:

   Splash::log()->setLevel(\Monolog\Logger::DEBUG);
   

2. Field Inspection:

   // Dump all defined fields
   print_r($this->fields());
   

3. Change Tracking:

   // Check which fields were modified
   var_dump($this->changedFields());
   

Configuration Quirks

1. Field Identifiers:

   • Must be unique within an object
   • Use underscores (user_email) not camelCase (userEmail)

2. Required Fields:

   • Mark with ->isRequired() during definition
   • Causes validation errors during update() if missing

3. List Fields:

   • Must implement isListed() for inclusion in objectsList()
   • Use SplFields::LIST type for collections

Extension Points

1. Custom Field Types:

   // Extend base field classes
   class CustomPriceField extends SplFields\Price
   {
       public function validate($value): bool
       {
           // Custom validation logic
       }
   }
   

2. Object Extensions:

   // Add to existing objects
   class ExtendedCustomer extends Customer
   {
       use ExtendedCustomer\AdditionalFieldsTrait;
   }
   

3. Filter System:

   // Implement custom filters
   public function applyFilters(array $filters): void
   {
       if (isset($filters['active_only'])) {
           $this->query->where('status', 'active');
       }
   }
   

Performance Considerations

1. Database Writes:

   • Always check $needed parameter in update()
   • Avoid unnecessary flush() calls

2. Field Processing:

   • Process simple fields with SimpleFieldsTrait
   • Reduces boilerplate code

3. Pagination:

   • Use database-level pagination (e.g., setMaxResults())
   • Avoid loading all records into memory

Laravel-Specific Tips

1. Service Provider Binding:

   public function register()
   {
       $this->app->bind('splash.customer', function($app) {
           return new \App\Splash\Objects\Customer();
       });
   }
   

2. Query Builder Integration:

   public function objectsList(?string $filter = null, array $params = []): array
   {
       $query = Customer::query();
   
       if ($filter) {
           $query->where('name', 'like', "%{$filter}%")
                 ->orWhere('email', 'like', "%{$filter}%");
       }
   
       // ... rest of pagination logic
   }
   

3. Event Listeners:

   // Sync after model events
   Customer::saved(function($model) {
       Splash::sync()->trigger('customer_updated', $model->id);
   });