Tlrv Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require sowork/tlrv dev-master
   

   Register the service provider in config/app.php:

   'providers' => [
       // ...
       Sowork\TLRV\TLRVProvider::class,
   ],
   

2. Publish Assets

   php artisan vendor:publish --provider="Sowork\TLRV\TLRVProvider"
   

   This creates the database table (tlrv_nodes), migrations, and frontend assets.

3. Frontend Setup

   npm install || yarn
   

   Register the Vue component in resources/assets/js/app.js:

   Vue.component('tlrv-node', require('./components/TLRVNode.vue'));
   

4. First Use Case

   • Access /tlrv in your browser to preview the admin interface.
   • Insert hierarchical data via the UI (e.g., for menus, permissions, or categories).
   • Query data programmatically via Eloquent (see Implementation Patterns).

Implementation Patterns

Core Workflows

1. Database Integration

• The package provides a TLRVNode Eloquent model (likely auto-generated after publishing).
• Example query for hierarchical data:

  use Sowork\TLRV\Models\TLRVNode;
  
  // Get all nodes (flat)
  $nodes = TLRVNode::all();
  
  // Get children of a parent (recursive)
  $children = TLRVNode::where('parent_id', $parentId)->get();
  
  // Recursive tree traversal (Laravel 8+)
  $tree = TLRVNode::with('children')->where('parent_id', null)->get();
  

• Tip: Use with('children') for nested relationships (ensure the model defines children()).

2. Admin Interface

• The /tlrv route provides a Vue.js-based UI to manage hierarchical data.
• Customize the UI by overriding published views in resources/views/vendor/tlrv/.

3. Frontend Usage

• Render nodes in Blade:

  @foreach($tree as $node)
      <tlrv-node :node="{{ $node }}"></tlrv-node>
  @endforeach
  

• Pass data to Vue:

  props: ['node'],
  data() {
      return {
          children: this.node.children || []
      };
  }
  

4. Data Seeding

• Seed initial hierarchical data in a DatabaseSeeder:

  TLRVNode::create([
      'uid' => 'root',
      'node_value' => 'Root',
      'parent_id' => null,
      'addition' => json_encode(['meta' => 'data']),
  ]);
  

5. API Endpoints

• Expose endpoints for dynamic loading (e.g., for SPAs):

  Route::get('/api/tlrv/tree', function () {
      return TLRVNode::with('children')->where('parent_id', null)->get();
  });
  

Gotchas and Tips

Pitfalls

1. Database Schema Assumptions

   • The package expects a tlrv_nodes table with columns:
     • uid (unique identifier, not auto-increment).
     • node_value (display value).
     • parent_id (foreign key to self).
     • addition (JSON field for metadata).
   • Fix: If columns differ, override the model or publish migrations and modify them.

2. Vue Component Registration

   • The tlrv-node component requires node prop with children nested.
   • Debug: Check browser console for node.children errors if data isn’t hierarchical.

3. Recursive Queries

   • Laravel’s with('children') may hit query limits for deep trees.
   • Optimization: Use withDepth() (Laravel 8+) or manual recursion:

     $tree = TLRVNode::where('parent_id', null)->get()->each->loadChildren();
     

4. UID vs. ID

   • The package uses uid (not Laravel’s default id). Ensure your queries use uid for lookups.

Debugging

• SQL Queries: Use DB::enableQueryLog() to inspect recursive queries.
• Vue DevTools: Inspect tlrv-node props to verify data structure.
• Artisan Tinker:

  php artisan tinker
  TLRVNode::where('parent_id', 1)->with('children')->get();
  

Extension Points

1. Custom Models

   • Extend Sowork\TLRV\Models\TLRVNode for additional fields:

     class CustomTLRVNode extends TLRVNode {
         protected $casts = ['addition' => 'array'];
     }
     

2. Override Views

   • Publish and modify:

     php artisan vendor:publish --tag=tlrv-views
     

   • Edit resources/views/vendor/tlrv/admin.blade.php.

3. Add Validation

   • Extend the TLRVNode model’s rules() in a service provider:

     TLRVNode::addGlobalScope('custom', function (Builder $builder) {
         $builder->where('node_value', '!=', 'deleted');
     });
     

4. API Responses

   • Transform responses for APIs:

     Route::get('/api/tlrv', function () {
         return TLRVNode::with('children')->where('parent_id', null)->get()
             ->map(fn ($node) => $node->toArray());
     });
     

5. Localization

   • Override labels in resources/lang/en/tlrv.php:

     return [
         'node_value' => 'Custom Label',
     ];
     

Performance

• Indexing: Add indexes to parent_id and uid in migrations:

  $table->index('parent_id');
  $table->unique('uid');
  

• Caching: Cache recursive queries:

  $tree = Cache::remember('tlrv-tree', now()->addHours(1), function () {
      return TLRVNode::with('children')->where('parent_id', null)->get();
  });
  

Security

• Authorization: Protect /tlrv route in routes/web.php:

  Route::middleware(['auth'])->group(function () {
      Route::get('/tlrv', [TLRVController::class, 'index']);
  });
  

• UID Sanitization: Validate uid input to prevent injection:

  $uid = request()->validate(['uid' => 'required|string|max:255']);