add installation page

Author: carlos-granados

docs/getting-started/docker.md

@@ -0,0 +1,13 @@
+---
+title: Docker
+---
+
+Run PHP Debugger in a container using an image with the debugger already compiled
+into the interpreter, with nothing to install.
+
+:::note
+This page is a work in progress — full documentation is coming soon.
+:::
+
+In the meantime, the [installer](./installation.mdx) covers installing directly
+onto your machine.

docs/getting-started/install-options.md

@@ -0,0 +1,12 @@
+---
+title: More install options
+---
+
+Ways to install PHP Debugger beyond the installer — prebuilt binaries, package
+managers, and building from source.
+
+:::note
+This page is a work in progress — full documentation is coming soon.
+:::
+
+For the recommended route, see [Installation](./installation.mdx).

docs/getting-started/installation.md

@@ -0,0 +1,106 @@
+---
+title: Installation
+---
+
+import InstallCommand from '@site/src/components/InstallCommand';
+
+The quickest way to get PHP Debugger onto your machine is the installer, a small
+command-line tool that fetches the right build for your system and puts it in
+place. Installing it is a single command.
+
+## 1. Get the installer
+
+<InstallCommand />
+
+The script downloads the latest release and drops the `php-debugger` binary into
+the current directory. Set `INSTALL_DIR` if you would rather it landed somewhere
+else.
+
+:::tip[Prefer Docker?]
+
+Use a container image instead — see [Docker](./docker.md).
+
+:::
+
+## 2. Install the debugger
+
+The installer offers two ways to get a working debugger. Run it with no arguments
+for the default:
+
+```bash
+php-debugger install
+```
+
+That installs a **self-contained PHP interpreter** with the debugger compiled
+straight into it, and makes it the active `php` on your PATH. Nothing else on your
+system needs to change.
+
+If you would rather keep the PHP you already have, install **only the extension**
+into it:
+
+```bash
+php-debugger install --extension-only
+```
+
+The two are mutually exclusive, and the installer knows it: installing the
+interpreter removes any extension you had installed, so you never end up running
+both at once.
+
+A few flags are worth knowing:
+
+| Flag | What it does |
+| --- | --- |
+| `-u, --user` | Install into a per-user directory, so no `sudo` is needed. The default is system-wide. |
+| `-p, --php <x.y>` | Pick the PHP version to install. Defaults to the latest, and applies to the interpreter only. |
+| `-e, --extension-only` | Install just the extension into your current PHP. |
+| `-z, --zts` | Install a thread-safe build instead of the default non-thread-safe one. |
+| `-y, --yes` | Answer yes to every prompt, for unattended or CI use. |
+
+If the directory it installs into is not on your `PATH`, the installer prints the
+exact line you need to add.
+
+## Changing your mind
+
+Nothing here is a one-way door. Whether you installed the interpreter or just the
+extension, whatever it replaced is backed up first — the PHP you already had, or
+the ini configuration it changed. To put things back as they were:
+
+```bash
+php-debugger uninstall
+```
+
+That removes whatever was installed and restores your previous setup from the
+backup — the interpreter it replaced, or the ini configuration it changed. You do
+not have to tell it which kind you installed; it works that out for itself.
+
+The installer also tries hard not to leave you with a broken `php` in the first
+place. It runs the downloaded interpreter before changing anything, so a build
+that cannot run on your system is never installed. After activating it, it checks
+that `php` still runs and reports the debugger module, and rolls everything back to
+the previous working state if either check fails.
+
+## Staying up to date
+
+To move to the latest release:
+
+```bash
+php-debugger update
+```
+
+It takes no arguments. Whether you installed the interpreter or just the
+extension, it detects what is there and reinstalls the same thing against the
+latest version.
+
+:::info[Prefer to install some other way?]
+
+See [More install options](./install-options.md).
+
+:::
+
+## Next steps
+
+With the debugger installed, point your editor at it and set your first
+breakpoint:
+
+- [Quick Start](./quick-start.md)
+- [Configuration](./configuration.md)

docs/getting-started/installation.mdx

@@ -15,5 +15,5 @@ because when you are not using it you can barely tell it is there.
 
 Ready to get started? Install PHP Debugger and try the quick start guide:
 
-- [Installation Guide](./installation.md)
+- [Installation Guide](./installation.mdx)
 - [Quick Start](./quick-start.md)

docs/getting-started/introduction.mdx

@@ -2,7 +2,7 @@
 title: Quick Start
 ---
 
