diff --git a/UPGRADE-2.0.md b/UPGRADE-2.0.md index 2b9ccf24a..ff6e6c597 100644 --- a/UPGRADE-2.0.md +++ b/UPGRADE-2.0.md @@ -3,7 +3,7 @@ ## For composer CLI users - The new platform-check feature means that Composer checks the runtime PHP version and available extensions to ensure they match the project dependencies. If a mismatch is found, it exits with error details to make sure problems are not overlooked. To avoid issues when deploying to production it is recommended to run `composer check-platform-reqs` with the production PHP process as part of your build or deployment process. -- If a packages exists in a higher priority repository, it will now be entirely ignored in lower priority repositories. See [repository priorities](https://getcomposer.org/repoprio) for details. +- If a package exists in a higher priority repository, it will now be entirely ignored in lower priority repositories. See [repository priorities](https://getcomposer.org/repoprio) for details. - Invalid PSR-0 / PSR-4 class configurations will not autoload anymore in optimized-autoloader mode, as per the warnings introduced in 1.10 - Package names now must comply to our [naming guidelines](doc/04-schema.md#name) or Composer will abort, as per the warnings introduced in 1.8.1 - Deprecated --no-suggest flag as it is not needed anymore @@ -27,7 +27,7 @@ - packages are now wrapped into a `"packages"` top level key instead of the whole file being the package array - packages now contain an `"installed-path"` key which lists where they were installed - there is a top level `"dev"` key which stores whether dev requirements were installed or not -- `PreFileDownloadEvent` now receives an `HttpDownloader` instance instead of `RemoteFilesystem`, and that instance can not be overridden by listeners anymore +- `PreFileDownloadEvent` now receives an `HttpDownloader` instance instead of `RemoteFilesystem`, and that instance cannot be overridden by listeners anymore - `VersionSelector::findBestCandidate`'s third argument (phpVersion) was removed in favor of passing in a complete PlatformRepository instance into the constructor - `InitCommand::determineRequirements`'s fourth argument (phpVersion) should now receive a complete PlatformRepository instance or null if platform requirements are to be ignored - `IOInterface` now extends PSR-3's `LoggerInterface`, and has new `writeRaw` + `writeErrorRaw` methods diff --git a/doc/00-intro.md b/doc/00-intro.md index ea88808a0..c686835b7 100644 --- a/doc/00-intro.md +++ b/doc/00-intro.md @@ -9,7 +9,7 @@ for you. 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 does not install anything globally. Thus, it is a dependency +default, it does not install anything globally. Thus, it is a dependency manager. It does however support a "global" project for convenience via the [global](03-cli.md#global) command. diff --git a/doc/01-basic-usage.md b/doc/01-basic-usage.md index db34783d0..5dd1726bd 100644 --- a/doc/01-basic-usage.md +++ b/doc/01-basic-usage.md @@ -77,7 +77,7 @@ versions, how versions relate to each other, and on version constraints. > **Note:** If you are trying to require a package but Composer throws an error > regarding package stability, the version you have specified may not meet your -> default minimum stability requirements. By default only stable releases are taken +> default minimum stability requirements. By default, only stable releases are taken > into consideration when searching for valid package versions in your VCS. > > You might run into this if you are trying to require dev, alpha, beta, or RC diff --git a/doc/02-libraries.md b/doc/02-libraries.md index c02756e50..4a6c58878 100644 --- a/doc/02-libraries.md +++ b/doc/02-libraries.md @@ -26,14 +26,14 @@ In this case the project name is `acme/hello-world`, where `acme` is the vendor name. Supplying a vendor name is mandatory. > **Note:** If you don't know what to use as a vendor name, your GitHub -> username is usually a good bet. While package names are case insensitive, the +> username is usually a good bet. While package names are case-insensitive, the > convention is all lowercase and dashes for word separation. ## Library Versioning In the vast majority of cases, you will be maintaining your library using some sort of version control system like git, svn, hg or fossil. In these cases, -Composer infers versions from your VCS and you **should not** specify a version +Composer infers versions from your VCS, and you **should not** specify a version in your `composer.json` file. (See the [Versions article](articles/versions.md) to learn about how Composer uses VCS branches and tags to resolve version constraints.) @@ -69,7 +69,7 @@ can help your team to always test against the same dependency versions. However, this lock file will not have any effect on other projects that depend on it. It only has an effect on the main project. -If you do not want to commit the lock file and you are using git, add it to +If you do not want to commit the lock file, and you are using git, add it to the `.gitignore`. ## Publishing to a VCS diff --git a/doc/03-cli.md b/doc/03-cli.md index edfaaa9ed..a5e0d5de4 100644 --- a/doc/03-cli.md +++ b/doc/03-cli.md @@ -185,7 +185,7 @@ php composer.phar update vendor/package:2.0.1 vendor/package2:3.0.* * **--with-all-dependencies:** Update also dependencies of packages in the argument list, including those which are root requirements. * **--optimize-autoloader (-o):** Convert PSR-0/4 autoloading to classmap to get a faster autoloader. This is recommended especially for production, but can take - a bit of time to run so it is currently not done by default. + a bit of time to run, so it is currently not done by default. * **--classmap-authoritative (-a):** Autoload classes from the classmap only. Implicitly enables `--optimize-autoloader`. * **--apcu-autoloader:** Use APCu to cache found/not-found classes. @@ -252,7 +252,7 @@ If you do not specify a package, composer will prompt you to search for a packag * **--sort-packages:** Keep packages sorted in `composer.json`. * **--optimize-autoloader (-o):** Convert PSR-0/4 autoloading to classmap to get a faster autoloader. This is recommended especially for production, but - can take a bit of time to run so it is currently not done by default. + can take a bit of time to run, so it is currently not done by default. * **--classmap-authoritative (-a):** Autoload classes from the classmap only. Implicitly enables `--optimize-autoloader`. * **--apcu-autoloader:** Use APCu to cache found/not-found classes. @@ -763,7 +763,7 @@ performance. * **--no-scripts:** Skips the execution of all scripts defined in `composer.json` file. * **--optimize (-o):** Convert PSR-0/4 autoloading to classmap to get a faster autoloader. This is recommended especially for production, but can take - a bit of time to run so it is currently not done by default. + a bit of time to run, so it is currently not done by default. * **--classmap-authoritative (-a):** Autoload classes from the classmap only. Implicitly enables `--optimize`. * **--apcu:** Use APCu to cache found/not-found classes. @@ -781,7 +781,7 @@ Deletes all content from Composer's cache directories. ## licenses Lists the name, version and license of every package installed. Use -`--format=json` to get machine readable output. +`--format=json` to get machine-readable output. ### Options @@ -897,7 +897,7 @@ directory to something other than `vendor/bin`. The `COMPOSER_CACHE_DIR` var allows you to change the Composer cache directory, which is also configurable via the [`cache-dir`](06-config.md#cache-dir) option. -By default it points to `$COMPOSER_HOME/cache` on \*nix and macOS, and +By default, it points to `$COMPOSER_HOME/cache` on \*nix and macOS, and `C:\Users\\AppData\Local\Composer` (or `%LOCALAPPDATA%/Composer`) on Windows. ### COMPOSER_CAFILE @@ -919,7 +919,7 @@ The `COMPOSER_HOME` var allows you to change the Composer home directory. This is a hidden, global (per-user on the machine) directory that is shared between all projects. -By default it points to `C:\Users\\AppData\Roaming\Composer` on Windows +By default, it points to `C:\Users\\AppData\Roaming\Composer` on Windows and `/Users//.composer` on macOS. On \*nix systems that follow the [XDG Base Directory Specifications](https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html), it points to `$XDG_CONFIG_HOME/composer`. On other \*nix systems, it points to @@ -964,8 +964,8 @@ commands) to finish executing. The default value is 300 seconds (5 minutes). ### COMPOSER_ROOT_VERSION -By setting this var you can specify the version of the root package, if it can -not be guessed from VCS info and is not present in `composer.json`. +By setting this var you can specify the version of the root package, if it +cannot be guessed from VCS info and is not present in `composer.json`. ### COMPOSER_VENDOR_DIR @@ -990,13 +990,13 @@ details. ### HTTP_PROXY_REQUEST_FULLURI -If you use a proxy but it does not support the request_fulluri flag, then you +If you use a proxy, but it does not support the request_fulluri flag, then you should set this env var to `false` or `0` to prevent Composer from setting the request_fulluri option. ### HTTPS_PROXY_REQUEST_FULLURI -If you use a proxy but it does not support the request_fulluri flag for HTTPS +If you use a proxy, but it does not support the request_fulluri flag for HTTPS requests, then you should set this env var to `false` or `0` to prevent Composer from setting the request_fulluri option. @@ -1019,7 +1019,7 @@ can also set it to `*` to ignore the proxy for all HTTP requests. If set to `1`, disables network access (best effort). This can be used for debugging or to run Composer on a plane or a starship with poor connectivity. -If set to `prime`, GitHub VCS repositories will prime the cache so it can then be used +If set to `prime`, GitHub VCS repositories will prime the cache, so it can then be used fully offline with `1`. ← [Libraries](02-libraries.md) | [Schema](04-schema.md) → diff --git a/doc/04-schema.md b/doc/04-schema.md index 8bdad86ee..28d0b4ecd 100644 --- a/doc/04-schema.md +++ b/doc/04-schema.md @@ -123,7 +123,7 @@ Optional. ### homepage -An URL to the website of the project. +A URL to the website of the project. Optional. @@ -184,7 +184,7 @@ An Example for disjunctive licenses: } ``` -Alternatively they can be separated with "or" and enclosed in parenthesis; +Alternatively they can be separated with "or" and enclosed in parentheses; ```json { @@ -192,8 +192,8 @@ Alternatively they can be separated with "or" and enclosed in parenthesis; } ``` -Similarly when multiple licenses need to be applied ("conjunctive license"), -they should be separated with "and" and enclosed in parenthesis. +Similarly, when multiple licenses need to be applied ("conjunctive license"), +they should be separated with "and" and enclosed in parentheses. ### authors @@ -265,8 +265,8 @@ development of new functionality. Each entry consists of the following -* **type:** The type of funding or the platform through which funding can be provided, e.g. patreon, opencollective, tidelift or github. -* **url:** URL to a website with details and a way to fund the package. +* **type:** The type of funding, or the platform through which funding can be provided, e.g. patreon, opencollective, tidelift or github. +* **url:** URL to a website with details, and a way to fund the package. An example: @@ -934,7 +934,7 @@ It can be boolean or a package name/URL pointing to a recommended alternative. Examples: Use `"abandoned": true` to indicates this package is abandoned. -Use `"abandoned": "monolog/monolog"` to indicates this package is abandoned and the +Use `"abandoned": "monolog/monolog"` to indicates this package is abandoned, and the recommended alternative is `monolog/monolog`. Defaults to false. @@ -949,7 +949,7 @@ that will NOT be handled as feature branches. This is an array of strings. If you have non-numeric branch names, for example like "latest", "current", "latest-stable" or something, that do not look like a version number, then Composer handles such branches as feature branches. This means it searches for parent branches, that look like a version -or ends at special branches (like master) and the root package version number becomes the +or ends at special branches (like master), and the root package version number becomes the version of the parent branch or at least master or something. To handle non-numeric named branches as versions instead of searching for a parent branch diff --git a/doc/05-repositories.md b/doc/05-repositories.md index 7a9cc8b46..b32d92690 100644 --- a/doc/05-repositories.md +++ b/doc/05-repositories.md @@ -6,7 +6,7 @@ of repositories are available, and how they work. ## Concepts Before we look at the different types of repositories that exist, we need to -understand some of the basic concepts that Composer is built on. +understand some basic concepts that Composer is built on. ### Package @@ -41,7 +41,7 @@ be preferred. A repository is a package source. It's a list of packages/versions. Composer will look in all your repositories to find the packages your project requires. -By default only the Packagist.org repository is registered in Composer. You can +By default, only the Packagist.org repository is registered in Composer. You can add more repositories to your project by declaring them in `composer.json`. Repositories are only available to the root package and the repositories @@ -122,7 +122,7 @@ It may include any of the other fields specified in the [schema](04-schema.md). The `notify-batch` field allows you to specify a URL that will be called every time a user installs a package. The URL can be either an absolute path -(that will use the same domain as the repository) or a fully qualified URL. +(that will use the same domain as the repository), or a fully qualified URL. An example value: @@ -217,7 +217,7 @@ from these systems. There are a few use cases for this. The most common one is maintaining your own fork of a third party library. If you are using a certain library for your -project and you decide to change something in the library, you will want your +project, and you decide to change something in the library, you will want your project to use the patched version. If the library is on GitHub (this is the case most of the time), you can simply fork it there and push your changes to your fork. After that you update the project's `composer.json`. All you have @@ -316,7 +316,7 @@ Please note: #### BitBucket Driver Configuration -The BitBucket driver uses OAuth to access your private repositories via the BitBucket REST APIs and you will need to create an OAuth consumer to use the driver, please refer to [Atlassian's Documentation](https://confluence.atlassian.com/bitbucket/oauth-on-bitbucket-cloud-238027431.html). You will need to fill the callback url with something to satisfy BitBucket, but the address does not need to go anywhere and is not used by Composer. +The BitBucket driver uses OAuth to access your private repositories via the BitBucket REST APIs, and you will need to create an OAuth consumer to use the driver, please refer to [Atlassian's Documentation](https://confluence.atlassian.com/bitbucket/oauth-on-bitbucket-cloud-238027431.html). You will need to fill the callback url with something to satisfy BitBucket, but the address does not need to go anywhere and is not used by Composer. After creating an OAuth consumer in the BitBucket control panel, you need to setup your auth.json file with the credentials like this (more info [here](https://getcomposer.org/doc/06-config.md#bitbucket-oauth)): @@ -437,7 +437,7 @@ Here is an example for the smarty template engine: } ``` -Typically you would leave the source part off, as you don't really need it. +Typically, you would leave the source part off, as you don't really need it. > **Note**: This repository type has a few limitations and should be avoided > whenever possible: diff --git a/doc/06-config.md b/doc/06-config.md index 30f31b98e..b7e5e8e45 100644 --- a/doc/06-config.md +++ b/doc/06-config.md @@ -192,14 +192,14 @@ metadata for the `git`/`hg` types and to speed up installs. ## cache-files-ttl -Defaults to `15552000` (6 months). Composer caches all dist (zip, tar, ..) +Defaults to `15552000` (6 months). Composer caches all dist (zip, tar, ...) packages that it downloads. Those are purged after six months of being unused by default. This option allows you to tweak this duration (in seconds) or disable it completely by setting it to 0. ## cache-files-maxsize -Defaults to `300MiB`. Composer caches all dist (zip, tar, ..) packages that it +Defaults to `300MiB`. Composer caches all dist (zip, tar, ...) packages that it downloads. When the garbage collection is periodically ran, this is the maximum size the cache will be able to use. Older (less used) files will be removed first until the cache fits. diff --git a/doc/articles/aliases.md b/doc/articles/aliases.md index d36eb11ff..c03ec52f2 100644 --- a/doc/articles/aliases.md +++ b/doc/articles/aliases.md @@ -107,5 +107,5 @@ and alias it to `1.0.x-dev`. > inline-aliased again in A's `composer.json`. > **Note:** Inline aliasing should be avoided, especially for published -> packages/libraries. If you found a bug, try and get your fix merged upstream. +> packages/libraries. If you found a bug, try to get your fix merged upstream. > This helps to avoid issues for users of your package. diff --git a/doc/articles/autoloader-optimization.md b/doc/articles/autoloader-optimization.md index 11faac8a7..8c8fc4fae 100644 --- a/doc/articles/autoloader-optimization.md +++ b/doc/articles/autoloader-optimization.md @@ -48,7 +48,7 @@ There are no real trade-offs with this method. It should always be enabled in production. The only issue is it does not keep track of autoload misses (i.e. when -it can not find a given class), so those fallback to PSR-4 rules and can still +it cannot find a given class), so those fallback to PSR-4 rules and can still result in slow filesystem checks. To solve this issue two Level 2 optimization options exist, and you can decide to enable either if you have a lot of class_exists checks that are done for classes that do not exist in your project. @@ -78,7 +78,7 @@ also means that in case a class is generated at runtime for some reason, it will not be allowed to be autoloaded. If your project or any of your dependencies does that then you might experience "class not found" issues in production. Enable this with care. -> Note: This can not be combined with Level 2/B optimizations. You have to choose one as +> Note: This cannot be combined with Level 2/B optimizations. You have to choose one as > they address the same issue in different ways. ## Optimization Level 2/B: APCu cache @@ -97,15 +97,15 @@ This option adds an APCu cache as a fallback for the class map. It will not automatically generate the class map though, so you should still enable Level 1 optimizations manually if you so desire. -Whether a class is found or not, that fact is always cached in APCu so it can be +Whether a class is found or not, that fact is always cached in APCu, so it can be returned quickly on the next request. ### Trade-offs This option requires APCu which may or may not be available to you. It also -uses APCu memory for autoloading purposes, but it is safe to use and can not +uses APCu memory for autoloading purposes, but it is safe to use and cannot result in classes not being found like the authoritative class map optimization above. -> Note: This can not be combined with Level 2/A optimizations. You have to choose one as +> Note: This cannot be combined with Level 2/A optimizations. You have to choose one as > they address the same issue in different ways. diff --git a/doc/articles/custom-installers.md b/doc/articles/custom-installers.md index 791c04956..421a49cb7 100644 --- a/doc/articles/custom-installers.md +++ b/doc/articles/custom-installers.md @@ -6,7 +6,7 @@ ## Synopsis -At times it may be necessary for a package to require additional actions during +At times, it may be necessary for a package to require additional actions during installation, such as installing packages outside of the default `vendor` library. diff --git a/doc/articles/versions.md b/doc/articles/versions.md index 85c9356d2..060352a79 100644 --- a/doc/articles/versions.md +++ b/doc/articles/versions.md @@ -159,7 +159,7 @@ Example: `~1.2` ### Caret Version Range (^) -The `^` operator behaves very similarly but it sticks closer to semantic +The `^` operator behaves very similarly, but it sticks closer to semantic versioning, and will always allow non-breaking updates. For example `^1.2.3` is equivalent to `>=1.2.3 <2.0.0` as none of the releases until 2.0 should break backwards compatibility. For pre-1.0 versions it also acts with safety diff --git a/doc/faqs/why-are-unbound-version-constraints-a-bad-idea.md b/doc/faqs/why-are-unbound-version-constraints-a-bad-idea.md index 9aef970f9..399a31d74 100644 --- a/doc/faqs/why-are-unbound-version-constraints-a-bad-idea.md +++ b/doc/faqs/why-are-unbound-version-constraints-a-bad-idea.md @@ -5,7 +5,7 @@ A version constraint without an upper bound such as `*`, `>=3.4` or This includes major versions breaking backward compatibility. Once a release of your package is tagged, you cannot tweak its dependencies -anymore in case a dependency breaks BC - you have to do a new release but the +anymore in case a dependency breaks BC - you have to do a new release, but the previous one stays broken. The only good alternative is to define an upper bound on your constraints, diff --git a/doc/faqs/why-can't-composer-load-repositories-recursively.md b/doc/faqs/why-can't-composer-load-repositories-recursively.md index a39aff6fb..1dff52c40 100644 --- a/doc/faqs/why-can't-composer-load-repositories-recursively.md +++ b/doc/faqs/why-can't-composer-load-repositories-recursively.md @@ -24,7 +24,7 @@ their package's packages, etc, then resolve requirements. It could work, but it slows down the initialization a lot since VCS repos can each take a few seconds, and it could end up in a completely broken state since many versions of a package could define the same packages inside a package repository, but with different -dist/source. There are many many ways this could go wrong. +dist/source. There are many ways this could go wrong. - Fetch the repositories of root package, then fetch the repositories of the first level dependencies, then fetch the repositories of their dependencies, etc,