psfs/nosql

NOSQL package for PSFS

1.0.2 2026-03-25 10:22 UTC

Requires

• php: >=8
• ext-mongodb: *
• mongodb/mongodb: ^2
• psfs/core: ^2

Requires (Dev)

• phpmd/phpmd: @stable
• phpunit/phpunit: ^11
• roave/security-advisories: dev-master

MIT

• Fran López

• nosql
• php
• api
• library
• restful
• psfs

README

NOSQL module for PSFS, aligned with the psfs/core 2.2.x-dev development line.

Technical Baseline

• Target runtime: PHP 8.3
• Main dependencies:
  • psfs/core: dev-master (branch alias 2.2.x-dev)
  • ext-mongodb
  • mongodb/mongodb:^2.1.2
• Metadata compatibility:
  • PHP 8 attributes as the primary contract
  • Legacy annotations kept temporarily as fallback

Local Development (Docker)

docker compose up -d
docker compose ps

Typical PHP container name: nosql-php-1.

docker exec nosql-php-1 php -v
docker exec nosql-php-1 composer install
docker exec nosql-php-1 php vendor/bin/phpunit -c src/NOSQL/phpunit.xml.dist

Minimum Validation

composer validate --no-check-publish --strict
vendor/bin/phpunit -c src/NOSQL/phpunit.xml.dist

Implemented Upgrade Contracts

• Routes and metadata in APIs/controllers migrated to attributes:
  • Api, Route, HttpMethod, Injectable, Label, Visible, Action
• Route convention normalized (Api, not APi).
• Generator templates updated to emit attributes in newly generated code.
• PHPUnit configuration migrated to 11.5 schema.
• GitHub Actions CI added for composer validate + tests.
• CRUD query planner optimized with:
  • unified query plan for find/count/deleteMany
  • strict custom pipeline whitelist
  • index metadata caching
  • cursor-mode pagination support (seek/after)
  • optional query hint, maxTimeMS, and allowDiskUse
  • configurable string filtering mode (contains|prefix|exact)

Query Planner Options

The NOSQL CRUD query layer supports these optional request keys:

• __string_mode: contains (default), prefix, or exact
• __cursor_mode: cursor/seek/after to enable cursor pagination
• __after: JSON object with sort field values for cursor pagination
• __hint: index hint (string or object)
• __maxTimeMS: max execution time for query operations
• __allowDiskUse: enable disk usage for aggregation if needed
• __collation: explicit collation object

Automatic index recommendations in syncCollections can be enabled with:

• nosql.sync.autoIndexes=true

Quick Troubleshooting

• PSFS autoload/class errors:
  • ensure composer install ran and vendor/ is up to date.
• Endpoints not discovered:
  • check that metadata.attributes.enabled=true in effective PSFS configuration.
• MongoDB extension errors:
  • verify ext-mongodb is enabled in runtime (php -m | grep mongodb).
• Scrutinizer CI:
  • install MongoDB extension using build.environment.php.pecl_extensions: [mongodb].

Migration: annotations -> attributes

For new APIs or code generated by the module:

1. Use attributes as the primary metadata source.
2. Keep annotations only if temporary compatibility is needed.
3. Avoid introducing new routes or methods only in annotation format.

This reduces legacy fallback usage and aligns the module with the current psfs/core contract.