View source for Manual:$wgForeignFileRepos

<languages/>
{{SettingSummary
|name=ForeignFileRepos
|version_min=1.11.0
|rev_introduced=22580
|section=Shared uploads
|range=(<translate><!--T:86--> array</translate>)
|default=''<translate><!--T:1--> (see below)</translate>''
|summary=<translate><!--T:2--> An array of repository structure for foreign repositories.</translate>
}}
<translate>
== Details == <!--T:3-->
</translate>
{{Warning|1=<translate><!--T:79--> When using Wikimedia Commons it is required to use HTTPS for links, instead of HTTP. As of 2015, Wikimedia Foundation redirects traffic from HTTP to HTTPS. For security reasons MediaWiki does '''not''' follow such redirects (see {{phabricator|T102566}}).</translate><br /><br /><translate><!--T:80--> The solution is to use HTTPS in the URLs for Wikimedia Commons! If you use <tvar name=1>{{wg|UseInstantCommons}}</tvar>, this issue is automatically fixed by using MediaWiki 1.25.2 or newer. If you have defined custom settings with <code>$wgForeignFileRepos</code> for Wikimedia Commons, then the URLs must be adjusted accordingly!</translate>}}

<translate>
=== Properties required for all repos === <!--T:4-->
</translate>
; class
: <translate><!--T:6--> The class name for the repository. May come from the core or an extension. The core repository classes are LocalRepo, ForeignDBRepo, FileRepo and ForeignAPIRepo.</translate>
; name
: <translate><!--T:8--> A unique name for the repository.</translate>

