1. class
  2. Hypervel
  3. \
  4. Filesystem
  5. \
  6. ScopedFilesystemProxy

ScopedFilesystemProxy

class ScopedFilesystemProxy implements Filesystem

Isolate every filesystem path behind a dynamically resolved prefix on a fixed disk or one resolved for each operation.

This class deliberately maps the complete path-bearing adapter surface and rejects every unknown call. Percent-encoded segments remain literal names; URL decoding belongs at the HTTP boundary and must happen exactly once.

Traits

Conditionable
TransfersFiles

Properties

protected PathNormalizer $normalizer

Methods

mixed
when(mixed $value = null, callable|null $callback = null, callable|null $default = null)

Apply the callback if the given "value" is (or resolves to) truthy.

from  Conditionable
mixed
unless(mixed $value = null, callable|null $callback = null, callable|null $default = null)

Apply the callback if the given "value" is (or resolves to) falsy.

from  Conditionable
bool
copyToDisk(Filesystem|string|UnitEnum $disk, string $from, string|null $to = null)

Copy a scoped file to another disk.

bool
moveToDisk(Filesystem|string|UnitEnum $disk, string $from, string|null $to = null)

Move a scoped file to another disk.

bool
transferFile(Filesystem $source, string $from, Filesystem $destination, string $to)

Transfer a file without holding a source lease during the destination write.

from  TransfersFiles
__construct(Filesystem|Closure $disk, Closure $prefixResolver, bool $allowRootPassthrough = false)

Create a dynamically scoped filesystem.

ScopedFilesystemProxy
assertExists(array|string $path, string|null $content = null)

Assert that the given file or directory exists.

ScopedFilesystemProxy
assertCount(string $path, int $count, bool $recursive = false)

Assert that the number of files in path equals the expected count.

ScopedFilesystemProxy
assertMissing(array|string $path)

Assert that the given file or directory does not exist.

ScopedFilesystemProxy
assertDirectoryEmpty(string $path)

Assert that the given directory is empty.

ScopedFilesystemProxy
assertEmpty()

Assert that the scoped disk contains no files.

string
path(string $path)

Get the full path to a scoped file.

bool
has(string $location)

Determine if a scoped path exists using the Flysystem operator.

string
read(string $location)

Read a scoped file using the Flysystem operator.

int
fileSize(string $path)

Get a scoped file size using the Flysystem operator.

string
visibility(string $path)

Get raw Flysystem visibility for a scoped path.

void
write(string $location, string $contents, array $config = [])

Write a scoped file using the Flysystem operator.

void
createDirectory(string $location, array $config = [])

Create a scoped directory using the Flysystem operator.

bool
exists(string $path)

Determine if a scoped file or directory exists.

bool
missing(string $path)

Determine if a scoped file or directory is missing.

bool
fileExists(string $path)

Determine if a scoped file exists.

bool
fileMissing(string $path)

Determine if a scoped file is missing.

bool
directoryExists(string $path)

Determine if a scoped directory exists.

bool
directoryMissing(string $path)

Determine if a scoped directory is missing.

string|null
get(string $path)

Get the contents of a scoped file.

array|bool|float|int|string|null
json(string $path, int $flags = 0)

Get the contents of a scoped file as decoded JSON.

StreamedResponse
response(string $path, string|null $name = null, array $headers = [], string $disposition = 'inline')

Create a streamed response for a scoped file.

Response
serve(Request $request, string $path, string|null $name = null, array $headers = [])

Create a streamed response for serving a scoped file.

StreamedResponse
download(string $path, string|null $name = null, array $headers = [])

Create a streamed download response for a scoped file.

Image
image(string $path)

Create an image instance from a scoped file in storage.

bool|string
put(string $path, mixed $contents, mixed $options = [])

Write the contents of a scoped file.

false|string
putFile(string|File|UploadedFile $path, array|string|File|UploadedFile|null $file = null, mixed $options = [])

Store an uploaded file on the scoped disk.

