diff --git a/doc/00-intro.md b/doc/00-intro.md index 0496390ca..c0fe1c4dc 100644 --- a/doc/00-intro.md +++ b/doc/00-intro.md @@ -1,54 +1,41 @@ # Introduction Composer is a tool for dependency management in PHP. It allows you to declare -the dependent libraries your project needs and it will install them in your -project for you. +the libraries your project depends on and it will manage (install/update) them +for you. ## Dependency management -Composer is not a package manager. Yes, it deals with "packages" or libraries, but -it manages them on a per-project basis, installing them in a directory (e.g. `vendor`) -inside your project. By default it will never install anything globally. Thus, -it is a dependency manager. +Composer is **not** a package manager in the same sense as Yum or Apt are. Yes, +it deals with "packages" or libraries, but it manages them on a per-project +basis, installing them in a directory (e.g. `vendor`) inside your project. By +default it will never install anything globally. Thus, it is a dependency +manager. -This idea is not new and Composer is strongly inspired by node's [npm](https://npmjs.org/) -and ruby's [bundler](http://bundler.io/). But there has not been such a tool -for PHP. +This idea is not new and Composer is strongly inspired by node's +[npm](https://npmjs.org/) and ruby's [bundler](http://bundler.io/). -The problem that Composer solves is this: +Suppose: a) You have a project that depends on a number of libraries. b) Some of those libraries depend on other libraries. -c) You declare the things you depend on. +Composer: -d) Composer finds out which versions of which packages need to be installed, and +c) Enables you to declare the libraries you depend on. + +d) Finds out which versions of which packages can and need to be installed, and installs them (meaning it downloads them into your project). -## Declaring dependencies - -Let's say you are creating a project, and you need a library that does logging. -You decide to use [monolog](https://github.com/Seldaek/monolog). In order to -add it to your project, all you need to do is create a `composer.json` file -which describes the project's dependencies. - -```json -{ - "require": { - "monolog/monolog": "1.2.*" - } -} -``` - -We are simply stating that our project requires some `monolog/monolog` package, -any version beginning with `1.2`. +See the [Basic usage](01-basic-usage.md) chapter for more details on declaring +dependencies. ## System Requirements Composer requires PHP 5.3.2+ to run. A few sensitive php settings and compile -flags are also required, but when using the installer you will be warned about any -incompatibilities. +flags are also required, but when using the installer you will be warned about +any incompatibilities. To install packages from sources instead of simple zip archives, you will need git, svn or hg depending on how the package is version-controlled. @@ -79,37 +66,48 @@ curl -sS https://getcomposer.org/installer | php php -r "readfile('https://getcomposer.org/installer');" | php ``` -The installer will just check a few PHP settings and then download `composer.phar` -to your working directory. This file is the Composer binary. It is a PHAR (PHP -archive), which is an archive format for PHP which can be run on the command -line, amongst other things. +The installer will just check a few PHP settings and then download +`composer.phar` to your working directory. This file is the Composer binary. It +is a PHAR (PHP archive), which is an archive format for PHP which can be run on +the command line, amongst other things. You can install Composer to a specific directory by using the `--install-dir` -option and providing a target directory (it can be an absolute or relative path): +option and providing a target directory (it can be an absolute or relative +path): ```sh curl -sS https://getcomposer.org/installer | php -- --install-dir=bin ``` +Now just run `php composer.phar` in order to run Composer. + #### Globally -You can place this file anywhere you wish. If you put it in your `PATH`, -you can access it globally. On unixy systems you can even make it -executable and invoke it without `php`. +You can place the Composer PHAR anywhere you wish. If you put it in a directory +that is part of your `PATH`, you can access it globally. On unixy systems you +can even make it executable and invoke it without directly using the `php` +interpreter. -You can run these commands to easily access `composer` from anywhere on your system: +Run these commands to globally install `composer` on your system: ```sh curl -sS https://getcomposer.org/installer | php mv composer.phar /usr/local/bin/composer +chmod 755 /usr/local/bin/composer ``` -> **Note:** If the above fails due to permissions, run the `mv` line +> **Note:** If the above fails due to permissions, run the `mv` and `chmod` line > again with sudo. -> **Note:** In OSX Yosemite the `/usr` directory does not exist by default. If you receive the error "/usr/local/bin/composer: No such file or directory" then you must create `/usr/local/bin/` manually before proceeding. +> **Note:** On some versions of OSX the `/usr` directory does not exist by +> default. If you receive the error "/usr/local/bin/composer: No such file or +> directory" then you must create the directory manually before proceeding: +> `mkdir -p /usr/local/bin`. -Then, just run `composer` in order to run Composer instead of `php composer.phar`. +> **Note:** For information on changing your PATH, please read the +> [Wikipedia article](https://en.wikipedia.org/wiki/PATH_(variable)) and/or use Google. + +Now just run `composer` in order to run Composer instead of `php composer.phar`. ## Installation - Windows @@ -117,24 +115,26 @@ Then, just run `composer` in order to run Composer instead of `php composer.phar This is the easiest way to get Composer set up on your machine. -Download and run [Composer-Setup.exe](https://getcomposer.org/Composer-Setup.exe), -it will install the latest Composer version and set up your PATH so that you can -just call `composer` from any directory in your command line. +Download and run +[Composer-Setup.exe](https://getcomposer.org/Composer-Setup.exe). It will +install the latest Composer version and set up your PATH so that you can just +call `composer` from any directory in your command line. -> **Note:** Close your current terminal. Test usage with a new terminal: -> That is important since the PATH only gets loaded when the terminal starts. +> **Note:** Close your current terminal. Test usage with a new terminal: This is +> important since the PATH only gets loaded when the terminal starts. ### Manual Installation Change to a directory on your `PATH` and run the install snippet to download -composer.phar: +`composer.phar`: ```sh C:\Users\username>cd C:\bin C:\bin>php -r "readfile('https://getcomposer.org/installer');" | php ``` -> **Note:** If the above fails due to readfile, use the `http` url or enable php_openssl.dll in php.ini +> **Note:** If the above fails due to readfile, use the `http` url or enable +> php_openssl.dll in php.ini Create a new `composer.bat` file alongside `composer.phar`: @@ -153,38 +153,7 @@ Composer version 27d8904 ## Using Composer -We will now use Composer to install the dependencies of the project. If you -don't have a `composer.json` file in the current directory please skip to the -[Basic Usage](01-basic-usage.md) chapter. +Now that you've installed Composer, you are ready to use it! Head on over to the +next chapter for a short and simple demonstration. -To resolve and download dependencies, run the `install` command: - -```sh -php composer.phar install -``` - -If you did a global install and do not have the phar in that directory -run this instead: - -```sh -composer install -``` - -Following the [example above](#declaring-dependencies), this will download -monolog into the `vendor/monolog/monolog` directory. - -## Autoloading - -Besides downloading the library, Composer also prepares an autoload file that's -capable of autoloading all of the classes in any of the libraries that it -downloads. To use it, just add the following line to your code's bootstrap -process: - -```php -require __DIR__ . '/vendor/autoload.php'; -``` - -Woah! Now start using monolog! To keep learning more about Composer, keep -reading the "Basic Usage" chapter. - -[Basic Usage](01-basic-usage.md) → +[Basic usage](01-basic-usage.md) → diff --git a/doc/06-config.md b/doc/06-config.md index 1dbcf7be2..2564fefef 100644 --- a/doc/06-config.md +++ b/doc/06-config.md @@ -46,6 +46,11 @@ A list of domain names and username/passwords to authenticate against them. For example using `{"example.org": {"username": "alice", "password": "foo"}` as the value of this option will let Composer authenticate against example.org. +> **Note:** Authentication-related config options like `http-basic` and +> `github-oauth` can also be specified inside a `auth.json` file that goes +> besides your `composer.json`. That way you can gitignore it and every +> developer can place their own credentials in there. + ## platform Lets you fake platform packages (PHP and extensions) so that you can emulate a @@ -99,7 +104,7 @@ first until the cache fits. ## prepend-autoloader -Defaults to `true`. If false, the Composer autoloader will not be prepended to +Defaults to `true`. If `false`, the Composer autoloader will not be prepended to existing autoloaders. This is sometimes required to fix interoperability issues with other autoloaders. @@ -110,7 +115,7 @@ autoloader. When null a random one will be generated. ## optimize-autoloader -Defaults to `false`. Always optimize when dumping the autoloader. +Defaults to `false`. If `true`, always optimize when dumping the autoloader. ## classmap-authoritative @@ -125,7 +130,7 @@ used for GitHub Enterprise setups. ## github-expose-hostname -Defaults to `true`. If set to `false`, the OAuth tokens created to access the +Defaults to `true`. If `false`, the OAuth tokens created to access the github API will have a date instead of the machine hostname. ## notify-on-install @@ -163,9 +168,4 @@ Example: } ``` -> **Note:** Authentication-related config options like `http-basic` and -> `github-oauth` can also be specified inside a `auth.json` file that goes -> besides your `composer.json`. That way you can gitignore it and every -> developer can place their own credentials in there. - ← [Repositories](05-repositories.md) | [Community](07-community.md) →