Merge branch '2.3' into 2.5

* 2.3:
  [ClassLoader] removes deprecated classes from documentation.
  [Yaml] Update README.md
  [Security] fixed wrong phpdoc

src/Symfony/Component/ClassLoader/ApcClassLoader.php

@@ -17,11 +17,19 @@ namespace Symfony\Component\ClassLoader;
  * It expects an object implementing a findFile method to find the file. This
  * allows using it as a wrapper around the other loaders of the component (the
  * ClassLoader and the UniversalClassLoader for instance) but also around any
- * other autoloader following this convention (the Composer one for instance)
+ * other autoloaders following this convention (the Composer one for instance).
+ *
+ *     // with a Symfony autoloader
+ *     use Symfony\Component\ClassLoader\ClassLoader;
  *
  *     $loader = new ClassLoader();
+ *     $loader->addPrefix('Symfony\Component', __DIR__.'/component');
+ *     $loader->addPrefix('Symfony',           __DIR__.'/framework');
  *
- *     // register classes with namespaces
+ *     // or with a Composer autoloader
+ *     use Composer\Autoload\ClassLoader;
+ *
+ *     $loader = new ClassLoader();
  *     $loader->add('Symfony\Component', __DIR__.'/component');
  *     $loader->add('Symfony',           __DIR__.'/framework');
  *

src/Symfony/Component/ClassLoader/README.md

@@ -4,34 +4,34 @@ ClassLoader Component
 ClassLoader loads your project classes automatically if they follow some
 standard PHP conventions.
 
-The Universal ClassLoader is able to autoload classes that implement the PSR-0
+The ClassLoader object is able to autoload classes that implement the PSR-0
 standard or the PEAR naming convention.
 
 First, register the autoloader:
 
 ```php
-require_once __DIR__.'/src/Symfony/Component/ClassLoader/UniversalClassLoader.php';
+require_once __DIR__.'/src/Symfony/Component/ClassLoader/ClassLoader.php';
 
-use Symfony\Component\ClassLoader\UniversalClassLoader;
+use Symfony\Component\ClassLoader\ClassLoader;
 
-$loader = new UniversalClassLoader();
+$loader = new ClassLoader();
 $loader->register();
 ```
 
-Then, register some namespaces with the `registerNamespace()` method:
+Then, register some namespaces with the `addPrefix()` method:
 
 ```php
-$loader->registerNamespace('Symfony', __DIR__.'/src');
-$loader->registerNamespace('Monolog', __DIR__.'/vendor/monolog/src');
+$loader->addPrefix('Symfony', __DIR__.'/src');
+$loader->addPrefix('Monolog', __DIR__.'/vendor/monolog/src');
 ```
 
-The `registerNamespace()` method takes a namespace prefix and a path where to
+The `addPrefix()` method takes a namespace prefix and a path where to
 look for the classes as arguments.
 
 You can also register a sub-namespaces:
 
 ```php
-$loader->registerNamespace('Doctrine\\Common', __DIR__.'/vendor/doctrine-common/lib');
+$loader->addPrefix('Doctrine\\Common', __DIR__.'/vendor/doctrine-common/lib');
 ```
 
 The order of registration is significant and the first registered namespace
@@ -40,14 +40,14 @@ takes precedence over later registered one.
 You can also register more than one path for a given namespace:
 
 ```php
-$loader->registerNamespace('Symfony', array(__DIR__.'/src', __DIR__.'/symfony/src'));
+$loader->addPrefix('Symfony', array(__DIR__.'/src', __DIR__.'/symfony/src'));
 ```
 
-Alternatively, you can use the `registerNamespaces()` method to register more
+Alternatively, you can use the `addPrefixes()` method to register more
 than one namespace at once:
 
 ```php
-$loader->registerNamespaces(array(
+$loader->addPrefixes(array(
     'Symfony' => array(__DIR__.'/src', __DIR__.'/symfony/src'),
     'Doctrine\\Common' => __DIR__.'/vendor/doctrine-common/lib',
     'Doctrine' => __DIR__.'/vendor/doctrine/lib',
@@ -55,16 +55,20 @@ $loader->registerNamespaces(array(
 ));
 ```
 
