petstore

Description

A simple skeleton to build api's based on the chubbyphp-framework.

Requirements

• php: ^8.3
• chubbyphp/chubbyphp-api: ^1.2
• chubbyphp/chubbyphp-clean-directories: ^1.5.2
• chubbyphp/chubbyphp-cors: ^1.7.2
• chubbyphp/chubbyphp-decode-encode: ^1.4.1
• chubbyphp/chubbyphp-framework: ^6.0.3
• chubbyphp/chubbyphp-framework-router-fastroute: ^2.3.4
• chubbyphp/chubbyphp-http-exception: ^1.3.3
• chubbyphp/chubbyphp-laminas-config: ^1.5.2
• chubbyphp/chubbyphp-laminas-config-doctrine: ^3.1.3
• chubbyphp/chubbyphp-laminas-config-factory: ^1.5.2
• chubbyphp/chubbyphp-negotiation: ^2.3.2
• chubbyphp/chubbyphp-oidc: ^1.0
• chubbyphp/chubbyphp-parsing: ^3.0
• doctrine/orm: ^3.6.8
• guzzlehttp/guzzle: ^7.10
• monolog/monolog: ^3.10
• ramsey/uuid: ^4.9.3
• slim/psr7: ^1.8
• symfony/console: ^7.4.16|^8.1.4
• symfony/var-exporter: ^7.4.16|^8.1.4

Environment

Add the following environment variable to your system, for example within ~/.bashrc or ~/.zshrc:

export USER_ID=$(id -u)
export GROUP_ID=$(id -g)

Mount points

Creates every file which gets mounted into the php container (shell rc/history, git, ssh, npm and the coding agent auth/settings files) without overwriting existing ones. Adjust the seeded settings files afterwards to your liking, they stay on the host and get mounted.

./setup-mount-points.sh

Coding agents

The following coding agents (harnesses) are preinstalled within the php container, their auth and settings files get mounted from the host (see docker-compose.yml):

• Claude Code: ~/.claude.json, ~/.claude/.credentials.json, ~/.claude/settings.json
• Codex: ~/.codex/auth.json, ~/.codex/config.toml
• Opencode: ~/.config/opencode/opencode.jsonc, ~/.config/opencode/tui.json, ~/.local/share/opencode/auth.json
• PI incl. pi-llama: ~/.pi/agent/auth.json

llama.cpp

PI can run against a local model via pi-llama, start a llama.cpp server on the host, for example:

llama-server \
    -hf lmstudio-community/Qwen3.6-35B-A3B-GGUF:Q4_K_M \
    -c 32768 \
    -ngl 999 \
    --flash-attn on \
    --host 0.0.0.0 \
    --port 9931

Docker

docker compose up -d
docker compose exec php bash

Setup

composer install
composer setup:dev

Urls

• GET https://localhost/ping
• GET https://localhost/swagger (https://localhost/openapi)

Pet (oidc protected)

• GET https://localhost/api/pets?sort[name]=asc
• POST https://localhost/api/pets
• GET https://localhost/api/pets/019c201f-6a83-7696-9899-50fbf7b2278d
• PUT https://localhost/api/pets/019c201f-6a83-7696-9899-50fbf7b2278d
• DELETE https://localhost/api/pets/019c201f-6a83-7696-9899-50fbf7b2278d

Database

psql "postgresql://petstore:4aAUfBjDACcdZxNwJgJ6@localhost:5432/petstore"

Oidc (keycloak)

All routes below /api are protected by chubbyphp/chubbyphp-oidc, only /ping and /openapi are public. The keycloak container acts as the identity provider, the realm petstore gets imported from docker/development/keycloak/import/petstore-realm.json on startup (delete and recreate the keycloak container to reimport after changes) and contains two users:

• john.doe (password: johndoe1234): a regular end user, meant to log in via the browser based frontend (petstore-frontend client, see below).
• petstore (password: GBanBPatEBRZ7hf7cAxKn8Ptt): a technical user for requesting tokens via password grant while testing (see the curl example below).

