Getting Started

Minimal Setup

Installation:

composer require 21torr/prismic-api

Publish the bundle configuration (if needed):

php artisan vendor:publish --provider="PrismicApi\PrismicApiServiceProvider"

Configuration: Add your Prismic repository name and API token to .env:
```
PRISMIC_REPOSITORY=your-repo-name
PRISMIC_API_TOKEN=your-api-token
```

First Use Case: Fetch a single document by ID:

use PrismicApi\Prismic;

$document = Prismic::query()
    ->document('page', 'your-document-id')
    ->get();

Or search for documents:

$documents = Prismic::query()
    ->documents('page')
    ->get();

Where to Look First

Facade: PrismicApi\Prismic (primary entry point).
Query Builder: Methods like document(), documents(), predicates(), and lang().
Document Transformation: Use transform() or transformField() for custom data shaping.
Configuration: config/prismic.php (if published).

Implementation Patterns

Core Workflows

1. Fetching and Transforming Documents

// Fetch and transform a document
$document = Prismic::query()
    ->document('page', 'page-id')
    ->lang('en-us')
    ->transform() // Applies default transformations
    ->get();

// Transform a specific field
$title = $document->transformField('title');

2. Querying with Predicates

$documents = Prismic::query()
    ->documents('page')
    ->predicates([
        ['at(document.type, "page")'],
        ['at(document.my.date, "2023-01-01T00:00:00+0000")'],
    ])
    ->get();

3. Handling Slices

// Access slices in a document
$slices = $document->get('slices');

// Generate extra data for slices (e.g., for React/Vue)
$sliceExtraData = Prismic::sliceExtraDataGenerator()
    ->generate($slices, 'page');

4. Working with Links and Embeds

// Resolve a link field
$link = $document->get('link_field');
$resolvedLink = $link->getUrl();

// Handle an embed field (e.g., video)
$embed = $document->get('embed_field');
$embed->setUrl('https://new-url.com'); // Using the `wither` method

5. Validation and Data Visitors

// Validate document translations
Prismic::translationCheckVisitor()->validate($document);

// Inspect every dataset with a custom visitor
Prismic::dataVisitor()->visit($document);

Integration Tips

Laravel-Specific Patterns

Service Container Binding: Bind the Prismic API to Laravel’s container for dependency injection:
```
$this->app->bind('prismic', function () {
    return Prismic::query();
});
```

Caching Responses: Cache API responses using Laravel’s cache system:

$documents = Cache::remember('prismic_pages', now()->addHours(1), function () {
    return Prismic::query()->documents('page')->get();
});

Middleware for API Access: Protect Prismic API routes with middleware:

Route::middleware(['auth:sanctum'])->group(function () {
    Route::get('/prismic-data', function () {
        return Prismic::query()->documents('page')->get();
    });
});

Event Listeners for Prismic Updates: Listen to Prismic webhook events (e.g., document updates):

use PrismicApi\Events\DocumentUpdated;

public function handle(DocumentUpdated $event) {
    // Refresh cached data or trigger a job
}

Custom Data Transformers: Extend the default DataTransformer for project-specific needs:

use PrismicApi\Transformer\DataTransformer;

class CustomDataTransformer extends DataTransformer {
    public function transform($data) {
        // Custom logic
        return parent::transform($data);
    }
}

// Register in services.php
$this->app->bind(DataTransformer::class, CustomDataTransformer::class);

Gotchas and Tips

Pitfalls

Deprecation Warning: The package is deprecated (as noted in the README). Evaluate whether to:
- Use the official Prismic PHP SDK instead.
- Fork and maintain this package if it fits your needs better.

Empty Response Handling: The fix in 6.3.6 ensures exceptions are thrown for empty responses. Ensure your error handling accounts for:

try {
    $document = Prismic::query()->document('page', 'id')->get();
} catch (\PrismicApi\Exception\EmptyResponseException $e) {
    // Handle empty response
}

Language-Specific Queries: Omitting a language defaults to *, but ensure your Prismic repository supports this. For unpublished documents:
```
Prismic::query()->documents('page')->unpublished()->get();
```

Slice Extra Data Generation: The SliceExtraDataGenerator requires a slice type (e.g., 'page'). Mismatches will return empty data:

$extraData = Prismic::sliceExtraDataGenerator()->generate($slices, 'wrong-type');
// Returns empty array if 'wrong-type' doesn’t match slice kinds.

Link Resolution in RTE Fields: Links in Rich Text fields (LinkField) must be resolved manually:

$rte = $document->get('rich_text_field');
$resolvedLinks = $rte->getLinks()->map(fn($link) => $link->getUrl());

Caching Quirks: The package does not cache by default. Configure Laravel’s cache drivers (e.g., Redis) for performance:
```
Cache::put('prismic_data', $data, now()->addMinutes(30));
```

Debugging Tips

Enable HTTP Client Logging: The package uses Symfony’s HttpClient, which can be debugged via:
```
$client = Prismic::getHttpClient();
$client->withOptions(['debug' => true]);
```

Validate Predicates: Use Prismic’s predicate tester to debug complex queries. Example:

Prismic::query()
    ->docicuments('page')
    ->predicates(['at(document.my.date, ">=2023-01-01")'])
    ->get();

Check Field Types: Ensure field types (e.g., LinkField, ImageField) are correctly mapped. For example:

if (!$document->has('image_field')) {
    throw new \RuntimeException('Field "image_field" not found.');
}

Handle API Timeouts: The package includes a timeout (configurable in config/prismic.php). Adjust if API responses are slow:
```
Prismic::query()->setTimeout(30); // 30 seconds
```

Extension Points

Custom Data Visitors: Implement DataVisitorInterface to inspect or modify data:

use PrismicApi\Visitor\DataVisitorInterface;

class CustomVisitor implements DataVisitorInterface {
    public function visit($data) {
        // Modify or log data
        return $data;
    }
}

// Register in services.php
$this->app->bind(DataVisitorInterface::class, CustomVisitor::class);

Override URL Rewriting: Extend the UrlRewriter to customize URL generation:

use PrismicApi\Rewriter\UrlRewriter;

class CustomUrlRewriter extends UrlRewriter {
    public function rewrite($url) {
        return str_replace('old-domain', 'new-domain', $url);
    }
}

// Bind in services.php
$this->app->bind(UrlRewriter::class, CustomUrlRewriter::class);

Add Custom Field Transformers: Register additional field types (e.g., for Prismic’s Date or Number fields):

use PrismicApi\Transformer\FieldTransformer;

class CustomFieldTransformer extends FieldTransformer {
    public function transform($data, string $fieldType) {
        if ($fieldType === 'date') {
            return Carbon::parse($

Prismic Api Laravel Package