Skip to content

Commit 7fe3923

Browse files
gnito-orgjaviereguiluz
gnito-org
authored and
javiereguiluz
committed
[Flex] Add instructions for use of private recipe repositories
1 parent 0d88091 commit 7fe3923

File tree

2 files changed

+232
-1
lines changed

2 files changed

+232
-1
lines changed

‎setup/flex.rst

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -133,7 +133,7 @@ manual steps:
133133

134134
#. Move the public assets, such as images or compiled CSS/JS files, from
135135
``src/AppBundle/Resources/public/`` to ``public/`` (e.g. ``public/images/``).
136-
136+
137137
#. Remove ``src/AppBundle/``.
138138

139139
#. Move the source of the assets (e.g. the SCSS files) to ``assets/`` and use
@@ -189,6 +189,11 @@ If you customize these paths, some files copied from a recipe still may contain
189189
references to the original path. In other words: you may need to update some things
190190
manually after a recipe is installed.
191191

192+
Learn more
193+
----------
194+
195+
* :doc:`/setup/flex_private_recipes`
196+
192197
.. _`default services.yaml file`: https://github.com/symfony/recipes/blob/master/symfony/framework-bundle/4.4/config/services.yaml
193198
.. _`shown in this example`: https://github.com/symfony/skeleton/blob/8e33fe617629f283a12bbe0a6578bd6e6af417af/composer.json#L24-L33
194199
.. _`shown in this example of the skeleton-project`: https://github.com/symfony/skeleton/blob/8e33fe617629f283a12bbe0a6578bd6e6af417af/composer.json#L44-L46

‎setup/flex_private_recipes.rst

