Elements Laravel Package

Getting Started

First Steps

1. Installation

   • Require the package via Composer:

     composer require milestone/elements
     

   • Publish the configuration file (if available):

     php artisan vendor:publish --provider="Milestone\Elements\ElementsServiceProvider" --tag="config"
     

   • Run migrations (if applicable):

     php artisan migrate
     

2. Initial Setup

   • Register the service provider in config/app.php under providers:

     Milestone\Elements\ElementsServiceProvider::class,
     

   • Check the config/elements.php file for required API keys, endpoints, or business logic configurations.

3. First Use Case: Creating a Quotation

   • Use the facade or service container to generate a basic quotation:

     use Milestone\Elements\Facades\Elements;
     
     $quotation = Elements::createQuotation([
         'client_id' => 1,
         'items' => [
             ['product_id' => 1, 'quantity' => 2, 'price' => 10.99],
             ['product_id' => 2, 'quantity' => 1, 'price' => 25.50],
         ],
     ]);
     

   • Save the quotation to the database (if applicable):

     $quotation->save();
     

Implementation Patterns

Core Workflows

1. Quotation Management

   • Create: Use Elements::createQuotation() with an array of items.
   • Retrieve: Fetch a quotation by ID:

     $quotation = Elements::getQuotation($id);
     

   • Update: Modify items or metadata:

     $quotation->updateItems([...]);
     

   • Send: Email or notify stakeholders (if integrated):

     $quotation->send();
     

2. Product Integration

   • Fetch products from an external source (e.g., API or database):

     $products = Elements::getProducts(['category' => 'electronics']);
     

   • Attach products to a quotation dynamically:

     $quotation->addProduct($productId, $quantity);
     

3. Business Logic Hooks

   • Use events or observers for custom logic (e.g., discounts, taxes):

     // Example: Apply a 10% discount if total exceeds $1000
     Elements::quotationCreated(function ($quotation) {
         if ($quotation->total > 1000) {
             $quotation->applyDiscount(0.10);
         }
     });
     

4. API Integration

   • If the package interacts with an external API, use Laravel’s HTTP client:

     $response = Http::withHeaders([
         'Authorization' => 'Bearer ' . config('elements.api_token'),
     ])->post('https://api.elements.example/quotes', $data);
     

Integration Tips

• Database Sync: Ensure the package’s models (e.g., Quotation, Product) align with your existing schema. Extend them if needed:

  class CustomQuotation extends \Milestone\Elements\Models\Quotation {
      protected $table = 'custom_quotes';
  }
  

• Service Container Binding: Override bindings for custom implementations:

  $this->app->bind(
      \Milestone\Elements\Contracts\QuotationRepository::class,
      \App\Repositories\CustomQuotationRepository::class
  );
  

• Middleware: Protect quotation routes or actions with middleware (e.g., auth, role):

  Route::middleware(['auth', 'can:manage.quotes'])->group(function () {
      Route::resource('quotes', \Milestone\Elements\Http\Controllers\QuotationController::class);
  });
  

Gotchas and Tips

Common Pitfalls

1. Deprecated Methods

   • The package was last updated in 2022. Check for deprecated methods or renamed classes in the source code. Example:

     // Old way (if exists)
     Elements::makeQuotation();
     
     // New way (hypothetical)
     Elements::createQuotation();
     

2. Missing Configuration

   • Ensure config/elements.php is properly set up with API keys, endpoints, or database connections. Example:

     'api' => [
         'base_url' => env('ELEMENTS_API_URL', 'https://api.elements.example'),
         'token' => env('ELEMENTS_API_TOKEN'),
     ],
     

3. Database Migrations

   • If the package includes migrations, run them before using models:

     php artisan migrate
     

   • If conflicts arise, manually adjust the migrations or use --force (caution advised).

4. Event System

   • The package may rely on Laravel events (e.g., QuotationCreated). Listen for them in EventServiceProvider:

     protected $listen = [
         \Milestone\Elements\Events\QuotationCreated::class => [
             \App\Listeners\ApplyDiscount::class,
         ],
     ];
     

Debugging Tips

• Log API Responses: Wrap API calls in a try-catch block to log errors:

  try {
      $response = Http::post(...);
  } catch (\Throwable $e) {
      \Log::error('Elements API Error: ' . $e->getMessage());
  }
  

• DD() for Inspection: Use Laravel’s dd() to inspect objects:

  $quotation = Elements::getQuotation(1);
  dd($quotation->toArray());
  

• Package Isolation: Test the package in a fresh Laravel install to rule out conflicts with other packages.

Extension Points

1. Custom Fields
   • Extend the Quotation model to add custom attributes:

     class Quotation extends \Milestone\Elements\Models\Quotation {
         protected $casts = [
             'custom_field' => 'string',
         ];
     }
     

2. API Overrides
   • Override the HTTP client configuration for testing or custom logic:

     $this->app->singleton(\Illuminate\Http\Client\PendingRequest::class, function () {
         return Http::baseUrl(config('elements.test_api_url'));
     });
     

3. Views and Notifications
   • Publish and customize views/notifications:

     php artisan vendor:publish --tag="elements-views"
     

   • Override the email template for quotations:

     // resources/views/vendor/elements/emails/quotation.blade.php