deprecate(file): Deprecates accessing filestore metadata

Warns plugin devs not to access `filestore::*` metadata on file objects.

Admins migrating sites are also warned about plugins using custom filestores.

Refs #9191

docs/admin/duplicate-installation.rst

@@ -198,7 +198,11 @@ Change the filestore data directory
 
 .. warning::
 
-   Only change the first path here!!
+   Only change the first path above!!
+
+.. warning::
+
+   If you have a plugin that uses custom filestores (contains an ``ElggFile::setFilestore`` method call or sets metadata with names like ``filestore::*``), then query above may not be safe (it overwrites *all* filesystem ``dir_root`` locations). Please seek guidance via the Elgg community.
 
 Check .htaccess
 ===============

docs/guides/upgrading.rst

@@ -610,6 +610,13 @@ Viewtype is static after the initial ``elgg_get_viewtype()`` call
 ``view`` input and ``$CONFIG->view`` initially, this is only done once per request.
 
 
+Deprecations
+------------
+
+It's deprecated to read or write to metadata keys starting with ``filestore::`` on ``ElggFile`` objects. In Elgg 3.0 this metadata will be deleted if it points to the current data root path, so few file objects will have it. Plugins should only use ``ElggFile::setFilestore`` if files need to be stored in a custom location.
+
+.. note:: This is not the only deprecation in Elgg 2.0. Plugin developers should watch their site error logs.
+
 From 1.10 to 1.11
 =================
 

engine/classes/ElggFile.php

@@ -49,6 +49,26 @@ public function __construct($row = null) {
 		$this->filestore = $this->getFilestore();
 	}
 
+	/**
+	 * {@inheritdoc}
+	 */
+	public function getMetadata($name) {
+		if (0 === strpos($name, 'filestore::')) {
+			elgg_deprecated_notice("Do not access the ElggFile filestore metadata directly. Use setFilestore().", '2.0');
+		}
+		return parent::getMetadata($name);
+	}
+
+	/**
+	 * {@inheritdoc}
+	 */
+	public function setMetadata($name, $value, $value_type = '', $multiple = false, $owner_guid = 0, $access_id = null) {
+		if (0 === strpos($name, 'filestore::')) {
+			elgg_deprecated_notice("Do not access the ElggFile filestore metadata directly. Use setFilestore().", '2.0');
+		}
+		return parent::setMetadata($name, $value, $value_type, $multiple, $owner_guid, $access_id);
+	}
+
 	/**
 	 * Set the filename of this file.
 	 *
@@ -442,11 +462,11 @@ public function save() {
 		// Save datastore metadata
 		$params = $this->filestore->getParameters();
 		foreach ($params as $k => $v) {
-			$this->setMetadata("filestore::$k", $v);
+			parent::setMetadata("filestore::$k", $v);
 		}
 
 		// Now make a note of the filestore class
-		$this->setMetadata("filestore::filestore", get_class($this->filestore));
+		parent::setMetadata("filestore::filestore", get_class($this->filestore));
 
 		return true;
 	}