Ink Laravel Package

Getting Started

Minimal Steps

1. Installation

   composer require relaticle/ink
   php artisan migrate
   

   Register the plugin in AppPanelProvider.php:

   ->plugin(\Relaticle\Ink\InkPlugin::make())
   

2. First Use Case: Headless Blog

   • Use Blade components directly in your views:

     <x-ink::post-header :post="$post" />
     <x-ink::post-body :post="$post" />
     

   • Ensure your Post model is passed to the view (e.g., via a controller or route model binding).

3. First Use Case: Public Routes (Opt-in)

   • Enable in config/ink.php:

     'features' => [
         'public_routes' => true,
     ],
     

   • Access /blog immediately without writing controllers.

Where to Look First

• Documentation: Blade Components for UI integration.
• Filament Admin: Filament Admin Guide for managing posts/categories.
• Configuration: config/ink.php for feature flags and customization.

Implementation Patterns

Workflows

1. Headless Integration

   • Fetching Posts: Use Eloquent queries with built-in scopes:

     use Relaticle\Ink\Models\Post;
     
     $posts = Post::published()->latest()->get();
     

   • SEO: Embed components in your layout:

     @push('head')
         <x-ink::meta-tags :post="$post" />
         <x-ink::structured-data :post="$post" />
     @endpush
     

   • Search: Use the BlogSearch Livewire component:

     <livewire:ink.blog-search />
     

2. Public Routes Mode

   • Routes: Automatically registered at /blog, /blog/{slug}, etc.
   • Customization: Publish views for overrides:

     php artisan vendor:publish --tag=ink-views
     

   • Feed: Enable RSS feed via config:

     'features' => ['feed' => true],
     

3. Filament Admin Workflow

   • Bulk Actions: Publish/unpublish posts in bulk from the Filament UI.
   • Scheduled Posts: Set published_at in the future for scheduling.
   • SEO Management: Edit meta tags directly in the Filament form.

4. MCP Tools for AI

   • AI Agents: Use MCP endpoints to create/update posts programmatically:

     $post = Post::createMcpContext([
         'title' => 'AI-Generated Post',
         'content' => '# Hello from AI!',
     ]);
     

   • Sanitization: Markdown content is automatically sanitized (HTML stripped, unsafe links blocked).

Integration Tips

• MediaLibrary: Enable for featured images:

  'features' => ['media_library' => true],
  

  Requires spatie/laravel-medialibrary and migrations.

• Tags Taxonomy: Enable with:

  'features' => ['tags' => true],
  

  Adds TagResource to Filament and /blog/tag/{slug} routes.

• Sitemap: Integrate with spatie/laravel-sitemap:

  use Relaticle\Ink\Facades\Ink;
  
  return Ink::sitemap()->getSitemap();
  

• Custom Post Model: Extend the base Post model for additional fields/methods:

  class BlogPost extends \Relaticle\Ink\Models\Post
  {
      protected $casts = [
          'custom_field' => 'boolean',
      ];
  }
  

Gotchas and Tips

Pitfalls

1. Public Routes Conflicts

   • If you define custom routes (e.g., Route::get('/blog', ...)), disable public_routes to avoid conflicts:

     'features' => ['public_routes' => false],
     

2. MediaLibrary Migration

   • Flipping media_library to true without installing spatie/laravel-medialibrary is a no-op but may cause confusion. Ensure the package is installed:

     composer require spatie/laravel-medialibrary
     

3. Slug Freezing

   • Post slugs are auto-generated and cannot be manually edited after creation (frozen). To change a slug, delete and recreate the post.

4. Feature Flag Dependencies

   • Some features (