diff --git a/04-schema.md b/04-schema.md new file mode 100644 index 0000000..0ce4d4f --- /dev/null +++ b/04-schema.md @@ -0,0 +1,861 @@ +# composer.json + +This chapter will explain all of the fields available in `composer.json`. + +## JSON schema + +We have a [JSON schema](http://json-schema.org) that documents the format and +can also be used to validate your `composer.json`. In fact, it is used by the +`validate` command. You can find it at: +[`res/composer-schema.json`](https://github.com/composer/composer/blob/master/res/composer-schema.json). + +## Root Package + +The root package is the package defined by the `composer.json` at the root of +your project. It is the main `composer.json` that defines your project +requirements. + +Certain fields only apply when in the root package context. One example of +this is the `config` field. Only the root package can define configuration. +The config of dependencies is ignored. This makes the `config` field +`root-only`. + +If you clone one of those dependencies to work on it, then that package is the +root package. The `composer.json` is identical, but the context is different. + +> **Note:** A package can be the root package or not, depending on the context. +> For example, if your project depends on the `monolog` library, your project +> is the root package. However, if you clone `monolog` from GitHub in order to +> fix a bug in it, then `monolog` is the root package. + +## Properties + +### name + +The name of the package. It consists of vendor name and project name, +separated by `/`. + +Examples: + +* monolog/monolog +* igorw/event-source + +Required for published packages (libraries). + +### description + +A short description of the package. Usually this is just one line long. + +Required for published packages (libraries). + +### version + +The version of the package. In most cases this is not required and should +be omitted (see below). + +This must follow the format of `X.Y.Z` or `vX.Y.Z` with an optional suffix +of `-dev`, `-patch`, `-alpha`, `-beta` or `-RC`. The patch, alpha, beta and +RC suffixes can also be followed by a number. + +Examples: + +- 1.0.0 +- 1.0.2 +- 1.1.0 +- 0.2.5 +- 1.0.0-dev +- 1.0.0-alpha3 +- 1.0.0-beta2 +- 1.0.0-RC5 + +Optional if the package repository can infer the version from somewhere, such +as the VCS tag name in the VCS repository. In that case it is also recommended +to omit it. + +> **Note:** Packagist uses VCS repositories, so the statement above is very +> much true for Packagist as well. Specifying the version yourself will +> most likely end up creating problems at some point due to human error. + +### type + +The type of the package. It defaults to `library`. + +Package types are used for custom installation logic. If you have a package +that needs some special logic, you can define a custom type. This could be a +`symfony-bundle`, a `wordpress-plugin` or a `typo3-module`. These types will +all be specific to certain projects, and they will need to provide an +installer capable of installing packages of that type. + +Out of the box, composer supports four types: + +- **library:** This is the default. It will simply copy the files to `vendor`. +- **project:** This denotes a project rather than a library. For example + application shells like the [Symfony standard edition](https://github.com/symfony/symfony-standard), + CMSs like the [SilverStripe installer](https://github.com/silverstripe/silverstripe-installer) + or full fledged applications distributed as packages. This can for example + be used by IDEs to provide listings of projects to initialize when creating + a new workspace. +- **metapackage:** An empty package that contains requirements and will trigger + their installation, but contains no files and will not write anything to the + filesystem. As such, it does not require a dist or source key to be + installable. +- **composer-plugin:** A package of type `composer-plugin` may provide an + installer for other packages that have a custom type. Read more in the + [dedicated article](articles/custom-installers.md). + +Only use a custom type if you need custom logic during installation. It is +recommended to omit this field and have it just default to `library`. + +### keywords + +An array of keywords that the package is related to. These can be used for +searching and filtering. + +Examples: + +- logging +- events +- database +- redis +- templating + +Optional. + +### homepage + +An URL to the website of the project. + +Optional. + +### time + +Release date of the version. + +Must be in `YYYY-MM-DD` or `YYYY-MM-DD HH:MM:SS` format. + +Optional. + +### license + +The license of the package. This can be either a string or an array of strings. + +The recommended notation for the most common licenses is (alphabetical): + +- Apache-2.0 +- BSD-2-Clause +- BSD-3-Clause +- BSD-4-Clause +- GPL-2.0 +- GPL-2.0+ +- GPL-3.0 +- GPL-3.0+ +- LGPL-2.1 +- LGPL-2.1+ +- LGPL-3.0 +- LGPL-3.0+ +- MIT + +Optional, but it is highly recommended to supply this. More identifiers are +listed at the [SPDX Open Source License Registry](http://www.spdx.org/licenses/). + +For closed-source software, you may use `"proprietary"` as the license identifier. + +An Example: + +```json +{ + "license": "MIT" +} +``` + +For a package, when there is a choice between licenses ("disjunctive license"), +multiple can be specified as array. + +An Example for disjunctive licenses: + +```json +{ + "license": [ + "LGPL-2.1", + "GPL-3.0+" + ] +} +``` + +Alternatively they can be separated with "or" and enclosed in parenthesis; + +```json +{ + "license": "(LGPL-2.1 or GPL-3.0+)" +} +``` + +Similarly when multiple licenses need to be applied ("conjunctive license"), +they should be separated with "and" and enclosed in parenthesis. + +### authors + +The authors of the package. This is an array of objects. + +Each author object can have following properties: + +* **name:** The author's name. Usually his real name. +* **email:** The author's email address. +* **homepage:** An URL to the author's website. +* **role:** The authors' role in the project (e.g. developer or translator) + +An example: + +```json +{ + "authors": [ + { + "name": "Nils Adermann", + "email": "naderman@naderman.de", + "homepage": "http://www.naderman.de", + "role": "Developer" + }, + { + "name": "Jordi Boggiano", + "email": "j.boggiano@seld.be", + "homepage": "http://seld.be", + "role": "Developer" + } + ] +} +``` + +Optional, but highly recommended. + +### support + +Various information to get support about the project. + +Support information includes the following: + +* **email:** Email address for support. +* **issues:** URL to the Issue Tracker. +* **forum:** URL to the Forum. +* **wiki:** URL to the Wiki. +* **irc:** IRC channel for support, as irc://server/channel. +* **source:** URL to browse or download the sources. + +An example: + +```json +{ + "support": { + "email": "support@example.org", + "irc": "irc://irc.freenode.org/composer" + } +} +``` + +Optional. + +### Package links + +All of the following take an object which maps package names to +[version constraints](01-basic-usage.md#package-versions). + +Example: + +```json +{ + "require": { + "monolog/monolog": "1.0.*" + } +} +``` + +All links are optional fields. + +`require` and `require-dev` additionally support stability flags (root-only). +These allow you to further restrict or expand the stability of a package beyond +the scope of the [minimum-stability](#minimum-stability) setting. You can apply +them to a constraint, or just apply them to an empty constraint if you want to +allow unstable packages of a dependency for example. + +Example: + +```json +{ + "require": { + "monolog/monolog": "1.0.*@beta", + "acme/foo": "@dev" + } +} +``` + +If one of your dependencies has a dependency on an unstable package you need to +explicitly require it as well, along with its sufficient stability flag. + +Example: + +```json +{ + "require": { + "doctrine/doctrine-fixtures-bundle": "dev-master", + "doctrine/data-fixtures": "@dev" + } +} +``` + +`require` and `require-dev` additionally support explicit references (i.e. +commit) for dev versions to make sure they are locked to a given state, even +when you run update. These only work if you explicitly require a dev version +and append the reference with `#`. + +Example: + +```json +{ + "require": { + "monolog/monolog": "dev-master#2eb0c0978d290a1c45346a1955188929cb4e5db7", + "acme/foo": "1.0.x-dev#abc123" + } +} +``` + +> **Note:** While this is convenient at times, it should not be how you use +> packages in the long term because it comes with a technical limitation. The +> composer.json metadata will still be read from the branch name you specify +> before the hash. Because of that in some cases it will not be a practical +> workaround, and you should always try to switch to tagged releases as soon +> as you can. + +It is also possible to inline-alias a package constraint so that it matches +a constraint that it otherwise would not. For more information [see the +aliases article](articles/aliases.md). + +#### require + +Lists packages required by this package. The package will not be installed +unless those requirements can be met. + +#### require-dev (root-only) + +Lists packages required for developing this package, or running +tests, etc. The dev requirements of the root package are installed by default. +Both `install` or `update` support the `--no-dev` option that prevents dev +dependencies from being installed. + +#### conflict + +Lists packages that conflict with this version of this package. They +will not be allowed to be installed together with your package. + +Note that when specifying ranges like `<1.0, >= 1.1` in a `conflict` link, +this will state a conflict with all versions that are less than 1.0 *and* equal +or newer than 1.1 at the same time, which is probably not what you want. You +probably want to go for `<1.0 | >= 1.1` in this case. + +#### replace + +Lists packages that are replaced by this package. This allows you to fork a +package, publish it under a different name with its own version numbers, while +packages requiring the original package continue to work with your fork because +it replaces the original package. + +This is also useful for packages that contain sub-packages, for example the main +symfony/symfony package contains all the Symfony Components which are also +available as individual packages. If you require the main package it will +automatically fulfill any requirement of one of the individual components, +since it replaces them. + +Caution is advised when using replace for the sub-package purpose explained +above. You should then typically only replace using `self.version` as a version +constraint, to make sure the main package only replaces the sub-packages of +that exact version, and not any other version, which would be incorrect. + +#### provide + +List of other packages that are provided by this package. This is mostly +useful for common interfaces. A package could depend on some virtual +`logger` package, any library that implements this logger interface would +simply list it in `provide`. + +### suggest + +Suggested packages that can enhance or work well with this package. These are +just informational and are displayed after the package is installed, to give +your users a hint that they could add more packages, even though they are not +strictly required. + +The format is like package links above, except that the values are free text +and not version constraints. + +Example: + +```json +{ + "suggest": { + "monolog/monolog": "Allows more advanced logging of the application flow" + } +} +``` + +### autoload + +Autoload mapping for a PHP autoloader. + +Currently [`PSR-0`](http://www.php-fig.org/psr/psr-0/) autoloading, +[`PSR-4`](http://www.php-fig.org/psr/psr-4/) autoloading, `classmap` generation and +`files` includes are supported. PSR-4 is the recommended way though since it offers +greater ease of use (no need to regenerate the autoloader when you add classes). + +#### PSR-4 + +Under the `psr-4` key you define a mapping from namespaces to paths, relative to the +package root. When autoloading a class like `Foo\\Bar\\Baz` a namespace prefix +`Foo\\` pointing to a directory `src/` means that the autoloader will look for a +file named `src/Bar/Baz.php` and include it if present. Note that as opposed to +the older PSR-0 style, the prefix (`Foo\\`) is **not** present in the file path. + +Namespace prefixes must end in `\\` to avoid conflicts between similar prefixes. +For example `Foo` would match classes in the `FooBar` namespace so the trailing +backslashes solve the problem: `Foo\\` and `FooBar\\` are distinct. + +The PSR-4 references are all combined, during install/update, into a single +key => value array which may be found in the generated file +`vendor/composer/autoload_psr4.php`. + +Example: + +```json +{ + "autoload": { + "psr-4": { + "Monolog\\": "src/", + "Vendor\\Namespace\\": "" + } + } +} +``` + +If you need to search for a same prefix in multiple directories, +you can specify them as an array as such: + +```json +{ + "autoload": { + "psr-4": { "Monolog\\": ["src/", "lib/"] } + } +} +``` + +If you want to have a fallback directory where any namespace will be looked for, +you can use an empty prefix like: + +```json +{ + "autoload": { + "psr-4": { "": "src/" } + } +} +``` + +#### PSR-0 + +Under the `psr-0` key you define a mapping from namespaces to paths, relative to the +package root. Note that this also supports the PEAR-style non-namespaced convention. + +Please note namespace declarations should end in `\\` to make sure the autoloader +responds exactly. For example `Foo` would match in `FooBar` so the trailing +backslashes solve the problem: `Foo\\` and `FooBar\\` are distinct. + +The PSR-0 references are all combined, during install/update, into a single key => value +array which may be found in the generated file `vendor/composer/autoload_namespaces.php`. + +Example: + +```json +{ + "autoload": { + "psr-0": { + "Monolog\\": "src/", + "Vendor\\Namespace\\": "src/", + "Vendor_Namespace_": "src/" + } + } +} +``` + +If you need to search for a same prefix in multiple directories, +you can specify them as an array as such: + +```json +{ + "autoload": { + "psr-0": { "Monolog\\": ["src/", "lib/"] } + } +} +``` + +The PSR-0 style is not limited to namespace declarations only but may be +specified right down to the class level. This can be useful for libraries with +only one class in the global namespace. If the php source file is also located +in the root of the package, for example, it may be declared like this: + +```json +{ + "autoload": { + "psr-0": { "UniqueGlobalClass": "" } + } +} +``` + +If you want to have a fallback directory where any namespace can be, you can +use an empty prefix like: + +```json +{ + "autoload": { + "psr-0": { "": "src/" } + } +} +``` + +#### Classmap + +The `classmap` references are all combined, during install/update, into a single +key => value array which may be found in the generated file +`vendor/composer/autoload_classmap.php`. This map is built by scanning for +classes in all `.php` and `.inc` files in the given directories/files. + +You can use the classmap generation support to define autoloading for all libraries +that do not follow PSR-0/4. To configure this you specify all directories or files +to search for classes. + +Example: + +```json +{ + "autoload": { + "classmap": ["src/", "lib/", "Something.php"] + } +} +``` + +#### Files + +If you want to require certain files explicitly on every request then you can use +the 'files' autoloading mechanism. This is useful if your package includes PHP functions +that cannot be autoloaded by PHP. + +Example: + +```json +{ + "autoload": { + "files": ["src/MyLibrary/functions.php"] + } +} +``` + +### autoload-dev (root-only) + +This section allows to define autoload rules for development purposes. + +Classes needed to run the test suite should not be included in the main autoload +rules to avoid polluting the autoloader in production and when other people use +your package as a dependency. + +Therefore, it is a good idea to rely on a dedicated path for your unit tests +and to add it within the autoload-dev section. + +Example: + +```json +{ + "autoload": { + "psr-4": { "MyLibrary\\": "src/" } + }, + "autoload-dev": { + "psr-4": { "MyLibrary\\Tests\\": "tests/" } + } +} +``` + +### include-path + +> **DEPRECATED**: This is only present to support legacy projects, and all new code +> should preferably use autoloading. As such it is a deprecated practice, but the +> feature itself will not likely disappear from Composer. + +A list of paths which should get appended to PHP's `include_path`. + +Example: + +```json +{ + "include-path": ["lib/"] +} +``` + +Optional. + +### target-dir + +> **DEPRECATED**: This is only present to support legacy PSR-0 style autoloading, +> and all new code should preferably use PSR-4 without target-dir and projects +> using PSR-0 with PHP namespaces are encouraged to migrate to PSR-4 instead. + +Defines the installation target. + +In case the package root is below the namespace declaration you cannot +autoload properly. `target-dir` solves this problem. + +An example is Symfony. There are individual packages for the components. The +Yaml component is under `Symfony\Component\Yaml`. The package root is that +`Yaml` directory. To make autoloading possible, we need to make sure that it +is not installed into `vendor/symfony/yaml`, but instead into +`vendor/symfony/yaml/Symfony/Component/Yaml`, so that the autoloader can load +it from `vendor/symfony/yaml`. + +To do that, `autoload` and `target-dir` are defined as follows: + +```json +{ + "autoload": { + "psr-0": { "Symfony\\Component\\Yaml\\": "" } + }, + "target-dir": "Symfony/Component/Yaml" +} +``` + +Optional. + +### minimum-stability (root-only) + +This defines the default behavior for filtering packages by stability. This +defaults to `stable`, so if you rely on a `dev` package, you should specify +it in your file to avoid surprises. + +All versions of each package are checked for stability, and those that are less +stable than the `minimum-stability` setting will be ignored when resolving +your project dependencies. Specific changes to the stability requirements of +a given package can be done in `require` or `require-dev` (see +[package links](#package-links)). + +Available options (in order of stability) are `dev`, `alpha`, `beta`, `RC`, +and `stable`. + +### prefer-stable (root-only) + +When this is enabled, Composer will prefer more stable packages over unstable +ones when finding compatible stable packages is possible. If you require a +dev version or only alphas are available for a package, those will still be +selected granted that the minimum-stability allows for it. + +Use `"prefer-stable": true` to enable. + +### repositories (root-only) + +Custom package repositories to use. + +By default composer just uses the packagist repository. By specifying +repositories you can get packages from elsewhere. + +Repositories are not resolved recursively. You can only add them to your main +`composer.json`. Repository declarations of dependencies' `composer.json`s are +ignored. + +The following repository types are supported: + +* **composer:** A composer repository is simply a `packages.json` file served + via the network (HTTP, FTP, SSH), that contains a list of `composer.json` + objects with additional `dist` and/or `source` information. The `packages.json` + file is loaded using a PHP stream. You can set extra options on that stream + using the `options` parameter. +* **vcs:** The version control system repository can fetch packages from git, + svn and hg repositories. +* **pear:** With this you can import any pear repository into your composer + project. +* **package:** If you depend on a project that does not have any support for + composer whatsoever you can define the package inline using a `package` + repository. You basically just inline the `composer.json` object. + +For more information on any of these, see [Repositories](05-repositories.md). + +Example: + +```json +{ + "repositories": [ + { + "type": "composer", + "url": "http://packages.example.com" + }, + { + "type": "composer", + "url": "https://packages.example.com", + "options": { + "ssl": { + "verify_peer": "true" + } + } + }, + { + "type": "vcs", + "url": "https://github.com/Seldaek/monolog" + }, + { + "type": "pear", + "url": "http://pear2.php.net" + }, + { + "type": "package", + "package": { + "name": "smarty/smarty", + "version": "3.1.7", + "dist": { + "url": "http://www.smarty.net/files/Smarty-3.1.7.zip", + "type": "zip" + }, + "source": { + "url": "http://smarty-php.googlecode.com/svn/", + "type": "svn", + "reference": "tags/Smarty_3_1_7/distribution/" + } + } + } + ] +} +``` + +> **Note:** Order is significant here. When looking for a package, Composer +will look from the first to the last repository, and pick the first match. +By default Packagist is added last which means that custom repositories can +override packages from it. + +### config (root-only) + +A set of configuration options. It is only used for projects. + +The following options are supported: + +* **process-timeout:** Defaults to `300`. The duration processes like git clones + can run before Composer assumes they died out. You may need to make this + higher if you have a slow connection or huge vendors. +* **use-include-path:** Defaults to `false`. If true, the Composer autoloader + will also look for classes in the PHP include path. +* **preferred-install:** Defaults to `auto` and can be any of `source`, `dist` or + `auto`. This option allows you to set the install method Composer will prefer to + use. +* **github-protocols:** Defaults to `["git", "https", "ssh"]`. A list of protocols to + use when cloning from github.com, in priority order. You can reconfigure it to + for example prioritize the https protocol if you are behind a proxy or have somehow + bad performances with the git protocol. +* **github-oauth:** A list of domain names and oauth keys. For example using + `{"github.com": "oauthtoken"}` as the value of this option will use `oauthtoken` + to access private repositories on github and to circumvent the low IP-based + rate limiting of their API. + [Read more](articles/troubleshooting.md#api-rate-limit-and-oauth-tokens) + on how to get an OAuth token for GitHub. +* **vendor-dir:** Defaults to `vendor`. You can install dependencies into a + different directory if you want to. +* **bin-dir:** Defaults to `vendor/bin`. If a project includes binaries, they + will be symlinked into this directory. +* **cache-dir:** Defaults to `$home/cache` on unix systems and + `C:\Users\\AppData\Local\Composer` on Windows. Stores all the caches + used by composer. See also [COMPOSER_HOME](03-cli.md#composer-home). +* **cache-files-dir:** Defaults to `$cache-dir/files`. Stores the zip archives + of packages. +* **cache-repo-dir:** Defaults to `$cache-dir/repo`. Stores repository metadata + for the `composer` type and the VCS repos of type `svn`, `github` and `bitbucket`. +* **cache-vcs-dir:** Defaults to `$cache-dir/vcs`. Stores VCS clones for + loading VCS repository 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, ..) 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 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. +* **prepend-autoloader:** 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. +* **autoloader-suffix:** Defaults to `null`. String to be used as a suffix for + the generated Composer autoloader. When null a random one will be generated. +* **optimize-autoloader** Defaults to `false`. Always optimize when dumping + the autoloader. +* **github-domains:** Defaults to `["github.com"]`. A list of domains to use in + github mode. This is used for GitHub Enterprise setups. +* **notify-on-install:** Defaults to `true`. Composer allows repositories to + define a notification URL, so that they get notified whenever a package from + that repository is installed. This option allows you to disable that behaviour. +* **discard-changes:** Defaults to `false` and can be any of `true`, `false` or + `"stash"`. This option allows you to set the default style of handling dirty + updates when in non-interactive mode. `true` will always discard changes in + vendors, while `"stash"` will try to stash and reapply. Use this for CI + servers or deploy scripts if you tend to have modified vendors. + +Example: + +```json +{ + "config": { + "bin-dir": "bin" + } +} +``` + +### scripts (root-only) + +Composer allows you to hook into various parts of the installation process +through the use of scripts. + +See [Scripts](articles/scripts.md) for events details and examples. + +### extra + +Arbitrary extra data for consumption by `scripts`. + +This can be virtually anything. To access it from within a script event +handler, you can do: + +```php +$extra = $event->getComposer()->getPackage()->getExtra(); +``` + +Optional. + +### bin + +A set of files that should be treated as binaries and symlinked into the `bin-dir` +(from config). + +See [Vendor Binaries](articles/vendor-binaries.md) for more details. + +Optional. + +### archive + +A set of options for creating package archives. + +The following options are supported: + +* **exclude:** Allows configuring a list of patterns for excluded paths. The + pattern syntax matches .gitignore files. A leading exclamation mark (!) will + result in any matching files to be included even if a previous pattern + excluded them. A leading slash will only match at the beginning of the project + relative path. An asterisk will not expand to a directory separator. + +Example: + +```json +{ + "archive": { + "exclude": ["/foo/bar", "baz", "/*.test", "!/foo/bar/baz"] + } +} +``` + +The example will include `/dir/foo/bar/file`, `/foo/bar/baz`, `/file.php`, +`/foo/my.test` but it will exclude `/foo/bar/any`, `/foo/baz`, and `/my.test`. + +Optional. + +← [Command-line interface](03-cli.md) | [Repositories](05-repositories.md) → diff --git a/05-repositories.md b/05-repositories.md index 93750d1..924c14b 100644 --- a/05-repositories.md +++ b/05-repositories.md @@ -26,27 +26,20 @@ Um repositório é uma fonte de pacotes. É uma lista de pacotes/versões. O com Por padrão o Packagist é o unico repositorio registrado no composer. Você pode adicionar mais repositorios no seu projeto declarando eles no composer.json. -Repositories are only available to the root package and the repositories -defined in your dependencies will not be loaded. Read the -[FAQ entry](faqs/why-can't-composer-load-repositories-recursively.md) if you -want to learn why. +Repositórios são disponibilizados na raiz do pacote e os repositórios definidos em suas dependências não iram ser carregados. Leia [FAQ entry](faqs/why-can't-composer-load-repositories-recursively.md) se você quiser saber porque. ## Tipos ### Composer -The main repository type is the `composer` repository. It uses a single -`packages.json` file that contains all of the package metadata. +O principal tipo de repositório é o repositório do `composer`. Que usa o arquivo `packages.json` que contem todo os metadados do pacote. +Esse é também o tipo de repositório que Packagist usa. Para referenciar um repositorio `composer`, apenas forneça o caminho depois do arquivo `packages.json`. -This is also the repository type that packagist uses. To reference a -`composer` repository, just supply the path before the `packages.json` file. -In case of packagist, that file is located at `/packages.json`, so the URL of -the repository would be `packagist.org`. For `example.org/packages.json` the -repository URL would be `example.org`. +No caso do packagist, esse arquivo fica em `/packages.json`, sendo assim a URL do repositorio sera `packagist.org`. Por exemplo `example.org/packages.json` a URL do repositorio é `example.org`. #### packages -The only required field is `packages`. The JSON structure is as follows: +O único campo obrigatório é o `packages`. A estrutura JSON é a seguinte: ```json { @@ -61,14 +54,13 @@ The only required field is `packages`. The JSON structure is as follows: } ``` -The `@composer.json` marker would be the contents of the `composer.json` from -that package version including as a minimum: +A marcação `@composer.json` sera o conteudo do arquivo `composer.json` from that package version including as a minimum: * name * version * dist or source -Here is a minimal package definition: +Abaixo a definição minima para um pacote: ```json { @@ -81,15 +73,13 @@ Here is a minimal package definition: } ``` -It may include any of the other fields specified in the [schema](04-schema.md). +Deve incluir qualuqer um dos outros campos espeficicados em [schema](04-schema.md). #### notify-batch -The `notify-batch` field allows you to specify an 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. +O campo `notify-batch` permite que seja espeficicado uma URL para ser chamada toda vez que um usuario instala um pacote. A URL pode ser tanto absoluta (que ira utilizar o mesmo dominio do repositorio) ou totalmente qualificada. -An example value: +Um valor de exemplo: ```json { @@ -97,9 +87,7 @@ An example value: } ``` -For `example.org/packages.json` containing a `monolog/monolog` package, this -would send a `POST` request to `example.org/downloads/` with following -JSON request body: +Em `example.org/packages.json` contendo o pacote `monolog/monolog` isso deve enviar uma requisição do tipo `POST` para `example.org/downloads/` e no corpo da requisição o JSON: ```json { @@ -109,18 +97,15 @@ JSON request body: } ``` -The version field will contain the normalized representation of the version -number. +A versão do campo ira conter a representação normalizada da versão numerada. -This field is optional. +Esse campo é opcional. #### includes -For larger repositories it is possible to split the `packages.json` into -multiple files. The `includes` field allows you to reference these additional -files. +Para grandes repositorios é possivel separar o `packages.json` em diversos arquivos. O campo `includes` permite qye você referencie esses arquivos adicionais. -An example: +Um exemplo: ```json { @@ -138,23 +123,17 @@ An example: } ``` -The SHA-1 sum of the file allows it to be cached and only re-requested if the -hash changed. +A soma SHA-1 do arquivo permite que seja feito cache e apenas sere requisitado novamente se o hash mudar. -This field is optional. You probably don't need it for your own custom -repository. +Esse campo é opcional. Você provavelmente não ira precisar usa-lo em seu repositório customizado. -#### provider-includes and providers-url +#### provider-includes e providers-url -For very large repositories like packagist.org using the so-called provider -files is the preferred method. The `provider-includes` field allows you to -list a set of files that list package names provided by this repository. The -hash should be a sha256 of the files in this case. +Para repositórios muito grandes como o packagist.org é recomendável utilizar o método o tão falado provider files. O campo `provider-includes` permite que você liste arquivos que cotem nomes de pacotes que esse repositorio possui. O hash deve ser um sha256 dos arquivos nesse caso. -The `providers-url` describes how provider files are found on the server. It -is an absolute path from the repository root. +O `providers-url` descreve como o provider files é encontrado no servidor. A notação é em um caminho absoluto a partir da raiz do repositório. -An example: +Um Exemplo: ```json { @@ -186,38 +165,22 @@ integrity, for example: } ``` -The file above declares that acme/foo and acme/bar can be found in this -repository, by loading the file referenced by `providers-url`, replacing -`%package%` by the package name and `%hash%` by the sha256 field. Those files -themselves just contain package definitions as described [above](#packages). +O arquivo acima declara que acme/foo e acme/bar podem ser encontrados nesse repositorio, carregando o arquivo referenciado por `providers-url`, replacing `%package%` pelo nome do pacote e `%hash%` pelo campo sha256. +Esses arquivos apenas contem definições de pacotes como descrito [acima](#packages) -This field is optional. You probably don't need it for your own custom -repository. +Esse campo é opcional. Você provavelmente não vai precisar usar no seu próprio repositório. #### stream options -The `packages.json` file is loaded using a PHP stream. You can set extra options -on that stream using the `options` parameter. You can set any valid PHP stream -context option. See [Context options and parameters](http://php.net/manual/en/context.php) -for more information. +O arquivo `packages.json` é carregado usando uma stream PHP. Você pode adicionar novas opções nesse stream usando o parametro `options`. Você pode adicionar qualquer stream PHP valido. Veja [Opções de Contexto e Parametros](http://php.net/manual/en/context.php) para mais informações. -### VCS +### SCV -VCS stands for version control system. This includes versioning systems like -git, svn or hg. Composer has a repository type for installing packages from -these systems. +SCV é um acrônimo para Sistema de Controle de Versão. Isso inclui o sistema de versionamento como git, svn or hg. Composer possui um tipo de repositório para instalar pacotes desses sistemas. -#### Carregando um pacote de um repositório VCS +#### Carregando um pacote de um repositório SCV -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 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 -to do is add your fork as a repository and update the version constraint to -point to your custom branch. For version constraint naming conventions see -[Libraries](02-libraries.md) for more information. +Existem alguns casos de uso para isso. O mais comum é manter seu próprio fork de uma biblioteca de terceiros. Se você esta usando certa biblioteca para o seu projeto e você decide mudar algo na biblioteca, você vai querer que seu projeto use a versão empacotada. Se a biblioteca esta no GitHub (como na maioria dos casos), você pode simplesmente realizar um fork realizar suas alterações e realizar um push com suas mudanças para o seu fork. Depois você atualiza o `composer.json` do projeto. Tudo quer você tem que fazer é adicionar o seu fork como um repositorio e atualizar a versão para apontar para a sua versão. Para version constraint convenções de nomeação de versão veja [Libraries](02-libraries.md) para mais informações. Example assuming you patched monolog to fix a bug in the `bugfix` branch: @@ -234,16 +197,13 @@ Example assuming you patched monolog to fix a bug in the `bugfix` branch: } } ``` +Quando você executa `php composer.phar update`, você deve pegar sua versão modificada de `monolog/monolog` em vez da versão do packgist. + +Quando você executa `php composer.pahr update` você deve pegar sua versão modificada do `monolog/monolog` em vez da versão do packagist -When you run `php composer.phar update`, you should get your modified version -of `monolog/monolog` instead of the one from packagist. +Noter que você não deva renomear o nome do pacote, ao menos que você deseje realizar um fork do projeto de fato, e decida ir em outra direção deiferente do projeto original. -Note that you should not rename the package unless you really intend to fork -it in the long term, and completely move away from the original package. -Composer will correctly pick your package over the original one since the -custom repository has priority over packagist. If you want to rename the -package, you should do so in the default (often master) branch and not in a -feature branch, since the package name is taken from the default branch. +Composer ira corretamente pegar o seu pacote em vez do original desde que pacotes customizados tenham prioridade sobre o packgist. Se você deseja renomear o pacote, você deve fazer na branch padrão (geralmente master) e não em uma branch de feature, sendo que o nome do pacote é pego da brach padrão. If other dependencies rely on the package you forked, it is possible to inline-alias it so that it matches a constraint that it otherwise would not. diff --git a/README.md b/README.md index 0f0d657..a053600 100644 --- a/README.md +++ b/README.md @@ -17,7 +17,7 @@ README como responsável pela tradução do mesmo. 03-cli.md [Gustavo](http://github.com/gustavoper) -04-schema.md +04-schema.md [alphabraga](http://github.com/alphabraga) 05-repositories.md [Gustavo](http://github.com/gustavoper)