false|string
putFileAs(string|File|UploadedFile $path, array|string|File|UploadedFile|null $file, array|string|null $name = null, mixed $options = [])

Store an uploaded file with a given name on the scoped disk.

bool
writeStream(string $path, mixed $resource, array $options = [])

Write a scoped file using a stream.

string
getVisibility(string $path)

Get the visibility for a scoped path.

bool
setVisibility(string $path, string $visibility)

Set the visibility for a scoped path.

bool
prepend(string $path, string $data, string $separator = PHP_EOL)

Prepend to a scoped file.

bool
append(string $path, string $data, string $separator = PHP_EOL)

Append to a scoped file.

bool
delete(array|string $paths)

Delete scoped files.

bool
copy(string $from, string $to)

Copy a scoped file to another scoped path.

bool
move(string $from, string $to)

Move a scoped file to another scoped path.

bool
transferToDisk(Filesystem|string|UnitEnum $disk, string $from, string|null $to, bool $move)

Transfer a file using one resolved source disk and prefix.

int
size(string $path)

Get the size of a scoped file.

false|string
checksum(string $path, array $options = [])

Get the checksum of a scoped file.

false|string
mimeType(string $path)

Get the MIME type of a scoped file.

int
lastModified(string $path)

Get the last modification time of a scoped file.

mixed
readStream(string $path)

Get a stream for a scoped file.

mixed
readStreamRange(string $path, int|null $start, int|null $end)

Get a partial stream for a scoped file.

string
temporaryUrl(string $path, DateTimeInterface $expiration, array $options = [])

Get a temporary URL for a scoped file.

array|string
temporaryUploadUrl(string $path, DateTimeInterface $expiration, array $options = [])

Get a temporary upload URL for a scoped file.

bool
providesTemporaryUrls()

Determine if the inner disk provides temporary URLs.

bool
providesTemporaryUploadUrls()

Determine if the inner disk provides temporary upload URLs.

array
getConfig()

Get the inner disk configuration.

array
files(string|null $directory = null, bool $recursive = false)

Get scoped files in a directory.

array
allFiles(string|null $directory = null)

Get all scoped files in a directory recursively.

array
directories(string|null $directory = null, bool $recursive = false)

Get scoped directories in a directory.

array
allDirectories(string|null $directory = null)

Get all scoped directories in a directory recursively.

bool
makeDirectory(string $path)

Create a scoped directory.

bool
deleteDirectory(string $directory)

Delete a scoped directory recursively.

never
getDriver()

Reject access to the inner Flysystem driver.

never
getAdapter()

Reject access to the inner Flysystem adapter.

never
getClient()

Reject access to the inner driver client.

never
serveUsing(Closure|null $callback)

Reject mutation of the shared inner disk's serve callback.

never
buildTemporaryUrlsUsing(Closure|null $callback)

Reject mutation of the shared inner disk's temporary URL callback.

never
buildTemporaryUploadUrlsUsing(Closure|null $callback)

Reject mutation of the shared inner disk's temporary upload URL callback.

never
__call(string $method, array $parameters)

Reject calls that have not been explicitly mapped through the prefix boundary.

string
prefix()

Resolve and validate the prefix for one public operation.

string
applyPrefix(string $prefix, string $path)

Apply a validated prefix to a normalized user path.

string
stripPrefix(string $prefix, string $path)

Strip a validated prefix from an inner returned path.

Filesystem
resolveDisk()

Resolve the inner filesystem for one public operation.

mixed
call(string $method, array $arguments)

Forward one audited method to the inner disk.

RuntimeException
unsupportedMutationOrInternal(string $method)

Create the exception for every rejected internal or shared-state mutator.

Details

in Conditionable at line 23
mixed when(mixed $value = null, callable|null $callback = null, callable|null $default = null)

Apply the callback if the given "value" is (or resolves to) truthy.

Parameters

mixed $value
callable|null $callback
callable|null $default

Return Value

mixed

