README

The philosophy behind this library is to provide a very basic interface (FileFetcher) that is ideal for 95% of network access cases, such as your typical file_get_contents call. It explicitly does not try to deal with the more complex cases.

Several basic implementations are provided. These include the test doubles you typically need to test services that use the FileFetcher interface. You can easily create an adapter to a more heavy network access library (such as Guzzle) in your own codebase.

Usage

$fileContent = $fileFetcher->fetchFile($fileLocation);

The library provides some trivial implementations of the FileFetcher interface at its heart:

SimpleFileFetcher: Adapter around file_get_contents
InMemoryFileFetcher: Adapter around an array provided to its constructor
ThrowingFileFetcher: Throws a FileFetchingException for all calls
NullFileFetcher: Returns an empty string for all calls
StubFileFetcher: Returns a stub value for all calls
CallbackFileFetcher: Adapter around a callback
LazyStubFileFetcher: Return a lazily retrieved stub value for all calls

It also provides a number of decorators:

ErrorLoggingFileFetcher: Logs errors via the PSR-3 LoggerInterface
SpyingFileFetcher: A spy (test double)

Decorators provided by jeroen/file-fetcher-cache:

PsrCacheFileFetcher: Caches file contents via PSR-16 SimpleCache
CachingFileFetcher: Caches file contents. Requires jeroen/simple-cache to be loaded

Decorators provided by jeroen/file-fetcher-stopwatch:

StopwatchFileFetcher: Profiles calls using Symfony Stopwatch. Requires symfony/stopwatch to be loaded

Installation

You can use Composer to download and install this package as well as its dependencies.

To add this package as a local, per-project dependency to your project, simply add a dependency on jeroen/file-fetcher to your project's composer.json file. Here is a minimal example of a composer.json file that just defines a dependency on FileFetcher 6.x:

{
    "require": {
        "jeroen/file-fetcher": "~6.0"
    }
}

Development

Start by installing the project dependencies by executing

composer update

You can run the tests by executing

make test

You can run the style checks by executing

make cs

To run all CI checks, execute

make ci

You can also invoke PHPUnit directly to pass it arguments, as follows

vendor/bin/phpunit --filter SomeClassNameOrFilter

Release notes

6.1.1 (2025-02-27)

Improved PHP 8.4+ compatibility by explicitly defining nullable types

6.1.0 (2022-04-26)

Added support for installation with psr/log 2.x and 3.x
Raised minimum PHP version from 7.1 to 7.3
Improved type documentation

6.0.0 (2019-01-17)

Breaking changes to increase package stability and avoid the need for breaking changes in the future.

Removed PsrCacheFileFetcher, now part of jeroen/file-fetcher-cache
Removed CachingFileFetcher, now part of jeroen/file-fetcher-cache
Removed StopwatchFileFetcher, now part of jeroen/file-fetcher-stopwatch

5.0.1 (2019-01-16)

PsrCacheFileFetcher now ensures cache keys are valid

5.0.0 (2019-01-16)

Added PsrCacheFileFetcher
Added StopwatchFileFetcher
jeroen/simple-cache, which is needed by CachingFileFetcher is no longer loaded by default

4.5.0 (2018-12-19)

Switched License from GPL-2.0-or-later to BSD-3-Clause

4.4.0 (2018-05-31)

Dropped support for PHP 7.0
Added CallbackFileFetcher
Added LazyStubFileFetcher

4.3.0 (2017-06-10)

Added getFirstFetchedUrl to SpyingFileFetcher
Added $defaultContent constructor parameter to InMemoryFileFetcher

4.2.0 (2017-06-07)

Added StubFileFetcher

4.1.0 (2017-05-11)

Added ThrowingFileFetcher
Added NullFileFetcher

4.0.0 (2017-05-09)

Breaking changes:

Added scalar type hints to the FileFetcher interface and its implementations
Added scalar type hints to FileFetchingException

Other changes:

Dropped support for PHP 5.x
Added ErrorLoggingFileFetcher
Added SpyingFileFetcher

3.1.0 (2016-01-07)

Added InMemoryFileFetcher

3.0.0 (2015-08-21)

Added FileFetchingException, which should now be thrown by implementations of FileFetcher on error
The non-public fields and methods of CachingFileFetcher are now private rather than protected
Added PHPCS and PHPMD integration

2.0.0 (2014-08-19)

Removed FileFetcher.php entry point. Autoloading is now done via Composers PSR-4 support.

1.0.1 (2013-07-06)

Added SimpleFileFetcher implementation

1.0.0 (2013-07-06)

Initial release with FileFetcher interface and CachingFileFetcher implementation

jeroen-de-dauw / file-fetcher

Maintainers

Details