yii2tech/sitemap

Provides support for site map creation

, _(*1)

Site Map Extension for Yii 2

This extension provides support for site map and site map index files generating., _(*2)

For license information check the LICENSE-file., _(*3)

, _(*4)

Installation

The preferred way to install this extension is through composer., _(*5)

Either run, _(*6)

php composer.phar require --prefer-dist yii2tech/sitemap

or add, _(*7)

"yii2tech/sitemap": "*"

to the require section of your composer.json., _(*8)

Usage

This extension provides support for site map and site map index files generation. You can use \yii2tech\sitemap\File for site map file composition:, _(*9)

writeUrl(['site/index'], ['priority' => '0.9']);
$siteMapFile->writeUrl(['site/about'], ['priority' => '0.8', 'changeFrequency' => File::CHECK_FREQUENCY_WEEKLY]);
$siteMapFile->writeUrl(['site/signup'], ['priority' => '0.7', 'lastModified' => '2015-05-07']);
$siteMapFile->writeUrl(['site/contact']);

$siteMapFile->close();
```

In case you put sitemap generation into a console command, you will need to manually configure URL manager
parameters for it. For example:

```php
 'my-console-application',
    'components' => [
        'urlManager' => [
            'hostInfo' => 'https://example.com',
            'baseUrl' => '/',
            'scriptUrl' => '/index.php',
        ],
        // ...
    ],
    // ...
];
```


## Creating site map index files 

There is a limitation on the site map maximum size. Such file can not contain more then 50000 entries and its
actual size can not exceed 50MB. If you web application has more then 50000 pages and you need to generate
site map for it, you'll have to split it between several files and then generate a site map index file.
It is up to you how you split your URLs between different site map files, however you can use `\yii2tech\sitemap\File::getEntriesCount()`
or `\yii2tech\sitemap\File::getIsEntriesLimitReached()` method to check count of already written entries.

For example: assume we have an 'item' table, which holds several millions of records, each of which has a detail
view page at the web application. In this case generating site map files for such pages may look like following:

```php
select(['slug'])->asArray();

$siteMapFileCount = 0;
foreach ($query->each() as $row) {
    if (empty($siteMapFile)) {
        // if there is no active file - create one with unique name:
        $siteMapFile = new File();
        $siteMapFileCount++;
        $siteMapFile->fileName = 'item_' . $siteMapFileCount . '.xml';
    }

    $siteMapFile->writeUrl(['item/view', 'slug' => $row['slug']]);
    if ($siteMapFile->getIsEntriesLimitReached()) {
        // once file is full - close it, allowing creating a new one at the next cycle iteration:
        unset($siteMapFile);
    }
}
```

Once all site map files are generated, you can compose index file, using the following code:

```php
writeUp();
```

> Note: by default site map files are stored under the path '@app/web/sitemap'. If you need a different file path
  you should adjust `fileBasePath` field accordingly.


## Rendering on-the-fly 

Saving sitemap to the physical file may be not a best option to keep it up-to-date. Such file should be manually re-created,
once some changes among site pages appear. You may setup a web controller, which will render 'sitemap.xml' file on demand,
once it is been requested. This controller may apply caching and its busting logic.
First of all, you'll have to set up a route for the controller action rendering the sitemap in your URL manager. For example:

```php
 [
        'urlManager' => [
            'rules' => [
                'sitemap.xml' => 'site/sitemap',
                // ...
            ],
        ],
        // ...
    ],
    // ...
];
```

Then you'll need to create an action, which will render sitemap file content and emit it to the web client.
You can use PHP 'in memory' stream as a file name for the sitemap file during its composition.
The final implementation may look like following:

```php
cache->get('sitemap.xml');
        if ($content === false) {
            // if no cached value exists - create an new one
            // create sitemap file in memory:
            $sitemap = new File();
            $sitemap->fileName = 'php://memory';
            
            // write your site URLs:
            $sitemap->writeUrl(['site/index'], ['priority' => '0.9']);
            // ...
            
            // get generated content:
            $content = $sitemap->getContent();

            // save generated content to cache
            Yii::$app->cache->set('sitemap.xml', $content);
        }

        // send sitemap content to the user agent:
        $response = Yii::$app->getResponse();
        $response->format = Response::FORMAT_RAW;
        $response->getHeaders()->add('Content-Type', 'application/xml;');
        $response->content = $content;
        
        return $response;
    }
}
```


## Customizing file envelope 

You can customize entries envelope for the particular file using following options:

 - `\yii2tech\sitemap\BaseFile::$header` - content, which should be written at the beginning of the file, once it has been opened;
 
 - `\yii2tech\sitemap\BaseFile::$footer` - content, which should be written at the end of the file before it is closed;
 
 - `\yii2tech\sitemap\BaseFile::$rootTag` - defines XML root tag name and attributes;
 
For example:

```php
 '',
    'rootTag' => [
        'tag' => 'urlset',
        'xmlns' => 'http://www.sitemaps.org/schemas/sitemap/0.9',
        'xmlns:xsi' => 'http://www.w3.org/2001/XMLSchema-instance',
        'xmlns:image' => 'http://www.google.com/schemas/sitemap-image/1.1',
        'xsi:schemaLocation' => 'http://www.sitemaps.org/schemas/sitemap/0.9 http://www.sitemaps.org/schemas/sitemap/0.9/sitemap.xsd http://www.google.com/schemas/sitemap-image/1.1 http://www.google.com/schemas/sitemap-image/1.1/sitemap-image.xsd',
    ],
]);