<translate>
=== For all core repos === <!--T:9-->
</translate>
; url
: <translate><!--T:11--> Base public URL</translate>
; thumbUrl
: <translate><!--T:13--> Base thumb url, if different from url/thumb</translate>
; hashLevels
: <translate><!--T:15--> The number of directory levels for hash-based division of files</translate>
; thumbScriptUrl
: <translate><!--T:17--> The URL for thumb.php (optional, not recommended)</translate>
; transformVia404
: <translate><!--T:19--> Whether to skip media file transformation on parse and [[<tvar name=tp>Special:MyLanguage/Manual:thumb.php</tvar>|rely on a 404 handler instead]].</translate>
; initialCapital
: <translate><!--T:21--> Equivalent to <tvar name=1>{{wg|CapitalLinks}}</tvar>, determines whether file names implicitly start with a capital letter. The current implementation may give incorrect description page links when the local <tvar name=1>{{wg|CapitalLinks}}</tvar> and <tvar name=2>initialCapital</tvar> are mismatched.</translate>
; pathDisclosureProtection
: <translate><!--T:23--> 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'.</translate> <translate><!--T:24--> Note, some image thumbnailing software puts the thumbnail path into the resulting thumb's metadata, so this setting may not provide full protection.</translate>
; descBaseUrl
: <translate><!--T:26--> URL of image description pages, e.g. <code><nowiki>https://en.wikipedia.org/wiki/File:</nowiki></code></translate>
; scriptDirUrl
: <translate><!--T:28--> URL of the MediaWiki installation, equivalent to <tvar name=1>{{wg|ScriptPath}}</tvar>, e.g.</translate> <code><nowiki>https://en.wikipedia.org/w</nowiki></code>
; articleUrl
: <translate><!--T:30--> Equivalent to <tvar name=1>{{wg|ArticlePath}}</tvar>, e.g.</translate> <code><nowiki>https://en.wikipedia.org/wiki/$1</nowiki></code>
; fetchDescription
: <translate><!--T:32--> Fetch the text of the remote file description page. Equivalent to <tvar name=1>{{wg|FetchCommonsDescriptions}}</tvar>.</translate>
: {{warning|1=<translate><!--T:33--> Due to a [[<tvar name=phab>phabricator:T61851</tvar>|bug]] in MediaWiki, the foreign wiki should have a full, or protocol-relative (but not a generally relative) url in <tvar name=UploadPath>{{wg|UploadPath}}</tvar>, or description pages with images on them won't be fetched properly.</translate>}}
; descriptionCacheExpiry
: <translate><!--T:35--> 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.</translate>

<translate>
=== ForeignAPIRepo class === <!--T:36-->
</translate>
; apibase
: <translate><!--T:38--> The base URL for the remote repository's API (e.g. <tvar name=eg3><code><nowiki>https://commons.wikimedia.org/w/api.php</nowiki></code></tvar>).</translate> <translate><!--T:39--> Only used for ForeignAPIRepo.</translate>
; apiThumbCacheExpiry
: <translate><!--T:41--> How long to cache thumbs locally for. Setting this to 0 disables local thumb caching.</translate> <translate><!--T:95--> Local thumb caching will reduce load on the foreign server, and improve user privacy. However it may cause your wiki to be slightly slower.</translate>

<translate>
=== ForeignDBRepo class === <!--T:42-->
</translate>
; directory
: <translate><!--T:87--> A path to MediaWiki's media directory local to the server, such as <code>/var/www/wiki/images</code>.</translate>
; dbType, dbServer, dbUser, dbPassword, dbName, dbFlags
: <translate><!--T:44--> equivalent to the corresponding member of <tvar name=1>{{wg|DBservers}}</tvar></translate>
; tablePrefix
: <translate><!--T:46--> Table prefix, the foreign wiki's <tvar name=1>{{wg|DBprefix}}</tvar></translate>
; hasSharedCache
: <translate><!--T:48--> True if the wiki's shared cache is accessible via the local <tvar name=1>{{wg|Memc}}</tvar></translate>
; favicon
: <translate><!--T:50--> A favicon for the remote repository</translate>

<translate>
<!--T:51-->
Default value (code in <tvar name=Setup>{{git file|file=includes/SetupDynamicConfig.php}}</tvar>):
</translate>

<syntaxhighlight lang="php">
if ( $wgUseSharedUploads ) {
	if ( $wgSharedUploadDBname ) {
		$wgForeignFileRepos[] = [
			'class' => ForeignDBRepo::class,
			'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::class,
			'name' => 'shared',
			'directory' => $wgSharedUploadDirectory,
			'url' => $wgSharedUploadPath,
			'hashLevels' => $wgHashedSharedUploadDirectory ? 2 : 0,
			'thumbScriptUrl' => $wgSharedThumbnailScriptPath,
			'transformVia404' => !$wgGenerateThumbnailOnParse,
			'descBaseUrl' => $wgRepositoryBaseUrl,
			'fetchDescription' => $wgFetchCommonsDescriptions,
		];
	}
}
</syntaxhighlight>

<translate>
=== ForeignDBViaLBRepo class === <!--T:81-->
</translate>
; wiki
: <translate><!--T:82--> wiki-db-name used in <tvar name=LBFactoryConf>{{wg|LBFactoryConf}}</tvar></translate>

<translate>
=== Directory permissions === <!--T:52-->

<!--T:53-->
You'll need rw on <code>$IP/images</code> and <code>$IP/images/thumbs</code> for whatever user php runs as.

== Usage == <!--T:54-->
</translate>
{{MW 1.31|+}}<!-- class was changed in 1.31-->

<translate>
=== Using files from Wikimedia Commons : ForeignAPIRepo === <!--T:55-->
</translate>
{{Note|1=''<translate><!--T:56--> Since 1.16.0 there is a more convenient shorthand to use Commons as a foreign repository: <tvar name=UseInstantCommons>{{wg|UseInstantCommons}}</tvar>.</translate>''|2=reminder}}

<translate>
<!--T:57-->
You can set your wiki to use media from [[commons:|Wikimedia Commons]] (or from any other MediaWiki-powered site, see below) directly. However, please beware any legal implications.

<!--T:58-->
To use this, you need:
</translate>

* {{ll|MediaWiki 1.13|MediaWiki 1.13}}+
* <translate><!--T:60--> '''PHP with JSON support''' (for the <code>json_decode()</code> 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.</translate>
* <translate><!--T:61--> The remote wiki must also use MediaWiki 1.13 or later; otherwise its <code>[[api.php]]</code> returns <tvar name=code><code><nowiki>{"error":{"code":"iiunknown_iiprop","info":"Unrecognised values for parameter 'iiprop'"}}</nowiki></code></tvar> and file requests fail silently (i.e. the requested files are just treated as non-existent).</translate>

<translate>
<!--T:62-->
The code below enables media files from Wikimedia Commons on your site. You should place it in your "LocalSettings.php" file:
</translate>

<syntaxhighlight lang="php">
$wgForeignFileRepos[] = [
	'class' => ForeignAPIRepo::class,
	'name' => 'commonswiki', // <translate nowrap><!--T:104--> Must be a distinct name</translate>
	'apibase' => 'https://commons.wikimedia.org/w/api.php',
	'hashLevels' => 2,
	'fetchDescription' => true, // <translate nowrap><!--T:105--> Optional</translate>
	'descriptionCacheExpiry' => 43200, // <translate nowrap><!--T:106--> 12 hours, optional (values are seconds)</translate>
    'apiMetadataExpiry' => 14400, // <translate nowrap><!--T:107--> 4 hours, optional. Consider increasing for better performance.</translate>
	'apiThumbCacheExpiry' => 86400, // <translate nowrap><!--T:108--> 24 hours, optional, but required for local thumb caching (Note local thumb caching is often slower than not doing it)</translate>
];
</syntaxhighlight>

{{Note|1=<translate><!--T:63--> If you decide to add this setting to your "LocalSettings.php" file instead of using <tvar name=1>{{wg|UseInstantCommons}}</tvar> you cannot use <code>wikimediacommons</code> as a setting for <code>name</code> since it is already present in core MediaWiki code (in "Setup.php").</translate>}}

<translate><!--T:64--> To pull images from another Wikimedia project, set <tvar name=1><code>apibase</code></tvar> to this wiki's "<tvar name=2>api.php</tvar>" file like e.g. <tvar name=3><code><nowiki>https://en.wikipedia.org/w/api.php</nowiki></code></tvar>.</translate>
<translate><!--T:65--> Example:</translate>

<syntaxhighlight lang="php">
$wgForeignFileRepos[] = [
	'class' => ForeignAPIRepo::class,
	'name' => 'enwikipedia',
	'apibase' => 'https://en.wikipedia.org/w/api.php',
	'hashLevels' => 2,
	'fetchDescription' => true,
	'descriptionCacheExpiry' => 43200,
	'apiThumbCacheExpiry' => 86400,
];
</syntaxhighlight>

<translate>
<!--T:66-->
To embed an image in your installation, simply use <code><nowiki> [[File:name_of_commons_picture.jpg]]</nowiki></code>.

====Performance==== <!--T:96-->
</translate>
<translate><!--T:67--> You may need to configure the <tvar name=1>{{wg|MainCacheType}}</tvar> as well.</translate>
<translate><!--T:93--> Default is often <tvar name=1>'''CACHE_NONE'''</tvar>, meaning it will load the image from the remote host on each page load which will be very slow.</translate>
<translate><!--T:94--> Similarly, you need to set <tvar name=1><code>apiThumbCacheExpiry</code></tvar> to zero if you prefer to use the foreign thumbnails which will be faster.</translate>
<translate><!--T:100--> The default for <tvar name=1>apiMetadataExpiry</tvar> is 4 hours.</translate>
<translate><!--T:101--> This is one of the most impactful settings for performance.</translate>
<translate><!--T:102--> Consider setting to a really high value, such as <tvar name=1>{{formatnum:604800}}</tvar> (1 week) for best performance.</translate>
<translate><!--T:103--> However this may mean that it can take up to that long for changes to the file to get to your wiki.</translate>

<translate>
<!--T:97-->
Setting <tvar name=1><code>{{ll|Manual:$wgResponsiveImages|$wgResponsiveImages}} = false;</code></tvar> may improve performance of instant commons at the cost of making images be lower quality on high resolution displays.
</translate>

<translate><!--T:98--> Currently MediaWiki does not support pipelining foreign api requests.</translate>
<translate><!--T:99--> A high performance site may want to look at setting up a local proxy (like nginx) that can coalesce multiple requests into a single pipelined request to reduce round trip times from TCP & TLS handshakes.</translate>

<translate><!--T:113--> There is also an alternative implementation at <tvar name=1>{{ll|Extension:QuickInstantCommons}}</tvar> which may be much faster</translate>

<translate>
=== Using files from a database that you can access : ForeignDBRepo, ForeignDBViaLBRepo === <!--T:68-->
</translate>
<translate><!--T:69--> The '''ForeignDBRepo''' class is very useful for creating [[<tvar name=wf>Special:MyLanguage/Manual:Wiki family</tvar>|wiki families]]. In a wiki family, each wiki will have its own database or table prefix.</translate>
<translate><!--T:70--> Using this class, you can make a family member aware of the tables  of another family member.</translate>
<translate><!--T:71--> Access through ForeignDBRepo is faster than through ForeignAPIRepo. This code should be deployed to LocalSettings.php.</translate>

<syntaxhighlight lang="php">
$wgForeignFileRepos[] = [
	'class' => ForeignDBRepo::class,
	'name' => 'otherwiki',
	'url' => "https://example.org/w/images",
	'directory' => '/path/to/uploads',
	'hashLevels' => 2, // <translate nowrap><!--T:109--> This must be the same for the other family member</translate>
	'dbType' => $wgDBtype,
	'dbServer' => $wgDBserver,
	'dbUser' => $wgDBuser,
	'dbPassword' => $wgDBpassword,
	'dbFlags' => DBO_DEFAULT,
	'dbName' => 'mydb',
	'tablePrefix' => 'mw_',
	'hasSharedCache' => false,
	'descBaseUrl' => 'https://example.org/wiki/File:',
	'fetchDescription' => false
];
</syntaxhighlight>

<translate>
<!--T:72-->
Alternatively, if you have <tvar name=lbfc>{{wg|LBFactoryConf}}</tvar> set up for multiple wikis, you can use <tvar name=1><syntaxhighlight lang=php inline>'class' => ForeignDBViaLBRepo::class</syntaxhighlight></tvar>:
</translate>

<syntaxhighlight lang="php">
$wgForeignFileRepos[] = [
	'class' => ForeignDBViaLBRepo::class,
	'wiki' => 'wiki-db-name-used-with-wgLBFactoryConf',
	'name' => 'otherwiki', # <translate nowrap><!--T:110--> displayname (eg. the vector-skin-tab “View on OtherWiki“) may be set at wiki-specific <tvar name=1>MediaWiki:Shared-repo-name-<otherwiki></tvar></translate>
	'url' => 'https://example.org/w/images',
	'directory' => '/path/to/uploads',
	'hashLevels' => 2, # <translate nowrap><!--T:111--> This must be the same for the other family member</translate>
	'tablePrefix' => 'mw_',
	'hasSharedCache' => false,
	'fetchDescription' => true,
	'scriptDirUrl' => 'https://example.org/w', # <translate nowrap><!--T:112--> has effect whether description can be fetched</translate>
];
</syntaxhighlight>

<translate>
<!--T:83-->
This needs not all the ''db*'' parameters as in <code>ForeignDBRepo</code>.

=== Using files from a local folder : FileRepo === <!--T:73-->

<!--T:74-->
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 added to LocalSettings.php.

<!--T:75-->
The below code enabled media files from it:
</translate>

<syntaxhighlight lang="php">
$wgForeignFileRepos[] = [
	'class' => FileRepo::class,
	'name' => 'sharedFsRepo',
	'directory' => 'media',
	'hashLevels' => 0,
	'url' => 'https://shared.example.org/path/to/media',
];
</syntaxhighlight>

<translate>
== Caveats == <!--T:88-->
</translate>
<translate><!--T:89--> For optimal performance, use a wiki whose primary purpose is to serve as a commons as the target of <code>$wgForeignFileRepos</code>.</translate>
<translate><!--T:90--> Avoid, for instance, pointing two content wikis at each other as foreign repositories in order to share files between them, because this will generate an excessive number of file requests on page views and edits as both wikis request the file from each other.</translate>

<translate><!--T:91--> Likewise, avoid sharing a database between the commons wiki and other content wikis, especially if you must use <code>ForeignAPIRepo</code> instead of <code>ForeignDBRepo</code> due to limitations imposed by your service provider or administrator.</translate>
<translate><!--T:92--> This generates a large number of potentially long-lived database connections that can result in impaired performance, or can exceed DB connection limits even on wikis with very little traffic or activity.</translate>

<translate>
== See also == <!--T:76-->
</translate>
* {{wg|LocalFileRepo}}
* {{ll|Manual:Wiki family}}
* {{ll|Manual:Configuring file uploads}} <translate><!--T:84--> (mainly for local uploads)</translate>
* {{wg|UseInstantCommons}} <translate><!--T:78--> (to automatically add commons to the file repository array)</translate>
<translate>
<!--T:85-->
* <tvar name=filerepoinfo>{{ll|API:Filerepoinfo|filerepoinfo}}</tvar> API for getting information about the configuration of a repo, e.g.</translate> https://www.mediawiki.org/w/api.php?action=query&format=json&meta=filerepoinfo
* [[Extension:QuickInstantCommons]]
* [[:Category:File repository extensions]]