PHPackages survos/dataset-bundle - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Utility & Helpers](/categories/utility) 4. / 5. survos/dataset-bundle ActiveSymfony-bundle[Utility & Helpers](/categories/utility) survos/dataset-bundle ===================== Shared data directory conventions and path utilities for dataset-driven apps (APP\_DATA\_DIR). 2.12.4(3w ago)0299↑400%4MITPHPPHP ^8.5CI failing Since May 21Pushed 3w agoCompare [ Source](https://github.com/survos/dataset-bundle)[ Packagist](https://packagist.org/packages/survos/dataset-bundle)[ GitHub Sponsors](https://github.com/kbond)[ RSS](/packages/survos-dataset-bundle/feed)WikiDiscussions main Synced 3w ago READMEChangelogDependencies (54)Versions (74)Used By (4) Survos Data Bundle ================== [](#survos-data-bundle) `survos/data-bundle` centralizes dataset filesystem conventions for dataset-driven Symfony applications. Despite the historical name, this bundle is not the owner of shared semantic metadata contracts. It manages where dataset files, provider metadata, Pixie databases, run artifacts, cache files, and related JSONL outputs live. For shared vocabulary and typed metadata contracts, use `survos/data-contracts`. Scope ----- [](#scope) This bundle provides: - `DataPaths`: root-level path resolution under `APP_DATA_DIR` - `DatasetPaths`: dataset-scoped path helpers - dataset metadata loading and ensuring - `DatasetInfo` / `Provider` registry entities - provider snapshot encoding - dataset context helpers for console/import workflows - commands for browsing, diagnosing, and resolving dataset paths This bundle does not provide: - Dublin Core vocabulary constants - collection-object DTO contracts - metadata claim storage - AI workflow execution - media upload, IIIF, or mediary publishing - import/normalize/profile logic Relationship to Other Packages ------------------------------ [](#relationship-to-other-packages) - `survos/data-contracts`: shared metadata vocabulary and DTO contracts. - `survos/data-bundle`: dataset paths, provider storage, and dataset registry. - `survos/import-bundle`: import/convert workflows that may ask this bundle for dataset paths. - `survos/ai-workflow-bundle`: task execution in apps that own subject context. - claims bundle: tracked metadata assertions with provenance and confidence. - `survos/media-bundle`: media identity and mediary publishing. The dependency direction should stay honest: packages should require `survos/data-contracts` directly when they only need `DcTerms`, `ContentType`, or metadata DTOs. Do not require this bundle just to get vocabulary classes. Core Idea --------- [](#core-idea) All dataset work lives under a single root directory: ``` APP_DATA_DIR=/absolute/path/to/data/root ``` The bundle avoids repository-relative paths and gives services and commands one place to ask for canonical locations. ### Tiers (v2) [](#tiers-v2) Placement is decided by one rule: *can I regenerate it from another tier + code?* TierHoldsBacked up / shipped?`vault/`acquired source + AI claims + `_vocab/` referenceyes — durable, mirror of HF/S3`cache/`bulky re-fetchable materializations (clones, firehose, unzipped)no`work/`pipeline output — **disposable** (`rm -rf work//` is always safe)no`folio/`built `.folio` databasesno — rebuilt from `work```` $APP_DATA_DIR/ vault/ // # acquired source files ai/claims.jsonl # AI claims (expensive → durable, never in work) _vocab/ # global reference vocab (non-provider → _) cache//... # disposable, re-fetchable work/// _meta/dataset.json # config (portal from code) _raw/ # source view (portal → vault; often a symlink) norm/ # normalized cores + term/termSet + link/linkType voc/ # extracted vocab (feeds AI content_type mapping) trans/ # translations _folio/ # assembled folio-input (portal → folio tier) folio//.folio ``` Work-tree stage directory names have **no numeric prefixes** and sort in pipeline order; `_`-prefixed dirs are **tier portals** (config / vault / folio), often symlinks, not computed stages. ### `Stage` enum — the single source of truth [](#stage-enum--the-single-source-of-truth) `Survos\DatasetBundle\Enum\Stage` owns stage identity and dir names. The backed value is the stable semantic key (events, `import:convert --stage`); `Stage::dir()` is the only place directory names live; `Stage::fromKey()` is the fail-loud string boundary (unknown → throws). Reference `Stage` cases in code — do not pass raw stage strings. ``` $paths->stageDir('dc/tb09jw350', Stage::Normalize); // .../norm ``` Installation ------------ [](#installation) ``` composer require survos/data-bundle ``` Set the root directory: ``` export APP_DATA_DIR=/absolute/path/to/data/root ``` Usage ----- [](#usage) Inject `DataPaths` for root and dataset path resolution: ``` use Survos\DataBundle\Service\DataPaths; final class SomeService { public function __construct( private readonly DataPaths $paths, ) { } } ``` Common dataset paths: ``` $paths->datasetDir('dc/tb09jw350'); $paths->extractDir('dc/tb09jw350'); $paths->extractFile('dc/tb09jw350'); $paths->normalizeDir('dc/tb09jw350'); $paths->normalizeFile('dc/tb09jw350'); $paths->profileDir('dc/tb09jw350'); $paths->profileFile('dc/tb09jw350'); $paths->termsDir('dc/tb09jw350'); ``` Pixie paths: ``` $paths->pixieTenantDb('larco'); ``` Operational directories: ``` $paths->runsDir; $paths->cacheDir; ``` Commands -------- [](#commands) Current command names retain the historical `data:*` prefix: ``` bin/console data:path dc/tb09jw350 20_normalize bin/console data:head dc/tb09jw350 20_normalize --limit=5 bin/console data:diag dc/tb09jw350 bin/console data:browse bin/console data:scan-datasets ``` These may eventually move to `dataset:*` aliases when the bundle is renamed. Directory Creation ------------------ [](#directory-creation) Ensure global roots exist: ``` $paths->ensureRootDirs(); ``` Ensure standard dataset stage directories exist: ``` $paths->ensureDatasetDirs('dc/tb09jw350'); ``` Atomic File Writes ------------------ [](#atomic-file-writes) For small metadata files: ``` $paths->atomicWrite($path, $contents); ``` The write uses a temporary file in the same directory followed by an atomic rename. Design Principles ----------------- [](#design-principles) - Dataset path conventions are centralized. - Paths are semantic, not stringly typed. - Dataset/provider storage concerns stay separate from semantic metadata contracts. - Import, AI workflow, claims, and media publishing remain in their own packages. - The bundle should stay boring and infrastructure-focused. Future Rename ------------- [](#future-rename) The better long-term name is `survos/dataset-bundle`. See [`docs/rename-to-dataset-bundle.md`](docs/rename-to-dataset-bundle.md). ### Health Score 51 — FairBetter than 95% of packages Maintenance95 Actively maintained with recent releases Popularity17 Limited adoption so far Community15 Small or concentrated contributor base Maturity66 Established project with proven stability Bus Factor1 Top contributor holds 100% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~0 days Total 73 Last Release 24d ago PHP version history (2 changes)2.5.0PHP ^8.4 2.8.0PHP ^8.5 ### Community Maintainers ![](https://www.gravatar.com/avatar/21b39551f92ed4143772c622f9e571589c5a72c96ab3c53fe67489ce0d83e806?d=identicon)[tacman1123](/maintainers/tacman1123) --- Top Contributors [![tacman](https://avatars.githubusercontent.com/u/619585?v=4)](https://github.com/tacman "tacman (45 commits)") ### Code Quality TestsPHPUnit ### Embed Badge ![Health badge](/badges/survos-dataset-bundle/health.svg) ``` [![Health](https://phpackages.com/badges/survos-dataset-bundle/health.svg)](https://phpackages.com/packages/survos-dataset-bundle) ``` ### Alternatives [easycorp/easyadmin-bundle Admin generator for Symfony applications 4.3k17.9M400](/packages/easycorp-easyadmin-bundle)[sylius/sylius E-Commerce platform for PHP, based on Symfony framework. 8.5k5.9M754](/packages/sylius-sylius)[shopware/core Shopware platform is the core for all Shopware ecommerce products. 585.6M600](/packages/shopware-core)[open-dxp/opendxp Content & Product Management Framework (CMS/PIM) 9421.6k64](/packages/open-dxp-opendxp)[2lenet/crudit-bundle The easy like Crud'it Bundle. 1616.4k14](/packages/2lenet-crudit-bundle)[chameleon-system/chameleon-base The Chameleon System core. 1028.7k5](/packages/chameleon-system-chameleon-base) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)