1
0
Fork 0

cleaned up intro page a bit

pull/4172/head
Rob Bast 2015-06-22 14:31:33 +02:00
parent a8e004c7e7
commit 4ddd5aa37f
2 changed files with 61 additions and 92 deletions

View File

@ -1,54 +1,41 @@
# Introduction # Introduction
Composer is a tool for dependency management in PHP. It allows you to declare 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 the libraries your project depends on and it will manage (install/update) them
project for you. for you.
## Dependency management ## Dependency management
Composer is not a package manager. Yes, it deals with "packages" or libraries, but Composer is **not** a package manager in the same sense as Yum or Apt are. Yes,
it manages them on a per-project basis, installing them in a directory (e.g. `vendor`) it deals with "packages" or libraries, but it manages them on a per-project
inside your project. By default it will never install anything globally. Thus, basis, installing them in a directory (e.g. `vendor`) inside your project. By
it is a dependency manager. 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/) This idea is not new and Composer is strongly inspired by node's
and ruby's [bundler](http://bundler.io/). But there has not been such a tool [npm](https://npmjs.org/) and ruby's [bundler](http://bundler.io/).
for PHP.
The problem that Composer solves is this: Suppose:
a) You have a project that depends on a number of libraries. a) You have a project that depends on a number of libraries.
b) Some of those libraries depend on other 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). installs them (meaning it downloads them into your project).
## Declaring dependencies See the [Basic usage](01-basic-usage.md) chapter for more details on 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`.
## System Requirements ## System Requirements
Composer requires PHP 5.3.2+ to run. A few sensitive php settings and compile 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 flags are also required, but when using the installer you will be warned about
incompatibilities. any incompatibilities.
To install packages from sources instead of simple zip archives, you will need 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. 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 php -r "readfile('https://getcomposer.org/installer');" | php
``` ```
The installer will just check a few PHP settings and then download `composer.phar` The installer will just check a few PHP settings and then download
to your working directory. This file is the Composer binary. It is a PHAR (PHP `composer.phar` to your working directory. This file is the Composer binary. It
archive), which is an archive format for PHP which can be run on the command is a PHAR (PHP archive), which is an archive format for PHP which can be run on
line, amongst other things. the command line, amongst other things.
You can install Composer to a specific directory by using the `--install-dir` 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 ```sh
curl -sS https://getcomposer.org/installer | php -- --install-dir=bin curl -sS https://getcomposer.org/installer | php -- --install-dir=bin
``` ```
Now just run `php composer.phar` in order to run Composer.
#### Globally #### Globally
You can place this file anywhere you wish. If you put it in your `PATH`, You can place the Composer PHAR anywhere you wish. If you put it in a directory
you can access it globally. On unixy systems you can even make it that is part of your `PATH`, you can access it globally. On unixy systems you
executable and invoke it without `php`. 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 ```sh
curl -sS https://getcomposer.org/installer | php curl -sS https://getcomposer.org/installer | php
mv composer.phar /usr/local/bin/composer 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. > 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 ## 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. 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), Download and run
it will install the latest Composer version and set up your PATH so that you can [Composer-Setup.exe](https://getcomposer.org/Composer-Setup.exe). It will
just call `composer` from any directory in your command line. 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: > **Note:** Close your current terminal. Test usage with a new terminal: This is
> That is important since the PATH only gets loaded when the terminal starts. > important since the PATH only gets loaded when the terminal starts.
### Manual Installation ### Manual Installation
Change to a directory on your `PATH` and run the install snippet to download Change to a directory on your `PATH` and run the install snippet to download
composer.phar: `composer.phar`:
```sh ```sh
C:\Users\username>cd C:\bin C:\Users\username>cd C:\bin
C:\bin>php -r "readfile('https://getcomposer.org/installer');" | php 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`: Create a new `composer.bat` file alongside `composer.phar`:
@ -153,38 +153,7 @@ Composer version 27d8904
## Using Composer ## Using Composer
We will now use Composer to install the dependencies of the project. If you Now that you've installed Composer, you are ready to use it! Head on over to the
don't have a `composer.json` file in the current directory please skip to the next chapter for a short and simple demonstration.
[Basic Usage](01-basic-usage.md) chapter.
To resolve and download dependencies, run the `install` command: [Basic usage](01-basic-usage.md) →
```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) →

View File

@ -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 example using `{"example.org": {"username": "alice", "password": "foo"}` as the
value of this option will let Composer authenticate against example.org. 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 ## platform
Lets you fake platform packages (PHP and extensions) so that you can emulate a 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 ## 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 existing autoloaders. This is sometimes required to fix interoperability issues
with other autoloaders. with other autoloaders.
@ -110,7 +115,7 @@ autoloader. When null a random one will be generated.
## optimize-autoloader ## optimize-autoloader
Defaults to `false`. Always optimize when dumping the autoloader. Defaults to `false`. If `true`, always optimize when dumping the autoloader.
## classmap-authoritative ## classmap-authoritative
@ -125,7 +130,7 @@ used for GitHub Enterprise setups.
## github-expose-hostname ## 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. github API will have a date instead of the machine hostname.
## notify-on-install ## 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) → ← [Repositories](05-repositories.md) | [Community](07-community.md) →