Getting Started

Minimal Setup

Installation
```
composer require reprovinci/solr-php-client
```
Ensure your composer.json includes "minimum-stability": "dev" if using unreleased versions.
Basic Client Initialization
```
use SolrPhpClient\Client;

$client = new Client('http://localhost:8983/solr/');
```
- Replace the URL with your Solr core URL (e.g., http://localhost:8983/solr/core_name/).

First Query

$response = $client->query('search_term');
$results = $response->getResponse()->getResponse()->getDocs();

Iterate over $results to access documents.

Document Indexing

$doc = new \SolrPhpClient\Document\Document();
$doc->addField('title', 'Sample Title');
$doc->addField('content', 'Sample content...');

$client->addDocument($doc);
$client->commit();

Key Files to Explore

src/SolrPhpClient/: Core classes for client, document, and response handling.
tests/: Example use cases and edge-case testing.

Implementation Patterns

Common Workflows

1. Searching with Filters

$query = $client->createQuery();
$query->setQuery('search_term');
$query->addFilterQuery('category:books'); // Facet or filter
$response = $client->query($query);

2. Paginated Results

$query->setStart(0)->setRows(10); // Page 1, 10 items
$results = $client->query($query)->getResponse()->getDocs();

3. Faceted Search

$query->setFacet(true);
$query->addFacetField('author'); // Facet by author
$query->addFacetField('category');
$facetResults = $client->query($query)->getFacetSets();

4. Bulk Indexing

$docs = [];
foreach ($products as $product) {
    $doc = new \SolrPhpClient\Document\Document();
    $doc->addField('id', $product['id']);
    $doc->addField('name', $product['name']);
    $docs[] = $doc;
}
$client->addDocuments($docs);
$client->commit();

5. Custom Solr Parameters

$query->setParam('defType', 'edismax');
$query->setParam('qf', 'title^2 content');

Integration Tips

Laravel Service Provider: Bind the client to the container for dependency injection:

$this->app->singleton('solr', function () {
    return new Client(config('solr.url'));
});

Use in controllers:

$results = app('solr')->query('term')->getResponse()->getDocs();

Eloquent Model Observers: Trigger Solr updates on model events (e.g., saved):

class ProductObserver {
    public function saved(Product $product) {
        $doc = new \SolrPhpClient\Document\Document();
        $doc->addField('id', $product->id);
        $doc->addField('name', $product->name);
        app('solr')->addDocument($doc);
        app('solr')->commit();
    }
}

Caching Responses: Cache frequent queries (e.g., autocomplete suggestions) using Laravel’s cache:

$cacheKey = "solr_autocomplete_{$term}";
$results = cache($cacheKey, function () use ($client, $term) {
    return $client->query($term)->getResponse()->getDocs();
}, now()->addMinutes(10));

Gotchas and Tips

Pitfalls

Deprecated Methods:

Avoid SolrPhpClient\Client::query() with raw strings. Use createQuery() for flexibility:

// ❌ Avoid (deprecated)
$client->query('term');

// ✅ Use
$query = $client->createQuery()->setQuery('term');

Solr Version Mismatches:
- The package supports Solr 3/4 but may behave differently. Test with your Solr version.
- Enable debug logging if issues arise:
```
$client->setDebug(true);
```
Connection Timeouts:
- Solr timeouts can cause silent failures. Configure retries or timeouts:
```
$client->setTimeout(30); // 30 seconds
```
Document Field Types:
- Solr schema mismatches (e.g., sending a string to a date field) cause errors. Validate fields against your schema.
Commit Behavior:
- commit() is not auto-flushed. Explicitly call it after bulk operations:
```
$client->addDocuments($docs);
$client->commit(); // Required!
```

Debugging Tips

Enable Debug Mode:
```
$client->setDebug(true);
```
Check logs for raw Solr requests/responses.
Validate Schema: Use Solr’s admin UI (http://localhost:8983/solr/#/) to verify field types and configurations.

Handle Exceptions: Wrap Solr calls in try-catch:

try {
    $response = $client->query($query);
} catch (\SolrPhpClient\Exception\SolrConnectionException $e) {
    Log::error("Solr connection failed: " . $e->getMessage());
    // Fallback to local cache or alternative data source
}

Extension Points

Custom Response Handlers: Extend \SolrPhpClient\Response\Response to parse non-standard Solr responses:

class CustomResponse extends \SolrPhpClient\Response\Response {
    public function getCustomData() {
        return $this->getResponse()->getParam('custom_field');
    }
}

Query Builders: Create reusable query builders for complex searches:

class ProductQueryBuilder {
    public static function getFeaturedQuery() {
        $query = (new Client())->createQuery();
        $query->setQuery('featured:true');
        $query->setFacet(true);
        return $query;
    }
}

Event Listeners: Listen for Solr events (e.g., post-commit hooks) using Laravel’s event system:

// In EventServiceProvider
protected $listen = [
    'solr.committed' => [
        \App\Listeners\UpdateSearchIndex::class,
    ],
];

Testing: Use Laravel’s HTTP testing to mock Solr responses:

$this->mock(\SolrPhpClient\Client::class, function ($mock) {
    $mock->shouldReceive('query')
         ->andReturn((new \SolrPhpClient\Response\Response())
             ->setResponse(['response' => ['docs' => []]]));
});

Configuration Quirks

Default Core: The client defaults to the root core (/). Specify a core explicitly:
```
$client = new Client('http://localhost:8983/solr/core_name/');
```
Authentication: For secured Solr instances, pass credentials:
```
$client = new Client('http://user:pass@localhost:8983/solr/');
```
Or use HTTP basic auth middleware in Laravel.
HTTPS: Ensure your Solr server uses valid certificates. Disable SSL verification only for testing:
```
$client->setUseCurl(false); // Fallback to streams (less secure)
```

Solr Php Client Laravel Package