renekreijveld/ddev-joomla

Watch

Fork 0

Table of contents

Site Management

jaddsite

Usage
Options
What it does
Joomla auto-install details (with -j)
Document root
Examples

jdelsite

Usage
Options
What it does
Example

jclone

Usage
Options
What it does
Examples

jsetconfig

Usage
Options
What it does
Examples

jphpswitch

Usage
Options
What it does
Examples

jxdb

Usage
Options
What it does
Example

Site Management

jaddsite

Create a new DDEV Joomla project.

Usage

jaddsite -n <sitename> [-p <php_version>] [-w <webserver>] [-j] [-a] [-v] [-s] [-h]

Options

Option	Description
`-n <sitename>`	The website name (no spaces). Required.
`-p <php_version>`	PHP version to use (default: `8.4`)
`-w <webserver>`	Webserver type: `nginx` or `apache` (default: from config)
`-j`	Download and install the latest Joomla automatically
`-a`	Add Adminer (MariaDB database management) to the project (optional)
`-v`	Verbose - show all DDEV output
`-s`	Silent - suppress all messages
`-h`	Display help

What it does

Creates the project folder ROOTFOLDER/<sitename>
Creates the document root subfolder inside it when DOCROOT is set in the config file. Without a DOCROOT value the project folder itself is the document root
Runs ddev config from the project folder with the specified PHP version and webserver, adding --docroot=<DOCROOT> when a document root subfolder is used
Creates .ddev/php/joomla.ini with display_errors = off and output_buffering = off
Starts the DDEV project
If Nginx is selected, depending on the ddev version it adds the Joomla API location block to nginx-site.conf:
```
location /api/ {
    try_files $uri $uri/ /api/index.php?$args;
}
```
If you use ddev version 1.25.2 or higher, joomla support is builtin into ddev, and a modification of nginx-site.conf is not needed.
If -a is specified, installs the Adminer add-on for database management and restarts DDEV
If -j is specified, downloads and installs Joomla into the document root with the CLI installer

Without -j a placeholder index.php is written to the document root, so the project answers with something instead of a directory listing.

Joomla auto-install details (with `-j`)

When -j is used, Joomla is installed with these defaults:

Setting	Value
Admin username	`admin`
Admin password	`AdminAdmin1!`
Admin email	`admin@example.com`
Site name	`Joomla`
Database host	`db`
Database name	`db`
Database user	`db`
Database password	`db`
Database prefix	Random 5-character lowercase string
SEF rewrite	Enabled
Session lifetime	120 minutes

For Apache, htaccess.txt is automatically copied to .htaccess.

Document root

jaddsite is the only script that reads the DOCROOT setting from the config file. With DOCROOT=public the layout of a new project mysite becomes:

ROOTFOLDER/mysite/          <- project folder, holds .ddev
ROOTFOLDER/mysite/public/   <- document root, holds the Joomla files

Leave DOCROOT empty and the project folder itself is the document root. See Configuration for the full story.

Examples

Create an empty site with default settings:

jaddsite -n mysite

Create a site with Joomla installed, using PHP 8.3 and Apache:

jaddsite -n mysite -p 8.3 -w apache -j

Create a site silently (e.g. from a script) and download and install Joomla:

jaddsite -n mysite -j -s

jdelsite

Permanently delete a DDEV Joomla project and all its files.

Usage

jdelsite -n <name> [-v] [-s] [-h]

Options

Option	Description
`-n <name>`	The name of the website to delete. Required.
`-v`	Verbose - show all DDEV and Docker output
`-s`	Silent - suppress all messages
`-h`	Display help

What it does

Shows a warning and asks for confirmation before proceeding
Stops the DDEV project (ddev stop)
Deletes the DDEV project without creating a database snapshot (ddev delete -O -y)
Prunes the Docker builder cache
Removes the site folder from disk

Warning: This action is irreversible. All files and the database will be permanently deleted. Make a backup first if needed.

Example

jdelsite -n mysite

jclone

Clone an existing DDEV Joomla project (including the database) to a new project name. Run from inside the source project's root folder.

Usage

jclone -n <new_name> [-v] [-s] [-h]

Options

Option	Description
`-n <new_name>`	The name for the cloned project (no spaces). Required.
`-v`	Verbose - show all DDEV output
`-s`	Silent - suppress all messages
`-h`	Display help

What it does

Reads the PHP version, webserver type and document root from the source project's .ddev/config.yaml
Prompts for confirmation before proceeding
Dumps the source database to a temporary file
Copies all source files to ROOTFOLDER/<new_name> (excluding .ddev)
Creates a fresh DDEV config for the clone using the same PHP version, webserver and document root
Starts the cloned DDEV project
Imports the database dump into the clone
Clears the Joomla cache and tmp folders

