Item Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require moox/item
   php artisan moox:install
   

   • The moox:install command sets up migrations, models, and basic configurations for the Item entity.

2. First Use Case:

   • Create an Item:

     use Moox\Item\Models\Item;
     
     $item = Item::create([
         'title' => 'My First Item',
         'slug' => 'my-first-item',
         'content' => '# Hello World',
         'type' => 'log', // or any custom type
     ]);
     

   • Retrieve an Item:

     $item = Item::find($item->id);
     echo $item->title; // Outputs: "My First Item"
     

3. Where to Look First:

   • Documentation: Start with the Get Started guide.
   • Migrations: Check database/migrations/ for the items table structure.
   • Model: Inspect app/Models/Moox/Item.php for available methods and relationships.

Implementation Patterns

Usage Patterns

1. CRUD Operations:

   • Create: Use Item::create() with an associative array of fields (e.g., title, content, type).
   • Update: Use Item::find($id)->update([...]) or $item->update([...]).
   • Delete: Use $item->delete() or Item::destroy($id).

2. Relationships:

   • Author (User):

     $item = Item::with('author')->find($id);
     $item->author->name; // Access user details
     

   • Taxonomies:

     $item->taxonomies()->attach(['category_id' => 1, 'tag_id' => 2]);
     $item->taxonomies; // Collection of taxonomy models
     

   • Relations:

     $item->relations()->attach(['related_item_id' => 3]);
     

3. Content Management:

   • Markdown Content:

     $item->content = "# Heading\n\nThis is **markdown**.";
     $item->save();
     

   • Render Markdown: Use a package like parsedown to convert markdown to HTML:

     use Parsedown;
     $parsedown = new Parsedown();
     echo $parsedown->text($item->content);
     

4. Data Key-Value Pairs:

   $item->data = ['key1' => 'value1', 'key2' => 'value2'];
   $item->save();
   // Access later:
   $item->data->key1; // Outputs: "value1"
   

5. Active Toggle:

   $item->active = false; // Disable item
   $item->save();
   // Query active items:
   Item::where('active', true)->get();
   

6. Media (Image):

   $item->image()->attach($mediaId); // Attach existing media
   // Or upload directly (if using a media library like Spatie Media Library):
   $item->addMediaFromRequest('image')->toMediaCollection('images');
   

7. Sections:

   $item->section = 'news'; // Assign to a section
   $item->save();
   // Query items by section:
   Item::where('section', 'news')->get();
   

Workflows

1. Logging System:

   • Create a log type item for system logs:

     Item::create([
         'title' => 'Login Attempt',
         'type' => 'log',
         'content' => 'User `john` logged in at ' . now(),
         'data' => ['ip' => request()->ip(), 'user_agent' => request()->userAgent()],
     ]);
     

2. Content Management System (CMS):

   • Use Item as a flexible CMS entry with content (markdown), type (e.g., article, page), and taxonomies (categories/tags).
   • Example:

     $article = Item::create([
         'title' => 'Laravel 10 Features',
         'slug' => 'laravel-10-features',
         'content' => '# Laravel 10\n\nNew features...',
         'type' => 'article',
         'section' => 'blog',
     ]);
     $article->taxonomies()->attach(['category_id' => 1]); // Attach category
     

3. Task Management:

   • Use due (datetime), type (e.g., task), and color for visual distinction:

     $task = Item::create([
         'title' => 'Finish Project',
         'type' => 'task',
         'due' => now()->addDays(7),
         'color' => '#FF5733',
     ]);
     

Integration Tips

1. Laravel Scout:

   • Enable full-text search for title, content, etc.:

     use Moox\Item\Models\Item;
     use Laravel\Scout\Searchable;
     
     class Item extends Model implements Searchable
     {
         public function toSearchableArray()
         {
             return [
                 'title' => $this->title,
                 'content' => $this->content,
                 'type' => $this->type,
             ];
         }
     }
     

   • Index items:

     php artisan scout:import "App\Models\Moox\Item"
     

2. API Resources:

   • Create a custom resource for API responses:

     php artisan make:resource ItemResource
     

     // app/Http/Resources/ItemResource.php
     public function toArray($request)
     {
         return [
             'id' => $this->id,
             'title' => $this->title,
             'slug' => $this->slug,
             'content' => $this->content,
             'type' => $this->type,
             'due' => $this->due,
             'author' => AuthorResource::make($this->author),
         ];
     }
     

3. Form Requests:

   • Validate incoming data for items:

     php artisan make:request StoreItemRequest
     

     // app/Http/Requests/StoreItemRequest.php
     public function rules()
     {
         return [
             'title' => 'required|string|max:255',
             'content' => 'nullable|string',
             'type' => 'required|string',
             'due' => 'nullable|date',
         ];
     }
     

4. Events:

   • Listen for item creation/updates:

     // app/Providers/EventServiceProvider.php
     protected $listen = [
         'Moox\Item\Events\ItemCreated' => [
             'App\Listeners\LogItemCreation',
         ],
     ];
     

5. Policies:

   • Restrict access to items:

     php artisan make:policy ItemPolicy --model=Item
     

     // app/Policies/ItemPolicy.php
     public function update(User $user, Item $item)
     {
         return $user->id === $item->author_id;
     }
     

Gotchas and Tips

Pitfalls

1. UUID/ULID Conflicts:

   • The Item model uses both uuid and ulid as identifiers. Ensure your database supports these types (e.g., char(36) for UUID, binary(16) for ULID).
   • If conflicts arise, explicitly cast the IDs in your queries:

     Item::where('uuid', $uuid)->first();
     // or
     Item::where('ulid', $ulid)->first();
     

2. Media Handling:

   • If using image or other media fields, ensure the spatie/laravel-medialibrary package is installed and configured. The moox:install command may not cover this automatically.
   • Example setup:

     composer require spatie/laravel-medialibrary
     php artisan vendor:publish --provider="Spatie\MediaLibrary\MediaLibraryServiceProvider"
     

3. Taxonomy Relationships:

   • Taxonomies are many-to-many relationships. Ensure the pivot table (item_taxonomies) exists and is properly linked. Run migrations if needed:

     php artisan migrate
     

4. Slug Generation:

   • Slugs are auto-generated from titles. Override this behavior by passing a slug in the create or update array. Conflicts may arise if slugs are not unique:

     $item = Item::create([
         'title' => 'New Post',
         'slug' => 'custom-slug', // Override auto-generated slug
     ]);
     

5. Active Toggle:

   • The `