Driver: Improve section about PHP

[amotl]

About

• What the title says.
• Add information about AMPHP and PDO_PGSQL.
• Reorganize section. Each client gets a dedicated page.

Preview

https://cratedb-guide--404.org.readthedocs.build/connect/php/

/cc @matriv, @seut

[coderabbitai]

Walkthrough

Replaces the single legacy PHP docs page with a PHP sub-index and four driver-specific pages (AMPHP, PDO_PGSQL, Crate PDO wrapper, Crate DBAL); updates driver listing and example badge anchors to point to the new PHP subpage/anchor and removes the old docs/connect/php.md.

Changes

Cohort / File(s)	Summary of Changes
Removed — legacy PHP guide docs/connect/php.md	Deleted the original PHP page containing PDO/DBAL examples, intro text, and sample snippets.
Updated — drivers listing & TOC anchors docs/connect/drivers.md, docs/connect/index.md	Updated PHP link targets and example badge anchors from #php to #connect-php; TOC entry now references php/index.
Added — PHP sub-index & driver pages docs/connect/php/index.md, docs/connect/php/amphp.md, docs/connect/php/pdo-pgsql.md, docs/connect/php/crate-pdo.md, docs/connect/php/crate-dbal.md	Added a PHP index and four driver-specific docs including CI badges, install notes, synopses, PHP code examples, and cross-links.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• Connect: Migrate pages from crate-clients-tools, to be retired soon #221 — Reorganized/added PHP connect documentation that this PR further restructures or replaces.
• Connect: Reorganize and clean up section #361 — Modifies the same docs/connect/index.md and TOC/navigation; related navigation changes.
• Drivers: Fix broken links. Improve wording. #338 — Updates driver link targets and anchors in docs/connect/*, overlapping edits.

Suggested reviewers

• surister
• matriv
• seut

Poem

A rabbit hops through docs tonight,
Old pages folded, new ones bright.
PDO and AMPHP take their place,
CrateDB sings in PHP's grace —
Hooray for tidy docs tonight. 🐇✨

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'Driver: Improve section about PHP' directly relates to the main objective of reorganizing and improving the PHP documentation section with new content and structure.
Description check	✅ Passed	The description clearly explains the changes made: adding AMPHP and PDO_PGSQL information, reorganizing with dedicated pages per client, and includes a preview link.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch php

---

📜 Recent review details

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 4274d39 and 697a1fe.

📒 Files selected for processing (8)

• docs/connect/drivers.md
• docs/connect/index.md
• docs/connect/php.md
• docs/connect/php/amphp.md
• docs/connect/php/crate-dbal.md
• docs/connect/php/crate-pdo.md
• docs/connect/php/index.md
• docs/connect/php/pdo-pgsql.md

💤 Files with no reviewable changes (1)

• docs/connect/php.md

🚧 Files skipped from review as they are similar to previous changes (3)

• docs/connect/drivers.md
• docs/connect/php/crate-dbal.md
• docs/connect/php/amphp.md

🧰 Additional context used

🧠 Learnings (2)

📚 Learning: 2025-10-06T16:40:16.322Z

Learnt from: amotl
Repo: crate/cratedb-guide PR: 0
File: :0-0
Timestamp: 2025-10-06T16:40:16.322Z
Learning: In the crate/cratedb-guide repository, documentation is organized by content type: files in `docs/feature/`, `docs/integrate/`, and `docs/ingest/` are reference material designed for quick access, while `docs/start/` contains learning path content. Reference material sections use top-right reference layouts for efficient navigation.

Applied to files:

• docs/connect/php/crate-pdo.md

📚 Learning: 2025-10-20T21:49:18.785Z

Learnt from: amotl
Repo: crate/cratedb-guide PR: 406
File: docs/connect/go.md:110-137
Timestamp: 2025-10-20T21:49:18.785Z
Learning: In the cratedb-guide repository, documentation examples for connecting to CrateDB (e.g., Go examples in docs/connect/go.md) should be kept minimal and focused on demonstrating basic functionality, rather than including comprehensive error handling. Full examples with proper error handling are maintained separately in the cratedb-examples repository.

Applied to files:

• docs/connect/php/crate-pdo.md

🪛 LanguageTool

docs/connect/php/crate-pdo.md

[grammar] ~1-~1: Ensure spelling is correct
Context: (crate-pdo)= # CrateDB PDO :::{div} .float-r...

(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)

🪛 markdownlint-cli2 (0.18.1)

docs/connect/php/pdo-pgsql.md

37-37: Bare URL used

(MD034, no-bare-urls)

---

44-44: Bare URL used

(MD034, no-bare-urls)

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)

• GitHub Check: Build docs

🔇 Additional comments (7)

docs/connect/index.md (1)

296-296: Toctree navigation updated correctly.

The change from php to php/index aligns with the new PHP sub-index structure and is consistent with how other multi-driver languages are organized (e.g., csharp/index, java/index).

docs/connect/php/index.md (1)

1-15: PHP index structure is clean and properly anchored.

The anchor (connect-php)= correctly enables the driver card navigation reference in docs/connect/index.md. The toctree lists all four PHP driver topics (amphp, pdo-pgsql, crate-pdo, crate-dbal) with appropriate maxdepth setting.

docs/connect/php/pdo-pgsql.md (2)

37-44: Static analysis flagged bare URLs in structured link attributes.

The markdownlint warnings (MD034) on lines 37 and 44 appear to be false positives, as these URLs are properly declared within grid-item-card :link: attributes using :link-type: url, which is the correct Sphinx Design syntax. However, if this linting rule is enforced project-wide, you may need to confirm with the project maintainers whether these warnings can be safely ignored.

The URLs themselves appear valid (PHP documentation and cratedb-examples repository).

---

19-27: Example is appropriately minimal and focused.

The PDO_PGSQL example shows the essential connection pattern and query execution without unnecessary complexity, aligning with the codebase's documentation practices. Based on learnings, full examples with error handling are maintained separately in cratedb-examples, which this page correctly references.

docs/connect/php/crate-pdo.md (3)

53-56: Verify external reference crate-pdo:index is correctly configured.

The See also section links to crate-pdo:index using an intersphinx reference (:link-type: ref). Please verify that this reference is properly registered in the Sphinx intersphinx configuration and points to the correct external documentation URL for the crate-pdo package documentation.

---

26-43: Example demonstrates proper CrateDB PDO usage with appropriate complexity.

The synopsis includes necessary context (require, use statements, DSN configuration with options), showing users how to properly instantiate the PDOCrateDB class and execute queries. This level of detail is appropriate for a focused driver overview, with comprehensive examples referenced in the cratedb-examples repository. Based on learnings, keeping documentation examples minimal yet functional aligns with project standards.

---

11-14: Clear explanation of PDO standard and crate-pdo implementation.

The description succinctly explains that crate-pdo implements the PHP PDO interface while wrapping CrateDB's HTTP interface, providing essential context for users unfamiliar with either technology.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}