feature #15719 Deprecate ResourceInterface::getResource() (mpdude)

fabpot · fabpot · commit 4fcf136079da · 2015-09-26T10:19:26.000+02:00
This PR was merged into the 2.8 branch. Discussion ---------- Deprecate ResourceInterface::getResource() | Q | A | ------------- | --- | Bug fix? | no | New feature? | no | BC breaks? | no | Deprecations? | yes | Tests pass? | yes | Fixed tickets | | License | MIT | Doc PR | n/a The return value of this method does not make sense if you do not exactly know about the type of resource at hand. For example, it may be [an array](https://github.com/symfony/symfony/blob/b49fa129bdb3c0aa970a006b16dd1ca63a9d7ebd/src/Symfony/Component/HttpKernel/Config/EnvParametersResource.php#L57) or a [file path](https://github.com/symfony/symfony/blob/87800ae47e64429f2544b798575d1cc1d4e5464a/src/Symfony/Component/Config/Resource/FileResource.php#L51). As all usages of getResource() within Symfony are in tests of particular Resource implementations anyway, deprecating and later removing this method helps us with simplifying the ResourceInterface (#7176). Commits ------- 87c0c7d Deprecate ResourceInterface::getResource()
diff --git a/src/Symfony/Component/Config/CHANGELOG.md b/src/Symfony/Component/Config/CHANGELOG.md
@@ -23,6 +23,10 @@ After: the code will work as expected and it will restrict the values of the
  
  * deprecated the `ResourceInterface::isFresh()` method. If you implement custom resource types and they
    can be validated that way, make them implement the new `SelfCheckingResourceInterface`.
+ * deprecated the getResource() method in ResourceInterface. You can still call this method
+   on concrete classes implementing the interface, but it does not make sense at the interface
+   level as you need to know about the particular type of resource at hand to understand the
+   semantics of the returned value.
 
 2.7.0
 -----
diff --git a/src/Symfony/Component/Config/Resource/ResourceInterface.php b/src/Symfony/Component/Config/Resource/ResourceInterface.php
@@ -47,6 +47,12 @@ public function isFresh($timestamp);
      * Returns the tied resource.
      *
      * @return mixed The resource
+     *
+     * @deprecated since 2.8, to be removed in 3.0. As there are many different kinds of resource,
+     *             a single getResource() method does not make sense at the interface level. You
+     *             can still call getResource() on implementing classes, probably after performing
+     *             a type check. If you know the concrete type of Resource at hand, the return value
+     *             of this method may make sense to you.
      */
     public function getResource();
 }

Original file line number	Diff line number	Diff line change
`@@ -47,6 +47,12 @@ public function isFresh($timestamp);`
`47`	`47`	`* Returns the tied resource.`
`48`	`48`	`*`
`49`	`49`	`* @return mixed The resource`
	`50`	`+ *`
	`51`	`+ * @deprecated since 2.8, to be removed in 3.0. As there are many different kinds of resource,`
	`52`	`+ * a single getResource() method does not make sense at the interface level. You`
	`53`	`+ * can still call getResource() on implementing classes, probably after performing`
	`54`	`+ * a type check. If you know the concrete type of Resource at hand, the return value`
	`55`	`+ * of this method may make sense to you.`
`50`	`56`	`*/`
`51`	`57`	`public function getResource();`
`52`	`58`	`}`