# sitemap [![Build Status](https://travis-ci.org/refinery29/sitemap.svg?branch=master)](https://travis-ci.org/refinery29/sitemap) [![Code Climate](https://codeclimate.com/github/refinery29/sitemap/badges/gpa.svg)](https://codeclimate.com/github/refinery29/sitemap) [![Latest Stable Version](https://poser.pugx.org/refinery29/sitemap/v/stable)](https://packagist.org/packages/refinery29/sitemap) [![Total Downloads](https://poser.pugx.org/refinery29/sitemap/downloads)](https://packagist.org/packages/refinery29/sitemap) 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 `Url`s, so let's create one: ```php 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) ; ``` :bulb: 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: ```php 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: ```php $url = $url->withImages([ $image, ]); ``` :bulb: 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: ```php 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, ]); ``` :bulb: `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: ```php 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, ]); ``` :bulb: `Video` has many more options, have a look at the source! ### `UrlSet` Now, let's create a `UrlSet` using the previously created `Url`: ```php 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: ```php 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 `Sitemap`s, so let's create them: ```php 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 `Sitemap`s: ```php 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: ```php use Refinery29\Sitemap\Writer; $sitemapIndexWriter = new Writer\SitemapIndexWriter(); $xml = $sitemapIndexWriter->write($sitemapIndex); ``` ## Contributing Please refer to [`CONTRIBUTING.md`](.github/CONTRIBUTING.md). ## Code of Conduct Please have a look at [`CONDUCT.md`](.github/CONDUCT.md). ## License This package is licensed using the MIT License.