feat: batch delivery off the request path and release automatically

.docker/php/Dockerfile

@@ -1,11 +1,11 @@
 FROM php:8.1-cli-alpine AS php-base
 
 # Install composer
-ENV COMPOSER_ALLOW_SUPERUSER 1
-ENV COMPOSER_HOME /var/www/.composer
+ENV COMPOSER_ALLOW_SUPERUSER=1
+ENV COMPOSER_HOME=/var/www/.composer
 
 COPY --from=composer:latest /usr/bin/composer /usr/bin/composer
 
 RUN apk add --update --no-cache --virtual .build-deps linux-headers $PHPIZE_DEPS && \
     pecl install xdebug && docker-php-ext-enable xdebug && \
-    apk del .build-deps \
+    apk del .build-deps

.gitattributes

@@ -4,12 +4,14 @@
 /.gitignore export-ignore
 /compose.yaml export-ignore
 /README.md export-ignore
-/phpunit.xml.dist export-ignore
+/phpunit.xml export-ignore
 /tests export-ignore
 /QUICKSTART.md export-ignore
 /phpstan.neon export-ignore
 /Makefile export-ignore
 /phpcs.xml export-ignore
 /CHANGELOG.md export-ignore
 /examples.php export-ignore
-/qodana.yaml export-ignore
+/qodana.yaml export-ignore
+/scripts export-ignore
+/check-deployed-package export-ignore

.github/workflows/check-deployed-package.yml

@@ -1,31 +1,28 @@
 name: Check deployed package
 
+# Installs logdash/php-sdk from Packagist and checks that its logs and metrics reach Logdash, see check-deployed-package.
+# CI runs it after each release; run it by hand on any branch to check a version, by default the latest.
 on:
+  workflow_call:
+    inputs:
+      version:
+        type: string
+        required: true
   workflow_dispatch:
-  workflow_run:
-    workflows: ["Publish Package to packagist"]
-    types:
-      - completed
-    branches:
-      - main
+    inputs:
+      version:
+        description: The version to check, such as 1.1.0; empty checks the latest
+        required: false
 
 jobs:
   check-deployed-package:
-    name: Check deployed package
     runs-on: ubuntu-latest
-    if: ${{ github.event.workflow_run.conclusion == 'success' }}
-
     steps:
-      - name: Checkout repository
-        uses: actions/checkout@v4
-
-      - name: Wait for package to propagate to Packagist
-        run: sleep 120
-
-      - name: Make run script executable
-        run: chmod +x check-deployed-package/run.sh
-
-      - name: Check deployed package
+      - uses: actions/checkout@v7
+      - run: ./check-deployed-package/run.sh
         env:
+          VERSION: ${{ inputs.version }}
+          # Sends the logs and metrics: the ingest key of the SDK smoke tests domain
           LOGDASH_API_KEY: ${{ secrets.LOGDASH_API_KEY }}
-        run: ./check-deployed-package/run.sh
+          # Reads them back: an ldp_ key with logs:read and metrics:read, restricted to that domain
+          LOGDASH_PERSONAL_API_KEY: ${{ secrets.LOGDASH_PERSONAL_API_KEY }}

.github/workflows/ci.yml

