Update TYPO3 recipe and improve docs (#4105)

* refactor: optimize bin/typo3 path usage

* docs: improve documentation of TYPO3 recipe

Author: david-bonhagen

docs/recipe/typo3.md

@@ -47,21 +47,44 @@ The [deploy](#deploy) task of **TYPO3** consists of:
 
 The typo3 recipe is based on the [common](/docs/recipe/common.md) recipe.
 
+
+TYPO3 Deployer Recipe
+
+Usage Examples:
+
+Deploy to production (using Git as source):
+    vendor/bin/dep deploy production
+
+Deploy to staging using rsync:
+    # In deploy.php or servers config, enable rsync
+    set('use_rsync', true);
+    vendor/bin/dep deploy staging
+
+Common TYPO3 commands:
+    vendor/bin/dep typo3:cache:flush       # Clear all TYPO3 caches
+    vendor/bin/dep typo3:cache:warmup      # Warmup system caches
+    vendor/bin/dep typo3:language:update   # Update extension language files
+    vendor/bin/dep typo3:extension:setup   # Set up all extensions
+
+
 ## Configuration
 ### composer_config
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/typo3.php#L10)
-
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/typo3.php#L34)
 
+Parse composer.json and return its contents as an array.
+Used for auto-detecting TYPO3 settings like public_dir and bin_dir.
 
 ```php title="Default value"
 return json_decode(file_get_contents('./composer.json'), true, 512, JSON_THROW_ON_ERROR);
 ```
 
 
 ### typo3/public_dir
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/typo3.php#L17)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/typo3.php#L43)
 
-DocumentRoot / WebRoot for the TYPO3 installation
+TYPO3 public (web) directory.
+Automatically determined from composer.json.
+Defaults to "public".
 :::info Autogenerated
 The value of this configuration is autogenerated on access.
 :::
@@ -70,9 +93,10 @@ The value of this configuration is autogenerated on access.
 
 
 ### bin/typo3
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/typo3.php#L30)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/typo3.php#L57)
 
-Path to TYPO3 cli
+Path to the TYPO3 CLI binary.
+Determined from composer.json "config.bin-dir" or defaults to "vendor/bin/typo3".
 :::info Autogenerated
 The value of this configuration is autogenerated on access.
 :::
@@ -81,7 +105,7 @@ The value of this configuration is autogenerated on access.
 
 
 ### log_files
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/typo3.php#L43)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/typo3.php#L70)
 
 Log files to display when running `./vendor/bin/dep logs:app`
 
@@ -91,11 +115,12 @@ Log files to display when running `./vendor/bin/dep logs:app`
 
 
 ### shared_dirs
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/typo3.php#L48)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/typo3.php#L76)
 
 Overrides [shared_dirs](/docs/recipe/deploy/shared.md#shared_dirs) from `recipe/deploy/shared.php`.
 
-Shared directories
+Directories that persist between releases.
+Shared via symlinks from the shared/ directory.
 
 ```php title="Default value"
 [
@@ -111,7 +136,7 @@ Shared directories
 
 
 ### writable_dirs
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/typo3.php#L70)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/typo3.php#L99)
 
 Overrides [writable_dirs](/docs/recipe/deploy/writable.md#writable_dirs) from `recipe/deploy/writable.php`.
 
@@ -130,29 +155,30 @@ Writeable directories
 
 
 ### composer_options
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/typo3.php#L82)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/typo3.php#L111)
 
 Overrides [composer_options](/docs/recipe/deploy/vendors.md#composer_options) from `recipe/deploy/vendors.php`.
 
-Composer options
+Composer install options for production.
 
 ```php title="Default value"
 ' --no-dev --verbose --prefer-dist --no-progress --no-interaction --optimize-autoloader'
 ```
 
 
 ### use_rsync
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/typo3.php#L88)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/typo3.php#L118)
 
-If set in the config this recipe uses rsync. Default: false (use the Git repository)
+If set in the config this recipe uses rsync.
+Default setting: false (uses the Git repository)
 
 ```php title="Default value"
 false
 ```
 
 
 ### update_code_task
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/typo3.php#L90)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/typo3.php#L120)
 
 
 
@@ -162,7 +188,7 @@ return get('use_rsync') ? 'rsync' : 'deploy:update_code';
 
 
 ### rsync
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/typo3.php#L118)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/typo3.php#L148)
 
 
 
@@ -186,51 +212,64 @@ return get('use_rsync') ? 'rsync' : 'deploy:update_code';
 ## Tasks
 
 ### typo3\:update_code {#typo3-update_code}
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/typo3.php#L94)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/typo3.php#L124)
 
 
 
 
 
 
 ### typo3\:cache\:flush {#typo3-cache-flush}
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/typo3.php#L133)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/typo3.php#L168)
 
 TYPO3 - Clear all caches.
 
-
+TYPO3 Commands
+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>
 
 
 ### typo3\:cache\:warmup {#typo3-cache-warmup}
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/typo3.php#L138)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/typo3.php#L173)
 
 TYPO3 - Cache warmup for system caches.
 
 
 
 
 ### typo3\:language\:update {#typo3-language-update}
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/typo3.php#L143)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/typo3.php#L178)
 
 TYPO3 - Update the language files of all activated extensions.
 
 
 
 
 ### typo3\:extension\:setup {#typo3-extension-setup}
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/typo3.php#L148)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/typo3.php#L183)
 
 TYPO3 - Set up all extensions.
 
 
 
 
 ### deploy {#deploy}
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/typo3.php#L156)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/typo3.php#L203)
 
 Deploys a TYPO3 project.
 
-Configure "deploy" task group.
+Main deploy task for TYPO3.
+
+1. Lock deploy to avoid concurrent runs
+2. Create release directory
+3. Update code (Git or rsync)
+4. Symlink shared dirs/files
+5. Ensure writable dirs
+6. Install vendors
+7. Warm up TYPO3 caches
+8. Run extension setup
+9. Update language files
+10. Flush caches
+11. Unlock and clean up
 
 
 This task is group task which contains next tasks:

recipe/typo3.php

@@ -1,18 +1,44 @@
 <?php
 
+/**
+ * TYPO3 Deployer Recipe
+ *
+ * Usage Examples:
+ *
+ * Deploy to production (using Git as source):
+ *     vendor/bin/dep deploy production
+ *
+ * Deploy to staging using rsync:
+ *     # In deploy.php or servers config, enable rsync
+ *     set('use_rsync', true);
+ *     vendor/bin/dep deploy staging
+ *
+ * Common TYPO3 commands:
+ *     vendor/bin/dep typo3:cache:flush       # Clear all TYPO3 caches
+ *     vendor/bin/dep typo3:cache:warmup      # Warmup system caches
+ *     vendor/bin/dep typo3:language:update   # Update extension language files
+ *     vendor/bin/dep typo3:extension:setup   # Set up all extensions
+ */
+
 namespace Deployer;
 
 require_once __DIR__ . '/common.php';
 require_once 'contrib/rsync.php';
 
 add('recipes', ['typo3']);
 
+/**
+ * Parse composer.json and return its contents as an array.
+ * Used for auto-detecting TYPO3 settings like public_dir and bin_dir.
+ */
 set('composer_config', function () {
     return json_decode(file_get_contents('./composer.json'), true, 512, JSON_THROW_ON_ERROR);
 });
 
 /**
- * DocumentRoot / WebRoot for the TYPO3 installation
+ * TYPO3 public (web) directory.
+ * Automatically determined from composer.json.
+ * Defaults to "public".
  */
 set('typo3/public_dir', function () {
     $composerConfig = get('composer_config');
@@ -25,7 +51,8 @@
 });
 
 /**
- * Path to TYPO3 cli
+ * Path to the TYPO3 CLI binary.
+ * Determined from composer.json "config.bin-dir" or defaults to "vendor/bin/typo3".
  */
 set('bin/typo3', function () {
     $composerConfig = get('composer_config');
@@ -43,7 +70,8 @@
 set('log_files', 'var/log/typo3_*.log');
 
 /**
- * Shared directories
+ * Directories that persist between releases.
+ * Shared via symlinks from the shared/ directory.
  */
 set('shared_dirs', [
     '{{typo3/public_dir}}/fileadmin',
@@ -56,7 +84,8 @@
 ]);
 
 /**
- * Shared files
+ * Files that persist between releases.
+ * By default: config/system/settings.php
  */
 if (!has('shared_files') || empty(get('shared_files'))) {
     set('shared_files', [
@@ -77,13 +106,14 @@
 ]);
 
 /**
- * Composer options
+ * Composer install options for production.
  */
 set('composer_options', ' --no-dev --verbose --prefer-dist --no-progress --no-interaction --optimize-autoloader');
 
 
 /**
- * If set in the config this recipe uses rsync. Default: false (use the Git repository)
+ * If set in the config this recipe uses rsync.
+ * Default setting: false (uses the Git repository)
  */
 set('use_rsync', false);
 
@@ -129,28 +159,45 @@
 ]);
 
 
+/**
+ * TYPO3 Commands
+ * All run via {{bin/php}} {{release_path}}/{{bin/typo3}} <command>
+ */
+
 desc('TYPO3 - Clear all caches');
 task('typo3:cache:flush', function () {
-    run('{{bin/php}} {{release_path}}/public/typo3 cache:flush ');
+    run('{{bin/php}} {{release_path}}/{{bin/typo3}} cache:flush');
 });
 
 desc('TYPO3 - Cache warmup for system caches');
 task('typo3:cache:warmup', function () {
-    run('{{bin/php}} {{release_path}}/public/typo3 cache:warmup --group system');
+    run('{{bin/php}} {{release_path}}/{{bin/typo3}} cache:warmup --group system');
 });
 
 desc('TYPO3 - Update the language files of all activated extensions');
 task('typo3:language:update', function () {
-    run('{{bin/php}} {{release_path}}/public/typo3 language:update');
+    run('{{bin/php}} {{release_path}}/{{bin/typo3}} language:update');
 });
 
 desc('TYPO3 - Set up all extensions');
 task('typo3:extension:setup', function () {
-    run('{{bin/php}} {{release_path}}/public/typo3 extension:setup');
+    run('{{bin/php}} {{release_path}}/{{bin/typo3}} extension:setup');
 });
 
 /**
- * Configure "deploy" task group.
+ * Main deploy task for TYPO3.
+ *
+ * 1. Lock deploy to avoid concurrent runs
+ * 2. Create release directory
+ * 3. Update code (Git or rsync)
+ * 4. Symlink shared dirs/files
+ * 5. Ensure writable dirs
+ * 6. Install vendors
+ * 7. Warm up TYPO3 caches
+ * 8. Run extension setup
+ * 9. Update language files
+ * 10. Flush caches
+ * 11. Unlock and clean up
  */
 desc('Deploys a TYPO3 project');
 task('deploy', [