cleaned up intro page a bit
Rob Bast
parent
a8e004c7e7
commit
4ddd5aa37f
137
doc/00-intro.md
137
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) →
|
||||
|
|
|
|||
|
|
@ -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) →
|
||||
|
|
|
|||
Loading…
Reference in New Issue