prestaSitemapPlugin - 1.0.4

Generate XML sitemaps

You are currently browsing
the website for symfony 1

Visit the Symfony2 website


« Back to the Plugins Home

Signin


Forgot your password?
Create an account

Tools

Stats

advanced search
Information Readme Releases Changelog Contribute
Show source

prestaSitemapPlugin

The prestaSitemapPlugin provides an easy way to generate a sitemap.xml.

Features

  • Quick to use
  • Cached (for generated files and urls sections during generation)
  • Compliant with sitemap protocol v0.9 as defined by http://www.sitemaps.org
  • Works with more than 50.000 urls (usage of sitemap index)
  • Manage file limit of 10Mo
  • Multi-domain support (http://fr.foo.bar/sitemap.xml and http://en.foo.bar/sitemap.xml may produce different sitemap contents)
  • Support Google's image and mobile extensions for sitemaps

License

The prestaSitemapPlugin is licensed under the MIT License.

Installation

  • Install the plugin:

    $ symfony plugin:install prestaSitemapPlugin
    $ symfony cc
  • Be sure that the plugin is activated in config/ProjectConfiguration.class.php

Usage

In order to register methods and or functions that should add URLs to the sitemap, we should add listeners for the event 'presta_sitemap.generate_urls'.

In apps/%appName%/config/%appName%Configuration.class.php, we declare one or more listeners in configure() method:

// 'sitemapUtils' and 'generateSitemapEntries' are just exemple of a valid callback. You can name them as you want.
$this->dispatcher->connect( 'presta_sitemap.generate_urls', array( 'sitemapUtils', 'generateSitemapEntries' ) );

We add the listener method in a new class (eg: apps/%appName%/lib/sitemapUtils.class.php ):

class sitemapUtils
{   
    /**
     * Listens to the presta_sitemap.generate_urls event.
     *
     * @param  sfEvent $event  An sfEvent instance
     */
    public static function generateSitemapEntries( sfEvent $event )
    {
        // create a new prestaSitemapSection object
        $o_sitemapSection   = new prestaSitemapSection( 'miscSectionName' );
        // check is it is up-to-date
        if( !$o_sitemapSection->isUpToDate() )
        {
            // add prestaSitemapUrl to the prestaSitemapSection
            $o_sitemapSection->addUrl( new prestaSitemapUrl( '@homepage', new DateTime(), prestaSitemapUrl::CHANGE_FREQUENCY_HOURLY, 0.9 ) );
 
            // add other urls
            $o_sitemapSection->addUrl( new prestaSitemapUrl( /* Put your own stuff here */ ) );
        }
    }
}

Enabled prestaSitemap module in your settings.yml:

all:
  .settings:    
    enabled_modules: [default, prestaSitemap]

You can now see your sitemap index file in http://www.mydomain.com/sitemap.xml. That's all, you now have a sitemap.

Notices

  • prestaSitemapPlugin use mbstring php's extension because it should produce UTF-8 xml files no matter the input encoding. This extension is not required but highly recommanded.

    If "mbstring" extension is not installed, you are responsible to give UTF-8 encoded absolute urls to prestaSitemapUrl objects.

    // Both lines are valid if "mbstring" extension is installed, but invalid if "mb_string" is not installed
    new prestaSitemapUrl( '@homepage?slug=non-UTF8-characters' );
    new prestaSitemapUrl( 'http://www.foo.bar/non-UTF8-characters' );
     
    // Valid even if "mbstring" extension is not installed
    $baseUrl    = 'http://www.foo.bar/non-UTF8-characters';
    $utf8Url    = aFunctionThatConvertToUTF8( $baseUrl ); 
    new prestaSitemapUrl( $utf8Url );
  • If you try to access to non-existing section's sitemap content (eg: http://www.mydomain.com/sitemap.nonExistingSection.xml), it will return a 404 page.

prestaSitemapUrl

A prestaSitemapUrl object expect 4 parameters that can be passed to the constructor or defined using setters methods:

  • The url. This is the only parameter that should be defined in order to see it appears in the sitemap.xml

    Constructor's 1st parameter or defined by ->setLocation().

    This can be a route or an absolute url. It will use url_for().

    If you specificly need to use url_for1() or url_for2() methods you can use setLocation1() (for url_for1()) or setLocation2() (for url_for2())

  • A last modification date. You should give a DateTime object.

    Constructor's 2nd parameter or defined by ->setLastModificationDate().

  • A change frequency.

    Constructor's 3rd parameter or defined by ->setChangeFrequency().

    Valid values are 'always', 'hourly', 'daily', 'weekly', 'monthly', 'yearly' and 'never'.

    It is recommended that you use prestaSitemapUrl::CHANGE_FREQUENCY_* constants.

    Invalid values will be ignored.

  • A priority.

    Constructor's 4th parameter or defined by ->setPriority().

    This must be a number between 0 and 1.

    Invalid values will be ignored.

So the 2 examples below will produce the same results

$o_prestaSitemapUrl1    = new prestaSitemapUrl( $miscUrl, $o_date, $changeFrequency, $priority );
$o_prestaSitemapUrl2    = new prestaSitemapUrl();
$o_prestaSitemapUrl2->
  setLocation( $miscUrl )->
  setLastModificationDate( $o_date )->
  setChangeFrequency( $changeFrequency )->
  setPriority( $priority );

Extension to prestaSitemapUrl

It is possible to add extra datas to prestaSitemapUrl in order to provid more informaiton about one url in the generated sitemap.

Extension for mobile website

You can use an option to generate a sitemap for mobile website. When the prestaSitemapUrl class is instanciated you can call the setMobile method with a boolean param. If you pass true, the plugin will generate a sitemap for a mobile website, with a specific tag : ''. If you don't call the method or if you pass false, the plugin will generate the traditionnal sitemap.

$o_prestaSitemapUrl1    = new prestaSitemapUrl( $miscUrl, $o_date, $changeFrequency, $priority );
o_prestaSitemapUrl1->setMobile( true );

Setting this parameter to true is mandatory if you want google to know that this is a mobile URL.

prestaSitemapUrlImage

prestaSitemapUrlImage object allow to implement Google's image extensions for Sitemaps. This allow to list the images currently present in you web page and to describe metadata about them.

Use the presteSitemapUrl method addImage() to add one prestaSitemapUrlImage. Currently only 1000 images can be added to one single url tag (can be reconfigured in yml).

Exemple:

$o_prestaSitemapUrl1        = new prestaSitemapUrl( $miscUrl, $o_date, $changeFrequency, $priority );
$o_prestaSitemapUrlImage1   = new prestaSitemapUrlImage( $miscUrl, $caption, $geo_location, $title, $license);
$o_prestaSitemapUrl1->addImage( $o_prestaSitemapUrlImage1 );

A prestaSitemapUrlImage object expect 5 parameters that can be passed to the constructor or defined using setters methods:

  • The image path. This is the only parameter that should be defined in order to see it appears in the sitemap.xml

    Constructor's 1st parameter or defined by ->setLocation().

    This can be a name or an absolute path. It will use image_path().

    If you specificly need to use url_for() for a dynamic image methods you can use setLocationUrlFor()

  • A caption [optionnal]. Corresponding to the alt attribute.

    Constructor's 2nd parameter or defined by ->setCaption().

  • A geolocation [optionnal].

    Constructor's 3rd parameter or defined by ->setGeoLocation().

  • A title [optionnal]. Corresponding to the title attribute.

    Constructor's 4th parameter or defined by ->setTitle().

  • A license [optionnal]. An URL to the license of the image.

    Constructor's 5th parameter or defined by ->setLicense().

So the 2 examples below will produce the same results

$o_prestaSitemapUrlImage1   = new prestaSitemapUrlImage( $miscUrl, $caption, $geo_location, $title, $license);
$o_prestaSitemapUrlImage2   = new prestaSitemapUrlImage();
$o_prestaSitemapUrlImage2->
  setLocation( $miscUrl )->
  setCaption( $caption )->
  setGeoLocation( $geo_location )->
  setTitle( $title )->
  setLicense( $license );

Caching

There si 2 cache levels: a generated xml file cache and a prestaSitemapSection cache

First the xml files are cached (for 1 hour by default).

When they expires, the 'presta_sitemap.generate_urls' event is triggered and prestaSitemapSection object are instanciated.

If they're up-to-date there is no need to do action for retrieving all possible urls and instanciting prestaSitemapUrl object for each.

By default generated xml files are cached for 3600 seconds. Here is the associated config used internally and that can be redefined in project's config.yml

all:
  prestaSitemapPlugin:
    mainCache:    # determine usage of generated xml files
      enabled:  true    # cache enable
      lifetime: 3600    # valid for 1 hour
    sectionCache: # determine usage of internal cached datas at prestaSitemapSection level
      enabled:  true    # enabled or disable internal cache usage for all prestaSitemapSection objects
      lifetime: 86400   # default lifetime used for section when cache secitonCache is enabled (can be respecified for each sitemapSection) 

Notice that in all cases (no matter the cache configuration) no datas will be generated when accessing to a section's sitemap (eg: sitemap.main.xml). Datas generation will only be triggered when calling sitemap.xml, this will ensure datas consistency and improved performances.

So if you want to see modifications in sitemap.main.xml don't forget to call sitemap.xml before.

Notice that if you want to see your latest modifications in url generation you can do manually a "symfony cache:clear" or add the follwing code to your app.yml in order to always see updated datas in your dev environement.

dev:
  prestaSitemapPlugin:
    mainCache:
      enabled:  false      # disable main cache
    sectionCache:
      enabled:  false      # disable section cache

prestaSitemapSection

A prestaSitemapSection is a group of url that will be valid for a given lifetime and will be displayed in the sitemap 'sitemap.sectionName.xml'

Here is a little example about prestaSitemapSection

$o_sitemapSection   = new prestaSitemapSection( 'sectionName', array( 'lifetime' => 172800 ) );
if( !$o_sitemapSection->isUpToDate() )
{
    // the code here will be executed each 48 hours, and the url will be outputed in 'sitemap.sectionName.xml'
}
$o_sitemapSection   = new prestaSitemapSection( 'sectionName', array( 'lifetime' => 86400 ) );
if( !$o_sitemapSection->isUpToDate() )
{
    // the code here will be executed each 24 hours, and the url will be outputed in 'sitemap.sectionName.xml'
    // Notice that 2 sections have the same name but different lifetime. This will correrctly work.
}
$o_sitemapSection   = new prestaSitemapSection( 'anotherSectionName', array( 'lifetime' => 86400 ) );
if( !$o_sitemapSection->isUpToDate() )
{
    // the code here will be executed each 24 hours, and the url will be outputed in 'sitemap.anotherSectionName.xml'
}
$o_sitemapSection   = new prestaSitemapSection();
if( !$o_sitemapSection->isUpToDate() )
{
    // the code here will have a lifetime as defined by 'app_prestaSitemapPlugin_sectionCache[enabled]', and the url will be outputed in 'sitemap.main.xml'
}

Changelog

2011-08-10 | 1.0.4

Add support for google's mobile extension for sitemaps

2010-10-07 | 1.0.3

  • Add the ability to index images in the sitemap as allowed by Google's image extensions for Sitemaps. (See: http://www.google.com/support/webmasters/bin/answer.py?hl=en&answer=178636)

2010-01-29 | 1.0.2

  • Remove code used for compatibility with sf1.1 (sfLoader) that is not used (as this plugin doesn't officially support symfony 1.1) that were producing notices with project:validate

2009-11-27 | 1.0.1

  • Add compatibility with symfony 1.3 & 1.4
  • Move default config from config.php to app.yml (fix old ugly code)
  • Fix bug where all datas where escaped if escaping strategy was enabled
  • Integrate tests inside plugin
  • Add the ability to customize the class used for data caching (Resolve: http://trac-symfony.prestaconcept.net/ticket/3)

2009-08-21 | 1.0.0

  • Ensure that HTTP header 'Content-Type' indicate charset UTF-8
  • This plugin has been tested in production environment with success, so it comes out to stable version 1.0

2009-08-07 | 0.0.4-beta

  • When accessing a section's sitemap, if cache is empty, it will regenerate sitemap datas.
  • Now return a 404 page when calling a non exisitng sitemap's section
  • Now can work if "mbstring" extension is not installed (see "Notice" section in README for more details)

2009-08-04 | 0.0.3-beta

  • More robust routing rules definition (force default config for used sfRoutes).

2009-08-04 | 0.0.2-beta

  • Initial internal beta release.