README

Composable PHP toolkit for ArangoDB. Part of the Oihana PHP ecosystem, this package bundles a modern HTTP client, a high-level façade, document/edge models, controllers, helpers and CLI commands — everything you need to build an ArangoDB-backed application end-to-end.

📚 Documentation

Full API reference (generated with phpDocumentor): https://bcommebois.github.io/oihana-php-arango

User guides (FR + EN) live under wiki/. A few entry points:

• Getting started — concepts and dependencies.
• Search & filtering — the ?search= / ?filter= / ?facets= query DSL.
• Testing — unit tests, code coverage and the live smoke tests.
• Contributing — setup, conventions and the PR workflow.

📦 Installation

Requires PHP 8.4+ and an ArangoDB 3.11+ server. Install via Composer:

composer require oihana/php-arango

✨ What you can do

• Talk to ArangoDB through a modern, ready-to-use HTTP client built on Guzzle — Basic + JWT/Bearer authentication, automatic 401 refresh, cluster failover, retry on transient errors.
• Run AQL queries with safe placeholder binding (aql() helper), an AqlBuilder for fluent assembly, and a lazy Cursor supporting map / forEach / reduce / flatMap.
• Manage collections, documents, edges and indexes — full CRUD, batch operations, bulk JSON-Lines import, 7 typed index types (PersistentIndex, GeoIndex, TtlIndex, FulltextIndex, MdiIndex, VectorIndex, InvertedIndex).
• Use transactions, graphs, analyzers and views — streaming transactions with withTransaction() auto-commit/abort, gharial-based graphs with typed vertex/edge collections, ArangoSearch analyzers and views (full-text SEARCH, PHRASE, BM25).
• Compose document models via fine-grained traits (CRUD, AQL helpers, signals before/after CRUD).
• Plug controllers into any Slim-compatible PSR-15 stack with DocumentsController + capability gating.
• Drive list queries from the URL — a declarative ?search=, ?filter= and ?facets= DSL on document models that compiles to safe, bound AQL: rich comparators, AND/OR/NOT, range (between) and array quantifiers (quant, AT LEAST), hierarchical field paths, edge/join facets, plus output-side alt projection transforms.
• Run live smoke tests against a real arangod via the built-in arango:test:clients and arango:test:facade console commands.

Under the hood

• A consistent set of value objects and enums — no magic strings.
• Pure-PHP transport based on GuzzleHttp v7.
• Helpers for PSR-11 Container wiring.
• Hydration delegated to oihana/php-reflect — the client returns array data by default, the high-level façade hydrates into typed objects.
• Casbin RBAC adapter for ArangoDB included (oihana\arango\casbin\ArangoCasbinAdapter).

✅ Running tests

Run all tests:

composer test

Run a specific test file:

composer test ./tests/oihana/arango/SomeTest.php

Code coverage

Measure how much of ./src the suite exercises (requires Xdebug or PCOV):

composer coverage       # text + Clover + HTML report under build/coverage/
composer coverage:md    # readable Markdown summary at build/coverage/COVERAGE.md

The build/ output is gitignored — regenerate it on demand rather than committing a snapshot. See the testing guide for the full workflow.

Live smoke tests against a real arango database

The package ships with two end-to-end smoke tests that exercise every public surface against a live ArangoDB server. They operate on an ephemeral database that is created and dropped per run, so production data is never touched.

# Copy the example config and adjust the [arango] section
cp configs/config.example.toml configs/config.toml

# Run the full smoke suite for the new clients/ HTTP library
./bin/console.php arango:test:clients

# Run the smoke suite for the high-level ArangoDB façade
./bin/console.php arango:test:facade

Both commands accept --step=N, --step=N1-N2, --step=all, --no-cleanup, --endpoint=…, --user=…, --password=…, --database=….

🛠️ Generate the documentation

We use phpDocumentor to generate documentation into the ./docs folder.

composer doc

🤝 Contributing

Contributions are welcome! See CONTRIBUTING.md for setup, coding conventions, the testing workflow and the pull-request process.

🧾 License

Licensed under the Mozilla Public License 2.0 (MPL‑2.0).

👤 About the author

• Author: Marc ALCARAZ (aka eKameleon)
• Email: marc@ooop.fr
• Website: https://www.ooop.fr

🔗 Related packages