in Conditionable at line 56
mixed unless(mixed $value = null, callable|null $callback = null, callable|null $default = null)

Apply the callback if the given "value" is (or resolves to) falsy.

Parameters

mixed $value
callable|null $callback
callable|null $default

Return Value

mixed

at line 477
bool copyToDisk(Filesystem|string|UnitEnum $disk, string $from, string|null $to = null)

Copy a scoped file to another disk.

Parameters

Filesystem|string|UnitEnum $disk
string $from
string|null $to

Return Value

bool

at line 485
bool moveToDisk(Filesystem|string|UnitEnum $disk, string $from, string|null $to = null)

Move a scoped file to another disk.

Parameters

Filesystem|string|UnitEnum $disk
string $from
string|null $to

Return Value

bool

in TransfersFiles at line 41
protected bool transferFile(Filesystem $source, string $from, Filesystem $destination, string $to)

Transfer a file without holding a source lease during the destination write.

Parameters

Filesystem $source
string $from
Filesystem $destination
string $to

Return Value

bool

at line 50
__construct(Filesystem|Closure $disk, Closure $prefixResolver, bool $allowRootPassthrough = false)

Create a dynamically scoped filesystem.

Parameters

Filesystem|Closure $disk
Closure $prefixResolver
bool $allowRootPassthrough

at line 61
ScopedFilesystemProxy assertExists(array|string $path, string|null $content = null)

Assert that the given file or directory exists.

Parameters

array|string $path
string|null $content

Return Value

ScopedFilesystemProxy

at line 75
ScopedFilesystemProxy assertCount(string $path, int $count, bool $recursive = false)

Assert that the number of files in path equals the expected count.

Parameters

string $path
int $count
bool $recursive

Return Value

ScopedFilesystemProxy

at line 86
ScopedFilesystemProxy assertMissing(array|string $path)

Assert that the given file or directory does not exist.

Parameters

array|string $path

Return Value

ScopedFilesystemProxy

at line 100
ScopedFilesystemProxy assertDirectoryEmpty(string $path)

Assert that the given directory is empty.

Parameters

string $path

Return Value

ScopedFilesystemProxy

at line 111
ScopedFilesystemProxy assertEmpty()

Assert that the scoped disk contains no files.

Return Value

ScopedFilesystemProxy

at line 122
string path(string $path)

Get the full path to a scoped file.

Parameters

string $path

Return Value

string

at line 132
bool has(string $location)

Determine if a scoped path exists using the Flysystem operator.

Parameters

string $location

Return Value

bool

at line 142
string read(string $location)

Read a scoped file using the Flysystem operator.

Parameters

string $location

Return Value

string

at line 152
int fileSize(string $path)

Get a scoped file size using the Flysystem operator.

Parameters

string $path

Return Value

int

at line 162
string visibility(string $path)

Get raw Flysystem visibility for a scoped path.

Parameters

string $path

Return Value

string

at line 172
void write(string $location, string $contents, array $config = [])

Write a scoped file using the Flysystem operator.

Parameters

string $location
string $contents
array $config

Return Value

void

at line 181
void createDirectory(string $location, array $config = [])

Create a scoped directory using the Flysystem operator.

Parameters

string $location
array $config

Return Value

void

at line 190
bool exists(string $path)

Determine if a scoped file or directory exists.

Parameters

string $path

Return Value

bool

at line 200
bool missing(string $path)

Determine if a scoped file or directory is missing.

Parameters

string $path

Return Value

bool

at line 210
bool fileExists(string $path)

Determine if a scoped file exists.

Parameters

string $path

Return Value

bool

at line 220
bool fileMissing(string $path)

Determine if a scoped file is missing.

Parameters

string $path

Return Value

bool

at line 230
bool directoryExists(string $path)

Determine if a scoped directory exists.

Parameters

string $path

Return Value

bool

at line 240
bool directoryMissing(string $path)

Determine if a scoped directory is missing.

Parameters

string $path

