liquidrazor/file-locator

Minimal filesystem discovery component for LiquidRazor.

v0.1.0 2026-03-26 21:53 UTC

Requires

• php: ^8.3

MIT

• Dan Radu Dragomir

• php
• filesystem
• dependency-injection
• file-locator
• file-discovery
• di-registry

README

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

• Fast, iterator-based filesystem traversal with low memory use
• Convention-first defaults for include/, lib/, and src/
• YAML-based configuration with project overrides
• Clean separation of concerns with no DI, reflection, or parsing
• Safe traversal with configurable symlink, hidden file, and unreadable path handling
• No framework or third-party runtime dependencies

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:

resources/config/roots.yaml

This defines the baseline discovery rules.

2. Project Override

You can override or extend discovery behavior by adding:

config/roots.yaml

or

config/roots.yml

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

discovery:
  roots:
    modules:
      path: modules
      recursive: true

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

discovery:
  roots:
    lib:
      enabled: false

Merge Strategy: How Config Is Built

Configuration is built as:

library defaults + project overrides → final discovery config

Rules:

• Scalars → overridden by project config
• Lists (e.g. exclude) → merged and deduplicated
• Roots → merged by key
• Root options → overridden per root
• Disabled roots → removed from traversal

Architecture: Main Layers

The system is intentionally split into layers:

1. Config Layer

• YamlDiscoveryConfigLoader
• DiscoveryConfigMerger
• 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

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

• 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:

FileLocator
   ↓
ClassLocator (future)
   ↓
RegistryLoader (future)
   ↓
DIRegistry

Notes: Additional Documentation

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

License: Package Terms

MIT