Getting Started

Minimal Setup

Installation:
```
composer require larament/seokit
php artisan seokit:install
php artisan migrate
```
- Publishes config (config/seokit.php), migrations, and Blade directives.

First Use Case: In a controller, set SEO metadata for a route:

use Larament\Seokit\Facades\SeoKit;

public function show(Post $post) {
    SeoKit::title($post->title)
          ->description($post->excerpt)
          ->image($post->featured_image)
          ->canonical(route('posts.show', $post));
    return view('posts.show', compact('post'));
}

Render in Blade: Add @seoKit directive to your layout’s <head>:

<!DOCTYPE html>
<html>
<head>
    @seoKit
    <!-- Other meta tags -->
</head>
</html>

Verify Output: View page source to confirm generated <title>, <meta>, Open Graph, and Twitter tags.

Key Starting Points

Facade API: SeoKit::title(), SeoKit::description(), etc. (see wiki/API).
Model Traits: HasSeo and HasSeoData for database-backed SEO (see wiki/Database-Backed-SEO).
Configuration: config/seokit.php (e.g., site_name, default_description).

Implementation Patterns

1. Controller-Driven SEO

Workflow:

Use SeoKit facade in controllers to set dynamic metadata.

Chain methods for clarity:

SeoKit::title("How to Use SeoKit")
      ->description("Learn Laravel SEO best practices with SeoKit.")
      ->image(url('images/seokit-hero.jpg'))
      ->twitterSite("@larament")
      ->ogType('article')
      ->jsonLd([
          '@context' => 'https://schema.org',
          '@type' => 'BlogPosting',
          'headline' => 'SeoKit Guide',
      ]);

Integration Tips:

Route Model Binding: Combine with HasSeo trait for automatic SEO fetching:

public function show(Post $post) {
    SeoKit::useModelFallback($post); // Fallback to model defaults if DB record missing
    return view('posts.show', compact('post'));
}

Middleware: Centralize SEO for guest routes:

SeoKit::title(config('app.name'))
      ->description(config('seokit.default_description'));

2. Model-Backed SEO

Workflow:

Add traits to your model:

use Larament\SeoKit\Traits\HasSeo;
use Larament\SeoKit\Traits\HasSeoData;

class Post extends Model {
    use HasSeo, HasSeoData;
}

Define fallback SEO in the model:

protected function fallbackSeoData(): array {
    return [
        'title' => 'Untitled Post',
        'description' => 'No description available.',
    ];
}

Access SEO via relationships:

$post->seoData; // Returns SeoData model or null

Integration Tips:

Polymorphic Relationships: Use seoable() for shared SEO tables:

public function seoData() {
    return $this->morphOne(SeoData::class, 'seoable');
}

Admin Panels: Integrate with Nova or Filament for SEO CRUD:

// Filament Resource
public static function form(Form $form): Form {
    return $form->schema([
        SeoKit::make('seo_data')->relationship(),
    ]);
}

3. Blade Directives

Patterns:

Dynamic SEO: Use @seoKit in layouts or partials.

Conditional Rendering: Override SEO for specific pages:

@if(request()->is('home'))
    @seoKit(['title' => 'Homepage'])
@else
    @seoKit
@endif

JSON-LD: Render structured data directly:

@seoKit(['jsonLd' => view('partials.schema.org/json-ld')])

4. Caching and Performance

Patterns:

Automatic Caching: SeoKit caches SEO data by default (TTL configurable in config/seokit.php).

Manual Cache Control:

SeoKit::cacheFor(3600); // Cache for 1 hour
SeoKit::forget(); // Clear cache

View Composers: Pre-load SEO for static pages:

public function compose(View $view) {
    $view->withSeo(SeoKit::getCached());
}

5. Inertia.js Integration

Workflow:

Enable Inertia.js support in config/seokit.php:
```
'inertia' => true,
```

SEO is automatically synced with Inertia page titles:

// Inertia Controller
public function show(Post $post) {
    SeoKit::title($post->title);
    return Inertia::render('Posts/Show', ['post' => $post]);
}

Gotchas and Tips

Pitfalls

Missing @seoKit Directive:
- Symptom: No meta tags rendered despite setting SEO in the controller.
- Fix: Ensure @seoKit is placed in the <head> of your layout.
Fallback SEO Not Triggering:
- Cause: HasSeo::prepareSeoTags() requires either a seoData record or a fallbackSeoData() method.
- Fix: Verify the model has:
```
use HasSeo;
protected function fallbackSeoData(): array { ... }
```
Canonical URL Conflicts:
- Cause: Multiple canonical() calls override each other.
- Fix: Set canonical once (e.g., in a middleware or base controller).
JSON-LD Validation Errors:
- Cause: Invalid schema.org syntax.
- Fix: Use Google’s Rich Results Test and validate with:
```
SeoKit::jsonLd($this->validateJsonLd($structuredData));
```
Caching Issues:
- Cause: Stale SEO data due to aggressive caching.
- Fix: Use SeoKit::forget() in critical paths (e.g., after SEO updates):
```
SeoKit::forget(); // Clear cache on SEO model updates
```

Debugging Tips

Inspect Raw SEO Data:
```
dd(SeoKit::getMetaTags()->toArray());
```

Check Cached Data:

SeoKit::getCached(); // Returns cached SEO array

Validate Open Graph/Twitter:
- Use Facebook Sharing Debugger and Twitter Card Validator.

Log SEO Changes:

SeoKit::logChanges(); // Enable in config/seokit.php

Configuration Quirks

site_name Default:
- Falls back to config('app.name') if not set in config/seokit.php.

Locale Support:

Use SeoKit::setLocale('es') for multi-language SEO:

SeoKit::setLocale(request()->locale)
      ->title(__('posts.title'));

Default Description:

Configure in config/seokit.php:

'default_description' => 'Welcome to our site!',

Extension Points

Custom Meta Tags:

Extend MetaTags class or use the extraTags method:

SeoKit::extraTags([
    '<meta name="author" content="John Doe">',
]);

Structured Data Helpers:

Create a helper for common JSON-LD:

function articleJsonLd(Post $post) {
    return [
        '@context' => 'https://schema.org',
        '@type' => 'BlogPosting',
        'headline' => $post->title,
        'datePublished' => $post->published_at->toISOString(),
    ];
}

Event Listeners:
- Trigger SEO updates on model events:
```
Post::updated(function (Post $post) {
```

Seokit Laravel Package

Getting Started

Minimal Setup

Key Starting Points

Implementation Patterns

1. Controller-Driven SEO

2. Model-Backed SEO

3. Blade Directives

4. Caching and Performance

5. Inertia.js Integration

Gotchas and Tips

Pitfalls

Debugging Tips

Configuration Quirks

Extension Points