Makhzun Laravel Package

Getting Started

Minimal Steps to Begin

1. Installation

   composer require firumon/makhzun
   

   Publish the package assets and configuration:

   php artisan vendor:publish --provider="Firumon\Makhzun\MakhzunServiceProvider" --tag="migrations"
   php artisan vendor:publish --provider="Firumon\Makhzun\MakhzunServiceProvider" --tag="config"
   php artisan vendor:publish --provider="Firumon\Makhzun\MakhzunServiceProvider" --tag="public"
   php artisan migrate
   

2. First Use Case: Adding a Product

   • Access the /products route (or /inventory if configured differently).
   • Use the provided UI to add a new product (name, SKU, quantity, etc.).
   • Verify the product appears in the inventory list.

3. Where to Look First

   • Configuration: Check config/makhzun.php for customizable settings (e.g., default routes, storage paths).
   • Migrations: Review database/migrations/ for schema details (e.g., products, categories, transactions tables).
   • Routes: Inspect routes/web.php for predefined routes (e.g., products, categories, reports).
   • Blade Views: Explore resources/views/makhzun/ for UI templates (e.g., products/index.blade.php).

Implementation Patterns

Core Workflows

1. Product Management

   • CRUD Operations: Use the built-in UI or manually interact with the Product model:

     use Firumon\Makhzun\Models\Product;
     
     $product = Product::create([
         'name' => 'Laptop',
         'sku' => 'LP-001',
         'quantity' => 10,
         'price' => 999.99,
     ]);
     

   • Bulk Actions: Leverage the UI for bulk updates (e.g., adjusting quantities across multiple products).

2. Inventory Tracking

   • Transactions: Record stock movements (in/out) via the Transaction model:

     use Firumon\Makhzun\Models\Transaction;
     
     Transaction::create([
         'product_id' => $product->id,
         'quantity' => 2,
         'type' => 'out', // 'in' or 'out'
         'reference' => 'Sale #123',
     ]);
     

   • Automatic Updates: The package auto-updates product quantities on transaction creation.

3. Categorization

   • Assign products to categories for better organization:

     $category = \Firumon\Makhzun\Models\Category::create(['name' => 'Electronics']);
     $product->categories()->attach($category);
     

4. Reporting

   • Generate reports (e.g., low-stock alerts, sales summaries) via the /reports route or programmatically:

     $lowStock = \Firumon\Makhzun\Models\Product::where('quantity', '<', 5)->get();
     

Integration Tips

• API Access: Use Laravel’s built-in API resources or create custom ones:

  Route::apiResource('api/products', \Firumon\Makhzun\Http\Controllers\ProductController::class);
  

• Custom Fields: Extend the Product model to add fields (e.g., barcode, expiry_date):

  php artisan make:model ProductExtension -m
  

  Then update migrations and models accordingly.
• Event Listeners: Hook into inventory events (e.g., ProductUpdated, TransactionCreated) for notifications or logging:

  use Firumon\Makhzun\Events\ProductUpdated;
  
  ProductUpdated::dispatch($product);
  

Gotchas and Tips

Pitfalls

1. Migration Conflicts

   • If you’ve customized the products table, reset migrations or manually merge changes before running php artisan migrate.
   • Fix: Backup your database and use php artisan migrate:fresh in a staging environment.

2. Quantity Overflows

   • The package doesn’t enforce negative stock by default. Handle edge cases in transactions:

     if ($product->quantity < $request->quantity && $request->type === 'out') {
         throw new \Exception("Insufficient stock for product {$product->name}.");
     }
     

3. Route Collisions

   • Default routes (e.g., /products) may conflict with existing routes. Override in routes/web.php:

     Route::prefix('admin')->group(function () {
         Route::resource('inventory/products', \Firumon\Makhzun\Http\Controllers\ProductController::class);
     });
     

4. Missing Dependencies

   • Ensure laravel/ui or laravelcollective/html is installed for Blade components (e.g., forms, tables):

     composer require laravelcollective/html
     

Debugging Tips

• Log Transactions: Enable query logging in config/database.php to debug slow inventory operations:

  'log' => env('DB_LOG_QUERIES', false),
  

• Check Middleware: Verify auth or can middleware is applied to sensitive routes (e.g., /products/create).

Extension Points

1. Custom Validation

   • Extend the ProductRequest or TransactionRequest in app/Http/Requests to add rules (e.g., SKU uniqueness):

     public function rules()
     {
         return [
             'sku' => 'required|unique:products,sku,' . $this->product,
         ];
     }
     

2. Storage Backends

   • Override the default storage logic (e.g., switch from database to Redis for caching):

     // config/makhzun.php
     'storage' => [
         'driver' => 'redis',
         'connection' => 'cache',
     ],
     

3. Localization

   • Translate UI strings by publishing language files:

     php artisan vendor:publish --tag=lang
     

   • Update resources/lang/{locale}/makhzun.php.

4. Testing

   • Use Laravel’s testing helpers to assert inventory states:

     $this->assertDatabaseHas('products', ['name' => 'Laptop', 'quantity' => 8]);