Skip to content

Update TYPO3 recipe and improve docs #4105

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
antonmedv merged 2 commits into from
Sep 17, 2025
+121 −35
Merged

Update TYPO3 recipe and improve docs #4105

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
92ffdc1
refactor: optimize bin/typo3 path usage
david-bonhagen Aug 13, 2025
7b345a4
docs: improve documentation of TYPO3 recipe
david-bonhagen Aug 13, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
87 changes: 63 additions & 24 deletions docs/recipe/typo3.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
:::
Expand All @@ -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.
:::
Expand All @@ -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`

Expand All @@ -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"
[
Expand All @@ -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`.

Expand All @@ -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)



Expand All @@ -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)



Expand All @@ -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:
Expand Down
69 changes: 58 additions & 11 deletions recipe/typo3.php
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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');
Expand All @@ -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');
Expand All @@ -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',
Expand All @@ -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', [
Expand All @@ -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);

Expand Down Expand Up @@ -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', [
Expand Down