Download the PHP package timjohnbancroft/constructor-laravel without Composer
On this page you can find all versions of the php package timjohnbancroft/constructor-laravel. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Download timjohnbancroft/constructor-laravel
More information about timjohnbancroft/constructor-laravel
Files in timjohnbancroft/constructor-laravel
Package constructor-laravel
Short Description Laravel integration for Constructor.io - AI-powered search, recommendations, and shopping agents
License MIT
Homepage https://github.com/timjohnbancroft/constructor-laravel
Informations about the package constructor-laravel
Constructor.io Laravel Integration
A Laravel package for Constructor.io - AI-powered product discovery.
Features
- Product Search - Full-text search with filters, sorting, pagination
- Category Browse - Browse products by category or facet
- Autocomplete - Search suggestions and product previews with zero-state support
- AI Shopping Agent - Natural language product discovery ("I need a gift for my mom")
- Product Insights Agent - AI-powered Q&A on product detail pages
- Recommendations - Personalized product recommendations
- Collections - Browse curated product collections
- Catalog Management - Bulk catalog uploads (CSV, JSONL)
- Backend Integration - Automatic forwarding of user context headers and cookies for server-side API calls
- Laravel Scout - Full Scout engine integration
Architecture Overview
Requirements
- PHP 8.1+
- Laravel 10.x, 11.x, or 12.x
- Constructor.io account (constructor.io)
Installation
1. Install via Composer
2. Publish Configuration
3. Configure Environment
Add to your .env file:
Get your credentials from the Constructor.io Dashboard.
Credential Types:
- API Key (public): Identifies your index, used for search/browse/autocomplete requests
- API Token (secret): Used for authenticated operations like catalog uploads
Quick Start
Search Products
Browse by Category
Autocomplete
Recommendations
Collections
AI Shopping Agent
Product Insights Agent
Catalog Management
Recipes (If Configured)
Data Transfer Objects (DTOs)
All search operations return strongly-typed DTOs with convenient methods.
SearchResults
Returned by search(), browse(), and browseCollection().
Facets Structure:
AutocompleteResults
Returned by autocomplete() and getZeroStateData().
RecommendationResults
Returned by getRecommendations() and getItemRecommendations().
Complete Facade Methods Reference
Search Options Reference
Options available for search() and browse():
Laravel Scout Integration
Register the Engine
The package automatically registers the constructor Scout driver. Configure in config/scout.php:
Make Models Searchable
Search with Scout
Configuration Reference
config/constructor.php
Available Services
| Service | Description |
|---|---|
ConstructorSandboxSearch |
Search, browse, autocomplete, recommendations, collections |
ConstructorAgentService |
AI Shopping Agent and Product Insights Agent |
ConstructorService |
Catalog uploads, task monitoring, admin operations |
ConstructorEngine |
Laravel Scout engine implementation |
Error Handling
The package handles errors gracefully:
- Search errors return empty
SearchResults(logged at error level) - Recommendation errors return empty
RecommendationResults(logged at error level) - Agent errors throw exceptions (for UI error handling)
- Catalog errors throw exceptions (for background job handling)
Troubleshooting
"Constructor.io configuration not properly set"
Ensure all required environment variables are set:
Empty results when products should exist
- Check API key: Verify the API key matches your Constructor index
- Check section name: Default is 'Products', ensure your index uses this
- Check filters: Some filters may be too restrictive
- View logs: Check
storage/logs/laravel.logfor API errors
Facets not returning
- Facets must be configured in the Constructor.io dashboard
- Not all indexes have facets enabled
- Try a broader search query to see available facets
Recommendations returning empty
- Verify the pod ID exists in your Constructor account
- Some pods require
item_id- usegetItemRecommendations()instead - Check that the pod has been trained with data
Agent authentication failures
- Ensure
CONSTRUCTOR_AGENT_DOMAINis set correctly - The agent domain is separate from the search API key
Rate limit errors
- Implement caching for repeated requests
- Contact Constructor.io to increase limits for production
Testing Your Integration
Artisan Test Command
Unit Testing
Mock the facade for testing:
Best Practices
Caching Recommendations
User Personalization
Pass user identifiers for personalized results:
Handling Zero-State Gracefully
Documentation
- Constructor.io Documentation
- Search API Reference
- Browse API Reference
- Autocomplete API Reference
- Recommendations API Reference
- AI Shopping Agent API Reference
License
MIT License. See LICENSE for details.
All versions of constructor-laravel with dependencies
illuminate/support Version ^10.0|^11.0|^12.0
illuminate/http Version ^10.0|^11.0|^12.0
guzzlehttp/guzzle Version ^7.0