Jump to: navigation, search

Other languages:
català • ‎Deutsch • ‎Ελληνικά • ‎English • ‎español • ‎suomi • ‎français • ‎italiano • ‎日本語 • ‎Bahasa Melayu • ‎Nederlands • ‎polski • ‎português • ‎português do Brasil • ‎中文
Shared uploads: $wgForeignFileRepos
An array of repository structure for foreign repositories.
Introduced in version: 1.11.0 (r22580)
Removed in version: still in use
Allowed values: array
Default value: (see below)
Other settings: Alphabetical | By function

Details[edit source]

Warning Warning: It is important to use HTTPS and not HTTP in the links pointing to the Wikimedia Commons. The Wikimedia Foundation has changed their setup, redirecting people from HTTP to HTTPS. Since for security reasons MediaWiki does not follow such redirects, this change broke the instant commons feature for a number of users. This change has been reverted for now (so that it's again working also with HTTP), but it is still planned to switch to HTTPS in the future (see task T102566).

The solution is to use HTTPS in the URLs pointing to the commons repository! If you use instant commons with the default setup as it comes from DefaultSettings.php, this issue will automatically be fixed by using MediaWiki 1.25.2 or newer. If you in contrast have defined $wgForeignFileRepos in LocalSettings.php, the URLs set there have to be adjusted accordingly!

Properties required for all repos[edit source]

The class name for the repository. May come from the core or an extension. The core repository classes are LocalRepo, ForeignDBRepo, FileRepo and ForeignAPIRepo.
A unique name for the repository.

For all core repos[edit source]

Base public URL
Base thumb url, if different from url/thumb
The number of directory levels for hash-based division of files
The URL for thumb.php (optional, not recommended)
Whether to skip media file transformation on parse and rely on a 404 handler instead.
Equivalent to $wgCapitalLinks, determines whether file names implicitly start with a capital letter. The current implementation may give incorrect description page links when the local $wgCapitalLinks and initialCapital are mismatched.
May be 'paranoid' to remove all parameters from error messages, 'none' to leave the paths in unchanged, or 'simple' to replace paths with place holders. Default for LocalRepo is 'simple'. Note, some image thumbnailing software puts the thumbnail path into the resulting thumb's metadata, so this setting may not provide full protection.
URL of image description pages, e.g.
URL of the MediaWiki installation, equivalent to $wgScriptPathManual:$wgScriptPath, e.g.
Equivalent to $wgArticlePathManual:$wgArticlePath, e.g.$1
Fetch the text of the remote file description page. Equivalent to $wgFetchCommonsDescriptions.
Warning Warning: Due to a bug in MediaWiki, the foreign wiki should have a full, or protocol-relative (but not a generally relative) url in $wgUploadPathManual:$wgUploadPath, or description pages with images on them won't be fetched properly.
If set to 0, no caching will be used. Set to 1 or more (seconds) to define how long the local cache of description pages will last. Must set fetchDescription to true to use.

ForeignAPIRepo class[edit source]

The base URL for the remote repository's API (eg: Only used for ForeignAPIRepo.
How long to cache thumbs locally for. Not setting this or setting to 0 disables local thumb caching

ForeignDBRepo class[edit source]

A path to MediaWiki's media directory local to the server, such as /var/www/wiki/images.
dbType, dbServer, dbUser, dbPassword, dbName, dbFlags
equivalent to the corresponding member of $wgDBservers
Table prefix, the foreign wiki's $wgDBprefix
True if the wiki's shared cache is accessible via the local $wgMemc
A favicon for the remote repository

Default value (code in includes/Setup.php):

if ( $wgUseSharedUploads ) {
  if ( $wgSharedUploadDBname ) {
    $wgForeignFileRepos[] = [
      'class' => 'ForeignDBRepo',
      'name' => 'shared',
      'directory' => $wgSharedUploadDirectory,
      'url' => $wgSharedUploadPath,
      'hashLevels' => $wgHashedSharedUploadDirectory ? 2 : 0,
      'thumbScriptUrl' => $wgSharedThumbnailScriptPath,
      'transformVia404' => !$wgGenerateThumbnailOnParse,
      'dbType' => $wgDBtype,
      'dbServer' => $wgDBserver,
      'dbUser' => $wgDBuser,
      'dbPassword' => $wgDBpassword,
      'dbName' => $wgSharedUploadDBname,
      'dbFlags' => ( $wgDebugDumpSql ? DBO_DEBUG : 0 ) | DBO_DEFAULT,
      'tablePrefix' => $wgSharedUploadDBprefix,
      'hasSharedCache' => $wgCacheSharedUploads,
      'descBaseUrl' => $wgRepositoryBaseUrl,
      'fetchDescription' => $wgFetchCommonsDescriptions,
  } else {
    $wgForeignFileRepos[] = [
      'class' => 'FileRepo',
      'name' => 'shared',
      'directory' => $wgSharedUploadDirectory,
      'url' => $wgSharedUploadPath,
      'hashLevels' => $wgHashedSharedUploadDirectory ? 2 : 0,
      'thumbScriptUrl' => $wgSharedThumbnailScriptPath,
      'transformVia404' => !$wgGenerateThumbnailOnParse,
      'descBaseUrl' => $wgRepositoryBaseUrl,
      'fetchDescription' => $wgFetchCommonsDescriptions,

ForeignDBViaLBRepo class[edit source]

wiki-db-name used in $wgLBFactoryConfManual:$wgLBFactoryConf

Directory permissions[edit source]

You'll need rw on $IP/images and $IP/images/thumbs for whatever user php runs as.

Usage[edit source]

MediaWiki version: 1.13

Using files from Wikimedia Commons : ForeignAPIRepo[edit source]

Since 1.16.0 there is a more convenient shorthand to use Commons as a foreign repository: $wgUseInstantCommonsManual:$wgUseInstantCommons.

You can set your wiki to use media from Wikimedia Commons (or from any other MediaWiki-powered site, see below) directly. However, please beware any legal implications.

To use this, you need:

  • MediaWiki 1.13 or later
  • PHP with JSON support (for the json_decode() function). JSON is enabled by default since PHP 5.2.0, you'll need the PECL extension for older versions. Since MediaWiki 1.16, this is no longer necessary; v. 1.16 will use custom (and slower) code if JSON is not available.
  • The remote wiki must also use MediaWiki 1.13 or later; otherwise its api.php returns {"error":{"code":"iiunknown_iiprop","info":"Unrecognised values for parameter 'iiprop'"}} and file requests fail silently (i.e. the requested files are just treated as non-existent).

The code below enables media files from Wikimedia Commons on your site. You should place it in you "LocalSettings.php" file:

$wgForeignFileRepos[] = [
   'class'                   => 'ForeignAPIRepo',
   'name'                    => 'commonswiki', // Must be a distinct name
   'apibase'                 => '',
   'hashLevels'              => 2,
   'fetchDescription'        => true, // Optional
   'descriptionCacheExpiry'  => 43200, // 12 hours, optional (values are seconds)
   'apiThumbCacheExpiry'     => 86400, // 24 hours, optional, but required for local thumb caching
If you decide to add this setting to your "LocalSettings.php" file instead of using $wgUseInstantCommons you cannot use wikimediacommons as a setting for name since it is already present in core MediaWiki code (in "Setup.php").

To pull images from another Wikimedia project, set apibase to this wiki's "api.php" file like e.g. Example:

1 $wgForeignFileRepos[] = [
2    'class'                   => 'ForeignAPIRepo',
3    'name'                    => 'enwiki',
4    'apibase'                 => '',
5    'hashLevels'              => 2,
6    'fetchDescription'        => true,
7    'descriptionCacheExpiry'  => 43200,
8    'apiThumbCacheExpiry'     => 86400,
9    ];

To embed an image in your installation, simply use [[File:name_of_commons_picture.jpg]].

You may need to configure the $wgMainCacheType as well. Default it is set to CACHE_NONE, meaning it will load the image from the remote host on each page load. Similarly, you need to set apiThumbCacheExpiry to zero if you prefer to use the foreign thumbnails.

Using files from a database that you can access : ForeignDBRepo, ForeignDBViaLBRepo[edit source]

The ForeignDBRepo class is very useful for creating wiki families. In a wiki family, each wiki will have its own database or table prefix. Using this class, you can make a family member aware of the tables of another family member. Access through ForeignDBRepo is faster than through ForeignAPIRepo. This code should be deployed to LocalSettings.php.

$wgForeignFileRepos[] = [
    'class' => 'ForeignDBRepo',
    'name' => 'otherwiki',
    'url' => "",
    'directory' => '/path/to/media',
    'hashLevels' => 2, // This must be the same for the other family member
    'dbType' => $wgDBtype,
    'dbServer' => $wgDBserver,
    'dbUser' => $wgDBuser,
    'dbPassword' => $wgDBpassword,
    'dbFlags' => DBO_DEFAULT,
    'dbName' => 'mydb',
    'tablePrefix' => 'mw_',
    'hasSharedCache' => false,
    'descBaseUrl' => '',
    'fetchDescription' => false

Alternatively, if you have $wgLBFactoryConf set up for multiple wikis, you can use 'class' => 'ForeignDBViaLBRepo':

$wgForeignFileRepos[] = [
  'class' => 'ForeignDBViaLBRepo',
  'wiki' => 'wiki-db-name-used-with-wgLBFactoryConf',
  'name' => 'otherwiki', # displayname (eg. the vector-skin-tab “View on OtherWiki“) may be set at wiki-specific MediaWiki:Shared-repo-name-<otherwiki>
  'url' => '',
  'directory' => '/path/to/media',
  'hashLevels' => 2, # This must be the same for the other family member
  'tablePrefix' => 'mw_',
  'hasSharedCache' => false,
  'fetchDescription' => true,
  'scriptDirUrl' => '', # has effect whether description can be fetched

This needs not all the db* parameters as in ForeignDBRepo.

Using files from a local folder : FileRepo[edit source]

You can set your wiki to use media from a single folder. This is just a demonstration feature at present, and will probably be too slow for busy wikis or slow servers due to the lack of caching. This code should be deployed to LocalSettings.php.

The below code enabled media files from it:

$wgForeignFileRepos[] = [
   'class'            => 'FileRepo',
   'name'             => 'sharedFsRepo',
   'directory'        => 'media/',
   'hashLevels'       => 0,
   'url'              => '',

See also[edit source]