Upgrading to SPIP 1.9

This is a step-by-step method to follow for performing a "clean" migration to SPIP 1.9, including the deletion of many files that have been recently obsoleted.

Version 1.9 introduces a new way of organising SPIP’s files. If you are updating an existing site that uses SPIP 1.8 or earlier version, you will need to take some precautions and make sure to remove all the obsolete files.

If you are in a hurry, the usual method of update (i.e. just upload the new files on top of the older version), together with the removal of all the files ending in .php3 (except your personalisation files) should work.

This article describe a step by step method that should guarantee a “clean” upgrade to SPIP 1.9.[

Upgrade steps

  1. Before doing any important operation on your site, you should take the precaution of making a backup of the database.
  2. Move all the files and folders of the old version to a subdirectory. Do not delete anything yet!
  3. Install the SPIP 1.9 files in your root directory (remember to check the access rights on the tmp folder (usually the CHMOD to be applied is 777) — which will contain a hierarchy of folders including those previously named CACHE/ and ecrire/data/.
  4. If you prefer using the automatic installation with spip_loader.php, this is still possible: simply stop just after the unzipping, perform the following steps, and then continue on with the installation.
  5. Copy your template directory from the old version backup to the root directory (and, if necessary, rename it “squelettes”).
  • Transfer the directory IMG/ (and all the sub-folders) from the old version backup to the root directory (it contains all the logos, images and documents used on your site). You can remove the following sub-directories:
    • icones_barre/,
    • icones/ if it only contains -dist files [1],
    • the cache..×../ folders which contain the cache of images calculated by the server (reduced versions of images/logos, mathematical formulas, etc.); SPIP will be able to recreate these, but in there new location in tmp}.
  • Transfer (if they exist) the personalisation files mes_fonctions.php3 (to your directory squelettes/) and mes_options.php3 (to the directory ecrire/), renaming them mes_fonctions.php and mes_options.php (i.e. remove the “3” at the end).
  1. Login to the private area of the site and start the update of the site (if you have forgotten the connexion parameters of your MySQL database, you can find them by looking in the file ecrire/inc_connect.php3 of the backup of the old version) - the new installation will create a new connect.php file in the config/ folder.
  2. We’ll never say it too often: do not try to import a “dump” backup created by a previous version of SPIP!.
  3. Test thoroughly!

Updating your templates

  • With SPIP 1.9, the template system is no longer based on a pair of files .php3/.html and now requires only the html file [2]: the PHP files can be completely removed. For example: remove the file article.php3 and keep the file article.html.
  • If that .php3 file contained functions or other specificy for the template, relocate them into squelettes/xxx_fonctions.php, for example for the article template: squelettes/article_fonctions.php
  • Language files can now be placed in a subdirectory lang/ of the template directory squelettes/.
  • Personalised forms should be placed directly in your squelettes/ directory (instead of in the formulaires/ directory in the root).
  • Personalised document icons should now be placed in IMG/icones/.

The template’s code should also be cleaned. This is not absolutely necessary — your old templates will work without it, but this will make your code “cleaner”:

  • Replace all the tags #DOSSIER_SQUELETTE/filename by #CHEMIN{filename},
  • The cache time, which used to be specified by the line $delais = 24 * 3600; in the discarded PHP file, is now specified by a tag #CACHE{24*3600} placed in each template.
  • HTTP headers can be declared by the tag: #HTTP_HEADER{Content-Type: text/css}. Note that if you were using the hack $flag_preserver=true; for some of your templates, its functionality (not displaying the administration buttons) can be reproduced by adding in the template: #HTTP_HEADER{Content-Type: text/html}
  • The inclusion syntax can be simplified, you do not need to specify the file “page.php”, only the name of the template to be included is required: <INCLURE{fond=my_template}{criterion1}{criterion2}{...}>.

Managing URLs

Now that the php3 files have been removed, the URLs of the pages have changed in SPIP 1.9, but you will probably want to keep the old URL scheme in place so that your visitors (and search engines) that referred to them can still find your site.

A htaccess file is provided with the standard distribution so that you can ensure a smooth transition to the new URLs of your site. You need only to rename the file htaccess.txt to .htaccess to activate it. On some sites, you will have to edit the file and enable the line with RewriteBase / (some FTP clients will not display this hidden file and you will have to specify its direct path to open it).

Conversion to utf-8

You can complete your migration by converting your site to the universal utf-8 character set. This is done from the “language management” configuration panel. This operation begins by making an automatic backup of your database in its original character set into the /tmp folder of your SPIP installation.

Reusing your plugins

If you are migrating from an intermediary version prior to SPIP 1.9 and you have used some plugins. you should first verify that those plugins are compatible (or offer compatible new versions) with your migration target version. This means that you will need to retrieve and update those plugins as necessary.

Additional notes

When you are sure that your site works well with this new version, do not forget to delete the backup subdirectory which you made at the beginning. If you have followed all the steps outlined above, it should only contain the files of the old version of SPIP. To be safe, before deleting it you may want to create an archive copy and keep it on your local computer — in case you forgot to copy something.


[1In other words, if there are any files without -dist in their name you need to keep these.

[2All templates are now called by the one page.php file.

Author Mark, mortimer Published : Updated : 26/10/12

Translations : عربي, català, English, Español, italiano