$siteMapFile->writeUrl(['site/index'], ['priority' => '0.9']);
// ...

$siteMapFile->close();

Rendering non-standard tags

While there is a standard, which defines sitemap content, particular search engines may accept extra tags and options. The most widely used are image and video descriptions. Method \yii2tech\sitemap\File::writeUrl() supports rendering image and video information., _(*10)

For adding images to the sitemap entry use 'images' option. For example:, _(*11)

<?php

use yii2tech\sitemap\File;

$siteMapFile = new File([
    'rootTag' => [
        'xmlns' => 'http://www.sitemaps.org/schemas/sitemap/0.9',
        'xmlns:image' => 'http://www.google.com/schemas/sitemap-image/1.1', // you will need to add XML namespace for non-standard tags
    ],
]);

$siteMapFile->writeUrl(['site/index'], [
    'images' => [
        [
            'url' => 'http://example.com/images/logo.jpg',
            'title' => 'Logo',
        ],
        [
            'url' => 'http://example.com/images/avatars/john-doe.jpg',
            'title' => 'Author',
        ],
        // ...
    ],
]);
// ...

$siteMapFile->close();

For adding videos to the sitemap entry use 'videos' option. For example:, _(*12)

<?php

use yii2tech\sitemap\File;

$siteMapFile = new File([
    'rootTag' => [
        'xmlns' => 'http://www.sitemaps.org/schemas/sitemap/0.9',
        'xmlns:video' => 'http://www.google.com/schemas/sitemap-video/1.1', // you will need to add XML namespace for non-standard tags
    ],
]);

$siteMapFile->writeUrl(['site/index'], [
    'videos' => [
        [
            'title' => 'Demo video',
            'description' => 'Demo video of the main process',
            'thumbnailUrl' => 'http://example.com/images/demo-video.jpg',
            'player' => [
                'url' => 'http://example.com/videos/demo.flv',
                'allowEmbed' => true,
                'autoplay' => 'ap=1',
            ],
            'publicationDate' => '2019-08-02',
            'duration' => 240,
        ],
        [
            'title' => 'Our team',
            'description' => 'Greetings from our team',
            'thumbnailUrl' => 'http://example.com/images/our-team.jpg',
            'player' => [
                'url' => 'http://example.com/videos/our-team.flv',
                'allowEmbed' => true,
                'autoplay' => 'ap=1',
            ],
            'publicationDate' => '2019-08-02',
            'duration' => 120,
        ],
        // ...
    ],
]);
// ...

$siteMapFile->close();

You can also add any custom content to the URL tag using 3rd argument of the \yii2tech\sitemap\File::writeUrl() method. For example:, _(*13)

<?php

use yii2tech\sitemap\File;

$siteMapFile = new File([
    'rootTag' => [
        'xmlns' => 'http://www.sitemaps.org/schemas/sitemap/0.9',
        'xmlns:image' => 'http://www.google.com/schemas/sitemap-image/1.1', // you will need to add XML namespace for non-standard tags
    ],
]);

$siteMapFile->writeUrl(
    ['site/index'],
    [],
    '<image:image><image:loc>http://example.com/images/logo.jpg</image:loc></image:image>'
);
// ...

$siteMapFile->close();

Heads up! Remember that you'll have to add corresponding XML namespaces to the sitemap file, using \yii2tech\sitemap\BaseFile::$rootTag, in order to non-standard tags being recognized by the search engines., _(*14)