README

RankForge

Enterprise-Grade SEO & Generative Engine Optimization (GEO) Engine for Laravel 11, 12, and 13.

Overview

RankForge bridges traditional search engine optimization (Google, Bing) and modern Generative Engine Optimization (GEO) for AI crawlers (ChatGPT Search, Perplexity, Claude, Apple Intelligence).

Designed for high-throughput applications, RankForge combines an ergonomic fluent API, strongly-typed Schema.org JSON-LD generation, memory-safe streaming sitemaps, automated /llms.txt compilation, and native Model Context Protocol (MCP) support for AI coding assistants.

Core Highlights

🏷️ Dynamic Meta Tags Engine: Configurable title templates, separators, word-boundary truncation, sanitized descriptions, keywords, robots directives, and canonical URLs with query parameter filtering.
📱 Social Graph & Rich Media: OpenGraph (articles, images with dimensions/alt/type, multi-locale) and Twitter/X Cards with fallback cascading.
📜 Strongly-Typed JSON-LD: Schema.org compliant generators for WebSite, Organization, LocalBusiness, BreadcrumbList, Article, BlogPosting, NewsArticle, Product, Offer, FAQPage, HowTo, and SoftwareApplication with a cohesive @graph builder.
🗺️ Scalable XML Sitemaps: Automatic 50,000 URL / 50 MB chunking, memory-safe Eloquent cursors, image/video/news/hreflang extensions, and instant IndexNow search engine pinging.
🤖 Generative Engine Optimization (GEO): Native /llms.txt and /llms-full.txt generators to present clean, structured Markdown summaries to LLMs.
🔌 Model Context Protocol (MCP): Built-in MCP server (php artisan rankforge:mcp) allowing Claude Desktop, Cursor, and AI agents to audit and interact with your application's SEO engine.
⚡ Headless & Inertia.js Ready: Full JSON serialization (toArray(), toJson()) for Vue 3, React, Next.js, and Nuxt frontends alongside the @rankforgeHead Blade directive.
🛡️ Environment-Safe Indexing: Automatic enforcement of noindex, nofollow in local, testing, and staging environments to prevent staging leakage.

Requirements

Platform	Minimum Version	Supported
PHP	`^8.2`	`8.2`, `8.3`, `8.4`
Laravel	`^11.0`	`11.x`, `12.x`, `13.x`

Installation

Install RankForge via Composer:

composer require eamirgh/rankforge

Publish the configuration file and views:

php artisan rankforge:install

This publishes config/rankforge.php and view templates to resources/views/vendor/rankforge/.

Quick Start

1. Blade Layout

Include the @rankforgeHead directive inside your <head> section:

<!DOCTYPE html>
<html lang="{{ str_replace('_', '-', app()->getLocale()) }}">
<head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">

    {{-- Renders all SEO meta tags, OpenGraph, Twitter Cards, and JSON-LD --}}
    @rankforgeHead

    @vite(['resources/css/app.css', 'resources/js/app.js'])
</head>
<body>
    @yield('content')
</body>
</html>

2. Controller Usage

Configure metadata fluently within any controller or route:

namespace App\Http\Controllers;

use App\Models\Post;
use Eamirgh\RankForge\Facades\RankForge;
use Eamirgh\RankForge\Schema\Types\BlogPosting;
use Illuminate\View\View;

class PostController extends Controller
{
    public function show(Post $post): View
    {
        RankForge::title($post->title)
            ->description($post->excerpt)
            ->canonical(route('posts.show', $post))
            ->keywords($post->tags->pluck('name')->toArray())
            ->ogImage(
                url: $post->featured_image_url,
                width: 1200,
                height: 630,
                alt: $post->title
            )
            ->articlePublishedTime($post->published_at)
            ->articleAuthor($post->author->name)
            ->articleSection($post->category->name)
            ->jsonLd(
                BlogPosting::make()
                    ->headline($post->title)
                    ->description($post->excerpt)
                    ->image($post->featured_image_url)
                    ->datePublished($post->published_at)
                    ->dateModified($post->updated_at)
                    ->author($post->author->name)
                    ->publisher(config('app.name'), logo: asset('images/logo.png'))
            );

        return view('posts.show', compact('post'));
    }
}

