PHPackages                             italystrap/finder - 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. italystrap/finder

ActiveLibrary

italystrap/finder
=================

A file finder for PHP the OOP way

11.4k↓100%2PHP

Since Oct 29Pushed 6mo ago1 watchersCompare

[ Source](https://github.com/ItalyStrap/finder)[ Packagist](https://packagist.org/packages/italystrap/finder)[ RSS](/packages/italystrap-finder/feed)WikiDiscussions master Synced 1mo ago

READMEChangelogDependenciesVersions (1)Used By (2)

ItalyStrap Finder
=================

[](#italystrap-finder)

[![Build Status](https://camo.githubusercontent.com/3f3c5ead515f99963f65c928be0b12758ffbfe2588908c5c77c18d667a47648d/68747470733a2f2f7472617669732d63692e6f72672f4974616c7953747261702f66696e6465722e7376673f6272616e63683d6d6173746572)](https://travis-ci.org/ItalyStrap/finder)[![Latest Stable Version](https://camo.githubusercontent.com/43f65888046fd9af376efdf0cb04ec9209aa8bd96a71890d6dfca390722cbc1d/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6974616c7973747261702f66696e6465722e737667)](https://packagist.org/packages/italystrap/finder)[![Total Downloads](https://camo.githubusercontent.com/48fe4bf75db96ec725ee48a231d6159127e0059ba436572450fd2536a698a7cb/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f6974616c7973747261702f66696e6465722e737667)](https://packagist.org/packages/italystrap/finder)[![Latest Unstable Version](https://camo.githubusercontent.com/a2ddec15e3fbb2e384fc485ad6ffdc69e39f0f4d8e90a590881b06bdf5dea59a/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f767072652f6974616c7973747261702f66696e6465722e737667)](https://packagist.org/packages/italystrap/finder)[![License](https://camo.githubusercontent.com/06e1afcd628a5d938d68ed83c78405e82af78005842f200b1b878d012310f60b/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f6974616c7973747261702f66696e6465722e737667)](https://packagist.org/packages/italystrap/finder)[![PHP from Packagist](https://camo.githubusercontent.com/ccdfa40ffa84271e632117cecb191e4c35f958fd1a7990253b87e0eb355b8c38/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f7068702d762f6974616c7973747261702f66696e646572)](https://camo.githubusercontent.com/ccdfa40ffa84271e632117cecb191e4c35f958fd1a7990253b87e0eb355b8c38/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f7068702d762f6974616c7973747261702f66696e646572)[![Mutation testing badge](https://camo.githubusercontent.com/b71d94cd4f36f0b55259c8555aed942fc2fb1167fe5da13a5317a1e5d3c81e74/68747470733a2f2f696d672e736869656c64732e696f2f656e64706f696e743f7374796c653d666c61742675726c3d687474707325334125324625324662616467652d6170692e737472796b65722d6d757461746f722e696f2532466769746875622e636f6d2532464974616c79537472617025324666696e6465722532466d6173746572)](https://dashboard.stryker-mutator.io/reports/github.com/ItalyStrap/finder/master)

File finder API the OOP way

This is still a WIP repository.

Table Of Contents
-----------------

[](#table-of-contents)

- [Installation](#installation)
- [Basic Usage](#basic-usage)
- [Advanced Usage](#advanced-usage)
- [Contributing](#contributing)
- [License](#license)

Installation
------------

[](#installation)

The best way to use this package is through Composer:

```
composer require italystrap/finder
```

This package adheres to the [SemVer](http://semver.org/) specification and will be fully backward compatible between minor versions.

Basic Usage
-----------

[](#basic-usage)

### Feature: search the first file available inside many directories

[](#feature-search-the-first-file-available-inside-many-directories)

```
Given a list of file name
    And a list of directories to search on
When I search a file
Then the first available file is returned

```

**Basic example**

*files*

```
    $list_of_file = [
        'file-specialized.php',
        'file.php',
    ];
```

*directories*

```
    $dirs = [
        'my/theme/child/template', // First dir to search the file
        'my/theme/parent/template', // Second dir to search the file
    ];
```

If `file-specialized.php` exists in one of the given directories it will return the name and full path of the file. `my/theme/child/template/file-specialized.php`or `my/theme/parent/template/file-specialized.php`

If the `file-specialized.php` is not found then will search for `file.php` and return full path if exists `my/theme/child/template/file.php`or `my/theme/parent/template/file.php`

If no `file.php` is founded it will throw an error message.

*real code example*

```
use ItalyStrap\Finder\Finder;
use ItalyStrap\Finder\FilesHierarchyIterator;
use ItalyStrap\Finder\FileInfoFactory;
use ItalyStrap\Finder\FinderFactory;

    $dirs = [
        'my/theme/child/template', // First dir to search the file
        'my/theme/parent/template', // Second dir to search the file
    ];

$find = new Finder( new FilesHierarchyIterator( new FileInfoFactory() ) );
//or
$find = ( new FinderFactory() )->make();
$find->in( $dirs );

// Will search for:
// my/theme/child/template/file-specialized.php
// my/theme/child/template/file.php
// my/theme/parent/template/file-specialized.php
// my/theme/parent/template/file.php
/**
 * @var \SplFileInfo $files_found
 */
$file_found = $find->firstFile(['file', 'specialized'], 'php', '-');
```

### Feature: search the asset file with priority

[](#feature-search-the-asset-file-with-priority)

```
Given a list of file name
    And a list of directories to search on
When I search an asset file
Then the file with highest priority file is returned

```

**Basic example**

*files*

```
    $min = \defined( 'WP_DEBUG' ) && WP_DEBUG ? '.min' : '';

    $list_of_file = [
        'style' . $min . '.css',
    ];
```

*directories*

```
    $dirs = [
        'my/theme/child/asset/css', // First dir to search the file
        'my/theme/parent/asset/css', // Second dir to search the file
    ];
```

If `style` exists in one of the given directories it will return the name and full path of the file from the directory with highest priority `my/theme/child/asset/css/style.css`

If the `style.css` is not found in the child directory then will search in parent directory and return full path if exists `my/theme/parent/asset/css/style.css`

If no `style.css` is founded it will throw an error message.

*real code example*

```
use ItalyStrap\Finder\Finder;
use ItalyStrap\Finder\FilesHierarchyIterator;
use ItalyStrap\Finder\FileInfoFactory;
use ItalyStrap\Finder\FinderFactory;

    $min = \defined( 'WP_DEBUG' ) && WP_DEBUG ? '.min' : '';
    $dirs = [
        'my/theme/child/asset/css', // First dir to search the file
        'my/theme/parent/asset/css', // Second dir to search the file
    ];

$find = new Finder( new FilesHierarchyIterator( new FileInfoFactory() ) );
//or
$find = ( new FinderFactory() )->make();
$find->in( $dirs );

// Will search for:
// my/theme/child/asset/css/style.min.css
// my/theme/child/asset/css/style.css
// my/theme/parent/asset/css/style.min.css
// my/theme/parent/asset/css/style.css
/**
 * @var \SplFileInfo $files_found
 */
$file_found = $find->firstFile(['style', $min], 'css', '.');
```

### Feature: search the config files

[](#feature-search-the-config-files)

```
Given a name of a config file
    And a list of directories to search on
When I search the config files
Then The list of all file with the same name founded are returned sorted

```

**Basic example**

*files*

```
    $list_of_file = [
        'config.php',
    ];
```

*directories*

```
    $dirs = [
        'my/theme/child/config', // First dir to search the file
        'my/theme/parent/config', // Second dir to search the file
    ];
```

If `config.php` exists in one or all of the given directories it will return the name and full path of the files from the directory `my/theme/child/config/config.php``my/theme/parent/config/config.php`

If no `config.php` is founded it will throw an error message.

*real code example*

```
use ItalyStrap\Finder\Finder;
use ItalyStrap\Finder\FilesHierarchyIterator;
use ItalyStrap\Finder\FileInfoFactory;
use ItalyStrap\Finder\FinderFactory;

    $dirs = [
        'my/theme/child/config', // First dir to search the file
        'my/theme/parent/config', // Second dir to search the file
    ];

$find = new Finder( new FilesHierarchyIterator( new FileInfoFactory() ) );
//or
$find = ( new FinderFactory() )->make();
$find->in( $dirs );

// Will search for:
// my/theme/child/config/config.php
// my/theme/parent/config/config.php
/**
 * @var array $files_found
 */
$files_found = $find->allFiles(['config'], 'php', '-');
```

Advanced Usage
--------------

[](#advanced-usage)

Contributing
------------

[](#contributing)

All feedback / bug reports / pull requests are welcome.

License
-------

[](#license)

Copyright (c) 2019 Enea Overclokk, ItalyStrap

This code is licensed under the [MIT](LICENSE).

Credits
-------

[](#credits)

###  Health Score

23

—

LowBetter than 27% of packages

Maintenance49

Moderate activity, may be stable

Popularity20

Limited adoption so far

Community9

Small or concentrated contributor base

Maturity12

Early-stage or recently created project

 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.

### Community

Maintainers

![](https://www.gravatar.com/avatar/13d145319a065be260ee79e728655780ddd63002e5ac6c317701c8996ec8d94c?d=identicon)[overclokk](/maintainers/overclokk)

---

Top Contributors

[![overclokk](https://avatars.githubusercontent.com/u/4604932?v=4)](https://github.com/overclokk "overclokk (53 commits)")

---

Tags

finderphpwordpress-php-library

### Embed Badge

![Health badge](/badges/italystrap-finder/health.svg)

```
[![Health](https://phpackages.com/badges/italystrap-finder/health.svg)](https://phpackages.com/packages/italystrap-finder)
```

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)