Return Value

bool

at line 250
string|null get(string $path)

Get the contents of a scoped file.

Parameters

string $path

Return Value

string|null

at line 260
array|bool|float|int|string|null json(string $path, int $flags = 0)

Get the contents of a scoped file as decoded JSON.

Parameters

string $path
int $flags

Return Value

array|bool|float|int|string|null

at line 270
StreamedResponse response(string $path, string|null $name = null, array $headers = [], string $disposition = 'inline')

Create a streamed response for a scoped file.

Parameters

string $path
string|null $name
array $headers
string $disposition

Return Value

StreamedResponse

at line 289
Response serve(Request $request, string $path, string|null $name = null, array $headers = [])

Create a streamed response for serving a scoped file.

Parameters

Request $request
string $path
string|null $name
array $headers

Return Value

Response

at line 304
StreamedResponse download(string $path, string|null $name = null, array $headers = [])

Create a streamed download response for a scoped file.

Parameters

string $path
string|null $name
array $headers

Return Value

StreamedResponse

at line 314
Image image(string $path)

Create an image instance from a scoped file in storage.

Parameters

string $path

Return Value

Image

at line 332
bool|string put(string $path, mixed $contents, mixed $options = [])

Write the contents of a scoped file.

Parameters

string $path
mixed $contents
mixed $options

Return Value

bool|string

at line 343
false|string putFile(string|File|UploadedFile $path, array|string|File|UploadedFile|null $file = null, mixed $options = [])

Store an uploaded file on the scoped disk.

Parameters

string|File|UploadedFile $path
array|string|File|UploadedFile|null $file
mixed $options

Return Value

false|string

at line 362
false|string putFileAs(string|File|UploadedFile $path, array|string|File|UploadedFile|null $file, array|string|null $name = null, mixed $options = [])

Store an uploaded file with a given name on the scoped disk.

Parameters

string|File|UploadedFile $path
array|string|File|UploadedFile|null $file
array|string|null $name
mixed $options

Return Value

false|string

at line 388
bool writeStream(string $path, mixed $resource, array $options = [])

Write a scoped file using a stream.

Parameters

string $path
mixed $resource
array $options

Return Value

bool

at line 398
string getVisibility(string $path)

Get the visibility for a scoped path.

Parameters

string $path

Return Value

string

at line 408
bool setVisibility(string $path, string $visibility)

Set the visibility for a scoped path.

Parameters

string $path
string $visibility

Return Value

bool

at line 418
bool prepend(string $path, string $data, string $separator = PHP_EOL)

Prepend to a scoped file.

Parameters

string $path
string $data
string $separator

Return Value

bool

at line 428
bool append(string $path, string $data, string $separator = PHP_EOL)

Append to a scoped file.

Parameters

string $path
string $data
string $separator

Return Value

bool

at line 438
bool delete(array|string $paths)

Delete scoped files.

Parameters

array|string $paths

Return Value

bool

at line 451
bool copy(string $from, string $to)

Copy a scoped file to another scoped path.

Parameters

string $from
string $to

Return Value

bool

at line 464
bool move(string $from, string $to)

Move a scoped file to another scoped path.

Parameters

string $from
string $to

Return Value

bool

at line 493
protected bool transferToDisk(Filesystem|string|UnitEnum $disk, string $from, string|null $to, bool $move)

Transfer a file using one resolved source disk and prefix.

Parameters

Filesystem|string|UnitEnum $disk
string $from
string|null $to
bool $move

Return Value

bool

at line 516
int size(string $path)

Get the size of a scoped file.

Parameters

string $path

Return Value

int

at line 526
false|string checksum(string $path, array $options = [])

Get the checksum of a scoped file.

Parameters

string $path
array $options

Return Value

false|string

at line 536
false|string mimeType(string $path)

Get the MIME type of a scoped file.

Parameters

string $path

Return Value

false|string

at line 546
int lastModified(string $path)

Get the last modification time of a scoped file.