and two clients:

• petstore-frontend: public client for a separate (browser based) frontend codebase, which authenticates against keycloak via authorization code flow + PKCE (S256) and sends the resulting access token as Authorization: Bearer <token> header to this api. The cors setup allows the Authorization header for localhost origins in development.
• petstore (secret: 5FbFAgTAWyVAWSQtDPqCLZzY): confidential client for backend integrations and for requesting tokens via password grant while testing.

Both clients use an audience mapper, so that the access token contains aud: petstore, which this api requires.

Admin console: http://keycloak:8080 (admin / TCUJyCbLtLbBc4eXYYzD9ecm). Keycloak is configured with the fixed hostname keycloak, so that the issuer claim is always http://keycloak:8080/realms/petstore; requests via http://localhost:8080 get redirected to that hostname. Add 127.0.0.1 keycloak to /etc/hosts on the host to use the admin console or to request tokens from the host:

ACCESS_TOKEN=$(curl -s http://keycloak:8080/realms/petstore/protocol/openid-connect/token \
  -d 'grant_type=password' \
  -d 'client_id=petstore' \
  -d 'client_secret=5FbFAgTAWyVAWSQtDPqCLZzY' \
  -d 'username=petstore' \
  -d 'password=GBanBPatEBRZ7hf7cAxKn8Ptt' | sed -E 's/.*"access_token":"([^"]+)".*/\1/')

curl --insecure -H "Authorization: Bearer ${ACCESS_TOKEN}" -H 'Accept: application/json' https://localhost/api/pets

The integration tests run against keycloak as well (no auth mocking): tests/Helper/AuthHelper.php waits for the discovery endpoint of OIDC_ISSUER to be reachable and requests tokens via password grant with the petstore client and user. Within the php container keycloak is reachable as keycloak, in ci a keycloak container gets started and published on the docker bridge gateway (see .github/workflows/ci.yml).

Structure

Collection

Collections are sortable, filterable paginated lists of models.

• App\Pet\Collection

Dto

A DTO, or Data Transfer Object, is a simple object used to transport data between software application components.

• App\Pet\Dto

Model

Models, entities, documents what ever fits your purpose the best.

• App\Pet\Model

ORM

ORM Mapping definitions.

• App\Pet\Orm

Parsing

Parses and validates data against predefined schemas, ensuring that incoming data conforms to expected structures and criteria.

• App\Pet\Parsing

Repository

Repositories get data from storages like databases, elasticsearch, redis or whereever your models are stored or cached.

• App\Pet\Repository

RequestHandler

RequestHandler alias Controller, or Controller actions to be more precise. There is a directory with generic crud controllers. If you like the idea adapt them for your generic use case, if not drop them. I highly recommend to not extend them.

• App\Core\RequestHandler

ServiceFactory

Service factories are the glue code of the dependeny injection container.

• App\Core\ServiceFactory
• App\Pet\ServiceFactory

Opensearch

Policy to delete logstash formatted indicies after 14 days.

curl -XPUT 'https://localhost:9200/_plugins/_ism/policies/logstash-policy' \
    -u 'admin:98T722Eqw99oqFCSJCnB' \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -d '{
      "policy": {
        "description": "Logstash",
        "default_state": "hot",
        "states": [
          {
            "name": "hot",
            "actions": [],
            "transitions": [
              {
                "state_name": "delete",
                "conditions": {
                  "min_index_age": "14d"
                }
              }
            ]
          },
          {
            "name": "delete",
            "actions": [
              {
                "delete": {}
              }
            ]
          }
        ],
        "ism_template": {
          "index_patterns" : ["logstash-*"],
          "priority": 100
        }
      }
    }' \
    --insecure

Dashboard

Before you start, produce at least one error, produce a 404.

Create Index Pattern

• Username: admin
• Password: 98T722Eqw99oqFCSJCnB
• Index pattern name: logstash-*
• Time field: @timestamp

Discover

Copyright

2026 Dominik Zogg