Lines changed: 226 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,226 @@
1+
How To Configure and Use Flex Private Recipe Repositories
2+
=========================================================
3+
4+
Since the `release of version 1.16`_ of ``symfony/flex``, you can build your own private
5+
flex recipe repositories, and seamlessly integrate them into the ``composer`` package
6+
installation and maintenance process.
7+
8+
This is particularly useful when you have private bundles or packages that must perform their own
9+
installation tasks, in a similar fashion that Symfony and other open-source bundles and packages handle their
10+
own installation tasks via ``symfony/flex``.
11+
12+
To do this, in broad strokes, you:
13+
14+
* Create a private GitHub repository;
15+
* Create your private recipes;
16+
* Create an index to the recipes;
17+
* Store your recipes in the private repository;
18+
* Grant ``composer`` access to the private repository;
19+
* Configure your project's ``composer.json`` file; and
20+
* Install the recipes in your project.
21+
22+
Create a Private GitHub Repository
23+
----------------------------------
24+
25+
Log in to your GitHub.com account, click your account icon in the top-right corner, and select
26+
**Your Repositories**. Then click the **New** button, fill in the **repository name**, select the
27+
**Private** radio button, and click the **Create Repository** button.
28+
29+
Create Your Private Recipes
30+
---------------------------
31+
32+
A ``symfony/flex`` recipe is a standard JSON file that has the following structure:
33+
34+
.. code-block:: json
35+
36+
{
37+
"manifests": {
38+
"myorg/package-name": {
39+
"manifest": {
40+
},
41+
"ref": "7405f3af1312d1f9121afed4dddef636c6c7ff00"
42+
}
43+
}
44+
}
45+
46+
If your package is a private Symfony bundle, you will have the following in the recipe:
47+
48+
.. code-block:: json
49+
50+
{
51+
"manifests": {
52+
"myorg/private-bundle": {
53+
"manifest": {
54+
"bundles": {
55+
"Myorg\\PrivateBundle\\MyorgPrivateBundle": [
56+
"all"
57+
]
58+
}
59+
},
60+
"ref": "7405f3af1312d1f9121afed4dddef636c6c7ff00"
61+
}
62+
}
63+
}
64+
65+
Replace ``myorg`` and ``private-bundle`` with your own private bundle details.
66+
67+
The ``"ref"`` entry is just a random 40-character string, which is used by ``composer`` to determine if
68+
your recipe was modified. Every time that you make changes to your recipe, you also need to
69+
generate a new ``"ref"`` value.
70+
71+
.. tip::
72+
73+
Use the following PHP script to generate a random ``"ref"`` value.
74+
75+
.. code-block::
76+
77+
$bytes = random_bytes(20);
78+
var_dump(bin2hex($bytes));
79+
80+
The ``"all"`` entry tells ``symfony/flex`` to create an entry in your project's ``bundles.php`` file
81+
for all environments. To load your bundle only for the ``dev`` environment, replace ``"all"`` with ``"dev"``.
82+
83+
The name of your recipe JSON file must conform to the following convention:
84+
85+
``myorg.private-bundle.1.0.json``
86+
87+
where ``1.0`` is the version number of your bundle.
88+
89+
Replace ``myorg`` and ``private-bundle`` with your own private bundle or package details.
90+
91+
You will probably also want ``symfony/flex`` to create configuration files for your bundle or package in the
92+
project's ``/config/packages`` directory. To do that, change the recipe JSON file as follows:
93+
94+
.. code-block:: json
95+
96+
{
97+
"manifests": {
98+
"myorg/private-bundle": {
99+
"manifest": {
100+
"bundles": {
101+
"Myorg\\PrivateBundle\\MyorgPrivateBundle": [
102+
"all"
103+
]
104+
},
105+
"copy-from-recipe": {
106+
"config/": "%CONFIG_DIR%"
107+
}
108+
},
109+
"files": {
110+
"config/packages/myorg_private.yaml": {
111+
"contents": [
112+
"myorg_private:",
113+
" encode: true",
114+
""
115+
],
116+
"executable": false
117+
}
118+
},
119+
"ref": "7405f3af1312d1f9121afed4dddef636c6c7ff00"
120+
}
121+
}
122+
}
123+
124+
For more examples of what you can include in a recipe file, browse the live `Symfony recipe files`_.
125+
126+
Create an Index to the Recipes
127+
------------------------------
128+
129+
The next step is to create an ``index.json`` file, which will contain entries for all your
130+
private recipes, and other general configuration information.
131+
132+
The ``index.json`` file has the following format:
133+
134+
.. code-block:: json
135+
136+
{
137+
"recipes": {
138+
"myorg/private-bundle": [
139+
"1.0"
140+
]
141+
},
142+
"branch": "master",
143+
"is_contrib": true,
144+
"_links": {
145+
"repository": "github.com/your-github-account-name/your-recipes-repository",
146+
"origin_template": "{package}:{version}@github.com/your-github-account-name/your-recipes-repository:master",
147+
"recipe_template": "https://api.github.com/repos/your-github-account-name/your-recipes-repository/contents/{package_dotted}.{version}.json"
148+
}
149+
}
150+
151+
Create an entry in ``"recipes"`` for each of your bundle recipes.
152+
153+
Replace ``your-github-account-name`` and ``your-recipes-repository`` with your own details.
154+
155+
Store Your Recipes in the Private Repository
156+
--------------------------------------------
157+
158+
Upload the recipe ``.json`` file(s) and the ``index.json`` file into the root directory of your
159+
private GitHub repository.
160+
161+
Grant ``composer`` Access to the Private Repository
162+
-------------------------------------------------
163+
164+
In your GitHub account, click your account icon in the top-right corner, select
165+
``Settings`` and ``Developer Settings``. Then select ``Personal Access Tokens``.
166+
167+
Generate a new access token with ``Full control of private repositories`` privileges.
168+
169+
Copy the access token value, switch to the terminal of your local computer, and execute
170+
the following command:
171+
172+
.. code-block:: terminal
173+
174+
composer config --global --auth github-oauth.github.com [token]
175+
176+
Replace ``[token]`` with the value of your GitHub personal access token.
177+
178+
Configure Your Project's ``composer.json`` File
179+
---------------------------------------------
180+
181+
Add the following to your project's ``composer.json`` file:
182+
183+
.. code-block:: json
184+
185+
{
186+
"extra": {
187+
"symfony": {
188+
"endpoint": [
189+
"https://api.github.com/repos/your-github-account-name/your-recipes-repository/contents/index.json",
190+
"flex://defaults"
191+
]
192+
}
193+
}
194+
}
195+
196+
Replace ``your-github-account-name`` and ``your-recipes-repository`` with your own details.
197+
198+
.. tip::
199+
200+
The ``extra.symfony`` key will most probably already exist in your ``composer.json``. Simply
201+
add the ``"endpoint"`` key to the existing ``extra.symfony`` entry.
202+
203+
.. tip::
204+
205+
The ``endpoint`` URL **must** point to ``https://api.github.com/repos`` and **not* to
206+
``https://www.github.com``. The latter will not work.
207+
208+
Install the Recipes in Your Project
209+
-----------------------------------
210+
211+
If your private bundles / packages have not yet been installed in your project, run the following command:
212+
213+
.. code-block:: terminal
214+
215+
composer update
216+
217+
If the private bundles / packages have already been installed and you just want to install the new
218+
private recipes, run the following command:
219+
220+
.. code-block:: terminal
221+
222+
composer recipes
223+
224+
.. _`release of version 1.16`: https://github.com/symfony/cli
225+
.. _`Symfony recipe files`: https://github.com/symfony/recipes/tree/flex/main
226+

0 commit comments

Comments
 (0)