Initial commit

Author: barryvdh

.github/workflows/build-docs.yml

@@ -0,0 +1,29 @@
+name: Build docs
+on:
+  workflow_dispatch:
+  push:
+    branches:
+      - main
+permissions:
+  contents: write
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Configure Git Credentials
+        run: |
+          git config user.name github-actions[bot]
+          git config user.email 41898282+github-actions[bot]@users.noreply.github.com
+      - uses: actions/setup-python@v5
+        with:
+          python-version: 3.x
+      - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
+      - uses: actions/cache@v4
+        with:
+          key: mkdocs-material-${{ env.cache_id }}
+          path: .cache
+          restore-keys: |
+            mkdocs-material-
+      - run: pip install mkdocs-material
+      - run: mkdocs gh-deploy --force

.gitignore

@@ -0,0 +1,3 @@
+/site
+.DS_Store
+/docs/overrides/__pycache__/

docs/CNAME

@@ -0,0 +1 @@
+php-debugbar.com

docs/ajax_and_stack.md

@@ -0,0 +1,85 @@
+# AJAX and Stacked data
+
+## AJAX
+
+As mentioned in the previous chapter, if you are performing AJAX requests
+which return HTML content, you can use `JavascriptRenderer::render(false)`.
+
+In the case you are sending back non-HTML data (eg: JSON), the DebugBar can
+send data to the client using HTTP headers using the `sendDataInHeaders()` method
+(no need to use the `JavascriptRenderer`):
+
+    $debugbar = new DebugBar();
+    // ...
+    $debugbar->sendDataInHeaders();
+
+On the client side, an instance of `PhpDebugBar.AjaxHandler` will
+parse the headers and add the dataset to the debugbar.
+
+The AjaxHandler automatically binds to jQuery's *ajaxComplete* event
+so if you are using jQuery, you have nothing to configure.
+
+If you're not using jQuery, you can call `AjaxHandler.handle(xhr)`.
+If you are using the `JavascriptRenderer` initialization, the instance
+of `AjaxHandler` is stored in the `ajaxHandler` property of the `DebugBar` object.
+
+    debugbar.ajaxHandler.handle(xhr);
+
+If you are sending a lot of data through headers, it may cause problems
+with your browser. Instead you can use a storage handler (see Storage chapter)
+and the open handler (see Open Handler chapter) to load the data after an ajax
+request. Use true as the first argument of `sendDataInHeaders()`.
+
+    $debugbar = new DebugBar();
+
+    // define a storage
+    $debugbar->setStorage(new DebugBar\Storage\FileStorage('/path/to/storage'));
+
+    // define the open handler url
+    $renderer = $debugbar->getJavascriptRenderer();
+    $renderer->setOpenHandlerUrl('open.php');
+
+    // ...
+
+    $debugbar->sendDataInHeaders(true);
+
+By default, the debug bar will immediately show new AJAX requests. If your page
+makes a lot of requests in the background (e.g. tracking), this can be
+disruptive. You can disable this behavior by calling
+`setAjaxHandlerAutoShow(false)` on the `JavascriptRenderer`, like this:
+
+    $renderer = $debugbar->getJavascriptRenderer();
+    $renderer->setAjaxHandlerAutoShow(false);
+
+## Fetch
+
+Fetch API is supported by wrapping `window.fetch` so that the promise is also
+passed through to the debugbar AJAX handler.
+
+If you find your fetch requests are not showing up in debugbar, you're probably
+initializing your JavaScript client library (e.g. Apollo) before debugbar has
+loaded, try adding `defer` onto your script tags, or moving them after the
+injected debugbar JavaScript.
+
+## Stacked data
+
+Some times you need to collect data about a request but the page won't actually
+be displayed. The best example of that is during a redirect. You can use the
+debug bar storage mechanism to store the data and re-open it later but it can
+be cumbersome while testing a redirect page.
+
+The solution is to use stacked data. The debug bar can temporarily store the
+collected data in the session until the next time it will be displayed.
+Simply call `DebugBar::stackData()` instead of rendering the debug bar.
+
+PHP's session must be started before using this feature.
+
+Note: The stacked data feature will use the storage mechanism if it's enabled
+instead of storing the data in the session.
+
+    $debugbar = new DebugBar();
+    // ...
+    $debugbar->stackData();
+
+Stacked data are rendered each time the debug bar is rendered using the
+`JavascriptRenderer`.