3. Automatic Model Fallback

Alternatively, pass your Eloquent model directly using forModel(). RankForge inspects the model for SEO getters/attributes and JSON-LD traits automatically:

public function show(Post $post): View
{
    RankForge::forModel($post);

    return view('posts.show', compact('post'));
}

Example Application

Explore a complete, production-ready Laravel application implementing RankForge (dynamic meta tags, Schema.org JSON-LD, XML sitemaps, llms.txt, and MCP):

👉 github.com/eamirgh/rankforge-blog-example

Detailed Features

1. Dynamic Meta Tags Engine

Title Management

RankForge::title('Cloud Hosting');
// Output: <title>Cloud Hosting | Acme Enterprise</title>

Templates: Configurable pattern ({title} {separator} {site_name}).
Separators: |, —, •, -.
Truncation: Automatic word-boundary truncation to recommended character lengths (default: 60 chars).
Warnings: Query character threshold warnings via RankForge::hasTitleWarning() and RankForge::getTitleWarning().

Descriptions & Keywords

RankForge::description('Deploy scalable Laravel apps in seconds.')
    ->keywords(['laravel', 'hosting', 'cloud']);

Descriptions are stripped of HTML tags, whitespace-normalized, and truncated to 160 characters.
Keywords accept either arrays or comma-separated strings and are deduplicated with configuration defaults.

Robots Directives

RankForge::index();
RankForge::noindex();
RankForge::follow();
RankForge::nofollow();
RankForge::noarchive();
RankForge::nosnippet();
RankForge::maxSnippet(160);
RankForge::maxImagePreview('large'); // 'none', 'standard', 'large'
RankForge::maxVideoPreview(30);

// Custom bot directives
RankForge::customRobots('googlebot', 'max-snippet:100');

Canonical URLs & Query Filtering

RankForge::canonical('https://example.com/shop?utm_source=fb&gclid=123&sort=price');
// Output: <link rel="canonical" href="https://example.com/shop?sort=price">

Strips tracking parameters (utm_*, fbclid, gclid, ref, etc.).
Supports both blacklist (strip_query_params) and whitelist (whitelist_query_params) modes.
Configurable trailing slash enforcement.

Hreflang & Internationalization

RankForge::hreflang('en-US', 'https://example.com/pricing')
    ->hreflang('es-ES', 'https://example.com/es/precios')
    ->hreflang('fr-FR', 'https://example.com/fr/tarifs')
    ->xDefault('https://example.com/pricing');

2. Social Media Cards

Open Graph

RankForge::ogTitle('RankForge Launch')
    ->ogDescription('Explore modern SEO for Laravel.')
    ->ogType('article')
    ->ogImage(
        url: 'https://example.com/og.jpg',
        width: 1200,
        height: 630,
        alt: 'Banner',
        type: 'image/jpeg'
    )
    ->ogLocaleAlternate(['es_ES', 'fr_FR'])
    ->articlePublishedTime(now())
    ->articleAuthor('Amir Ghaffari')
    ->articleSection('Technology')
    ->articleTags(['laravel', 'seo']);

Twitter / X Cards

RankForge::twitterCard('summary_large_image') // 'summary', 'summary_large_image', 'app', 'player'
    ->twitterSite('@rankforge')
    ->twitterCreator('@eamirgh')
    ->twitterImage('https://example.com/twitter.jpg', alt: 'Feature Banner');

3. JSON-LD Structured Data Engine

All Schema types strictly adhere to Schema.org standards:

use Eamirgh\RankForge\Schema\Types\WebSite;
use Eamirgh\RankForge\Schema\Types\LocalBusiness;
use Eamirgh\RankForge\Schema\Types\Product;
use Eamirgh\RankForge\Schema\Types\Offer;
use Eamirgh\RankForge\Schema\Types\FAQPage;
use Eamirgh\RankForge\Schema\Types\BreadcrumbList;

// WebSite with Sitelinks Searchbox
RankForge::jsonLd(
    WebSite::make()
        ->name('Acme Inc')
        ->url('https://example.com')
        ->searchAction('https://example.com/search?q={search_term_string}')
);

