PHPackages liquidrazor/file-locator - 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. [File & Storage](/categories/file-storage) 4. / 5. liquidrazor/file-locator ActiveLibrary[File & Storage](/categories/file-storage) liquidrazor/file-locator ======================== Minimal filesystem discovery component for LiquidRazor. v0.1.1(2mo ago)032MITPHPPHP ^8.3 Since Mar 26Pushed 2mo agoCompare [ Source](https://github.com/LiquidRazor/FileLocator)[ Packagist](https://packagist.org/packages/liquidrazor/file-locator)[ Docs](https://github.com/LiquidRazor/FileLocator)[ RSS](/packages/liquidrazor-file-locator/feed)WikiDiscussions main Synced 3w ago READMEChangelogDependencies (1)Versions (3)Used By (2) LiquidRazor File Discovery ========================== [](#liquidrazor-file-discovery) A lightweight, high-performance filesystem discovery component for the LiquidRazor ecosystem. This library provides a **deterministic, memory-efficient, and extensible way** to locate PHP files across a project using convention-first defaults with optional project-level overrides. It is the first step in the LiquidRazor pipeline: ``` filesystem → files → classes → descriptors → DI registry ``` --- Features: Core Capabilities --------------------------- [](#features-core-capabilities) - Fast, iterator-based filesystem traversal with low memory use - Convention-first defaults for `include/`, `lib/`, and `src/` - YAML-based configuration loaded through `liquidrazor/config-loader` - Clean separation of concerns with no DI, reflection, or PHP parsing - Safe traversal with configurable symlink, hidden file, and unreadable path handling - Config loading delegated to a dedicated LiquidRazor library --- Default Behavior: Built-In Roots And Exclusions ----------------------------------------------- [](#default-behavior-built-in-roots-and-exclusions) Out of the box, the discovery system scans: - `include/` - `lib/` - `src/` With automatic exclusions: - `vendor/` - `node_modules/` - `.git/` - `.idea/` - `.vscode/` - `var/cache/` Only `.php` files are considered. --- Configuration: Config Sources ----------------------------- [](#configuration-config-sources) ### 1. Default Configuration (Library) [](#1-default-configuration-library) The library ships with an internal configuration: ``` resources/config/roots.yaml ``` This defines the baseline discovery rules. --- ### 2. Project Override [](#2-project-override) You can override or extend discovery behavior by adding: ``` config/roots.yaml ``` or ``` config/roots.yml ``` Config loading is delegated to `liquidrazor/config-loader` with YAML selected explicitly. If both `config/roots.yaml` and `config/roots.yml` exist, loading fails instead of silently picking one. --- Configuration Structure: Supported YAML Shape --------------------------------------------- [](#configuration-structure-supported-yaml-shape) ``` discovery: defaults: follow_symlinks: false include_hidden: false on_unreadable: skip extensions: [php] exclude: - vendor - node_modules - .git roots: include: enabled: true path: include recursive: true extensions: [php] exclude: [] lib: enabled: true path: lib recursive: true extensions: [php] exclude: [] src: enabled: true path: src recursive: true extensions: [php] exclude: [] ``` --- Adding Custom Roots: Extending Discovery ---------------------------------------- [](#adding-custom-roots-extending-discovery) ``` discovery: roots: modules: path: modules recursive: true ``` --- Excluding Paths: Global And Root-Specific Rules ----------------------------------------------- [](#excluding-paths-global-and-root-specific-rules) Global exclusions: ``` discovery: exclude: - storage/tmp ``` Root-specific exclusions: ``` discovery: roots: src: exclude: - src/Legacy - src/Experimental ``` --- Disabling Default Roots: Removing Built-In Paths ------------------------------------------------ [](#disabling-default-roots-removing-built-in-paths) ``` discovery: roots: lib: enabled: false ``` --- Config Loading Boundary ----------------------- [](#config-loading-boundary) `FileLocator` no longer locates config files by full path, reads raw config contents, parses YAML, merges raw config layers, or interpolates environment variables itself. Those responsibilities now belong to `liquidrazor/config-loader`. `DiscoveryConfigFactory` only: - asks ConfigLoader for normalized config arrays using the logical name `roots` - validates the discovery schema - normalizes project-relative paths - builds `DiscoveryConfig`, `DiscoveryDefaults`, and `RootConfig` --- Merge Strategy: How Config Is Built ----------------------------------- [](#merge-strategy-how-config-is-built) Configuration is built as: ``` library defaults + project overrides → final discovery config ``` The default resource is loaded from `resources/config/roots.yaml`. The optional project override is loaded from the project `config` root using the logical name `roots`. Raw config merge behavior now follows `liquidrazor/config-loader`: - Associative arrays → merged recursively - Scalars → overridden by later config - Indexed arrays → replaced by later config After loading, FileLocator still validates the discovery schema and removes disabled roots from the runtime config. --- Architecture: Main Layers ------------------------- [](#architecture-main-layers) The system is intentionally split into layers: ### 1. Config Layer [](#1-config-layer) - `DiscoveryConfigFactory` - `DiscoveryConfigValidator` - `DiscoveryConfig` ### 2. Discovery Layer [](#2-discovery-layer) - `FileLocator` - streaming traversal using generators - zero accumulation by default ### 3. Future Layers [](#3-future-layers) - Class discovery (static parsing) - DI registry loading --- Usage: Basic Flow ----------------- [](#usage-basic-flow) ``` use LiquidRazor\FileLocator\Config\DiscoveryConfigFactory; use LiquidRazor\FileLocator\FileLocator; $factory = new DiscoveryConfigFactory(); $config = $factory->create(__DIR__); $locator = new FileLocator($config); foreach ($locator->locate() as $file) { // process file } ``` The locator yields files **lazily**, ensuring minimal memory usage. --- Performance Principles: Traversal Behavior ------------------------------------------ [](#performance-principles-traversal-behavior) - Depth-first traversal - Early directory pruning - Generator-based streaming - No reflection or file inclusion - No unnecessary allocations --- Safety: Failure And Traversal Controls -------------------------------------- [](#safety-failure-and-traversal-controls) - Unreadable paths: configurable (`skip` or `fail`) - Symlinks: disabled by default - Hidden files: excluded by default - Deterministic behavior (no implicit magic) --- Design Philosophy: Implementation Priorities -------------------------------------------- [](#design-philosophy-implementation-priorities) - Convention over configuration (but never forced) - Explicit over implicit - Small, composable components - No framework lock-in - Predictable behavior under load --- Role in LiquidRazor: Pipeline Position -------------------------------------- [](#role-in-liquidrazor-pipeline-position) This component is the **foundation of the DI pipeline**: ``` FileLocator ↓ ClassLocator (future) ↓ RegistryLoader (future) ↓ DIRegistry ``` --- Notes: Additional Documentation ------------------------------- [](#notes-additional-documentation) - [Discovery flow documentation](docs/01_data_flow/discovery_flow.md) - [Architecture overview documentation](docs/02_architecture/overview.md) - [Configuration system documentation](docs/02_architecture/config_system.md) - [File locator API documentation](docs/02_architecture/file_locator.md) - [Config loading integration documentation](docs/02_architecture/yaml_strategy.md) - [Development setup documentation](docs/03_development/setup.md) - [Implementation guidelines documentation](docs/03_development/implementation_guidelines.md) - [Testing strategy documentation](docs/03_development/testing.md) - [Supported extension points documentation](docs/03_development/extension_points.md) --- License: Package Terms ---------------------- [](#license-package-terms) MIT ### Health Score 35 — LowBetter than 77% of packages Maintenance84 Actively maintained with recent releases Popularity3 Limited adoption so far Community10 Small or concentrated contributor base Maturity40 Maturing project, gaining track record 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 ~7 days Total 2 Last Release 83d ago ### Community Maintainers ![](https://avatars.githubusercontent.com/u/4306922?v=4)[Noramarth](/maintainers/Noramarth)[@Noramarth](https://github.com/Noramarth) --- Top Contributors [![Noramarth](https://avatars.githubusercontent.com/u/4306922?v=4)](https://github.com/Noramarth "Noramarth (3 commits)") --- Tags phpfilesystemdependency-injectionfile-locatorfile-discoverydi-registry ### Embed Badge ![Health badge](/badges/liquidrazor-file-locator/health.svg) ``` [![Health](https://phpackages.com/badges/liquidrazor-file-locator/health.svg)](https://phpackages.com/packages/liquidrazor-file-locator) ``` PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)