@@ -0,0 +1,88 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  # A release in progress must finish; a newer merge waits and releases after it.
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        # The oldest PHP that composer.json allows, and the newest
+        php-version: ["8.1", "8.5"]
+    steps:
+      - uses: actions/checkout@v7
+      - uses: shivammathur/setup-php@v2
+        with:
+          php-version: ${{ matrix.php-version }}
+          coverage: none
+      - run: composer validate --strict
+      - run: composer install --prefer-dist --no-progress
+      - run: composer run-script phpstan
+      - run: composer run-script cs
+      - run: composer run-script test
+      - uses: actions/setup-node@v7
+        with:
+          node-version: 24
+      - run: node --test 'scripts/*.test.ts'
+
+  # The version the merged commits call for; empty when none of them is a feat, fix, perf, or breaking change.
+  version:
+    if: github.event_name == 'push'
+    runs-on: ubuntu-latest
+    outputs:
+      next: ${{ steps.next.outputs.version }}
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0 # the tags and commits since the last release
+      - uses: actions/setup-node@v7
+        with:
+          node-version: 24
+      # On its own line, so that version.ts failing fails the job instead of releasing nothing
+      - id: next
+        run: |
+          version=$(node scripts/version.ts)
+          echo "version=$version" >> "$GITHUB_OUTPUT"
+
+  # Tags the merge v<version>, the tag Packagist publishes as that version.
+  release:
+    needs: [test, version]
+    if: needs.version.outputs.next != ''
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    env:
+      V: ${{ needs.version.outputs.next }}
+    steps:
+      # Skipped when a rerun after a failed step below finds the release already made
+      - run: gh release view "v$V" >/dev/null 2>&1 || gh release create "v$V" --generate-notes --target "$GITHUB_SHA"
+        env:
+          GH_TOKEN: ${{ github.token }}
+          GH_REPO: ${{ github.repository }}
+      - name: Ask Packagist to read the new tag now
+        run: |
+          curl -sS --fail-with-body --retry 3 -X POST -H 'Content-Type: application/json' \
+            -d '{"repository":{"url":"https://github.com/logdash-io/php-sdk"}}' \
+            "https://packagist.org/api/update-package?username=$PACKAGIST_USERNAME&apiToken=$PACKAGIST_TOKEN"
+        env:
+          PACKAGIST_USERNAME: ${{ secrets.PACKAGIST_USERNAME }}
+          PACKAGIST_TOKEN: ${{ secrets.PACKAGIST_TOKEN }}
+
+  # Installs the version just released from Packagist and checks that its logs and metrics reach Logdash.
+  check-deployed-package:
+    needs: [version, release]
+    uses: ./.github/workflows/check-deployed-package.yml
+    with:
+      version: ${{ needs.version.outputs.next }}
+    secrets: inherit

.github/workflows/pr-title.yml

@@ -0,0 +1,20 @@
+name: PR title
+
+# Squash merges use the PR title as the commit subject, and scripts/version.ts reads it to pick the next version.
+on:
+  pull_request:
+    types: [opened, edited, reopened, synchronize]
+
+permissions: {}
+
+jobs:
+  conventional:
+    runs-on: ubuntu-latest
+    steps:
+      - env:
+          TITLE: ${{ github.event.pull_request.title }}
+        run: |
+          printf '%s' "$TITLE" | grep -qE '^(feat|fix|perf|refactor|docs|test|build|ci|chore|style|revert)(\(.+\))?!?: .+' || {
+            echo "::error::PR title \"$TITLE\" is not a Conventional Commit, e.g. \"feat(logger): log exceptions with their trace\" or \"fix(metrics): send a mutate once\". feat releases a minor, fix/perf a patch, ! a major; other types do not release."
+            exit 1
+          }

QUICKSTART.md