// E-commerce Product & Offer
RankForge::jsonLd(
    Product::make()
        ->name('Noise-Cancelling Headphones')
        ->sku('AUDIO-400')
        ->brand('SonicSound')
        ->offers(
            Offer::make()
                ->price(249.99)
                ->priceCurrency('USD')
                ->availability('https://schema.org/InStock')
                ->priceValidUntil(now()->addYear())
        )
        ->aggregateRating(ratingValue: 4.8, reviewCount: 350)
);

// Breadcrumbs from URL segments
RankForge::jsonLd(
    BreadcrumbList::fromUrl('https://example.com/docs/getting-started/installation')
);

// Dynamic FAQ Page
RankForge::jsonLd(
    FAQPage::make()
        ->addQuestion('Does RankForge support Laravel 13?', 'Yes, Laravel 11, 12, and 13 are supported.')
        ->addQuestion('Does it support Inertia.js?', 'Yes, via toArray() and toJson() serialization.')
);

Schema Graph Builder (`@graph`)

Link multiple entities in a single cohesive graph:

use Eamirgh\RankForge\Schema\Graph;

$graph = Graph::make()
    ->add($organization)
    ->add($website)
    ->add($article);

RankForge::jsonLd($graph);

4. XML Sitemaps & IndexNow

Built for high-volume catalogs without memory exhaustion.

Registering Sources

use Eamirgh\RankForge\Facades\RankForge;
use Eamirgh\RankForge\Sitemap\SitemapUrl;
use App\Models\Product;

RankForge::sitemap()->register('products', function () {
    return Product::query()
        ->where('is_active', true)
        ->cursor()
        ->map(fn (Product $p) => SitemapUrl::make(route('products.show', $p))
            ->lastmod($p->updated_at)
            ->changefreq('daily')
            ->priority(0.9)
            ->image($p->featured_image_url, $p->name)
        );
});

Automatic Chunking: Auto-splits when exceeding 50,000 URLs or 50 MB (sitemap.xml, sitemap-products-1.xml, etc.).
Extensions: Full support for <image:image>, <video:video>, <news:news>, and <xhtml:link rel="alternate">.
Automatic Cache Invalidation: Add use InvalidatesSitemapCache; to your Eloquent models to clear the sitemap cache on saved and deleted.

Instant IndexNow Pinging

Submit updated URLs directly to Microsoft Bing and Yandex:

RankForge::indexNow()->submit([
    'https://example.com/posts/new-post',
    'https://example.com/products/updated-product',
]);

5. Crawlers: `robots.txt` & `llms.txt` (GEO)

Dynamic `robots.txt`

Served at /robots.txt:

Non-Production: Automatically returns User-agent: * Disallow: / in local, staging, and testing.
Production: Serves configured allow/disallow paths, bot rules (Googlebot, Bingbot), and AI crawler policies (GPTBot, ClaudeBot, PerplexityBot, CCBot, Google-Extended).

`llms.txt` & `llms-full.txt` (Generative Engine Optimization)

Served at /llms.txt and /llms-full.txt:

RankForge::llmsTxt()
    ->title('Acme Developer Platform')
    ->description('Official API documentation and architectural guides.')
    ->addSection('Guides', 'Key guides', [
        ['title' => 'Quickstart', 'url' => 'https://example.com/quickstart', 'description' => '5-minute setup'],
    ])
    ->addDirectory(base_path('docs'), 'https://example.com/docs');

6. Model Context Protocol (MCP) Server

RankForge provides a built-in, native MCP server over stdio for AI assistants (Claude Desktop, Cursor, Windsurf, Zed):

php artisan rankforge:mcp

MCP Tools Provided to LLMs:

check_seo_health: Runs an automated SEO health audit.
get_llms_txt: Generates semantic Markdown context (/llms.txt or /llms-full.txt).
get_robots_txt: Returns active robots.txt directives.
get_sitemap: Queries root sitemap index or specific chunked sections.
inspect_html_meta: Parses and audits SEO metadata from raw HTML.
submit_indexnow: Submits URLs to IndexNow.

MCP Resources:

rankforge://llms.txt (text/markdown)
rankforge://llms-full.txt (text/markdown)
rankforge://robots.txt (text/plain)
rankforge://sitemap.xml (application/xml)

