README

A PHP library for working with SEO meta tags, Open Graph, Schema.org markup, and sitemap.xml generation.

Installation

Install via Composer:

composer require akse1a/seo

Or add to your composer.json:

{
    "require": {
        "akse1a/seo": "^1.0"
    }
}

Usage

Basic Usage

<?php

use Akse1a\Seo\Seo;

$seo = new Seo();

// Set basic meta tags
$seo->setTitle('Page Title')
    ->setDescription('Page description')
    ->setKeywords(['keyword', 'word', 'more']);

// Open Graph
$seo->setImage('https://example.com/image.jpg')
    ->setUrl('https://example.com/page')
    ->setType(\Akse1a\Seo\Enum\OpenGraphType::ARTICLE);

// Output HTML
echo $seo->render();

Adding Custom Meta Tags

$seo->addMetaTag('author', 'Author Name')
    ->addMetaTag('robots', 'index, follow');

Adding Open Graph Tags

$seo->addOpenGraph('og:site_name', 'Site Name')
    ->addOpenGraph('og:locale', 'en_US');

Schema.org Markup

$seo->addSchema([
    '@context' => 'https://schema.org',
    '@type' => 'Article',
    'headline' => 'Article Headline',
    'author' => [
        '@type' => 'Person',
        'name' => 'Author Name'
    ]
]);

Generating sitemap.xml

Basic Example

<?php

use Akse1a\Seo\Sitemap;
use Akse1a\Seo\Enum\ChangeFrequency;
use Akse1a\Seo\Exception\RuntimeException;

$sitemap = new Sitemap();

// Add URLs
$sitemap->addUrl('https://example.com/')
    ->addUrl(
        'https://example.com/page',
        '2024-01-15',  // lastmod
        'weekly',      // changefreq
        0.8            // priority
    )
    ->addUrlWithNow('https://example.com/new-page', ChangeFrequency::DAILY, 1.0);

// Generate XML string
$xml = $sitemap->generate();
echo $xml;

// Save to file sitemap.xml
try {
    $sitemap->save('sitemap.xml');
    echo "Sitemap successfully saved to sitemap.xml\n";
} catch (RuntimeException $e) {
    echo "Error saving: " . $e->getMessage() . "\n";
}

Full Example with Error Handling

<?php

use Akse1a\Seo\Sitemap;
use Akse1a\Seo\Enum\ChangeFrequency;
use Akse1a\Seo\Exception\InvalidArgumentException;
use Akse1a\Seo\Exception\RuntimeException;

try {
    $sitemap = new Sitemap();
    
    // Add URLs with different parameters
    $sitemap->addUrl('https://example.com/')
        ->addUrl(
            'https://example.com/about',
            new \DateTime('2024-01-15'),
            ChangeFrequency::MONTHLY,
            0.8
        )
        ->addUrl(
            'https://example.com/blog',
            '2024-01-20',
            ChangeFrequency::WEEKLY,
            0.9
        )
        ->addUrlWithNow('https://example.com/contact', ChangeFrequency::YEARLY, 0.7);
    
    // Generate XML
    $xml = $sitemap->generate();
    
    // Save to file
    $filename = __DIR__ . '/sitemap.xml';
    $sitemap->save($filename);
    
    // Check if file was created
    if (file_exists($filename)) {
        echo sprintf("Sitemap successfully created: %s (%d bytes)\n", $filename, filesize($filename));
    }
    
} catch (InvalidArgumentException $e) {
    echo "Validation error: " . $e->getMessage() . "\n";
} catch (RuntimeException $e) {
    echo "Runtime error: " . $e->getMessage() . "\n";
}

Output Sitemap Directly to Browser

<?php

use Akse1a\Seo\Sitemap;

$sitemap = new Sitemap();
$sitemap->addUrl('https://example.com/')
    ->addUrl('https://example.com/page');

// Output with correct HTTP headers
$sitemap->output();
exit;

Parameters for addUrl()

$loc (required) - Page URL (automatically validated)
$lastmod (optional) - Last modification date (format: Y-m-d or DateTimeInterface object)
$changefreq (optional) - Change frequency: string or ChangeFrequency enum
$priority (optional) - Priority from 0.0 to 1.0 (automatically validated)

Duplicate URL Handling

The library automatically prevents duplicate URLs in the sitemap. If you try to add the same URL twice:

Duplicate URLs are automatically detected using URL normalization (case-insensitive scheme/host, trailing slash handling)
Existing URL is updated with new parameters if provided (lastmod, changefreq, priority)
Original parameters are preserved if new ones are not provided

Examples of URLs considered duplicates:

https://example.com/page and https://example.com/page/ (trailing slash)
https://Example.com/page and https://example.com/page (case difference)
http://example.com/page and https://example.com/page (different schemes are NOT considered duplicates)

You can check if a URL exists using:

if ($sitemap->hasUrl('https://example.com/page')) {
    echo "URL already exists in sitemap";
}

Error Handling

The library throws exceptions for invalid data:

use Akse1a\Seo\Exception\InvalidArgumentException;
use Akse1a\Seo\Sitemap;

try {
    $sitemap = new Sitemap();
    $sitemap->addUrl('invalid-url'); // Will throw InvalidArgumentException
} catch (InvalidArgumentException $e) {
    echo $e->getMessage();
}

Example with Multiple Pages

$sitemap = new Sitemap();

$pages = [
    ['url' => 'https://example.com/', 'priority' => 1.0, 'changefreq' => 'daily'],
    ['url' => 'https://example.com/about', 'priority' => 0.8, 'changefreq' => 'monthly'],
    ['url' => 'https://example.com/contact', 'priority' => 0.7, 'changefreq' => 'monthly'],
];

foreach ($pages as $page) {
    $sitemap->addUrlWithNow($page['url'], $page['changefreq'], $page['priority']);
}

$sitemap->save('sitemap.xml');

Development

Requirements

PHP 8.0 or higher
Composer

Install Dependencies for Development

composer install

Run Examples

# Run sitemap generation example
php example_sitemap.php

License

MIT

Author

akse1a

akse1a / seo

Maintainers

Details