Parameters

string $path

Return Value

int

at line 558
mixed readStream(string $path)

Get a stream for a scoped file.

Parameters

string $path

Return Value

mixed

the path resource or null on failure

at line 570
mixed readStreamRange(string $path, int|null $start, int|null $end)

Get a partial stream for a scoped file.

Parameters

string $path
int|null $start
int|null $end

Return Value

mixed

the path resource or null on failure

at line 580
string temporaryUrl(string $path, DateTimeInterface $expiration, array $options = [])

Get a temporary URL for a scoped file.

Parameters

string $path
DateTimeInterface $expiration
array $options

Return Value

string

at line 590
array|string temporaryUploadUrl(string $path, DateTimeInterface $expiration, array $options = [])

Get a temporary upload URL for a scoped file.

Parameters

string $path
DateTimeInterface $expiration
array $options

Return Value

array|string

at line 603
bool providesTemporaryUrls()

Determine if the inner disk provides temporary URLs.

Return Value

bool

at line 611
bool providesTemporaryUploadUrls()

Determine if the inner disk provides temporary upload URLs.

Return Value

bool

at line 619
array getConfig()

Get the inner disk configuration.

Return Value

array

at line 627
array files(string|null $directory = null, bool $recursive = false)

Get scoped files in a directory.

Parameters

string|null $directory
bool $recursive

Return Value

array

at line 641
array allFiles(string|null $directory = null)

Get all scoped files in a directory recursively.

Parameters

string|null $directory

Return Value

array

at line 652
array directories(string|null $directory = null, bool $recursive = false)

Get scoped directories in a directory.

Parameters

string|null $directory
bool $recursive

Return Value

array

at line 666
array allDirectories(string|null $directory = null)

Get all scoped directories in a directory recursively.

Parameters

string|null $directory

Return Value

array

at line 677
bool makeDirectory(string $path)

Create a scoped directory.

Parameters

string $path

Return Value

bool

at line 687
bool deleteDirectory(string $directory)

Delete a scoped directory recursively.

Parameters

string $directory

Return Value

bool

at line 697
never getDriver()

Reject access to the inner Flysystem driver.

Return Value

never

at line 705
never getAdapter()

Reject access to the inner Flysystem adapter.

Return Value

never

at line 713
never getClient()

Reject access to the inner driver client.

Return Value

never

at line 721
never serveUsing(Closure|null $callback)

Reject mutation of the shared inner disk's serve callback.

Parameters

Closure|null $callback

Return Value

never

at line 729
never buildTemporaryUrlsUsing(Closure|null $callback)

Reject mutation of the shared inner disk's temporary URL callback.

Parameters

Closure|null $callback

Return Value

never

at line 737
never buildTemporaryUploadUrlsUsing(Closure|null $callback)

Reject mutation of the shared inner disk's temporary upload URL callback.

Parameters

Closure|null $callback

Return Value

never

at line 745
never __call(string $method, array $parameters)

Reject calls that have not been explicitly mapped through the prefix boundary.

Parameters

string $method
array $parameters

Return Value

never

at line 755
protected string prefix()

Resolve and validate the prefix for one public operation.

Return Value

string

at line 772
protected string applyPrefix(string $prefix, string $path)

Apply a validated prefix to a normalized user path.

Parameters

string $prefix
string $path

Return Value

string

at line 782
protected string stripPrefix(string $prefix, string $path)

Strip a validated prefix from an inner returned path.

Parameters

string $prefix
string $path

Return Value

string

at line 804
protected Filesystem resolveDisk()

Resolve the inner filesystem for one public operation.

Return Value

Filesystem

at line 814
protected mixed call(string $method, array $arguments)

Forward one audited method to the inner disk.

Parameters

string $method
array $arguments

Return Value

mixed

at line 840
protected RuntimeException unsupportedMutationOrInternal(string $method)

Create the exception for every rejected internal or shared-state mutator.

Parameters

string $method

Return Value

RuntimeException