Download the PHP package liquidrazor/file-locator without Composer

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:

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

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

1. Default Configuration (Library)

The library ships with an internal configuration:

This defines the baseline discovery rules.

2. Project Override

You can override or extend discovery behavior by adding:

or

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

Adding Custom Roots: Extending Discovery

Excluding Paths: Global And Root-Specific Rules

Global exclusions:

Root-specific exclusions:

Disabling Default Roots: Removing Built-In Paths

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

Configuration is built as:

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

The system is intentionally split into layers:

1. Config Layer

• DiscoveryConfigFactory
• DiscoveryConfigValidator
• DiscoveryConfig

2. Discovery Layer

• FileLocator
• streaming traversal using generators
• zero accumulation by default

3. Future Layers

• Class discovery (static parsing)
• DI registry loading

Usage: Basic Flow

The locator yields files lazily, ensuring minimal memory usage.

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

• Unreadable paths: configurable (skip or fail)
• Symlinks: disabled by default
• Hidden files: excluded by default
• Deterministic behavior (no implicit magic)

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

This component is the foundation of the DI pipeline:

Notes: Additional Documentation

• Discovery flow documentation
• Architecture overview documentation
• Configuration system documentation
• File locator API documentation
• Config loading integration documentation
• Development setup documentation
• Implementation guidelines documentation
• Testing strategy documentation
• Supported extension points documentation

License: Package Terms

MIT