From 8775a89710b1168d05d4e8478bb27acdaa4cf1ac Mon Sep 17 00:00:00 2001 From: Jordi Boggiano Date: Fri, 3 Jan 2014 16:46:56 +0100 Subject: [PATCH] deprecate target-dir and update docs to recommend psr-4, refs #2459 --- doc/01-basic-usage.md | 17 +++++------ doc/03-cli.md | 10 +++---- doc/04-schema.md | 63 ++++++++++++++++++++++++++++++++++------ res/composer-schema.json | 2 +- 4 files changed, 68 insertions(+), 24 deletions(-) diff --git a/doc/01-basic-usage.md b/doc/01-basic-usage.md index c353b8b6f..1aa3eee05 100644 --- a/doc/01-basic-usage.md +++ b/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 -[PSR-0](https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-0.md) -autoloader for the `Acme` namespace. +Composer will register a [PSR-4](http://www.php-fig.org/psr/psr-4/) 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 -classes to be autoloaded even if they do not conform to PSR-0. See the +In addition to PSR-4 autoloading, classmap is also supported. This allows +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`, -which returns an associative array mapping namespaces to directories. +that one, you can just include `vendor/composer/autoload_*.php` files, +which return associative arrays allowing you to configure your own autoloader. ← [Intro](00-intro.md) | [Libraries](02-libraries.md) → diff --git a/doc/03-cli.md b/doc/03-cli.md index 84539b4da..8d34fb49e 100644 --- a/doc/03-cli.md +++ b/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. diff --git a/doc/04-schema.md b/doc/04-schema.md index e52f19902..f0852668d 100644 --- a/doc/04-schema.md +++ b/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) -autoloading, `classmap` generation and `files` are supported. PSR-0 is the recommended way though -since it offers greater flexibility (no need to regenerate the autoloader when you add -classes). +Currently [`PSR-0`](http://www.php-fig.org/psr/psr-0/) autoloading, +[`PSR-4`](http://www.php-fig.org/psr/psr-4/) autoloading, `classmap` generation and +`files` includes are supported. PSR-4 is the recommended way though since it offers +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 diff --git a/res/composer-schema.json b/res/composer-schema.json index 41a4ab5ff..962398447 100644 --- a/res/composer-schema.json +++ b/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": {