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/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 45344adea..855fca837 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`. @@ -190,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 f7cd9bfe5..5886608e6 100644 --- a/doc/04-schema.md +++ b/doc/04-schema.md @@ -1,17 +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). -## Package root +## Root Package -The root of the package definition is a JSON object. +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 @@ -155,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. @@ -188,7 +198,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 +222,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: @@ -235,6 +245,8 @@ Example: "include-path": ["lib/"] } +Optional. + ### target-dir Defines the installation target. @@ -260,7 +272,7 @@ To do that, `autoload` and `target-dir` are defined as follows: Optional. -### repositories +### repositories (root-only) Custom package repositories to use. @@ -326,7 +338,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. @@ -348,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) 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. 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/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. 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/`.