deprecate target-dir and update docs to recommend psr-4, refs #2459

doc/01-basic-usage.md

@@ -183,17 +183,16 @@ to `composer.json`.
 
     {
         "autoload": {
-            "psr-0": {"Acme\\": "src/"}
+            "psr-4": {"Acme\\": "src/"}
         }
     }
 
-Composer will register a
+Composer will register a [PSR-4](http://www.php-fig.org/psr/psr-4/) autoloader
-[PSR-0](https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-0.md)
+for the `Acme` namespace.
-autoloader for the `Acme` namespace.
 
 You define a mapping from namespaces to directories. The `src` directory would
 be in your project root, on the same level as `vendor` directory is. An example
-filename would be `src/Acme/Foo.php` containing an `Acme\Foo` class.
+filename would be `src/Foo.php` containing an `Acme\Foo` class.
 
 After adding the `autoload` field, you have to re-run `install` to re-generate
 the `vendor/autoload.php` file.
@@ -205,12 +204,12 @@ This can be useful for autoloading classes in a test suite, for example.
     $loader = require 'vendor/autoload.php';
     $loader->add('Acme\\Test\\', __DIR__);
 
-In addition to PSR-0 autoloading, classmap is also supported. This allows
+In addition to PSR-4 autoloading, classmap is also supported. This allows
-classes to be autoloaded even if they do not conform to PSR-0. See the
+classes to be autoloaded even if they do not conform to PSR-4. See the
 [autoload reference](04-schema.md#autoload) for more details.
 
 > **Note:** Composer provides its own autoloader. If you don't want to use
-that one, you can just include `vendor/composer/autoload_namespaces.php`,
+that one, you can just include `vendor/composer/autoload_*.php` files,
-which returns an associative array mapping namespaces to directories.
+which return associative arrays allowing you to configure your own autoloader.
 
 ← [Intro](00-intro.md)  |  [Libraries](02-libraries.md) →

doc/03-cli.md

@@ -85,7 +85,7 @@ resolution.
 * **--no-plugins:** Disables plugins.
 * **--no-progress:** Removes the progress display that can mess with some
   terminals or scripts which don't handle backspace characters.
-* **--optimize-autoloader (-o):** Convert PSR-0 autoloading to classmap to get a faster
+* **--optimize-autoloader (-o):** Convert PSR-0/4 autoloading to classmap to get a faster
   autoloader. This is recommended especially for production, but can take
   a bit of time to run so it is currently not done by default.
 
@@ -118,7 +118,7 @@ You can also use wildcards to update a bunch of packages at once:
 * **--no-plugins:** Disables plugins.
 * **--no-progress:** Removes the progress display that can mess with some
   terminals or scripts which don't handle backspace characters.
-* **--optimize-autoloader (-o):** Convert PSR-0 autoloading to classmap to get a faster
+* **--optimize-autoloader (-o):** Convert PSR-0/4 autoloading to classmap to get a faster
   autoloader. This is recommended especially for production, but can take
   a bit of time to run so it is currently not done by default.
 * **--lock:** Only updates the lock file hash to suppress warning about the
@@ -373,16 +373,16 @@ If you need to update the autoloader because of new classes in a classmap
 package for example, you can use "dump-autoload" to do that without having to
 go through an install or update.
 
-Additionally, it can dump an optimized autoloader that converts PSR-0 packages
+Additionally, it can dump an optimized autoloader that converts PSR-0/4 packages
 into classmap ones for performance reasons. In large applications with many
 classes, the autoloader can take up a substantial portion of every request's
 time. Using classmaps for everything is less convenient in development, but
-using this option you can still use PSR-0 for convenience and classmaps for
+using this option you can still use PSR-0/4 for convenience and classmaps for
 performance.
 
 ### Options
 
-* **--optimize (-o):** Convert PSR-0 autoloading to classmap to get a faster
+* **--optimize (-o):** Convert PSR-0/4 autoloading to classmap to get a faster
   autoloader. This is recommended especially for production, but can take
   a bit of time to run so it is currently not done by default.
 

doc/04-schema.md

@@ -380,10 +380,55 @@ Example:
 
 Autoload mapping for a PHP autoloader.
 
-Currently [`PSR-0`](https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-0.md)
+Currently [`PSR-0`](http://www.php-fig.org/psr/psr-0/) autoloading,
-autoloading, `classmap` generation and `files` are supported. PSR-0 is the recommended way though
+[`PSR-4`](http://www.php-fig.org/psr/psr-4/) autoloading, `classmap` generation and
-since it offers greater flexibility (no need to regenerate the autoloader when you add
+`files` includes are supported. PSR-4 is the recommended way though since it offers
-classes).
+greater ease of use (no need to regenerate the autoloader when you add classes).
+
+#### PSR-4
+
+Under the `psr-4` key you define a mapping from namespaces to paths, relative to the
+package root. When autoloading a class like `Foo\\Bar\\Baz` a namespace prefix
+`Foo\\` pointing to a directory `src/` means that the autoloader will look for a
+file named `src/Bar/Baz.php` and include it if present. Note that as opposed to
+the older PSR-0 style, the prefix (`Foo\\`) is **not** present in the file path.
+
+Namespace prefixes must end in `\\` to avoid conflicts between similar prefixes.
+For example `Foo` would match classes in the `FooBar` namespace so the trailing
+backslashes solve the problem: `Foo\\` and `FooBar\\` are distinct.
+
+The PSR-4 references are all combined, during install/update, into a single
+key => value array which may be found in the generated file
+`vendor/composer/autoload_psr4.php`.
+
+Example:
+
+    {
+        "autoload": {
+            "psr-4": {
+                "Monolog\\": "src/",
+                "Vendor\\Namespace\\": "",
+            }
+        }
+    }
+
+If you need to search for a same prefix in multiple directories,
+you can specify them as an array as such:
+
+    {
+        "autoload": {
+            "psr-4": { "Monolog\\": ["src/", "lib/"] }
+        }
+    }
+
+If you want to have a fallback directory where any namespace will be looked for,
+you can use an empty prefix like:
+
+    {
+        "autoload": {
+            "psr-4": { "": "src/" }
+        }
+    }
 
 #### PSR-0
 
@@ -438,10 +483,6 @@ use an empty prefix like:
         }
     }
 
-#### PSR-4
-
-Stub: Similar to PSR-0.
-
 #### Classmap
 
 The `classmap` references are all combined, during install/update, into a single
@@ -450,7 +491,7 @@ key => value array which may be found in the generated file
 classes in all `.php` and `.inc` files in the given directories/files.
 
 You can use the classmap generation support to define autoloading for all libraries
-that do not follow PSR-0. To configure this you specify all directories or files
+that do not follow PSR-0/4. To configure this you specify all directories or files
 to search for classes.
 
 Example:
@@ -493,6 +534,10 @@ Optional.
 
 ### target-dir
 
+> **DEPRECATED**: This is only present to support legacy PSR-0 style autoloading,
+> and all new code should preferably use PSR-4 without target-dir and projects
+> using PSR-0 with PHP namespaces are encouraged to migrate to PSR-4 instead.
+
 Defines the installation target.
 
 In case the package root is below the namespace declaration you cannot

res/composer-schema.json

@@ -13,7 +13,7 @@
             "type": "string"
         },
         "target-dir": {
-            "description": "Forces the package to be installed into the given subdirectory path. This is used for autoloading PSR-0 packages that do not contain their full path. Use forward slashes for cross-platform compatibility.",
+            "description": "DEPRECATED: Forces the package to be installed into the given subdirectory path. This is used for autoloading PSR-0 packages that do not contain their full path. Use forward slashes for cross-platform compatibility.",
             "type": "string"
         },
         "description": {