Skip to content
Newer
Older
100644 197 lines (144 sloc) 6.85 KB
f4984e9 @igorw [docs] first parts of the libraries chapter
igorw authored Feb 18, 2012
1 # Libraries
2
3 This chapter will tell you how to make your library installable through composer.
4
5 ## Every project is a package
6
c42e370 @igorw [docs] wrap all lines to 80 chars
igorw authored Feb 20, 2012
7 As soon as you have a `composer.json` in a directory, that directory is a
8 package. When you add a `require` to a project, you are making a package that
9 depends on other packages. The only difference between your project and
10 libraries is that your project is a package without a name.
f4984e9 @igorw [docs] first parts of the libraries chapter
igorw authored Feb 18, 2012
11
c42e370 @igorw [docs] wrap all lines to 80 chars
igorw authored Feb 20, 2012
12 In order to make that package installable you need to give it a name. You do
13 this by adding a `name` to `composer.json`:
f4984e9 @igorw [docs] first parts of the libraries chapter
igorw authored Feb 18, 2012
14
605fae4 @Seldaek Remove fenced blocks in docs
Seldaek authored Feb 29, 2012
15 {
16 "name": "acme/hello-world",
17 "require": {
18 "monolog/monolog": "1.0.*"
19 }
f4984e9 @igorw [docs] first parts of the libraries chapter
igorw authored Feb 18, 2012
20 }
21
c42e370 @igorw [docs] wrap all lines to 80 chars
igorw authored Feb 20, 2012
22 In this case the project name is `acme/hello-world`, where `acme` is the
23 vendor name. Supplying a vendor name is mandatory.
f4984e9 @igorw [docs] first parts of the libraries chapter
igorw authored Feb 18, 2012
24
c42e370 @igorw [docs] wrap all lines to 80 chars
igorw authored Feb 20, 2012
25 > **Note:** If you don't know what to use as a vendor name, your GitHub
26 username is usually a good bet. While package names are case insensitive, the
27 convention is all lowercase and dashes for word separation.
f4984e9 @igorw [docs] first parts of the libraries chapter
igorw authored Feb 18, 2012
28
29 ## Specifying the version
30
4c75a2d @Seldaek Reinforce language about not specifying the version
Seldaek authored Jun 14, 2012
31 You need to specify the package's version some way. When you publish your
32 package on Packagist, it is able to infer the version from the VCS (git, svn,
33 hg) information, so in that case you do not have to specify it, and it is
34 recommended not to. See [tags](#tags) and [branches](#branches) to see how
35 version numbers are extracted from these.
f4984e9 @igorw [docs] first parts of the libraries chapter
igorw authored Feb 18, 2012
36
4c75a2d @Seldaek Reinforce language about not specifying the version
Seldaek authored Jun 14, 2012
37 If you are creating packages by hand and really have to specify it explicitly,
38 you can just add a `version` field:
f4984e9 @igorw [docs] first parts of the libraries chapter
igorw authored Feb 18, 2012
39
605fae4 @Seldaek Remove fenced blocks in docs
Seldaek authored Feb 29, 2012
40 {
41 "version": "1.0.0"
42 }
f4984e9 @igorw [docs] first parts of the libraries chapter
igorw authored Feb 18, 2012
43
44 ### Tags
45
c42e370 @igorw [docs] wrap all lines to 80 chars
igorw authored Feb 20, 2012
46 For every tag that looks like a version, a package version of that tag will be
47 created. It should match 'X.Y.Z' or 'vX.Y.Z', with an optional suffix for RC,
48 beta, alpha or patch.
f4984e9 @igorw [docs] first parts of the libraries chapter
igorw authored Feb 18, 2012
49
50 Here are a few examples of valid tag names:
51
52 1.0.0
53 v1.0.0
54 1.10.5-RC1
55 v4.4.4beta2
56 v2.0.0-alpha
57 v2.0.4-p1
58
31a75f0 @igorw [docs] put notes into quote blocks to highlight them
igorw authored Feb 19, 2012
59 > **Note:** If you specify an explicit version in `composer.json`, the tag name must match the specified version.
f4984e9 @igorw [docs] first parts of the libraries chapter
igorw authored Feb 18, 2012
60
61 ### Branches
62
c42e370 @igorw [docs] wrap all lines to 80 chars
igorw authored Feb 20, 2012
63 For every branch, a package development version will be created. If the branch
64 name looks like a version, the version will be `{branchname}-dev`. For example
28941f1 @Seldaek Fix docs
Seldaek authored May 2, 2012
65 a branch `2.0` will get a version `2.0.x-dev` (the `.x` is added for technical
66 reasons, to make sure it is recognized as a branch, a `2.0.x` branch would also
67 be valid and be turned into `2.0.x-dev` as well. If the branch does not look
4c75a2d @Seldaek Reinforce language about not specifying the version
Seldaek authored Jun 14, 2012
68 like a version, it will be `dev-{branchname}`. `master` results in a
28941f1 @Seldaek Fix docs
Seldaek authored May 2, 2012
69 `dev-master` version.
f4984e9 @igorw [docs] first parts of the libraries chapter
igorw authored Feb 18, 2012
70
71 Here are some examples of version branch names:
72
28941f1 @Seldaek Fix docs
Seldaek authored May 2, 2012
73 1.x
74 1.0 (equals 1.0.x)
f4984e9 @igorw [docs] first parts of the libraries chapter
igorw authored Feb 18, 2012
75 1.1.x
868fc25 @igorw [docs] add section about publishing to vcs and on packagist
igorw authored Feb 18, 2012
76
c42e370 @igorw [docs] wrap all lines to 80 chars
igorw authored Feb 20, 2012
77 > **Note:** When you install a dev version, it will install it from source.
868fc25 @igorw [docs] add section about publishing to vcs and on packagist
igorw authored Feb 18, 2012
78
7b88247 @igorw [docs] Aliases: branch-alias and inline aliasing
igorw authored Apr 26, 2012
79 ### Aliases
80
81 It is possible alias branch names to versions. For example, you could alias
28941f1 @Seldaek Fix docs
Seldaek authored May 2, 2012
82 `dev-master` to `1.0.x-dev`, which would allow you to require `1.0.x-dev` in all
7b88247 @igorw [docs] Aliases: branch-alias and inline aliasing
igorw authored Apr 26, 2012
83 the packages.
84
85 See [Aliases](articles/aliases.md) for more information.
86
7a66eb3 @igorw [docs] add a note about the lock file to the libs chapter
igorw authored Feb 19, 2012
87 ## Lock file
88
ea19aba @igorw [docs] move lib lockfile notes into lib chapter
igorw authored Mar 27, 2012
89 For your library you may commit the `composer.lock` file if you want to. This
90 can help your team to always test against the same dependency versions.
91 However, this lock file will not have any effect on other projects that depend
92 on it. It only has an effect on the main project.
7a66eb3 @igorw [docs] add a note about the lock file to the libs chapter
igorw authored Feb 19, 2012
93
ea19aba @igorw [docs] move lib lockfile notes into lib chapter
igorw authored Mar 27, 2012
94 If you do not want to commit the lock file and you are using git, add it to
95 the `.gitignore`.
7a66eb3 @igorw [docs] add a note about the lock file to the libs chapter
igorw authored Feb 19, 2012
96
45e6fa3 @cordoval add documentation segment recommending .gitattributes use to exclude …
cordoval authored Aug 3, 2012
97 ## Light-weight distribution packages
98
6e42fa4 @Seldaek Rewrap new content and tweak wording a bit
Seldaek authored Aug 13, 2012
99 Including the tests and other useless information like .travis.yml in
100 distributed packages is not a good idea.
45e6fa3 @cordoval add documentation segment recommending .gitattributes use to exclude …
cordoval authored Aug 3, 2012
101
6e42fa4 @Seldaek Rewrap new content and tweak wording a bit
Seldaek authored Aug 13, 2012
102 The `.gitattributes` file is a git specific file like `.gitignore` also living
103 at the root directory of your library. It overrides local and global
104 configuration (`.git/config` and `~/.gitconfig` respectively) when present and
105 tracked by git.
45e6fa3 @cordoval add documentation segment recommending .gitattributes use to exclude …
cordoval authored Aug 3, 2012
106
6e42fa4 @Seldaek Rewrap new content and tweak wording a bit
Seldaek authored Aug 13, 2012
107 Use `.gitattributes` to prevent unwanted files from bloating the zip
108 distribution packages.
45e6fa3 @cordoval add documentation segment recommending .gitattributes use to exclude …
cordoval authored Aug 3, 2012
109
110 // .gitattributes
111 Tests/ export-ignore
112 phpunit.xml.dist export-ignore
113 Resources/doc/ export-ignore
114 .travis.yml export-ignore
115
116 Test it by inspecting the zip file generated manually:
117
118 git archive branchName --format zip -o file.zip
119
1939407 @igorw Minor docs nitpick
igorw authored Oct 4, 2012
120 > **Note:** Files would be still tracked by git just not included in the
6e42fa4 @Seldaek Rewrap new content and tweak wording a bit
Seldaek authored Aug 13, 2012
121 > distribution. This will only work for GitHub packages installed from
122 > dist (i.e. tagged releases) for now.
45e6fa3 @cordoval add documentation segment recommending .gitattributes use to exclude …
cordoval authored Aug 3, 2012
123
868fc25 @igorw [docs] add section about publishing to vcs and on packagist
igorw authored Feb 18, 2012
124 ## Publishing to a VCS
125
c42e370 @igorw [docs] wrap all lines to 80 chars
igorw authored Feb 20, 2012
126 Once you have a vcs repository (version control system, e.g. git) containing a
127 `composer.json` file, your library is already composer-installable. In this
128 example we will publish the `acme/hello-world` library on GitHub under
129 `github.com/composer/hello-world`.
868fc25 @igorw [docs] add section about publishing to vcs and on packagist
igorw authored Feb 18, 2012
130
c42e370 @igorw [docs] wrap all lines to 80 chars
igorw authored Feb 20, 2012
131 Now, To test installing the `acme/hello-world` package, we create a new
7c43ecd @Seldaek Reflow text
Seldaek authored Mar 17, 2012
132 project locally. We will call it `acme/blog`. This blog will depend on
133 `acme/hello-world`, which in turn depends on `monolog/monolog`. We can
134 accomplish this by creating a new `blog` directory somewhere, containing a
c42e370 @igorw [docs] wrap all lines to 80 chars
igorw authored Feb 20, 2012
135 `composer.json`:
868fc25 @igorw [docs] add section about publishing to vcs and on packagist
igorw authored Feb 18, 2012
136
605fae4 @Seldaek Remove fenced blocks in docs
Seldaek authored Feb 29, 2012
137 {
138 "name": "acme/blog",
139 "require": {
140 "acme/hello-world": "dev-master"
141 }
868fc25 @igorw [docs] add section about publishing to vcs and on packagist
igorw authored Feb 18, 2012
142 }
143
c42e370 @igorw [docs] wrap all lines to 80 chars
igorw authored Feb 20, 2012
144 The name is not needed in this case, since we don't want to publish the blog
145 as a library. It is added here to clarify which `composer.json` is being
146 described.
868fc25 @igorw [docs] add section about publishing to vcs and on packagist
igorw authored Feb 18, 2012
147
c42e370 @igorw [docs] wrap all lines to 80 chars
igorw authored Feb 20, 2012
148 Now we need to tell the blog app where to find the `hello-world` dependency.
149 We do this by adding a package repository specification to the blog's
150 `composer.json`:
868fc25 @igorw [docs] add section about publishing to vcs and on packagist
igorw authored Feb 18, 2012
151
605fae4 @Seldaek Remove fenced blocks in docs
Seldaek authored Feb 29, 2012
152 {
153 "name": "acme/blog",
ca5662b @stof Fixed the doc to use the new format for versions
stof authored Mar 8, 2012
154 "repositories": [
155 {
156 "type": "vcs",
157 "url": "https://github.com/composer/hello-world"
605fae4 @Seldaek Remove fenced blocks in docs
Seldaek authored Feb 29, 2012
158 }
49a2146 @Seldaek Fix typo
Seldaek authored Mar 8, 2012
159 ],
605fae4 @Seldaek Remove fenced blocks in docs
Seldaek authored Feb 29, 2012
160 "require": {
161 "acme/hello-world": "dev-master"
868fc25 @igorw [docs] add section about publishing to vcs and on packagist
igorw authored Feb 18, 2012
162 }
163 }
164
c42e370 @igorw [docs] wrap all lines to 80 chars
igorw authored Feb 20, 2012
165 For more details on how package repositories work and what other types are
f3c4b86 @Seldaek finish updating links to .md
Seldaek authored Mar 8, 2012
166 available, see [Repositories](05-repositories.md).
868fc25 @igorw [docs] add section about publishing to vcs and on packagist
igorw authored Feb 18, 2012
167
c42e370 @igorw [docs] wrap all lines to 80 chars
igorw authored Feb 20, 2012
168 That's all. You can now install the dependencies by running composer's
169 `install` command!
868fc25 @igorw [docs] add section about publishing to vcs and on packagist
igorw authored Feb 18, 2012
170
c42e370 @igorw [docs] wrap all lines to 80 chars
igorw authored Feb 20, 2012
171 **Recap:** Any git/svn/hg repository containing a `composer.json` can be added
172 to your project by specifying the package repository and declaring the
173 dependency in the `require` field.
868fc25 @igorw [docs] add section about publishing to vcs and on packagist
igorw authored Feb 18, 2012
174
175 ## Publishing to packagist
176
c42e370 @igorw [docs] wrap all lines to 80 chars
igorw authored Feb 20, 2012
177 Alright, so now you can publish packages. But specifying the vcs repository
178 every time is cumbersome. You don't want to force all your users to do that.
868fc25 @igorw [docs] add section about publishing to vcs and on packagist
igorw authored Feb 18, 2012
179
c42e370 @igorw [docs] wrap all lines to 80 chars
igorw authored Feb 20, 2012
180 The other thing that you may have noticed is that we did not specify a package
181 repository for `monolog/monolog`. How did that work? The answer is packagist.
868fc25 @igorw [docs] add section about publishing to vcs and on packagist
igorw authored Feb 18, 2012
182
38ef1dc @Seldaek Doc fixes
Seldaek authored Feb 20, 2012
183 [Packagist](http://packagist.org/) is the main package repository for
184 composer, and it is enabled by default. Anything that is published on
185 packagist is available automatically through composer. Since monolog
186 [is on packagist](http://packagist.org/packages/monolog/monolog), we can depend
187 on it without having to specify any additional repositories.
868fc25 @igorw [docs] add section about publishing to vcs and on packagist
igorw authored Feb 18, 2012
188
3cccc29 @igorw [improve-docs] Explain what the root package is, refs #500
igorw authored Apr 13, 2012
189 If we wanted to share `hello-world` with the world, we would publish it on
190 packagist as well. Doing so is really easy.
868fc25 @igorw [docs] add section about publishing to vcs and on packagist
igorw authored Feb 18, 2012
191
c42e370 @igorw [docs] wrap all lines to 80 chars
igorw authored Feb 20, 2012
192 You simply hit the big "Submit Package" button and sign up. Then you submit
38ef1dc @Seldaek Doc fixes
Seldaek authored Feb 20, 2012
193 the URL to your VCS repository, at which point packagist will start crawling
194 it. Once it is done, your package will be available to anyone.
cee5fed @tnorthcutt added prev/next links to docs
tnorthcutt authored Mar 7, 2012
195
3cccc29 @igorw [improve-docs] Explain what the root package is, refs #500
igorw authored Apr 13, 2012
196 ← [Basic usage](01-basic-usage.md) | [Command-line interface](03-cli.md) →
Something went wrong with that request. Please try again.