The new project is available at https://<new_name>.ddev.site.

The clone deliberately mirrors the layout of the source project rather than the DOCROOT config setting, so a source project with a public document root produces a clone with a public document root, and a source project without one produces a clone without one. You can run jclone from the project folder or from the document root.

Note: If the source site has its hostname hardcoded (in articles, custom modules, $live_site, etc.), those references will need to be updated manually.

Examples

Clone the current site to a new project named mysite-clone:

cd ~/Development/Sites/mysite
jclone -n mysite-clone

Clone with verbose output:

jclone -n mysite-test -v

jsetconfig

Configure the essential DDEV values in the configuration.php of the current Joomla site. Useful after restoring a backup or copying a production site into a DDEV project, when the database credentials and paths still point at the original server. Run it from the project folder or from the document root.

Usage

jsetconfig [-b] [-d] [-o] [-s] [-h]

Options

Option	Description
`-b`	Keep a backup of the original file as `configuration.php.bak`
`-d`	Prefix the value of `$sitename` with `[DEV] -` , so a development copy is recognisable in the browser
`-o`	Overwrite without the confirmation prompt
`-s`	Silent - suppress all messages
`-h`	Display help

What it does

Rewrites these values in configuration.php so they match the DDEV environment:

Variable	New value
`$db`	`'db'`
`$host`	`'db'`
`$user`	`'db'`
`$password`	`'db'`
`$log_path`	`__DIR__ . '/administrator/logs'`
`$tmp_path`	`__DIR__ . '/tmp'`
`$live_site`	`''` (empty, so Joomla determines the URL itself)

With -d, $sitename is also prefixed with [DEV] - . The prefix is added only once - a site name that already starts with it is left alone.

Before anything is written, the values that will change are listed and you are asked to confirm. Use -o to skip that prompt. Variables that are not present in the file are reported and skipped, so no invalid PHP is written. When none of the variables are found, nothing is changed.

Examples

Configure the current site for DDEV:

jsetconfig
About to overwrite the following values in configuration.php:
  public $db = 'db';
  public $host = 'db';
  public $user = 'db';
  public $password = 'db';
  public $log_path = __DIR__ . '/administrator/logs';
  public $tmp_path = __DIR__ . '/tmp';
  public $live_site = '';
Press Enter to continue, or Ctrl-C to abort.
Set public $db = 'db';
Set public $host = 'db';
Set public $user = 'db';
Set public $password = 'db';
Set public $log_path = __DIR__ . '/administrator/logs';
Set public $tmp_path = __DIR__ . '/tmp';
Set public $live_site = '';

configuration.php configured for DDEV.

Mark the site as a development copy, keep a backup and skip the prompt:

jsetconfig -d -b -o

jphpswitch

Switch the PHP version of an existing DDEV Joomla project. Run from the project folder or from the document root.

Usage

jphpswitch -p <php_version> [-v] [-s] [-h]

Options

Option	Description
`-p <php_version>`	The new PHP version (e.g. `8.2`, `8.3`, `8.4`). Required.
`-v`	Verbose - show all DDEV output
`-s`	Silent - suppress all messages
`-h`	Display help

What it does

Reads the current PHP version from .ddev/config.yaml
If the project is already on the requested version, exits without doing anything
Prompts for confirmation before proceeding
Updates the DDEV config with ddev config --php-version=<version>
Restarts the DDEV project with ddev restart

Examples

Switch to PHP 8.3:

cd ~/Development/Sites/mysite
jphpswitch -p 8.3

Switch to PHP 8.4 with verbose output:

jphpswitch -p 8.4 -v

jxdb

Displays the Xdebug status and enables or disables Xdebug. Run from the project folder or from the document root.

Usage

jxdb [on|off]

Options

Option	Description
`no parameter`	Shows current xdebug status
`on`	Enables xdebug
`off`	Disables xdebug

What it does

Wraps ddev xdebug:

Without a parameter it runs ddev xdebug status and shows whether Xdebug is currently on or off
on runs ddev xdebug enable
off runs ddev xdebug disable

Example

cd ~/Development/Sites/mysite
jxdb on

Site Management

jaddsite

Usage

Options

What it does

Joomla auto-install details (with -j)

Document root

Examples

jdelsite

Usage

Options

What it does

Example

jclone

Usage

Options

What it does

Examples

jsetconfig

Usage

Options

What it does

Examples

jphpswitch

Usage

Options

What it does

Examples

jxdb

Usage

Options

What it does

Example

ddev-joomla

Joomla auto-install details (with `-j`)