@@ -129,12 +129,6 @@ Run the examples:
 php examples.php
 ```
 
-Run the test script:
-
-```bash
-php test.php
-```
-
 ## Next Steps
 
 1. Explore the [examples.php](examples.php) file for more usage patterns

README.md

@@ -3,7 +3,7 @@
 [![Packagist Version](https://img.shields.io/packagist/v/logdash/php-sdk)](https://packagist.org/packages/logdash/php-sdk)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![PHP Version](https://img.shields.io/badge/PHP-8.1+-blue.svg)](https://php.net)
-[![Tests](https://github.com/logdash-io/php-sdk/workflows/Tests/badge.svg)](https://github.com/logdash-io/php-sdk/actions)
+[![CI](https://github.com/logdash-io/php-sdk/actions/workflows/ci.yml/badge.svg)](https://github.com/logdash-io/php-sdk/actions/workflows/ci.yml)
 
 > **Official PHP SDK for [Logdash.io](https://logdash.io/) - Zero-configuration observability platform designed for developers working on side projects and prototypes.**
 
@@ -161,6 +161,20 @@ Creates a new Logdash instance.
 - `host` (string, optional): Logdash API host. Defaults to `https://api.logdash.io`
 - `verbose` (bool, optional): Enable verbose internal logging. Defaults to `false`
 - `app` (string, optional): Name of this app within its domain, sent with every log, metric and event. See [Apps](#apps)
+- `httpClient` (`GuzzleHttp\ClientInterface`, optional): Client that sends the requests to the API, such as one with a proxy. Defaults to a client with a 5 second timeout
+
+#### `flush(): void`
+
+Sends the logs, metrics and events buffered so far, and waits for the API.
+
+Logdash buffers them and sends them together, so that a log costs no HTTP request of its own.
+It sends them when 100 are buffered, when the logs near the API's 2 MB request limit, when one comes a second or more after the last send, and when the PHP request or script ends.
+Call `flush()` where the process lives on, such as in a queue worker after each job:
+
+```php
+$logdash->logger()->info('Job done');
+$logdash->flush();
+```
 
 ### Logger
 

check-deployed-package/Dockerfile

@@ -1,32 +1,11 @@
-FROM php:8.3-cli
+# logdash/php-sdk as Packagist serves it, VERSION or else the latest, never this checkout
+FROM composer:2
 
 WORKDIR /app
 
-# Install system dependencies needed for PHP extensions and Composer
-RUN apt-get update && apt-get install -y \
-  git \
-  unzip \
-  zip \
-  libzip-dev \
-  pkg-config \
-  && docker-php-ext-install zip \
-  && rm -rf /var/lib/apt/lists/*
+ARG VERSION=
+RUN composer require --no-interaction --no-progress "logdash/php-sdk${VERSION:+:$VERSION}"
 
-# Install Composer
-COPY --from=composer:latest /usr/bin/composer /usr/bin/composer
+COPY check.php .
 
-# Copy the source files (they should be available in the build context)
-COPY src /app/logdash-php-sdk/src
-COPY composer.json /app/logdash-php-sdk/composer.json
-
-# Copy test files
-COPY check-deployed-package/check.php /app/
-
-# Create a simple composer.json that uses the local version and its dependencies
-RUN echo '{"require": {"php": ">=8.1", "guzzlehttp/guzzle": "^7.0"}, "autoload": {"psr-4": {"Logdash\\\\": "logdash-php-sdk/src/"}}}' > composer.json
-
-# Install dependencies and generate autoloader
-RUN composer install --no-dev --optimize-autoloader
-
-# Run the application
 CMD ["php", "check.php"]

check-deployed-package/README.md

@@ -1,7 +1,12 @@
-# Logdash PHP SDK Demo
+# Check the deployed package
 
-Use command below to test if the published SDK works:
+`run.sh` installs `logdash/php-sdk` from Packagist in Docker, sends a log of each level and a metric with it, and reads them back from Logdash.
+CI runs it after each release, against the version it released.
 
+```sh
+LOGDASH_API_KEY=<api-key> LOGDASH_PERSONAL_API_KEY=<personal-api-key> VERSION=1.1.0 ./check-deployed-package/run.sh
 ```
-LOGDASH_API_KEY=<your-api-key> ./check-deployed-package/run.sh
-```
+
+- `LOGDASH_API_KEY` sends: the ingest key of the shared "SDK smoke tests" domain, from its Settings page. The check sends as the app `php-sdk`.
+- `LOGDASH_PERSONAL_API_KEY` reads back: an `ldp_` personal API key with `logs:read` and `metrics:read`, restricted to that one domain.
+- `VERSION` picks the version, by default the latest. The check waits until Packagist serves it.