🔎 Provides components for building and writing XML sitemaps.
Clone or download
Latest commit f5f5afb Dec 10, 2018

README.md

sitemap

Build Status Code Climate Latest Stable Version Total Downloads

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.