Skip to content

Commit 953519f

Browse files
javiereguiluzjaviereguiluz
committed
Merge branch '4.4' into 5.3
* 4.4: Tweaks [Flex] Add instructions for use of private recipe repositories
2 parents 3f9ff65 + 021d9af commit 953519f

File tree

2 files changed

+229
-1
lines changed

2 files changed

+229
-1
lines changed

‎setup/flex.rst

+6-1
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/5.3/config/services.yaml
193198
.. _`shown in this example`: https://github.com/symfony/skeleton/blob/a0770a7f26eeda9890a104fa3de8f68c4120fca5/composer.json#L30-L39
194199
.. _`shown in this example of the skeleton-project`: https://github.com/symfony/skeleton/blob/a0770a7f26eeda9890a104fa3de8f68c4120fca5/composer.json#L55-L57

‎setup/flex_private_recipes.rst

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

0 commit comments

Comments
 (0)