Skip to content

Commit 11e97a2

Browse files
david-bonhagendavid-bonhagen
authored
Update TYPO3 recipe and improve docs (#4105)
* refactor: optimize bin/typo3 path usage * docs: improve documentation of TYPO3 recipe
1 parent edc08f2 commit 11e97a2

File tree

2 files changed

+121
-35
lines changed

2 files changed

+121
-35
lines changed

‎docs/recipe/typo3.md‎

Lines changed: 63 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -47,21 +47,44 @@ The [deploy](#deploy) task of **TYPO3** consists of:
4747

4848
The typo3 recipe is based on the [common](/docs/recipe/common.md) recipe.
4949

50+
51+
TYPO3 Deployer Recipe
52+
53+
Usage Examples:
54+
55+
Deploy to production (using Git as source):
56+
vendor/bin/dep deploy production
57+
58+
Deploy to staging using rsync:
59+
# In deploy.php or servers config, enable rsync
60+
set('use_rsync', true);
61+
vendor/bin/dep deploy staging
62+
63+
Common TYPO3 commands:
64+
vendor/bin/dep typo3:cache:flush # Clear all TYPO3 caches
65+
vendor/bin/dep typo3:cache:warmup # Warmup system caches
66+
vendor/bin/dep typo3:language:update # Update extension language files
67+
vendor/bin/dep typo3:extension:setup # Set up all extensions
68+
69+
5070
## Configuration
5171
### composer_config
52-
[Source](https://github.com/deployphp/deployer/blob/master/recipe/typo3.php#L10)
53-
72+
[Source](https://github.com/deployphp/deployer/blob/master/recipe/typo3.php#L34)
5473

74+
Parse composer.json and return its contents as an array.
75+
Used for auto-detecting TYPO3 settings like public_dir and bin_dir.
5576

5677
```php title="Default value"
5778
return json_decode(file_get_contents('./composer.json'), true, 512, JSON_THROW_ON_ERROR);
5879
```
5980

6081

6182
### typo3/public_dir
62-
[Source](https://github.com/deployphp/deployer/blob/master/recipe/typo3.php#L17)
83+
[Source](https://github.com/deployphp/deployer/blob/master/recipe/typo3.php#L43)
6384

64-
DocumentRoot / WebRoot for the TYPO3 installation
85+
TYPO3 public (web) directory.
86+
Automatically determined from composer.json.
87+
Defaults to "public".
6588
:::info Autogenerated
6689
The value of this configuration is autogenerated on access.
6790
:::
@@ -70,9 +93,10 @@ The value of this configuration is autogenerated on access.
7093

7194

7295
### bin/typo3
73-
[Source](https://github.com/deployphp/deployer/blob/master/recipe/typo3.php#L30)
96+
[Source](https://github.com/deployphp/deployer/blob/master/recipe/typo3.php#L57)
7497

75-
Path to TYPO3 cli
98+
Path to the TYPO3 CLI binary.
99+
Determined from composer.json "config.bin-dir" or defaults to "vendor/bin/typo3".
76100
:::info Autogenerated
77101
The value of this configuration is autogenerated on access.
78102
:::
@@ -81,7 +105,7 @@ The value of this configuration is autogenerated on access.
81105

82106

83107
### log_files
84-
[Source](https://github.com/deployphp/deployer/blob/master/recipe/typo3.php#L43)
108+
[Source](https://github.com/deployphp/deployer/blob/master/recipe/typo3.php#L70)
85109

86110
Log files to display when running `./vendor/bin/dep logs:app`
87111

@@ -91,11 +115,12 @@ Log files to display when running `./vendor/bin/dep logs:app`
91115

92116

93117
### shared_dirs
94-
[Source](https://github.com/deployphp/deployer/blob/master/recipe/typo3.php#L48)
118+
[Source](https://github.com/deployphp/deployer/blob/master/recipe/typo3.php#L76)
95119

96120
Overrides [shared_dirs](/docs/recipe/deploy/shared.md#shared_dirs) from `recipe/deploy/shared.php`.
97121

98-
Shared directories
122+
Directories that persist between releases.
123+
Shared via symlinks from the shared/ directory.
99124

100125
```php title="Default value"
101126
[
@@ -111,7 +136,7 @@ Shared directories
111136

112137

113138
### writable_dirs
114-
[Source](https://github.com/deployphp/deployer/blob/master/recipe/typo3.php#L70)
139+
[Source](https://github.com/deployphp/deployer/blob/master/recipe/typo3.php#L99)
115140

116141
Overrides [writable_dirs](/docs/recipe/deploy/writable.md#writable_dirs) from `recipe/deploy/writable.php`.
117142

@@ -130,29 +155,30 @@ Writeable directories
130155

131156

132157
### composer_options
133-
[Source](https://github.com/deployphp/deployer/blob/master/recipe/typo3.php#L82)
158+
[Source](https://github.com/deployphp/deployer/blob/master/recipe/typo3.php#L111)
134159

135160
Overrides [composer_options](/docs/recipe/deploy/vendors.md#composer_options) from `recipe/deploy/vendors.php`.
136161

137-
Composer options
162+
Composer install options for production.
138163

139164
```php title="Default value"
140165
' --no-dev --verbose --prefer-dist --no-progress --no-interaction --optimize-autoloader'
141166
```
142167

143168

144169
### use_rsync
145-
[Source](https://github.com/deployphp/deployer/blob/master/recipe/typo3.php#L88)
170+
[Source](https://github.com/deployphp/deployer/blob/master/recipe/typo3.php#L118)
146171

147-
If set in the config this recipe uses rsync. Default: false (use the Git repository)
172+
If set in the config this recipe uses rsync.
173+
Default setting: false (uses the Git repository)
148174

149175
```php title="Default value"
150176
false
151177
```
152178

153179

154180
### update_code_task
155-
[Source](https://github.com/deployphp/deployer/blob/master/recipe/typo3.php#L90)
181+
[Source](https://github.com/deployphp/deployer/blob/master/recipe/typo3.php#L120)
156182

157183

158184

@@ -162,7 +188,7 @@ return get('use_rsync') ? 'rsync' : 'deploy:update_code';
162188

163189

164190
### rsync
165-
[Source](https://github.com/deployphp/deployer/blob/master/recipe/typo3.php#L118)
191+
[Source](https://github.com/deployphp/deployer/blob/master/recipe/typo3.php#L148)
166192

167193

168194

@@ -186,51 +212,64 @@ return get('use_rsync') ? 'rsync' : 'deploy:update_code';
186212
## Tasks
187213

188214
### typo3\:update_code {#typo3-update_code}
189-
[Source](https://github.com/deployphp/deployer/blob/master/recipe/typo3.php#L94)
215+
[Source](https://github.com/deployphp/deployer/blob/master/recipe/typo3.php#L124)
190216

191217

192218

193219

194220

195221

196222
### typo3\:cache\:flush {#typo3-cache-flush}
197-
[Source](https://github.com/deployphp/deployer/blob/master/recipe/typo3.php#L133)
223+
[Source](https://github.com/deployphp/deployer/blob/master/recipe/typo3.php#L168)
198224

199225
TYPO3 - Clear all caches.
200226

201-
227+
TYPO3 Commands
228+
All run via [bin/php](/docs/recipe/common.md#bin/php) [release_path](/docs/recipe/deploy/release.md#release_path)/[bin/typo3](/docs/recipe/typo3.md#bin/typo3) <command>
202229

203230

204231
### typo3\:cache\:warmup {#typo3-cache-warmup}
205-
[Source](https://github.com/deployphp/deployer/blob/master/recipe/typo3.php#L138)
232+
[Source](https://github.com/deployphp/deployer/blob/master/recipe/typo3.php#L173)
206233

207234
TYPO3 - Cache warmup for system caches.
208235

209236

210237

211238

212239
### typo3\:language\:update {#typo3-language-update}
213-
[Source](https://github.com/deployphp/deployer/blob/master/recipe/typo3.php#L143)
240+
[Source](https://github.com/deployphp/deployer/blob/master/recipe/typo3.php#L178)
214241

215242
TYPO3 - Update the language files of all activated extensions.
216243

217244

218245

219246

220247
### typo3\:extension\:setup {#typo3-extension-setup}
221-
[Source](https://github.com/deployphp/deployer/blob/master/recipe/typo3.php#L148)
248+
[Source](https://github.com/deployphp/deployer/blob/master/recipe/typo3.php#L183)
222249

223250
TYPO3 - Set up all extensions.
224251

225252

226253

227254

228255
### deploy {#deploy}
229-
[Source](https://github.com/deployphp/deployer/blob/master/recipe/typo3.php#L156)
256+
[Source](https://github.com/deployphp/deployer/blob/master/recipe/typo3.php#L203)
230257

231258
Deploys a TYPO3 project.
232259

233-
Configure "deploy" task group.
260+
Main deploy task for TYPO3.
261+
262+
1. Lock deploy to avoid concurrent runs
263+
2. Create release directory
264+
3. Update code (Git or rsync)
265+
4. Symlink shared dirs/files
266+
5. Ensure writable dirs
267+
6. Install vendors
268+
7. Warm up TYPO3 caches
269+
8. Run extension setup
270+
9. Update language files
271+
10. Flush caches
272+
11. Unlock and clean up
234273

235274

236275
This task is group task which contains next tasks:

‎recipe/typo3.php‎

Lines changed: 58 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1,18 +1,44 @@
11
<?php
22

3+
/**
4+
* TYPO3 Deployer Recipe
5+
*
6+
* Usage Examples:
7+
*
8+
* Deploy to production (using Git as source):
9+
* vendor/bin/dep deploy production
10+
*
11+
* Deploy to staging using rsync:
12+
* # In deploy.php or servers config, enable rsync
13+
* set('use_rsync', true);
14+
* vendor/bin/dep deploy staging
15+
*
16+
* Common TYPO3 commands:
17+
* vendor/bin/dep typo3:cache:flush # Clear all TYPO3 caches
18+
* vendor/bin/dep typo3:cache:warmup # Warmup system caches
19+
* vendor/bin/dep typo3:language:update # Update extension language files
20+
* vendor/bin/dep typo3:extension:setup # Set up all extensions
21+
*/
22+
323
namespace Deployer;
424

525
require_once __DIR__ . '/common.php';
626
require_once 'contrib/rsync.php';
727

828
add('recipes', ['typo3']);
929

30+
/**
31+
* Parse composer.json and return its contents as an array.
32+
* Used for auto-detecting TYPO3 settings like public_dir and bin_dir.
33+
*/
1034
set('composer_config', function () {
1135
return json_decode(file_get_contents('./composer.json'), true, 512, JSON_THROW_ON_ERROR);
1236
});
1337

1438
/**
15-
* DocumentRoot / WebRoot for the TYPO3 installation
39+
* TYPO3 public (web) directory.
40+
* Automatically determined from composer.json.
41+
* Defaults to "public".
1642
*/
1743
set('typo3/public_dir', function () {
1844
$composerConfig = get('composer_config');
@@ -25,7 +51,8 @@
2551
});
2652

2753
/**
28-
* Path to TYPO3 cli
54+
* Path to the TYPO3 CLI binary.
55+
* Determined from composer.json "config.bin-dir" or defaults to "vendor/bin/typo3".
2956
*/
3057
set('bin/typo3', function () {
3158
$composerConfig = get('composer_config');
@@ -43,7 +70,8 @@
4370
set('log_files', 'var/log/typo3_*.log');
4471

4572
/**
46-
* Shared directories
73+
* Directories that persist between releases.
74+
* Shared via symlinks from the shared/ directory.
4775
*/
4876
set('shared_dirs', [
4977
'{{typo3/public_dir}}/fileadmin',
@@ -56,7 +84,8 @@
5684
]);
5785

5886
/**
59-
* Shared files
87+
* Files that persist between releases.
88+
* By default: config/system/settings.php
6089
*/
6190
if (!has('shared_files') || empty(get('shared_files'))) {
6291
set('shared_files', [
@@ -77,13 +106,14 @@
77106
]);
78107

79108
/**
80-
* Composer options
109+
* Composer install options for production.
81110
*/
82111
set('composer_options', ' --no-dev --verbose --prefer-dist --no-progress --no-interaction --optimize-autoloader');
83112

84113

85114
/**
86-
* If set in the config this recipe uses rsync. Default: false (use the Git repository)
115+
* If set in the config this recipe uses rsync.
116+
* Default setting: false (uses the Git repository)
87117
*/
88118
set('use_rsync', false);
89119

@@ -129,28 +159,45 @@
129159
]);
130160

131161

162+
/**
163+
* TYPO3 Commands
164+
* All run via {{bin/php}} {{release_path}}/{{bin/typo3}} <command>
165+
*/
166+
132167
desc('TYPO3 - Clear all caches');
133168
task('typo3:cache:flush', function () {
134-
run('{{bin/php}} {{release_path}}/public/typo3 cache:flush ');
169+
run('{{bin/php}} {{release_path}}/{{bin/typo3}} cache:flush');
135170
});
136171

137172
desc('TYPO3 - Cache warmup for system caches');
138173
task('typo3:cache:warmup', function () {
139-
run('{{bin/php}} {{release_path}}/public/typo3 cache:warmup --group system');
174+
run('{{bin/php}} {{release_path}}/{{bin/typo3}} cache:warmup --group system');
140175
});
141176

142177
desc('TYPO3 - Update the language files of all activated extensions');
143178
task('typo3:language:update', function () {
144-
run('{{bin/php}} {{release_path}}/public/typo3 language:update');
179+
run('{{bin/php}} {{release_path}}/{{bin/typo3}} language:update');
145180
});
146181

147182
desc('TYPO3 - Set up all extensions');
148183
task('typo3:extension:setup', function () {
149-
run('{{bin/php}} {{release_path}}/public/typo3 extension:setup');
184+
run('{{bin/php}} {{release_path}}/{{bin/typo3}} extension:setup');
150185
});
151186

152187
/**
153-
* Configure "deploy" task group.
188+
* Main deploy task for TYPO3.
189+
*
190+
* 1. Lock deploy to avoid concurrent runs
191+
* 2. Create release directory
192+
* 3. Update code (Git or rsync)
193+
* 4. Symlink shared dirs/files
194+
* 5. Ensure writable dirs
195+
* 6. Install vendors
196+
* 7. Warm up TYPO3 caches
197+
* 8. Run extension setup
198+
* 9. Update language files
199+
* 10. Flush caches
200+
* 11. Unlock and clean up
154201
*/
155202
desc('Deploys a TYPO3 project');
156203
task('deploy', [

0 commit comments

Comments
 (0)