feat(stats): add query params for Meilisearch v1.44 showInternalDatabaseSizes and sizeFormat

[arieleli01212]

Closes #915.

Adds support for the two new query parameters introduced in Meilisearch v1.44.0 for the stats endpoints.

Changes

src/Contracts/Stats.php — databaseSize and usedDatabaseSize widened from int to int|string to accommodate human-readable responses when sizeFormat='human'

src/Contracts/IndexStats.php — same widening for rawDocumentDbSize and avgDocumentSize; new optional internalDatabaseSizes: ?array field (present only when showInternalDatabaseSizes=true; keys subject to change per spec)

src/Endpoints/Stats.php — overrides show() to accept a $query array passed through to http->get

src/Endpoints/Delegates/HandlesSystem.php — stats(array $query = []) passes query to Stats::show()

src/Endpoints/Indexes.php — stats(array $query = []) passes query to http->get

.code-samples.meilisearch.yaml — updated get_index_stats_1 and get_indexes_stats_1

All existing callers with no arguments continue to work unchanged.

Summary

This pull request adds support for two new query parameters introduced in Meilisearch v1.44.0 to the stats endpoints: showInternalDatabaseSizes and sizeFormat.

Key Changes

Contracts Updated:

• Stats.php: databaseSize and usedDatabaseSize types changed from int to int|string to support both byte counts and human-readable strings.
• IndexStats.php: rawDocumentDbSize and avgDocumentSize types changed from int to int|string; added new optional internalDatabaseSizes property (array mapping internal database names to their sizes).

Endpoints and Delegates Enhanced:

• Stats.php: Added show(array $query = []): ?array method to forward query parameters to HTTP GET request.
• HandlesSystem.php: stats() method now accepts optional $query parameter and forwards it to Stats::show().
• Indexes.php: stats() method now accepts optional $query parameter and forwards it to the HTTP GET request.

Documentation:

• .code-samples.meilisearch.yaml: Updated get_index_stats_1 and get_indexes_stats_1 examples to demonstrate calling stats() with showInternalDatabaseSizes: true and sizeFormat: 'human' parameters.

Backward Compatibility

All changes are backward compatible. Existing code that calls stats() without arguments continues to work unchanged, as all new parameters are optional with default values.

Related Issues

Closes issue #915

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: d21e5828-83e8-45fb-977f-5df70dc583b4

📥 Commits

Reviewing files that changed from the base of the PR and between c651751 and 74b4f8e.

📒 Files selected for processing (6)

• .code-samples.meilisearch.yaml
• src/Contracts/IndexStats.php
• src/Contracts/Stats.php
• src/Endpoints/Delegates/HandlesSystem.php
• src/Endpoints/Indexes.php
• src/Endpoints/Stats.php

---

📝 Walkthrough

Walkthrough

This PR extends the Meilisearch PHP SDK to support v1.44.0's new stats features: human-formatted database sizes and detailed internal database size breakdowns. Data contracts now accept int|string sizes and optional internal database maps. Endpoint methods accept query parameters to control size format and detail level, forwarding them through the HTTP layer. Documentation examples demonstrate usage.

Changes

Stats API v1.44.0 Feature Support

Layer / File(s)	Summary
Data contracts for flexible size formats and internal database details src/Contracts/Stats.php, src/Contracts/IndexStats.php	Stats and IndexStats now accept and expose database sizes as int|string (raw bytes or human-readable). IndexStats adds optional internalDatabaseSizes getter and constructor parameter for a map of internal database names to sizes. fromArray factories accept both types in input arrays.
Endpoint methods accept and forward stats query parameters src/Endpoints/Stats.php, src/Endpoints/Delegates/HandlesSystem.php, src/Endpoints/Indexes.php	Stats::show(array $query = []) method added to execute parameterized GET requests. HandlesSystem::stats() and Indexes::stats() method signatures updated to accept optional $query parameter, forwarding it to the underlying HTTP calls to control size format and internal database size visibility.
Documentation examples demonstrating new stats parameters .code-samples.meilisearch.yaml	Code samples for get_index_stats_1 and get_indexes_stats_1 updated to pass showInternalDatabaseSizes: true and sizeFormat: 'human' query options to stats calls.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related issues

• Meilisearch Rust #789: Implements the same Meilisearch v1.44.0 stats API updates across the Rust SDK.
• Meilisearch Swift #521: Implements the same v1.44.0 stats feature additions (query parameters and data structure updates) in the Swift SDK.
• Meilisearch JavaScript #2185: Addresses the same stats API enhancements for the JavaScript SDK.
• Meilisearch Java #966: Implements the same v1.44.0 stats updates in the Java SDK.
• Meilisearch Dart #488: Adds support for the same v1.44.0 stats feature across the Dart SDK.

Poem

🐰 Sizes now speak both tongues—bytes and words so grand,
Human-readable charm blooms across the land,
Internal databases mapped, their secrets on display,
Stats queries flex with options, guiding the way!
v1.44 dances through, with parameters to play. 🌟

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The PR title clearly and concisely describes the main feature: adding support for query parameters for Meilisearch v1.44, specifically showInternalDatabaseSizes and sizeFormat.
Linked Issues check	✅ Passed	All requirements from issue #915 are met: query parameter support added to stats endpoints, contract types widened for size fields, internalDatabaseSizes field added, and code samples updated.
Out of Scope Changes check	✅ Passed	All changes are directly related to supporting the new Meilisearch v1.44 query parameters for stats endpoints; no unrelated modifications detected.
Docstring Coverage	✅ Passed	Docstring coverage is 85.71% which is sufficient. The required threshold is 80.00%.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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.}

[norkunas]

I'd use request object instead

[norkunas]

@Strift i'd instead tighten the return type to https://github.com/zenstruck/bytes, but not sure if team agrees on using external packages here (when i tried to implem stats command in meilisearch-bundle, i relied on this package, but the stats are not ported to v1 yet IIRC? so i didn't open a PR)
why? because then it's a consumers choice how to format to human readable format, what unit to use, etc.

[codecov]

Codecov Report

❌ Patch coverage is 69.23077% with 4 lines in your changes missing coverage. Please review.
✅ Project coverage is 88.30%. Comparing base (0078a8c) to head (74b4f8e).
⚠️ Report is 157 commits behind head on main.

Files with missing lines	Patch %	Lines
src/Contracts/IndexStats.php	20.00%	4 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #916      +/-   ##
==========================================
- Coverage   89.78%   88.30%   -1.48%     
==========================================
  Files          59       93      +34     
  Lines        1449     1933     +484     
==========================================
+ Hits         1301     1707     +406     
- Misses        148      226      +78     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.