islamic-network/ilm-api-base

Shared serving runtime for the ilm domain APIs: snapshot repository, DTO utilities, response cache, base controller and search scanner.

0.2 2026-07-14 03:31 UTC

Requires

• php: >=8.4
• ext-intl: *
• cuyz/valinor: ^2
• islamic-network/qalam: ^0.2
• islamic-network/sdk: ^0.3
• kipchak/core: ^3
• kipchak/driver-config: ^1
• kipchak/driver-filecache: ^1
• kipchak/driver-logger: ^1
• kipchak/driver-s3: ^1

Requires (Dev)

• phpunit/phpunit: ^12

MIT

Published on Packagist.org on 2026-07-14 03:31 UTC

README

The shared serving runtime for the ilm domain APIs (pray, events, people, quotes, stories). A domain API built on this package ships only what makes it that domain: its DTO classes (which ARE its contract), its Corpus (joins and projections), its controllers and routes. Everything domain-blind lives here:

• Snapshot\Repository — polls snapshots/manifest.json in the ilm bucket, loads the domain's snapshot file into worker memory when the version changes, maps it strictly into the domain's snapshot DTOs (drift throws; the last good version keeps serving), and constructs the domain Corpus. Configured via kipchak.snapshot: connection, bucket, prefix, refresh, plus the domain key and the Document/Corpus class names.
• Snapshot\CorpusInterface — what a domain corpus must expose (its snapshot version); constructor convention ($document, $version).
• Utils\Dto — strict valinor mapping in, array normalization out, with the contracts' "empty values are omitted" null-stripping (keepNulls for the exceptions).
• Utils\Hijri — Gregorian → Hijri via the AlAdhan API (islamic-network/sdk IslamicCalendarClient, pinned to HJCoSA): the authoritative, sighting-adjusted date. Conversions are worker-memoized and disk-cached for a day; if AlAdhan is unreachable on a cold cache, ext-intl's tabular islamic-civil answers as a logged fallback. ALADHAN_API_URL overrides the endpoint.
• Middlewares\ResponseCache — disk cache for 200 GET responses (Kipchak filecache driver); keys carry the snapshot version so publishes invalidate naturally and a pod restart is a full flush.
• Controllers\SnapshotController — withCorpus() (503 on a cold worker), pagination, and the paginated meta envelope via Kipchak's Response::json.
• Search\Scanner — the diacritic-folded search mechanism: query tokenization (folded exactly like the sync-time search blobs), AND-token matching, and per-field matched_in computation. Field maps per record type stay in each domain's Corpus.
• DataTransferObjects\Prose — the {raw, html} prose rendition shape every contract shares.

Wiring a domain API

// config/kipchak.snapshot.php
return [
    'connection' => 'ilm',
    'bucket' => env('S3_BUCKET', 'ilm'),
    'prefix' => env('SNAPSHOT_PREFIX', 'snapshots'),
    'refresh' => (int) env('SNAPSHOT_REFRESH', '60'),
    'domain' => 'pray',                          // key in the manifest files map
    'document' => Snapshot\Document::class,      // strict-mapped snapshot DTO
    'corpus' => Snapshot\Corpus::class,          // implements CorpusInterface
];

Controllers extend SnapshotController; Middlewares\ResponseCache is added in the app's global middleware stack before Kipchak's Error middleware.

pray-api is the reference consumer.

Developing

composer install
vendor/bin/phpunit

PHP 8.4+ (all ilm code stays 8.4-compatible), kipchak/core 3.