0.7.0 - cleanups, refactoring, legacy support and more

Two things this time. TYPO3 9 and 10 can be installed, for the extension that still runs on old code and needs to move forward. And every instance now comes with phpMyAdmin, so looking into the database is a link, not a detour.

typo3quickstarter --release=9

Highlights

--release=9 and --release=10 (#21)

You have an extension written for TYPO3 9. Before you can move it anywhere, you need a running 9 to see what it currently does. That's the whole point of this:

typo3quickstarter --release=9 --extension=/home/me/extensions/my-old-extension

Both lines run on PHP 7.4 — their typo3/cms-core requires ^7.2, so that's as new as it gets — and both are installed with the legacy typo3cms install:setup from TYPO3 Console, the same installer --release=11 has been using all along. Everything else works as it does everywhere else: --extension, --require, --require-dev, --with-git, --list, --cleanup.

Getting there took more than adding two numbers to a list, and all of it is handled for you:

• Composer 2.2+ refused to install TYPO3 9 at all. The 9.5 and 10.4 base distributions carry an allow-plugins list written before TYPO3 Console's Composer plugin had to be on it, and Composer doesn't skip a plugin that's missing from that list — it aborts the whole install. The entry is added before anything gets installed.
• TYPO3 9 wrote a broken site configuration. The --site-base-url option only exists from TYPO3 Console 6 (TYPO3 10) on; without it, TYPO3 9 derives the base from the current request, and on the CLI there isn't one — leaving base: ht/ behind, which no incoming request can ever match. The real URL is written into config/sites/*/config.yaml afterwards.
• 9 and 10 still have PackageStates.php. Anything added with --require or --extension only becomes active once that file is regenerated, so that happens before the extension setup.
• The extension kickstarter still needs TYPO3 12+. --with-git will still put the whole project under version control on 9, 10 and 11; the "scaffold a new extension" option is skipped with a note.

One thing to know going in: 9 and 10 are long past end of life, and PHP 7.4 is too. Your IDE and your tooling will say so. See docs/versions.md.

phpMyAdmin, in every instance (#20)

Done.
URL:         https://typo3-v13-101.ddev.site
Backend:     https://typo3-v13-101.ddev.site/typo3
Admin:       admin
Password:    _m3v8QbFD#8M9eTlqRcB
Credentials: /home/you/typo3-v13-101/typo3-credentials.txt
phpMyAdmin:  https://typo3-v13-101.ddev.site:8037 (or 'ddev phpmyadmin' inside the project)

DDEV's official add-on, installed for you. There is no login screen — the add-on hands phpMyAdmin the database credentials itself, so the link opens straight into the database. The URL is in the summary and in typo3-credentials.txt.

The detail that makes it worth automating: the add-on is installed between ddev config and the first ddev start, so the service comes up with everything else. Added to a project that's already running, it only takes effect after a ddev restart — exactly the step this saves you.

--no-pma leaves it out. And it can never cost you an instance: the add-on is fetched from GitHub, and if that fails the setup says so and carries on without it. See docs/phpmyadmin.md.

Fixed

• TYPO3 11 answered every request with a trusted-hosts error (#23). TYPO3 11 has no config/system/settings.php — its configuration still lives in public/typo3conf/LocalConfiguration.php — so the step that relaxes trustedHostsPattern found no file to edit and quietly did nothing. It's now written through TYPO3 Console for that version line.
• The debug settings now reach 9, 10 and 11 too. Same root cause as above: no settings.php to write into. BE/debug and FE/debug were already being switched on by the installer those versions use; the empty SYS/debugExceptionHandler is now set as well, so every version ends up in the same state.
• --extension with a path that doesn't exist aborted with realpath's own error message instead of the one written for it, because the check that the directory exists ran after realpath.

Under the hood

No change to what the script does, but a large diff if you're reading along: the shapes that had piled up in several copies are now helpers — die/step/warn/ok for messages, plus t3console, extension_setup, composer_package_name, register_local_package and a shared COMPOSER_ARGS for the install pipeline. --list and --cleanup share one preamble instead of two identical ones.

Thanks

• @thomasrawiel for reporting the TYPO3 11 trusted-hosts bug and fixing it (#25) — third release running.

Upgrading

typo3quickstarter update

Existing instances are unaffected; nothing here touches an instance that's already set up. To get phpMyAdmin into one you already have, run this inside its directory:

ddev add-on get ddev/ddev-phpmyadmin
ddev restart

Full changelog: CHANGELOG.md

0.6.0 More Features and TYPO3 15, before it exists

Highlights

--release=15: the development branch (#19)

TYPO3 15 is developed on main, and neither typo3/cms-core nor typo3/cms-base-distribution publish a 15.x branch — dev-main (branch alias 15.0.x-dev) is the only thing that resolves. --release=15 installs exactly that, on PHP 8.5, and says so up front:

==> TYPO3 15 has no release yet - installing the development branch (dev-main).
    Expect breakage, and expect two installs made on different days to differ.

Three things follow from that, and all three are handled for you:

• It's never the default. Leaving out --release still gives you the highest released version. You have to ask for 15 by name.
• It can't be pinned. --release=15.0.1 is rejected immediately — there's no such release — rather than failing several minutes later inside Composer.
• It actually resolves. The base distribution's main branch sets no minimum-stability, and still pins config.platform.php to 8.2.0 from the 14 line while the core it pulls in wants ^8.5. Left alone, Composer rejects its own packages. The script sets minimum-stability: dev plus prefer-stable: true and drops the stale platform override, so the install goes through.

See docs/versions.md.

It tells you when it's out of date

Every normal run now compares your version against the latest release and prints one green line under the banner:

typo3quickstarter v0.5.0 by Pagea Development
https://github.com/pagea-dev/typo3quickstarter · https://pagea.dev/

An update is available: 0.5.0 -> 0.6.0. Run 'typo3quickstarter update' to get the newest version.

A notice and nothing more — nothing is asked, nothing is installed, and the run continues either way. Offline, no curl, GitHub unreachable, or a copy inside a git checkout where git pull is the right answer: it stays quiet. The check gives up after 3 seconds so it can never hold up a setup, and TYPO3QUICKSTARTER_NO_UPDATE_CHECK=1 switches it off entirely.

--require-dev: dev dependencies (#18)

typo3quickstarter --release=13 --require-dev=ssch/typo3-rector a9f/typo3-fractor

For everything that belongs in a test instance but not in a real project's require — Rector, Fractor, PHPStan and friends. Same repeat/space-separated syntax as --require. See docs/composer-packages.md.

Changes

• Shorter instance names. Auto-generated names now end in three digits (typo3-v14-101) instead of four hex characters (typo3-v14-a1b2), so the suffix the cleanup hint prints is something you can read off and type back without picking letters out of a blob. The digits are checked before they're used — against the target directory and against DDEV, whose project names are global — so a name is never reused by an instance sitting in some other directory.
• The summary ends with what you need. It no longer runs ddev describe on the way out; that full-width table pushed the backend URL and the admin password off the screen. The summary now points at ddev describe for ports, database and Mailpit details instead of printing them unasked.

Fixed

• typo3quickstarter uninstall on a copy with no uninstaller next to it told you to delete the script and nothing else, quietly leaving the t3quickstarter alias behind as a symlink pointing at a file that no longer exists. It now names every symlink pointing back at the running copy, so the printed commands remove all of it.

Thanks

• @thomasrawiel for --require-dev (#18) — the second release in a row with your fingerprints on it, well done!

Upgrading

typo3quickstarter update

Existing instances are unaffected: nothing in this release touches an instance that's already set up.

Full changelog: CHANGELOG.md

0.5.0 — install it once, run it anywhere and step debugging

typo3quickstarter no longer has to sit in the folder you want to work in. Install it once and it's a command like any other, wherever you are.

curl -fsSL https://raw.githubusercontent.com/pagea-dev/typo3quickstarter/main/install.sh | bash

cd ~/projects/customer-x
typo3quickstarter --release=13

The instance still lands in the directory you're standing in — the tool moved, your workflow didn't.

Highlights

A system-wide command (#9)

install.sh puts typo3quickstarter — plus t3quickstarter as a short alias — into ~/.local/bin (--prefix=DIR for anywhere else). It works from a checkout as well as piped straight from curl, tells you which version it's installing and whether this is a fresh install, a reinstall or an update, and refuses to overwrite a same-named command it didn't put there.

Keeping it current and getting rid of it are commands of their own:

typo3quickstarter update      # checks the latest release, asks, then installs it
typo3quickstarter uninstall   # removes the command, its alias and the uninstaller

update only ever moves forward, leaves a copy inside a git checkout alone, and swaps the new version in by renaming rather than writing into the file it's currently running from.

Prefer no install at all? The single file still works exactly as before — grab typo3-ddev-setup.sh, chmod +x, run it. Same flags, portable, nothing left behind outside the instance folder.

--xdebug: step debugging from the first start (#16)

typo3quickstarter --release=13 --xdebug

Xdebug ships with DDEV but is off by default because it slows every request down. --xdebug enables it at ddev config time, so it's live from the very first ddev start — no ddev xdebug on and no restart afterwards. Point your IDE's PHP server at <project>.ddev.site and set a breakpoint; PHP_IDE_CONFIG already comes from DDEV. Off unless you ask for it, exactly like DDEV's own default. See docs/xdebug.md.

--env: your own environment variables (#16)

typo3quickstarter --release=13 --env=MY_API_TOKEN=abc123 TYPO3_CONTEXT=Development/DDEV

Set anything the web container should see, in place before TYPO3 is even installed — so the install itself sees it too. Same repeat/space-separated syntax as --require, and your value wins over the TYPO3_CONTEXT the script sets by default instead of ending up alongside it. See docs/environment-variables.md.

Fixed

• An unknown option or a stray argument aborted with C_RED: unbound variable instead of printing the actual error and the usage text.

Changed

• The closing summary prints absolute paths for the credentials file, the verbose log and the project directory — relative paths stopped being useful once the tool can be run from anywhere.
• Reworked README: installation leads with the system-wide command, everything else moved into a collapsible section, plus status badges and a support section.

Thanks

• @thomasrawiel for #16, which is where both --xdebug and --env come from.

Full changelog: CHANGELOG.md

0.4.1 Bugfix Release

Every install run aborted at ddev composer create-project with ".typo3-ddev-setup-marker is not allowed to be present": ddev composer create-project refuses to run unless the project directory is empty apart from a small whitelist, and 0.4.0 wrote that marker file to the project root beforehand. The marker now lives in .ddev/.typo3-ddev-setup-marker - a directory ddev skips over during that check - so it is still written before anything that can fail, and --list/--cleanup keep finding partway-failed runs. Instances created with 0.4.1 are still recognized at the old path (#8).

0.4.0 — Git-Ready Extensions, Smarter Defaults & Safer Cleanup

The headline feature: --with-git can now kickstart a brand-new TYPO3 extension via the official TYPO3 extension kickstarter and hand you back a working instance and a freshly versioned extension, from a single command. Alongside that, every instance is now pre-loaded for actually debugging things, cleanup got a lot smarter (and safer), and the whole script got a lot more pleasant to look at.

Added

• --with-git — after setup, asks whether to put the whole project under version control (with a sensible .gitignore on top of the base distribution's own), or run the TYPO3 extension kickstarter to scaffold a brand-new extension under packages/ and version that alone (TYPO3 12+). See docs/with-git.md.
• docs/examples.md — practical recipes for common scenarios (pinning a patch release, custom admin logins, extensions, cleanup, and more).
• --c all / --clear all / --cleanup all removes every instance found under --path in one go — skips the checklist and asks once to confirm removing all of them.
• Every instance now also gets typo3/cms-scheduler and typo3/cms-extensionmanager, runs under TYPO3_CONTEXT=Development, and has BE/debug, FE/debug on and SYS/debugExceptionHandler disabled. See docs/development-settings.md.
• Runs ddev describe right before opening the backend, alongside the existing summary.
• --cleanup/--clear/--c now refuses to silently delete an instance containing a .git directory anywhere inside it — a separate warning requires typing out yes in full (not just y) before it proceeds.
• A "Special thanks" section in the README for DDEV, Docker, TYPO3, and the TYPO3 Extension Kickstarter.

Fixed

• Requiring the new core extensions right after create-project --no-install could fail with "affected by security advisories" on a completely plain, unpinned --release, since Composer audits the whole dependency tree the moment it resolves it for the first time. --no-security-blocking is now used throughout instead of only for pinned installs.
• Composer-required extensions (--require/--extension) never got their database tables created or caches cleared, since nothing ran extension:setup after composer require. Now runs automatically after the TYPO3 install step.
• The backend's Database Analyzer permanently showed pending "CHANGE COLUMN" diffs for every table, since DDEV's database defaults to a different collation than TYPO3 expects. Now set correctly right after ddev start, before any tables exist.
• --list/--cleanup required typo3-credentials.txt to recognize an instance, written only once a run finishes successfully — a run that failed partway left an orphaned DDEV project neither command could find or remove. A marker file is now written right after ddev config, before anything that could still fail.

Full Changelog: 0.3.0...0.4.0

0.3.0 — Target, log, and clean up with confidence

Version 0.3.0 brings many more features to this tool. Let`s find out what changed:

Added

• docs/CONTRIBUTING.md with PR guidelines (branch from an up-to-date main, test the script for real, keep the executable bit, update docs/CHANGELOG for user-facing changes), linked from README.md.
• -v/--verbose writes the full console output to verbose.log in the project directory (chmod 600 + .gitignore, same as typo3-credentials.txt — it can contain the same passwords).
• Compatibility section in README.md: tested on Ubuntu-based Linux and WSL; macOS not yet supported.
• --clear and --c as aliases for --cleanup.
• --cleanup/--clear/--c now accept one or more name/ID substrings (e.g. --c 0392) to target specific instances directly, narrowing the checklist or skipping straight to the single-instance confirmation. Every "Done" summary now prints the ready-to-use command for the instance just created, e.g. To clean up this instance: ./typo3-ddev-setup.sh --c 0392.
• README "More examples" section: installing several Composer packages plus a custom admin login in one command, and pinning an exact TYPO3 patch release alongside a specific extension version.

Changed

• --cleanup now asks for confirmation before deleting anything, instead of deleting as soon as you press Enter in the checklist. With exactly one instance found, it skips the checklist and asks "Are you sure you want to remove it?" directly; with more than one, confirming the checklist selection shows "Are you sure you want to remove the following instances?" with the list before proceeding.

Fixed

• generate_password now guarantees at least one uppercase, lowercase, digit, and special character instead of drawing all 20 characters uniformly at random — the latter had roughly a 1-in-5 chance of producing a password with no special character, which TYPO3's default password policy rejects outright, failing the whole setup.
• --list/--cleanup showed a doubled "V" (e.g. "TYPO3 Vv13.4.34") for real instances, since composer.lock stores the version with a leading v (git-tag style) that wasn't stripped.

Removed

• --beuser/--bepass/--bemail (added in 0.2.0). Both this and --admin-user/--admin-password/--admin-email created an admin backend user, and no non-admin/editor role was ever planned, so the two overlapping flag sets were pure duplication. --admin-* remains as the one way to control the backend user's credentials.

Full Changelog: 0.2.0...0.3.0

0.2.0 — Pin, extend, and list your instances

0.2.0 is out and it brings some nice features

Added

• --release (-r) selects the TYPO3 version to install, now accepting a specific minor/patch release (e.g. 12.4.20) in addition to a bare major version. Renamed from --v, which collided with the new --version flag.
• --beuser/--bepass/--bemail create an additional admin backend user after setup, via TYPO3's backend:user:create (not available for --release=11, which fails fast with a clear error).
• --require installs extra Composer packages after setup; --extension mounts a local extension directory and requires it at :@dev for development. Both accept several values after one occurrence of the flag.
• --list lists all instances this script created (name, TYPO3 version, URL) — non-interactive, safe for scripts/CI. Shares instance detection with --cleanup.
• docs/ folder with per-topic documentation (TYPO3 versions, backend users, Composer packages/extensions, instance listing/cleanup, script versioning), split out of README.md.

Changed

• Pinning an exact minor/patch release installs it with Composer's --no-security-blocking, since older patch releases are commonly flagged by Composer's security-advisory check. The script now prints a warning when this applies.
• --cleanup now recognizes instances by the marker files this script always creates (.ddev/config.yaml, typo3-credentials.txt) instead of matching the folder name against the auto-generated naming pattern — instances started with a custom --name= are now found too.
• Randomly generated admin/backend-user passwords now come from a 20-character mix of upper/lowercase letters, digits, and #*%-_, instead of the previous fixed Ddev-<number>-Aa1 pattern.

Fixed

• Restored the script's executable bit (accidentally committed as non-executable by an external contribution).
• Removed duplicate extension-path validation and leftover dead debug code from the --extension implementation.
• Every instance now gets trustedHostsPattern set to .* in config/system/settings.php right after setup. Without it, requests could fail with a 500 "does not match the configured trusted hosts pattern" error, because DDEV's router terminates TLS and proxies to the web container over plain HTTP, so PHP sees HTTPS=on but SERVER_PORT=80 — a mismatch TYPO3's default 'SERVER_NAME' pattern rejects. DDEV normally papers over this by auto-generating its own override, but only during a plain composer create-project — the pinned-version install path (--release=X.Y.Z) bypasses that, so it was hit every time.

Full Changelog: main...0.2.0

Thanks

Thanks to @thomasrawiel for contributing to this tool