-For better performance, you can use the APC based version of the universal
-class loader:
+For better performance, you can use the APC class loader:
 
 ```php
-require_once __DIR__.'/src/Symfony/Component/ClassLoader/UniversalClassLoader.php';
-require_once __DIR__.'/src/Symfony/Component/ClassLoader/ApcUniversalClassLoader.php';
+require_once __DIR__.'/src/Symfony/Component/ClassLoader/ClassLoader.php';
+require_once __DIR__.'/src/Symfony/Component/ClassLoader/ApcClassLoader.php';
 
-use Symfony\Component\ClassLoader\ApcUniversalClassLoader;
+use Symfony\Component\ClassLoader\ClassLoader;
+use Symfony\Component\ClassLoader\ApcClassLoader;
 
-$loader = new ApcUniversalClassLoader('apc.prefix.');
+$loader = new ClassLoader();
+$loader->addPrefix('Symfony', __DIR__.'/src');
+
+$loader = new ApcClassLoader('apc.prefix.', $loader);
+$loader->register();
 ```
 
 Furthermore, the component provides tools to aggregate classes into a single

src/Symfony/Component/ClassLoader/WinCacheClassLoader.php

@@ -17,11 +17,19 @@ namespace Symfony\Component\ClassLoader;
  * It expects an object implementing a findFile method to find the file. This
  * allow using it as a wrapper around the other loaders of the component (the
  * ClassLoader and the UniversalClassLoader for instance) but also around any
- * other autoloader following this convention (the Composer one for instance)
+ * other autoloaders following this convention (the Composer one for instance).
+ *
+ *     // with a Symfony autoloader
+ *     use Symfony\Component\ClassLoader\ClassLoader;
  *
  *     $loader = new ClassLoader();
+ *     $loader->addPrefix('Symfony\Component', __DIR__.'/component');
+ *     $loader->addPrefix('Symfony',           __DIR__.'/framework');
  *
- *     // register classes with namespaces
+ *     // or with a Composer autoloader
+ *     use Composer\Autoload\ClassLoader;
+ *
+ *     $loader = new ClassLoader();
  *     $loader->add('Symfony\Component', __DIR__.'/component');
  *     $loader->add('Symfony',           __DIR__.'/framework');
  *

src/Symfony/Component/ClassLoader/XcacheClassLoader.php

@@ -17,11 +17,19 @@ namespace Symfony\Component\ClassLoader;
  * It expects an object implementing a findFile method to find the file. This
  * allows using it as a wrapper around the other loaders of the component (the
  * ClassLoader and the UniversalClassLoader for instance) but also around any
- * other autoloader following this convention (the Composer one for instance)
+ * other autoloaders following this convention (the Composer one for instance).
+ *
+ *     // with a Symfony autoloader
+ *     use Symfony\Component\ClassLoader\ClassLoader;
  *
  *     $loader = new ClassLoader();
+ *     $loader->addPrefix('Symfony\Component', __DIR__.'/component');
+ *     $loader->addPrefix('Symfony',           __DIR__.'/framework');
  *
- *     // register classes with namespaces
+ *     // or with a Composer autoloader
+ *     use Composer\Autoload\ClassLoader;
+ *
+ *     $loader = new ClassLoader();
  *     $loader->add('Symfony\Component', __DIR__.'/component');
  *     $loader->add('Symfony',           __DIR__.'/framework');
  *

src/Symfony/Component/Security/Core/Authentication/Token/TokenInterface.php

@@ -47,8 +47,10 @@ interface TokenInterface extends \Serializable
     /**
      * Returns a user representation.
      *
-     * @return mixed either returns an object which implements __toString(), or
-     *               a primitive string is returned.
+     * @return mixed Can be a UserInterface instance, an object implementing a __toString method,
+     *               or the username as a regular string
+     *
+     * @see AbstractToken::setUser()
      */
     public function getUser();
 

src/Symfony/Component/Yaml/README.md

@@ -6,7 +6,7 @@ YAML implements most of the YAML 1.2 specification.
 ```php
 use Symfony\Component\Yaml\Yaml;
 
-$array = Yaml::parse($file);
+$array = Yaml::parse(file_get_contents(filename));
 
 print Yaml::dump($array);
 ```