-Get up and running with PHP Debugger in a few minutes. This guide assumes you have already [installed](./installation.md) the extension.
+Get up and running with PHP Debugger in a few minutes. This guide assumes you have already [installed](./installation.mdx) the extension.
 
 ## 1. Enable the debugger
 

docs/getting-started/quick-start.md

@@ -125,7 +125,7 @@ const config = {
       prism: {
         theme: prismThemes.github,
         darkTheme: prismThemes.dracula,
-        additionalLanguages: ['php', 'ini', 'bash'],
+        additionalLanguages: ['php', 'ini', 'bash', 'powershell'],
       },
     }),
 };

docusaurus.config.js

@@ -12,6 +12,8 @@ const sidebars = {
       items: [
         'getting-started/introduction',
         'getting-started/installation',
+        'getting-started/docker',
+        'getting-started/install-options',
         'getting-started/quick-start',
         'getting-started/configuration',
       ],

sidebars.js

@@ -0,0 +1,69 @@
+import {useEffect, useState} from 'react';
+import clsx from 'clsx';
+import CodeBlock from '@theme/CodeBlock';
+import styles from './styles.module.css';
+
+/* macOS and Linux run the same script -- it detects the OS and architecture
+   itself -- so both tabs deliberately show the same command. */
+const UNIX_COMMAND =
+  'curl -fsSL https://github.com/php-debugger/installer/releases/latest/download/install.sh | sh';
+const WINDOWS_COMMAND =
+  'powershell -c "irm https://github.com/php-debugger/installer/releases/latest/download/install.ps1 | iex"';
+
+const PLATFORMS = [
+  {id: 'macos', label: 'macOS', language: 'bash', command: UNIX_COMMAND},
+  {id: 'linux', label: 'Linux', language: 'bash', command: UNIX_COMMAND},
+  {id: 'windows', label: 'Windows', language: 'powershell', command: WINDOWS_COMMAND},
+];
+
+function detectPlatform() {
+  const ua = navigator.userAgent;
+  if (/Windows/i.test(ua)) {
+    return 'windows';
+  }
+  if (/Mac OS X|Macintosh/i.test(ua)) {
+    return 'macos';
+  }
+  /* Android reports Linux too, and the command is the same either way. */
+  if (/Linux|Android|X11/i.test(ua)) {
+    return 'linux';
+  }
+  return null;
+}
+
+export default function InstallCommand() {
+  /* The page is prerendered without knowing the visitor's OS, so start on macOS
+     and correct it after mounting. Detecting in an effect rather than during
+     render keeps the first client render identical to the server's, which is
+     what hydration compares. A visitor who picks a tab keeps their choice --
+     the effect only runs on mount. */
+  const [platform, setPlatform] = useState('macos');
+
+  useEffect(() => {
+    const detected = detectPlatform();
+    if (detected) {
+      setPlatform(detected);
+    }
+  }, []);
+
+  const active = PLATFORMS.find((p) => p.id === platform) ?? PLATFORMS[0];
+
+  return (
+    <div className={styles.wrapper}>
+      <div className={styles.tabs} role="tablist" aria-label="Operating system">
+        {PLATFORMS.map((p) => (
+          <button
+            key={p.id}
+            type="button"
+            role="tab"
+            aria-selected={p.id === active.id}
+            className={clsx(styles.tab, p.id === active.id && styles.tabActive)}
+            onClick={() => setPlatform(p.id)}>
+            {p.label}
+          </button>
+        ))}
+      </div>
+      <CodeBlock language={active.language}>{active.command}</CodeBlock>
+    </div>
+  );
+}

src/components/InstallCommand/index.js

@@ -0,0 +1,32 @@
+.wrapper {
+  margin-bottom: 1.5rem;
+}
+
+.tabs {
+  display: flex;
+  gap: 0.25rem;
+  margin-bottom: 0.5rem;
+}
+
+.tab {
+  border: 1px solid var(--phpdbg-card-border);
+  background: transparent;
+  color: var(--ifm-color-emphasis-700);
+  border-radius: 0.5rem;
+  padding: 0.35rem 0.9rem;
+  font-size: 0.85rem;
+  font-weight: 600;
+  cursor: pointer;
+}
+
+.tab:hover {
+  border-color: var(--ifm-color-primary);
+  color: var(--ifm-color-primary);
+}
+
+.tabActive,
+.tabActive:hover {
+  border-color: var(--ifm-color-primary);
+  background: var(--ifm-color-primary);
+  color: #fff;
+}