README

This repository provides components for building and writing XML sitemaps, following Google recommendations.

Installation

Run:

$ composer require refinery29/sitemap

Content

Components

This package provides all of the components we need to build a sitemap or a sitemap index.

The components are immutable objects, that is, their mutators clone the instance, then set the values. This helps preventing issues with unwillingly modifying a graph of components.

There are two different types of graphs we are interested in building:

Component\UrlSet (represents a set of URLs)
Component\SiteMapIndex (represents a set of sitemaps)

Writers

Once a graph of components has been build, they need to passed to a writer so they can be turned into XML.

There are two different types of writers:

Writer\UrlSetWriter (turns a Component\UrlSet into XML)
Writer\SitemapIndexWriter (turns a Component\SitemapIndex into XML)

Creating a sitemap

`Url`

Before we can create a sitemap, we need Urls, so let's create one:

use Refinery29\Sitemap\Component;

$url = new Component\Url('http://www.example.org/foo/bar.html');

$url = $url
    ->withLastModified(new DateTime())
    ->withChangeFrequency(Component\Url::CHANGE_FREQUENCY_MONTHLY)
    ->withPriority(0.8)
;

💡 Google imposes a limit of 50,000 URLs that can be added to any sitemap.

`Image`

We may want to add images to a Url so let's create one:

use Refinery29\Sitemap\Component;

$image = new Component\Image\Image('http://www.example.org/img/beach.jpg');

$image = $image
    ->withTitle('Our day at the beach')
    ->withCaption('Here we are sitting at the bar, enjoying our drinks')
    ->withGeoLocation('Majorca, Canyamel')
;

We can now add the image:

$url = $url->withImages([
    $image,
]);

💡 We can attach up to 1.000 images to a Url.

`News`

We may want to add news to a Url, if the URL identifies a news article, for example, so let's do this, too:

use Refinery29\Sitemap\Component;

$publication = new Component\News\Publication(
    'The Example Times',
    'en'
);

$news = new Component\News\News(
    $publication,
    new DateTime(),
    'Something happened and you should know about it',
);

$url = $url->withNews([
    $news,
]);

💡 News has many more options, have a look at the source!

`Video`

We may want to add video to a Url, if the URL identifies a page where you can watch a video, so let's also do this:

use Refinery29\Sitemap\Component;

$video = new Component\Video\Video(
    'http://www.example.org/img/funny-video-thumbnail.gif',
    'Jerry dropped his lemonade',
    'Here you can see how Jerry dropped his lemonade and everyone laughs, it is really funny!',
    'http://www.example.org/img/funny-video.mov',
);

$url = $url->withVideos([
    $video,
]);

💡 Video has many more options, have a look at the source!

`UrlSet`

Now, let's create a UrlSet using the previously created Url:

use Refinery29\Sitemap\Component;

$urlSet = new Component\UrlSet([
    $url,
]);

Writing a Sitemap

When we're finished building a UrlSet, we probably want to write it, so let's do it:

use Refinery29\Sitemap\Writer;

$urlSetWriter = new Writer\UrlSetWriter();

$xml = $urlSetWriter->write($urlSet);

Creating a Sitemap Index

If we have many URLs, we may want to spread our sitemaps across multiple files and index them.

`Sitemap`

Before we can create a SitemapIndex, we need a few Sitemaps, so let's create them:

use Refinery29\Sitemap\Component;

$lastModified = new DateTime();

$sitemap = new Component\Sitemap('http://www.example.org/funny.xml');

$sitemap = $sitemap->withLastModifed($lastModified);

$anotherSitemap = new Component\Sitemap(
    'http://www.example.org/news.xml',
    $lastModified
);

`SitemapIndex`

Let's create a SitemapIndex using the previously created Sitemaps:

use Refinery29\Sitemap\Component;

$sitemapIndex = new Component\SitemapIndex([
    $sitemap,
    $anotherSitemap,
]);

Writing a Sitemap Index

When we're finished building a SitemapIndex, we probably want to write, so let's do it:

use Refinery29\Sitemap\Writer;

$sitemapIndexWriter = new Writer\SitemapIndexWriter();

$xml = $sitemapIndexWriter->write($sitemapIndex);

Contributing

Please refer to CONTRIBUTING.md.

Code of Conduct

Please have a look at CONDUCT.md.

License

This package is licensed using the MIT License.

refinery29 / sitemap

Maintainers

Details