From a2eeeab79ac5537d2c9723005ade603d2ca8893e Mon Sep 17 00:00:00 2001 From: Igor Wiedler Date: Fri, 13 Apr 2012 12:06:53 +0200 Subject: [PATCH 1/8] [improve-docs] Mention classmap autoloading in basic-usage --- doc/01-basic-usage.md | 27 +++++++++++++++++---------- doc/04-schema.md | 4 ++-- 2 files changed, 19 insertions(+), 12 deletions(-) diff --git a/doc/01-basic-usage.md b/doc/01-basic-usage.md index 42c543a6f..025631b8e 100644 --- a/doc/01-basic-usage.md +++ b/doc/01-basic-usage.md @@ -103,7 +103,7 @@ to those specific versions. This is important because the `install` command checks if a lock file is present, and if it is, it downloads the versions specified there (regardless of what `composer.json` says). This means that anyone who sets up the project will download the exact -same version of the dependencies. +same version of the dependencies. If no `composer.json` lock file exists, it will read the dependencies and versions from `composer.json` and create the lock file. @@ -135,16 +135,15 @@ but it makes life quite a bit simpler. ## Autoloading -For libraries that follow the [PSR-0](https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-0.md) -naming standard, Composer generates a `vendor/.composer/autoload.php` file -for autoloading. You can simply include this file and you will get autoloading -for free. +For libraries that specify autoload information, Composer generates a +`vendor/.composer/autoload.php` file. You can simply include this file and you +will get autoloading for free. require 'vendor/.composer/autoload.php'; -This makes it really easy to use third party code: For monolog, it -means that we can just start using classes from it, and they will be -autoloaded. +This makes it really easy to use third party code. For example: If your +project depends on monolog, you can just start using classes from it, and they +will be autoloaded. $log = new Monolog\Logger('name'); $log->pushHandler(new Monolog\Handler\StreamHandler('app.log', Monolog\Logger::WARNING)); @@ -160,8 +159,12 @@ to `composer.json`. } } -This is a mapping from namespaces to directories. The `src` directory would be -in your project root. An example filename would be `src/Acme/Foo.php` +Composer will register a +[PSR-0](https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-0.md) +autoloader for the `Acme` namespace. + +You define a mapping from namespaces to directories. The `src` directory would +be in your project root. An example filename would be `src/Acme/Foo.php` containing an `Acme\Foo` class. After adding the `autoload` field, you have to re-run `install` to re-generate @@ -174,6 +177,10 @@ This can be useful for autoloading classes in a test suite, for example. $loader = require 'vendor/.composer/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 +[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. diff --git a/doc/04-schema.md b/doc/04-schema.md index f7cd9bfe5..c7fa866f6 100644 --- a/doc/04-schema.md +++ b/doc/04-schema.md @@ -188,7 +188,7 @@ Optional. Autoload mapping for a PHP autoloader. Currently [PSR-0](https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-0.md) -autoloading and ClassMap generation are supported. +autoloading and classmap generation are supported. Under the `psr-0` key you define a mapping from namespaces to paths, relative to the package root. @@ -212,7 +212,7 @@ you can specify them as an array as such: } 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 +that do not follow PSR-0. To configure this you specify all directories to search for classes. Example: From 3580f033df5d7084dbc6ff98144ad9c49a2246a7 Mon Sep 17 00:00:00 2001 From: Igor Wiedler Date: Fri, 13 Apr 2012 12:13:52 +0200 Subject: [PATCH 2/8] [improve-docs] Add taglines to articles --- doc/articles/custom-installers.md | 2 +- doc/articles/handling-private-packages-with-satis.md | 3 +++ doc/articles/vendor-bins.md | 5 ++++- 3 files changed, 8 insertions(+), 2 deletions(-) diff --git a/doc/articles/custom-installers.md b/doc/articles/custom-installers.md index 506127d97..f69e90f0c 100644 --- a/doc/articles/custom-installers.md +++ b/doc/articles/custom-installers.md @@ -1,5 +1,5 @@ # Setting up and using custom installers diff --git a/doc/articles/handling-private-packages-with-satis.md b/doc/articles/handling-private-packages-with-satis.md index aa6b360a5..a91123f90 100644 --- a/doc/articles/handling-private-packages-with-satis.md +++ b/doc/articles/handling-private-packages-with-satis.md @@ -1,3 +1,6 @@ + # Handling private packages with Satis Satis can be used to host the metadata of your company's private packages, or diff --git a/doc/articles/vendor-bins.md b/doc/articles/vendor-bins.md index ce7a0607c..a915bbca6 100644 --- a/doc/articles/vendor-bins.md +++ b/doc/articles/vendor-bins.md @@ -1,3 +1,6 @@ + # bin and vendor/bin ## What is a bin? @@ -99,4 +102,4 @@ An example of the former looks like this: Running `composer install` for this `composer.json` will result in all of the vendor bins being installed in `scripts/` instead of -`vendor/bin/`. \ No newline at end of file +`vendor/bin/`. From cfe53bdc255f6c6a36b98eba31529e59f206ebbc Mon Sep 17 00:00:00 2001 From: Igor Wiedler Date: Fri, 13 Apr 2012 12:14:29 +0200 Subject: [PATCH 3/8] [improve-docs] Remove packagist update schedule article It is wrong and doesn't belong in the composer docs. --- doc/articles/packagist-update-schedule.md | 25 ----------------------- 1 file changed, 25 deletions(-) delete mode 100644 doc/articles/packagist-update-schedule.md diff --git a/doc/articles/packagist-update-schedule.md b/doc/articles/packagist-update-schedule.md deleted file mode 100644 index d5daedf30..000000000 --- a/doc/articles/packagist-update-schedule.md +++ /dev/null @@ -1,25 +0,0 @@ -# Packagist Update Schedule - -## How often does Packagist crawl newly added packages? - -New packages will be crawled **within ten minutes**. - - -## How often does Packagist crawl existing packages? - -Existing packages will be crawled **every hour**. - - -## How often does the Packagist search index update? - -The search index is updated **every five minutes**. It will index (or reindex) -any package that has been crawled since the last time the search -indexer ran. - - -## Can Packagist be triggered to recrawl a package (on commit or by other means)? - -Yes, you can click the "Force update" button on your package page if you are -logged in as a maintainer. The recommended way is to set up the GitHub hook, -you can find the URL and instructions on your Packagist -[profile](http://packagist.org/profile/) page. From e802b98897a1c4fb5b1c4e12ca319a01e7d3d841 Mon Sep 17 00:00:00 2001 From: Igor Wiedler Date: Fri, 13 Apr 2012 12:36:27 +0200 Subject: [PATCH 4/8] [improve-docs] Move create-project command documentation into cli chapter --- doc/03-cli.md | 28 ++++++++++++++++++++++++++++ doc/articles/create-projects.md | 23 ----------------------- 2 files changed, 28 insertions(+), 23 deletions(-) delete mode 100644 doc/articles/create-projects.md diff --git a/doc/03-cli.md b/doc/03-cli.md index 45344adea..d973783e1 100644 --- a/doc/03-cli.md +++ b/doc/03-cli.md @@ -142,6 +142,34 @@ command. It will replace your `composer.phar` with the latest version. $ php composer.phar self-update +## create-project + +You can use Composer to create new projects from an existing package. +There are several applications for this: + +1. You can deploy application packages. +2. You can check out any package and start developing on patches for example. +3. Projects with multiple developers can use this feature to bootstrap the + initial application for development. + +To create a new project using composer you can use the "create-project" command. +Pass it a package name, and the directory to create the project in. You can also +provide a version as third argument, otherwise the latest version is used. + +The directory is not allowed to exist, it will be created during installation. + + php composer.phar create-project doctrine/orm path 2.2.0 + +By default the command checks for the packages on packagist.org. + +### Options + +* **--repository-url:** Provide a custom repository to search for the package, + which will be used instead of packagist. Can be either an HTTP URL pointing + to a `composer` repository, or a path to a local `packages.json` file. +* **--prefer-source:** Get a development version of the code checked out + from version control. + ## help To get more information about a certain command, just use `help`. diff --git a/doc/articles/create-projects.md b/doc/articles/create-projects.md deleted file mode 100644 index 9dda91117..000000000 --- a/doc/articles/create-projects.md +++ /dev/null @@ -1,23 +0,0 @@ -# Create Projects - -You can use Composer to create new projects from an existing package. -There are several applications for this: - -1. You can deploy application packages. -2. You can check out any package and start developing on patches for example. -3. Projects with multiple developers can use this feature to bootstrap the initial application for development. - -To create a new project using composer you can use the "create-project" command. -Pass it a package name, and the directory to create the project in. You can also -provide a version as third argument, otherwise the latest version is used. - -The directory is not allowed to exist, it will be created during installation. - - php composer.phar create-project doctrine/orm path 2.2.0 - -By default the command checks for the packages on packagist.org. To change this behavior -you can use the --repository-url parameter and either point it to an HTTP url -for your own packagist repository or to a packages.json file. - -If you want to get a development version of the code directly checked out -from version control you have to add the --prefer-source parameter. From 6c4f47da7403152e3584161f09012ba231e0d742 Mon Sep 17 00:00:00 2001 From: Igor Wiedler Date: Fri, 13 Apr 2012 12:37:15 +0200 Subject: [PATCH 5/8] [improve-docs] Remove "Package root" from schema chapter --- doc/04-schema.md | 4 ---- 1 file changed, 4 deletions(-) diff --git a/doc/04-schema.md b/doc/04-schema.md index c7fa866f6..cdb597ad2 100644 --- a/doc/04-schema.md +++ b/doc/04-schema.md @@ -9,10 +9,6 @@ can also be used to validate your `composer.json`. In fact, it is used by the `validate` command. You can find it at: [`Resources/composer-schema.json`](https://github.com/composer/composer/blob/master/res/composer-schema.json). -## Package root - -The root of the package definition is a JSON object. - ## Properties ### name From 99c90cde5ae415d386966966e467ff96536964ca Mon Sep 17 00:00:00 2001 From: Igor Wiedler Date: Fri, 13 Apr 2012 12:41:16 +0200 Subject: [PATCH 6/8] [improve-docs] Specify that config and repositories are root-only, closes #500 --- doc/04-schema.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/doc/04-schema.md b/doc/04-schema.md index cdb597ad2..23fe42dde 100644 --- a/doc/04-schema.md +++ b/doc/04-schema.md @@ -231,6 +231,8 @@ Example: "include-path": ["lib/"] } +Optional. + ### target-dir Defines the installation target. @@ -256,7 +258,7 @@ To do that, `autoload` and `target-dir` are defined as follows: Optional. -### repositories +### repositories (root-only) Custom package repositories to use. @@ -322,7 +324,7 @@ will look from the first to the last repository, and pick the first match. By default Packagist is added last which means that custom repositories can override packages from it. -### config +### config (root-only) A set of configuration options. It is only used for projects. From 3cccc29b55fd441fc640ac313ad8b9e5d632bc6e Mon Sep 17 00:00:00 2001 From: Igor Wiedler Date: Fri, 13 Apr 2012 14:35:13 +0200 Subject: [PATCH 7/8] [improve-docs] Explain what the root package is, refs #500 --- doc/02-libraries.md | 6 +++--- doc/03-cli.md | 2 +- doc/04-schema.md | 20 +++++++++++++++++--- doc/05-repositories.md | 2 +- doc/06-community.md | 2 +- 5 files changed, 23 insertions(+), 9 deletions(-) diff --git a/doc/02-libraries.md b/doc/02-libraries.md index a6adab3a0..990246537 100644 --- a/doc/02-libraries.md +++ b/doc/02-libraries.md @@ -151,11 +151,11 @@ packagist is available automatically through composer. Since monolog [is on packagist](http://packagist.org/packages/monolog/monolog), we can depend on it without having to specify any additional repositories. -Assuming we want to share `hello-world` with the world, we would want to -publish it on packagist as well. And this is really easy. +If we wanted to share `hello-world` with the world, we would publish it on +packagist as well. Doing so is really easy. You simply hit the big "Submit Package" button and sign up. Then you submit the URL to your VCS repository, at which point packagist will start crawling it. Once it is done, your package will be available to anyone. -← [Basic usage](01-basic-usage.md) | [Command-line interface](03-cli.md) → \ No newline at end of file +← [Basic usage](01-basic-usage.md) | [Command-line interface](03-cli.md) → diff --git a/doc/03-cli.md b/doc/03-cli.md index d973783e1..855fca837 100644 --- a/doc/03-cli.md +++ b/doc/03-cli.md @@ -218,4 +218,4 @@ some tools like git or curl will only use the lower-cased `http_proxy` version. Alternatively you can also define the git proxy using `git config --global http.proxy `. -← [Libraries](02-libraries.md) | [Schema](04-schema.md) → \ No newline at end of file +← [Libraries](02-libraries.md) | [Schema](04-schema.md) → diff --git a/doc/04-schema.md b/doc/04-schema.md index 23fe42dde..853444d8f 100644 --- a/doc/04-schema.md +++ b/doc/04-schema.md @@ -1,13 +1,27 @@ # composer.json -This chapter will explain all of the options available in `composer.json`. +This chapter will explain all of the fields available in `composer.json`. ## JSON schema We have a [JSON schema](http://json-schema.org) that documents the format and can also be used to validate your `composer.json`. In fact, it is used by the `validate` command. You can find it at: -[`Resources/composer-schema.json`](https://github.com/composer/composer/blob/master/res/composer-schema.json). +[`res/composer-schema.json`](https://github.com/composer/composer/blob/master/res/composer-schema.json). + +## Root Package + +The root package is the package defined by the `composer.json` at the root of +your project. It is the main `composer.json` that defines your project +requirements. + +Certain fields only apply when in the root package context. One example of +this is the `config` field. Only the root package can define configuration. +The config of dependencies is ignored. This makes the `config` field +`root-only`. + +If you clone one of those dependencies to work on it, then that package is the +root package. The `composer.json` is identical, but the context is different. ## Properties @@ -346,7 +360,7 @@ Example: } } -### scripts +### scripts (root-only) Composer allows you to hook into various parts of the installation process through the use of scripts. diff --git a/doc/05-repositories.md b/doc/05-repositories.md index 79589fcb9..ba1272d21 100644 --- a/doc/05-repositories.md +++ b/doc/05-repositories.md @@ -274,4 +274,4 @@ You can disable the default Packagist repository by adding this to your } -← [Schema](04-schema.md) | [Community](06-community.md) → \ No newline at end of file +← [Schema](04-schema.md) | [Community](06-community.md) → diff --git a/doc/06-community.md b/doc/06-community.md index efd10d17a..a863e82cd 100644 --- a/doc/06-community.md +++ b/doc/06-community.md @@ -27,4 +27,4 @@ IRC channels are available for discussion as well, on irc.freenode.org [#composer](irc://irc.freenode.org/composer) for users and [#composer-dev](irc://irc.freenode.org/composer-dev) for development. -← [Repositories](05-repositories.md) \ No newline at end of file +← [Repositories](05-repositories.md) From be9ca486a6223aa63b5eeee119ef7ffa7689f46f Mon Sep 17 00:00:00 2001 From: Igor Wiedler Date: Fri, 13 Apr 2012 15:26:10 +0200 Subject: [PATCH 8/8] [improve-docs] List link types in link types reference title --- doc/04-schema.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/04-schema.md b/doc/04-schema.md index 853444d8f..5886608e6 100644 --- a/doc/04-schema.md +++ b/doc/04-schema.md @@ -165,7 +165,7 @@ An example: Optional, but highly recommended. -### Link types +### Link types (require, recommend, suggest, replace, provide) Each of these takes an object which maps package names to version constraints.