7. Headless & Inertia.js (Vue 3 / React)

Share in Middleware

namespace App\Http\Middleware;

use Eamirgh\RankForge\Facades\RankForge;
use Inertia\Middleware;

class HandleInertiaRequests extends Middleware
{
    public function share(Request $request): array
    {
        return array_merge(parent::share($request), [
            'seo' => fn () => RankForge::toArray(),
        ]);
    }
}

Vue 3 (`<Head>`)

<script setup>
import { Head, usePage } from '@inertiajs/vue3';
const { props } = usePage();
</script>

<template>
  <Head>
    <title>{{ props.seo.title }}</title>
    <meta name="description" :content="props.seo.description" />
    <meta name="robots" :content="props.seo.robots" />
    <link v-if="props.seo.canonical" rel="canonical" :href="props.seo.canonical" />

    <meta v-for="(val, key) in props.seo.open_graph" :key="key" :property="`og:${key}`" :content="val" />
    <meta v-for="(val, key) in props.seo.twitter" :key="key" :name="`twitter:${key}`" :content="val" />

    <component
      :is="'script'"
      v-for="(schema, i) in props.seo.json_ld"
      :key="i"
      type="application/ld+json"
      v-html="JSON.stringify(schema)"
    />
  </Head>
</template>

Artisan Command Palette

Command	Description
`php artisan rankforge:install`	Publishes package configuration and Blade views
`php artisan rankforge:sitemap:generate`	Pre-renders XML sitemaps to disk storage
`php artisan rankforge:sitemap:ping`	Pings search engines and IndexNow with updated sitemaps
`php artisan rankforge:robots:generate`	Generates physical `robots.txt` file to `public/`
`php artisan rankforge:llms:generate`	Compiles physical `llms.txt` and `llms-full.txt` files
`php artisan rankforge:check`	Audits SEO health (title, description, robots, sitemaps, JSON-LD)
`php artisan rankforge:mcp`	Starts the Model Context Protocol (MCP) server over stdio

Performance Benchmarks

Measured on PHP 8.4:

Benchmark Feature	Throughput	Average Latency	Peak Memory
Meta Tags Rendering (`renderHead`)	~7,000 ops/sec	0.15 ms/op	2.00 MB
JSON-LD `@graph` Serialization	~55,000 ops/sec	0.02 ms/op	~0.00 MB
BreadcrumbList URL Parsing	~95,000 ops/sec	0.01 ms/op	~0.00 MB
50,000 URL XML Sitemap Generation	~105,000 URLs/sec	0.48 s (14.5 MB XML)	35.1 MB
Canonical URL Filtering (Wildcards & Whitelist)	~120,000 ops/sec	0.008 ms/op	14.5 MB
Robots.txt Rule Engine (Multi-Agent & AI Bots)	~72,000 ops/sec	0.014 ms/op	14.5 MB
LLMs.txt & LLMs-Full.txt Compilation (GEO)	~58,000 ops/sec	0.017 ms/op	14.5 MB
HTML to Markdown (`ContentTransformer`)	~34,000 ops/sec	0.030 ms/op	14.5 MB
Eloquent Model Integration (`forModel`)	~4,500 ops/sec	0.23 ms/op	14.5 MB
Headless Serialization (`toArray` / `toJson`)	~7,700 ops/sec	0.13 ms/op	14.5 MB
Model Context Protocol (MCP) JSON-RPC Handling	~230,000 ops/sec	0.004 ms/op	14.5 MB

Run benchmarks locally:

make benchmark

Testing

RankForge is covered by 148+ automated tests and 558+ assertions across PHP 8.2, 8.3, 8.4 and Laravel 11, 12, 13:

make test
# or
./vendor/bin/pest

Documentation

Full interactive documentation is available at eamirgh.github.io/RankForge.

To run documentation locally:

npm install
npm run docs:dev

Contributing

Please review AGENTS.md before contributing. Follow the 3-step development cycle:

Test First in tests/Unit/ or tests/Feature/.
Implement Code in src/.
Document in docs/.

License

RankForge is open-sourced software licensed under the MIT license.

eamirgh / rankforge

Package info

Security

Statistics