From 903eff10eb3fd8a9724807bdc118dd618e009c87 Mon Sep 17 00:00:00 2001 From: Ryan Weaver Date: Tue, 13 Mar 2012 22:07:22 -0500 Subject: [PATCH 1/3] Proofreading the first and second chapters of the very well-written docs Changes are mostly wording, rephrasing. I did remove some duplicate content between the intro and the basic usage --- doc/00-intro.md | 62 ++++++++++++++++++++++++------------- doc/01-basic-usage.md | 72 +++++++++++++++++++------------------------ 2 files changed, 73 insertions(+), 61 deletions(-) diff --git a/doc/00-intro.md b/doc/00-intro.md index 1169a06a0..d218c59a7 100644 --- a/doc/00-intro.md +++ b/doc/00-intro.md @@ -1,23 +1,30 @@ # Introduction Composer is a tool for dependency management in PHP. It allows you to declare -the dependencies of your project and will install them for you. +the dependent libraries your project needs and it will install them in your +project for you. ## Dependency management -One important distinction to make is that composer is not a package manager. It -deals with packages, but it manages them on a per-project basis. By default it -will never install anything globally. Thus, it is a dependency manager. +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. -This idea is not new by any means. Composer is strongly inspired by -node's [npm](http://npmjs.org/) and ruby's [bundler](http://gembundler.com/). -But there has not been such a tool for PHP so far. +This idea is not new and Composer is strongly inspired by node's [npm](http://npmjs.org/) +and ruby's [bundler](http://gembundler.com/). But there has not been such a tool +for PHP. -The problem that composer solves is the following. You have a project that -depends on a number of libraries. Some of those libraries have dependencies of -their own. You declare the things you depend on. Composer will then go ahead -and find out which versions of which packages need to be installed, and -install them. +The problem that composer solves is this: + +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 + +d) Composer finds out which versions of which packages need to be installed, and + install them (meaning it downloads them into your project). ## Declaring dependencies @@ -32,37 +39,50 @@ which describes the project's dependencies. } } -We are simply stating that our project requires the `monolog/monolog` package, +We are simply stating that our project requires some `monolog/monolog` package, any version beginning with `1.0`. ## Installation -To actually get it, we need to do two things. The first one is installing -composer: +### 1) Downloading the Composer Executable + +To actually get Composer, we need to do two things. The first one is installing +composer (again, this mean downloading it into your project): $ curl -s http://getcomposer.org/installer | php This will just check a few PHP settings and then download `composer.phar` to -your working directory. This file is the composer binary. +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): $ curl -s http://getcomposer.org/installer | php -- --install-dir=bin -After that we run the command for installing all dependencies: +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`. + +### 2) Using Composer + +Next, run the command the `install` command to calculate and download dependencies: $ php composer.phar install -This will download monolog and dump it into `vendor/monolog/monolog`. +This will download monolog into the `vendor/monolog/monolog` directory. ## Autoloading -After this you can just add the following line to your bootstrap code to get -autoloading: +Besides download 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: require 'vendor/.composer/autoload.php'; -That's all it takes to have a basic setup. +Woh! Now starting using monolog! To keep learning more about Composer, keep +reading the "Basic Usage" chapter. [Basic Usage](01-basic-usage.md) → diff --git a/doc/01-basic-usage.md b/doc/01-basic-usage.md index 8056ae713..7f090bfce 100644 --- a/doc/01-basic-usage.md +++ b/doc/01-basic-usage.md @@ -2,26 +2,11 @@ ## Installation -To install composer, simply run this command on the command line: +To install composer, you just need to download the `composer.phar` executable. $ curl -s http://getcomposer.org/installer | php -This will perform some checks on your environment to make sure you can -actually run it. - -Then it will download `composer.phar` and place it in your working directory. -`composer.phar` 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 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 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): - - $ curl -s http://getcomposer.org/installer | php -- --install-dir=bin +For the details, see the [Introduction](00-intro.md) chapter. To check if composer is working, just run the PHAR through `php`: @@ -34,7 +19,7 @@ This should give you a list of available commands. > > $ curl -s http://getcomposer.org/installer | php -- --help -## Project setup +## `composer.json`: Project Setup To start using composer in your project, all you need is a `composer.json` file. This file describes the dependencies of your project and may contain @@ -43,6 +28,8 @@ other metadata as well. The [JSON format](http://json.org/) is quite easy to write. It allows you to define nested structures. +### The `require` Key + The first (and often only) thing you specify in `composer.json` is the `require` key. You're simply telling composer which packages your project depends on. @@ -53,12 +40,13 @@ depends on. } } -As you can see, `require` takes an object that maps package names to versions. +As you can see, `require` takes an object that maps **package names(()) (e.g. `monolog/monolog`) +to ** package versions** (e.g. `1.0.*`). -## Package names +### Package Names The package name consists of a vendor name and the project's name. Often these -will be identical. The vendor name exists to prevent naming clashes. It allows +will be identical - the vendor name just exists to prevent naming clashes. It allows two different people to create a library named `json`, which would then just be named `igorw/json` and `seldaek/json`. @@ -68,10 +56,10 @@ allows adding more related projects under the same namespace later on. If you are maintaining a library, this would make it really easy to split it up into smaller decoupled parts. -## Package versions +### Package Versions -We are also requiring the version `1.0.*` of monolog. This means any version -in the `1.0` development branch. It would match `1.0.0`, `1.0.2` and `1.0.20`. +We are requiring version `1.0.*` of monolog. This means any version in the `1.0` +development branch. It would match `1.0.0`, `1.0.2` or `1.0.20`. Version constraints can be specified in a few different ways. @@ -80,14 +68,14 @@ Version constraints can be specified in a few different ways. * **Range:** By using comparison operators you can specify ranges of valid versions. Valid operators are `>`, `>=`, `<`, `<=`. An example range would be - `>=1.0`. You can define multiple of these, separated by comma: `>=1.0,<2.0`. + `>=1.0`. You can define multiple ranges, separated by a comma: `>=1.0,<2.0`. * **Wildcard:** You can specify a pattern with a `*` wildcard. `1.0.*` is the equivalent of `>=1.0,<1.1-dev`. -## Installing dependencies +## Installing Dependencies -To fetch the defined dependencies into the local project, you simply run the +To fetch the defined dependencies into your local project, just run the `install` command of `composer.phar`. $ php composer.phar install @@ -104,29 +92,33 @@ In case of monolog it will put it into `vendor/monolog/monolog`. Another thing that the `install` command does is it adds a `composer.lock` file into your project root. -## Lock file +## `composer.json` - The Lock File After installing the dependencies, composer writes the list of the exact versions it installed into a `composer.lock` file. This locks the project to those specific versions. -**Commit your project's `composer.lock` into version control.** +**Commit your project's `composer.lock` (along with `composer.json`) into version control.** + +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. -The reason is that anyone who sets up the project should get the same version. -The `install` command will check if a lock file is present. If it is, it will -use the versions specified there. If not, it will resolve the dependencies and -create a lock file. +If no `composer.json` lock file exists, it will read the dependencies and +versions from `composer.json` and create the lock file. -If any of the dependencies gets a new version, you can update to that version -by using the `update` command. This will fetch the latest matching versions and -also update the lock file. +This means that if any of the dependencies gets a new version, you won't be updated +automatically. To update to the new version, use `update` command. This will fetch +the latest matching versions (according to your `composer.json` file) and also update +the lock file with the new version. $ php composer.phar update ## Packagist [Packagist](http://packagist.org/) is the main composer repository. A composer -repository is basically a package source. A place where you can get packages +repository is basically a package source: a place where you can get packages from. Packagist aims to be the central repository that everybody uses. This means that you can automatically `require` any package that is available there. @@ -135,7 +127,8 @@ If you go to the [packagist website](http://packagist.org/) (packagist.org), you can browse and search for packages. Any open source project using composer should publish their packages on -packagist. +packagist. A library doesn't need to be on packagist to be used by composer, +but it makes life quite a bit simpler. ## Autoloading @@ -146,8 +139,7 @@ this file and you will get autoloading for free. require 'vendor/.composer/autoload.php'; -This makes it really easy to use third party code, because you only -have to add one line to `composer.json` and run `install`. For monolog, it +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. From 37b4edc25d958f9f1c8c3f8fa14e4622bc41bdc1 Mon Sep 17 00:00:00 2001 From: Ryan Weaver Date: Wed, 14 Mar 2012 00:25:17 -0500 Subject: [PATCH 2/3] Fixing typo per @stof --- doc/01-basic-usage.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/01-basic-usage.md b/doc/01-basic-usage.md index 7f090bfce..450da9cad 100644 --- a/doc/01-basic-usage.md +++ b/doc/01-basic-usage.md @@ -92,7 +92,7 @@ In case of monolog it will put it into `vendor/monolog/monolog`. Another thing that the `install` command does is it adds a `composer.lock` file into your project root. -## `composer.json` - The Lock File +## `composer.lock` - The Lock File After installing the dependencies, composer writes the list of the exact versions it installed into a `composer.lock` file. This locks the project From caf29268be519afead34600fe6c1d7549c6e1e36 Mon Sep 17 00:00:00 2001 From: Ryan Weaver Date: Thu, 15 Mar 2012 07:53:34 -0500 Subject: [PATCH 3/3] Tweaks per @igorw and @Seldaek. Biggest change is the capitalization of Composer (in these first 2 chapters so far) when we're talking about the actual library --- doc/00-intro.md | 16 ++++++++-------- doc/01-basic-usage.md | 30 +++++++++++++++--------------- 2 files changed, 23 insertions(+), 23 deletions(-) diff --git a/doc/00-intro.md b/doc/00-intro.md index d218c59a7..289483336 100644 --- a/doc/00-intro.md +++ b/doc/00-intro.md @@ -15,7 +15,7 @@ This idea is not new and Composer is strongly inspired by node's [npm](http://np and ruby's [bundler](http://gembundler.com/). But there has not been such a tool for PHP. -The problem that composer solves is this: +The problem that Composer solves is this: a) You have a project that depends on a number of libraries. @@ -24,7 +24,7 @@ b) Some of those libraries depend on other libraries . c) You declare the things you depend on d) Composer finds out which versions of which packages need to be installed, and - install them (meaning it downloads them into your project). + installs them (meaning it downloads them into your project). ## Declaring dependencies @@ -47,16 +47,16 @@ any version beginning with `1.0`. ### 1) Downloading the Composer Executable To actually get Composer, we need to do two things. The first one is installing -composer (again, this mean downloading it into your project): +Composer (again, this mean downloading it into your project): $ curl -s http://getcomposer.org/installer | php This 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 +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` +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): $ curl -s http://getcomposer.org/installer | php -- --install-dir=bin @@ -67,7 +67,7 @@ executable and invoke it without `php`. ### 2) Using Composer -Next, run the command the `install` command to calculate and download dependencies: +Next, run the command the `install` command to resolve and download dependencies: $ php composer.phar install @@ -75,14 +75,14 @@ This will download monolog into the `vendor/monolog/monolog` directory. ## Autoloading -Besides download the library, Composer also prepares an autoload file that's +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: require 'vendor/.composer/autoload.php'; -Woh! Now starting using monolog! To keep learning more about Composer, keep +Woh! Now start using monolog! To keep learning more about Composer, keep reading the "Basic Usage" chapter. [Basic Usage](01-basic-usage.md) → diff --git a/doc/01-basic-usage.md b/doc/01-basic-usage.md index 450da9cad..e8037b7cd 100644 --- a/doc/01-basic-usage.md +++ b/doc/01-basic-usage.md @@ -2,26 +2,26 @@ ## Installation -To install composer, you just need to download the `composer.phar` executable. +To install Composer, you just need to download the `composer.phar` executable. $ curl -s http://getcomposer.org/installer | php For the details, see the [Introduction](00-intro.md) chapter. -To check if composer is working, just run the PHAR through `php`: +To check if Composer is working, just run the PHAR through `php`: $ php composer.phar This should give you a list of available commands. -> **Note:** You can also perform the checks only without downloading composer +> **Note:** You can also perform the checks only without downloading Composer > by using the `--check` option. For more information, just use `--help`. > > $ curl -s http://getcomposer.org/installer | php -- --help ## `composer.json`: Project Setup -To start using composer in your project, all you need is a `composer.json` +To start using Composer in your project, all you need is a `composer.json` file. This file describes the dependencies of your project and may contain other metadata as well. @@ -31,7 +31,7 @@ define nested structures. ### The `require` Key The first (and often only) thing you specify in `composer.json` is the -`require` key. You're simply telling composer which packages your project +`require` key. You're simply telling Composer which packages your project depends on. { @@ -40,8 +40,8 @@ depends on. } } -As you can see, `require` takes an object that maps **package names(()) (e.g. `monolog/monolog`) -to ** package versions** (e.g. `1.0.*`). +As you can see, `require` takes an object that maps **package names** (e.g. `monolog/monolog`) +to **package versions** (e.g. `1.0.*`). ### Package Names @@ -94,7 +94,7 @@ file into your project root. ## `composer.lock` - The Lock File -After installing the dependencies, composer writes the list of the exact +After installing the dependencies, Composer writes the list of the exact versions it installed into a `composer.lock` file. This locks the project to those specific versions. @@ -108,7 +108,7 @@ 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. -This means that if any of the dependencies gets a new version, you won't be updated +This means that if any of the dependencies get a new version, you won't get the updates. automatically. To update to the new version, use `update` command. This will fetch the latest matching versions (according to your `composer.json` file) and also update the lock file with the new version. @@ -117,7 +117,7 @@ the lock file with the new version. ## Packagist -[Packagist](http://packagist.org/) is the main composer repository. A composer +[Packagist](http://packagist.org/) is the main Composer repository. A Composer repository is basically a package source: a place where you can get packages from. Packagist aims to be the central repository that everybody uses. This means that you can automatically `require` any package that is available @@ -126,16 +126,16 @@ there. If you go to the [packagist website](http://packagist.org/) (packagist.org), you can browse and search for packages. -Any open source project using composer should publish their packages on -packagist. A library doesn't need to be on packagist to be used by composer, +Any open source project using Composer should publish their packages on +packagist. A library doesn't need to be on packagist to be used by Composer, 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. +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. require 'vendor/.composer/autoload.php';