Improve docs (#5)

* markdown linting * Drupal setup uses local settings * Remove commends for using `settings.ddev.php` * Standardize "WordPress" * Remove double space * Simplified language and use active voice * Update README.md Co-authored-by: Randy Fay <[email protected]> * Remove Drupal version number * Update README.md Co-authored-by: Randy Fay <[email protected]> * Remove rambling * Update README.md Co-authored-by: Randy Fay <[email protected]> * Update README.md Co-authored-by: Randy Fay <[email protected]> * Use PHP collector from addon folder * Revert "Drupal setup uses local settings" * Sync installation steps * Add demonstration link * Add description for detailed information * Helper command to launch website * Add note about config with timezone example --------- Co-authored-by: tyler36 <[email protected]> Co-authored-by: Randy Fay <[email protected]>
ddev · Nov 10, 2023 · 46d9893 · 46d9893
1 parent 462b767
commit 46d9893
Show file tree

Hide file tree

Showing 6 changed files with 120 additions and 37 deletions.
diff --git a/README.md b/README.md
@@ -6,21 +6,24 @@
 - [Warning](#warning)
 - [Getting started](#getting-started)
 - [Framework configuration](#framework-configuration)
- - [Drupal 8+](#drupal-8)
- - [Wordpress](#wordpress)
+ - [Drupal](#drupal)
+ - [WordPress](#wordpress)
  - [Silverstripe](#silverstripe)
 - [Usage](#usage)
+- [Configuration](#configuration)
 
 ## Introduction
 
-This addon is designed to add the XHGui service to a project served by DDEV.
+This addon adds the XHGui service to a project served by DDEV.
 
 [XhGui](https://github.com/perftools/xhgui) is a graphical interface for XHProf profiling data that can store the results in MongoDB or PDO database.
 
+See <https://performance.wikimedia.org/xhgui/> for an demonstration of XHGui data collection.
+
 ## Warning
 
-This addon is intended for debugging in a development environment.
-Profiling in a production environment is not recommend.
+This addon is for debugging in a development environment.
+Profiling in a production environment is not recommended.
 
 ## Getting started
 
@@ -31,61 +34,66 @@ Profiling in a production environment is not recommend.
  ddev restart
  ```
 
-- Install a profiler. If your application uses composer, you can install it with
-
- ```shell
- ddev composer require perftools/php-profiler --dev
- ```
-
 ## Framework configuration
 
-### Drupal 8+
+### Drupal
 
-The `xhgui/examples` contains files which can be used to quick-start a Drupal installation.
+- Install `perftools/php-profiler`
 
-- Copy the files from `xhgui/examples` to the sites's `web/sites/default` folder.
+ ```shell
+ ddev composer require perftools/php-profiler --dev
+ ```
 
 - Add the following line to `web/sites/default/settings.php` to include the collector.
 
  ```php
- require_once __DIR__ . '/xhgui.collector.php';
+ if (file_exists("/mnt/ddev_config/xhgui/collector/xhgui.collector.php")) {
+ require_once "/mnt/ddev_config/xhgui/collector/xhgui.collector.php";
+ }
  ```
 
-You can update `web/sites/default/settings.ddev.php` instead, however this file will be overwritten when DDEV restarts unless you remove `#ddev-generated` from the top of the file.
+- Run `ddev xhprof` to start profiling.
+ - XHGui is now available at `https://yourproject.ddev.site:8142`
 
-- Comment out the above line to disable profiling.
+### WordPress
 
-### Wordpress
+- Install `perftools/php-profiler`
+ - If using [bedrock](https://roots.io/bedrock/)
 
-Download latest version of `perftools/php-profiler` (this has been validated with the current latest release, 0.18.0).
-If you use [bedrock](https://roots.io/bedrock/), just use the composer command from the previous section.
+ ```shell
+ ddev composer require perftools/php-profiler --dev
+ ```
 
-If you use vanilla WordPress:
+ - If using vanilla WordPress:
 
  ```shell
  wget https://github.com/perftools/php-profiler/archive/refs/tags/0.18.0.tar.gz
  tar -xvf 0.18.0.tar.gz
  ```
 
-- Copy the two files in the `.ddev/xhgui/examples` folder (not the `php-profiler` you just downloaded) to your WordPress folder, and append to your `wp-config-ddev.php`:
+- Add the following line to `wp-config-ddev.php` to include the collector.
 
  ```php
  require_once __DIR__ . '/php-profiler-0.18.0/autoload.php';
- require_once __DIR__ . '/xhgui.collector.php';
+ if (file_exists("/mnt/ddev_config/xhgui/collector/xhgui.collector.php")) {
+ require_once "/mnt/ddev_config/xhgui/collector/xhgui.collector.php";
+ }
  ```
 
-- Comment out the above line to disable profiling.
+- Remove `#ddev-generated` from `wp-config-ddev.php` to prevent DDEV overriding it.
+- Run `ddev xhprof` to start profiling
+ - XHGui is now available at `https://yourproject.ddev.site:8142`
 
-If you want to stop profiling, you can just comment/remove those lines.
+### Silverstripe
 
-Take into account that with the default configuration, every time you `ddev start`, DDEV will recreate this file. You can remove the `#ddev-generated` at the top of the file if you want to avoid that.
+- Install `perftools/php-profiler`
 
-### Silverstripe
+ ```shell
+ ddev composer require perftools/php-profiler --dev
+ ```
 
-Add/install `perftools/php-profiler`, as per [getting started](#getting-started)
+- Add the following line to `public/index.php`, right after the autoload includes, to include the collector.
 
-- Copy the files from `.ddev/xhgui/examples` folder to your `public` folder (`cp .ddev/xhgui/examples/*.php public/`)
-- Add the requirement to your `public/index.php`, right after the autoload includes:
  ```php
  if (file_exists(__DIR__ . '/../vendor/autoload.php')) {
  require __DIR__ . '/../vendor/autoload.php';
@@ -96,19 +104,28 @@ Add/install `perftools/php-profiler`, as per [getting started](#getting-started)
  echo "autoload.php not found";
  exit(1);
  }
- if (file_exists(__DIR__ . '/xhgui.collector.php')) {
-  require_once __DIR__ . '/xhgui.collector.php';
+ if (file_exists("/mnt/ddev_config/xhgui/collector/xhgui.collector.php")) {
+ require_once "/mnt/ddev_config/xhgui/collector/xhgui.collector.php";
  }
  ```
+
 - Run `ddev xhprof` to start profiling
-- XHGui is now available at <https://>`yourproject.ddev.site`:8142
+ - XHGui is now available at `https://yourproject.ddev.site:8142`
 
- 
 ## Usage
 
 The service will automatically start when run: `ddev start` or `ddev restart`.
 
-By default, xhgui will be available at <https://>`<your site>`:8143.
+By default, xhgui will be available at `https://yourproject.ddev.site:8143`.
+Use the following command to launch the xhgui in your browser:
+
+```shell
+ddev xhgui
+```
+
+For detailed information about a single request, click on the "Method" keyword on the "Recent runs" dashboard.
+
+![Click GET method](./images/xhgui-get.png)
 
 Remember, if you updated `settings.ddev.php` or `wp-config-ddev.php`, these file will be overwritten unless you remove the `#ddev-generated`.
 
@@ -118,4 +135,18 @@ Use the following command to check the logs:
  ddev logs -s xhgui
  ```
 
+## Configuration
+
+To configure Xhgui, update `.ddev/xhgui/xhgui.config.php`.
+
+For example, to set xhgui to use `Asia/Toyko` timezone for dates:
+
+- Remove `#ddev-generated` from `.ddev/xhgui/xhgui.config.php`
+- Change the timezone value
+
+ ```php
+ 'timezone' => 'Asia/Tokyo',
+ 'date.format' => 'Y-m-d H:i:s',
+ ```
+
 **Contributed and maintained by [@tyler36](https://github.com/tyler36) based on the original [ddev-contrib PR](https://github.com/ddev/ddev-contrib/pull/128) by [@penyaskito](https://github.com/penyaskito)**
diff --git a/commands/host/xhgui b/commands/host/xhgui
@@ -0,0 +1,51 @@
+#!/bin/bash
+
+## #ddev-generated
+## Description: Launch a browser to XHGui
+## Usage: xhgui
+## Example: "xhgui"
+
+DDEV_XHGUI_PORT=8142
+DDEV_XHGUI_HTTPS_PORT=8143
+
+FULLURL=${DDEV_PRIMARY_URL}
+HTTPS=""
+if [ ${DDEV_PRIMARY_URL%://*} = "https" ]; then HTTPS=true; fi
+
+if [[ ! -z "${GITPOD_INSTANCE_ID}" ]] || [[ "${CODESPACES}" == "true" ]]; then
+ FULLURL="${FULLURL/-${DDEV_HOST_WEBSERVER_PORT}/-${DDEV_XHGUI_PORT}}"
+else
+ if [ "${HTTPS}" = "" ]; then
+ FULLURL="${FULLURL%:[0-9]*}:${DDEV_XHGUI_PORT}"
+ else
+ FULLURL="${FULLURL%:[0-9]*}:${DDEV_XHGUI_HTTPS_PORT}"
+ fi
+fi
+
+if [ -n "${1:-}" ]; then
+ if [[ ${1::1} != "/" ]]; then
+ FULLURL="${FULLURL}/"
+ fi
+
+ FULLURL="${FULLURL}${1}"
+fi
+
+if [ "${DDEV_DEBUG:-}" = "true" ]; then
+ printf "FULLURL $FULLURL\n" && exit 0
+fi
+
+case $OSTYPE in
+linux-gnu)
+ if [[ ! -z "${GITPOD_INSTANCE_ID}" ]]; then
+ gp preview ${FULLURL}
+ else
+ xdg-open ${FULLURL}
+ fi
+ ;;
+"darwin"*)
+ open ${FULLURL}
+ ;;
+"win*"* | "msys"*)
+ start ${FULLURL}
+ ;;
+esac
diff --git a/images/xhgui-get.png b/images/xhgui-get.png
diff --git a/install.yaml b/install.yaml
@@ -2,10 +2,11 @@ name: xhgui
 
 project_files:
 - docker-compose.xhgui.yaml
+- commands/host/xhgui
 - xhgui/Dockerfile
 - xhgui/xhgui.config.php
-- xhgui/examples/xhgui.collector.config.php
-- xhgui/examples/xhgui.collector.php
+- xhgui/collector/xhgui.collector.config.php
+- xhgui/collector/xhgui.collector.php
 - xhgui/nginx.conf
 - xhprof/xhprof_prepend.php
 - xhgui-mongo/mongo.init.d
diff --git a/xhgui/examples/xhgui.collector.config.php → xhgui/collector/xhgui.collector.config.php b/xhgui/examples/xhgui.collector.config.php → xhgui/collector/xhgui.collector.config.php
diff --git a/xhgui/examples/xhgui.collector.php → xhgui/collector/xhgui.collector.php b/xhgui/examples/xhgui.collector.php → xhgui/collector/xhgui.collector.php