Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Appearance settings

Commit 706855b

Browse filesBrowse files
javiereguiluzjaviereguiluz
committed
minor #15888 [Flex] Add instructions for use of private recipe repositories (gnito-org)
This PR was squashed before being merged into the 4.4 branch. Discussion ---------- [Flex] Add instructions for use of private recipe repositories <!-- If your pull request fixes a BUG, use the oldest maintained branch that contains the bug (see https://symfony.com/releases for the list of maintained branches). If your pull request documents a NEW FEATURE, use the same Symfony branch where the feature was introduced (and `5.x` for features of unreleased versions). --> Commits ------- 7fe3923 [Flex] Add instructions for use of private recipe repositories
2 parents 350d4e0 + 7fe3923 commit 706855b
Copy full SHA for 706855b

File tree

Expand file treeCollapse file tree

2 files changed

+232
-1
lines changed
Filter options
Expand file treeCollapse file tree

2 files changed

+232
-1
lines changed

‎setup/flex.rst

Copy file name to clipboardExpand all lines: setup/flex.rst
+6-1Lines 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

Copy file name to clipboard
+226Lines 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 (0)
Morty Proxy This is a proxified and sanitized view of the page, visit original site.