UserFrosting API

ResourceLocator implements ResourceLocatorInterface

ResourceLocator Class.

The locator is used to find resources.

Tags
author

Louis Charette

Table of Contents

$streams The list of registered streams :: [ 'stream_name' => [ 'prefix' => [ ResourceStreamInterface ] ] ]. array>
$locations \UserFrosting\UniformResourceLocator\ResourceLocationInterface[]
$cache (\UserFrosting\UniformResourceLocator\ResourceInterface[]|\UserFrosting\UniformResourceLocator\ResourceInterface|bool)[]
$basePath string
$filesystem Filesystem
$separator string
$streamBuilder StreamBuilder
$reservedStreams string[]
__construct() Constructor. mixed
__invoke() string|bool
addStream() Add an exisitng ResourceStream to the stream list. static
setupStreamWrapper() Register the scheme as a php stream wrapper. void
unsetStreamWrapper() Unset a php stream wrapper. void
registerStream() Register a new stream. static
registerSharedStream() Register a new shared stream. static
addPath() AddPath function. Used to preserve compatibility with RocketTheme/Toolbox. void
removeStream() Unregister the specified stream. static
getStream() Return information about a specfic stream. array
getStreams() Return information about a all registered stream. array>
listStreams() Return a list of all the stream scheme registered. string[]
schemeExists() Returns true if a stream has been defined. bool
addLocation() Add an existing RessourceLocation instance to the location list. static
registerLocation() Register a new location. static
removeLocation() Unregister the specified location. static
getLocation() Get a location instance based on it's name. ResourceLocationInterface
getLocations() Get a a list of all registered locations. \UserFrosting\UniformResourceLocator\ResourceLocationInterface[]
listLocations() Return a list of all the locations registered by name. string[]
locationExist() Returns true if a location has been defined. bool
getResource() Return a resource instance. ResourceInterface|bool
getResources() Return a list of resources instances. \UserFrosting\UniformResourceLocator\ResourceInterface[]
listResources() List all ressources found at a given uri. \UserFrosting\UniformResourceLocator\ResourceInterface[]
reset() Reset locator by removing all the registered streams and locations. static
normalize() Returns the canonicalized URI on success. string|array|bool
isStream() Returns true if uri is resolvable by using locator. bool
findResource() Find highest priority instance from a resource. Return the path for said resource For example, if looking for a `test.json` ressource, only the top priority instance of `test.json` found will be returned. string|bool
findResources() Find all instances from a resource. Return an array of paths for said resource For example, if looking for a `test.json` ressource, all instance of `test.json` found will be listed. string[]
findCached() Find a resource from the cached properties. \UserFrosting\UniformResourceLocator\ResourceInterface[]|ResourceInterface|bool
searchPaths() Build the search path out of the defined strean and locations. array
find() Returns path of a file (or directory) based on a search uri. ResourceInterface|\UserFrosting\UniformResourceLocator\ResourceInterface[]
getStreamBuilder() StreamBuilder
getBasePath() string
setBasePath() static

Properties

$streams

The list of registered streams :: [ 'stream_name' => [ 'prefix' => [ ResourceStreamInterface ] ] ].

protected array> $streams = []

$locations

protected \UserFrosting\UniformResourceLocator\ResourceLocationInterface[] $locations = []

$cache

protected (\UserFrosting\UniformResourceLocator\ResourceInterface[]|\UserFrosting\UniformResourceLocator\ResourceInterface|bool)[] $cache = []

Methods

__construct()

Constructor.

public __construct( [ $basePath : string = '' ] ) : mixed
Parameters
$basePath : string = ''

(default '')

Return values
mixed

__invoke()

public __invoke( $uri : mixed ) : string|bool
Parameters
$uri : mixed
Return values
string|bool

setupStreamWrapper()

Register the scheme as a php stream wrapper.

protected setupStreamWrapper( $scheme : string ) : void
Parameters
$scheme : string

The stream scheme

unsetStreamWrapper()

Unset a php stream wrapper.

protected unsetStreamWrapper( $scheme : string ) : void
Parameters
$scheme : string

The stream scheme

registerStream()

Register a new stream.

public registerStream( $scheme : string [, $prefix : string = '' ] [, $paths : mixed = null ] [, $shared : bool = false ] ) : static
Parameters
$scheme : string
$prefix : string = ''

(default '')

$paths : mixed = null

(default null). When using null path, the scheme will be used as a path

$shared : bool = false

(default false) Shared resoureces are not affected by locations

Return values
static

registerSharedStream()

Register a new shared stream.

public registerSharedStream( $scheme : string [, $prefix : string = '' ] [, $paths : string|string[]|null = null ] ) : static

Shortcut for registerStream with $shared flag set to true.

Parameters
$scheme : string
$prefix : string = ''

(default '')

$paths : string|string[]|null = null

(default null). When using null path, the scheme will be used as a path

Return values
static

addPath()

AddPath function. Used to preserve compatibility with RocketTheme/Toolbox.

public addPath( $scheme : string , $prefix : string , $paths : string|string[] [, $override : bool|string = false ] [, $force : bool = false ] ) : void
Parameters
$scheme : string
$prefix : string
$paths : string|string[]
$override : bool|string = false

Not used. Kept for backward compatibility.

$force : bool = false

Not used. Kept for backward compatibility.

Tags
deprecated

removeStream()

Unregister the specified stream.

public removeStream( $scheme : string ) : static
Parameters
$scheme : string

The stream scheme

Return values
static

getStream()

Return information about a specfic stream.

public getStream( $scheme : string ) : array

Return value is an array of ResourceStreamInterface, for each prefix For example : $array = array( '' => ResourceStreamInterface, 'prefix' => ResourceStreamInterface );.

Parameters
$scheme : string

The stream scheme

Return values
array

getStreams()

Return information about a all registered stream.

public getStreams( ) : array>

Return value is an array of array of ResourceStreamInterface, for each prefix For example : 'bar' => array( '' => ResourceStreamInterface, 'prefix' => ResourceStreamInterface ), 'foo' => array( '' => ResourceStreamInterface, 'blah' => ResourceStreamInterface );.

Return values
array>

listStreams()

Return a list of all the stream scheme registered.

public listStreams( ) : string[]
Return values
string[] —

An array of registered scheme => location

schemeExists()

Returns true if a stream has been defined.

public schemeExists( $scheme : string ) : bool
Parameters
$scheme : string

The stream scheme

Return values
bool

registerLocation()

Register a new location.

public registerLocation( $name : string [, $path : string|null = null ] ) : static
Parameters
$name : string

The location name

$path : string|null = null

The location base path (default null)

Return values
static

removeLocation()

Unregister the specified location.

public removeLocation( $name : string ) : static
Parameters
$name : string

The location name

Return values
static

getLocations()

Get a a list of all registered locations.

public getLocations( ) : \UserFrosting\UniformResourceLocator\ResourceLocationInterface[]
Return values
\UserFrosting\UniformResourceLocator\ResourceLocationInterface[]

listLocations()

Return a list of all the locations registered by name.

public listLocations( ) : string[]
Return values
string[] —

An array of registered name => location

locationExist()

Returns true if a location has been defined.

public locationExist( $name : string ) : bool
Parameters
$name : string

The location name

Return values
bool

getResource()

Return a resource instance.

public getResource( $uri : string [, $first : bool = false ] ) : ResourceInterface|bool
Parameters
$uri : string

Input URI to be searched (can be a file/path)

$first : bool = false

Whether to return first path even if it doesn't exist.

Return values
ResourceInterface|bool —

Returns false if resource is not found

getResources()

Return a list of resources instances.

public getResources( $uri : string [, $all : bool = false ] ) : \UserFrosting\UniformResourceLocator\ResourceInterface[]
Parameters
$uri : string

Input URI to be searched (can be a file/path)

$all : bool = false

Whether to return all paths even if they don't exist.

Return values
\UserFrosting\UniformResourceLocator\ResourceInterface[] —

Array of Resources

listResources()

List all ressources found at a given uri.

public listResources( $uri : string [, $all : bool = false ] [, $sort : bool = true ] ) : \UserFrosting\UniformResourceLocator\ResourceInterface[]

Same as listing all file in a directory, except here all topmost ressources will be returned when considering all locations.

Parameters
$uri : string

Input URI to be searched (can be a uri/path ONLY)

$all : bool = false

If true, all resources will be returned, not only topmost ones

$sort : bool = true

Set to true to sort results alphabetically by absolute path. Set to false to sort by absolute priority, higest location first. Default to true.

Return values
\UserFrosting\UniformResourceLocator\ResourceInterface[] —

The ressources list

reset()

Reset locator by removing all the registered streams and locations.

public reset( ) : static
Return values
static

normalize()

Returns the canonicalized URI on success.

public normalize( $uri : string [, $throwException : bool = false ] [, $splitStream : bool = false ] ) : string|array|bool

The resulting path will have no '/./' or '/../' components. Trailing delimiter / is kept. Can also split the scheme for the path part of the uri if $splitStream parameter is set to true By default (if $throwException parameter is not set to true) returns false on failure.

Parameters
$uri : string
$throwException : bool = false
$splitStream : bool = false
Tags
throws
BadMethodCallException
Return values
string|array|bool

isStream()

Returns true if uri is resolvable by using locator.

public isStream( $uri : string ) : bool
Parameters
$uri : string

URI to test

Return values
bool —

True if is resolvable

findResource()

Find highest priority instance from a resource. Return the path for said resource For example, if looking for a `test.json` ressource, only the top priority instance of `test.json` found will be returned.

public findResource( $uri : string [, $absolute : bool = true ] [, $first : bool = false ] ) : string|bool
Parameters
$uri : string

Input URI to be searched (can be a file or directory)

$absolute : bool = true

Whether to return absolute path.

$first : bool = false

Whether to return first path even if it doesn't exist.

Tags
throws
BadMethodCallException
Return values
string|bool —

The ressource path, or false if not found resource

findResources()

Find all instances from a resource. Return an array of paths for said resource For example, if looking for a `test.json` ressource, all instance of `test.json` found will be listed.

public findResources( $uri : string [, $absolute : bool = true ] [, $all : bool = false ] ) : string[]
Parameters
$uri : string

Input URI to be searched (can be a file or directory)

$absolute : bool = true

Whether to return absolute path.

$all : bool = false

Whether to return all paths even if they don't exist.

Return values
string[] —

An array of all the ressources path

findCached()

Find a resource from the cached properties.

protected findCached( $uri : string , $array : bool , $all : bool ) : \UserFrosting\UniformResourceLocator\ResourceInterface[]|ResourceInterface|bool
Parameters
$uri : string

Input URI to be searched (file or directory)

$array : bool

Return an array or a single path

$all : bool

Whether to return all paths even if they don't exist.

Return values
\UserFrosting\UniformResourceLocator\ResourceInterface[]|ResourceInterface|bool —

The ressource path or an array of all the ressources path or false if not resource can be found

searchPaths()

Build the search path out of the defined strean and locations.

protected searchPaths( $stream : ResourceStreamInterface ) : array

If the scheme is shared, we don't need to involve locations and can return it's path directly.

Parameters
$stream : ResourceStreamInterface

The stream to search for

Return values
array —

The search paths based on this stream and all available locations

find()

Returns path of a file (or directory) based on a search uri.

protected find( $scheme : string , $file : string , $array : bool , $all : bool ) : ResourceInterface|\UserFrosting\UniformResourceLocator\ResourceInterface[]
Parameters
$scheme : string

The scheme to search in

$file : string

The file to search for

$array : bool

Return an array or a single path

$all : bool

Whether to return all paths even if they don't exist.

Tags
throws
InvalidArgumentException
Return values
ResourceInterface|\UserFrosting\UniformResourceLocator\ResourceInterface[]

getStreamBuilder()

public getStreamBuilder( ) : StreamBuilder
Return values
StreamBuilder

setBasePath()

public setBasePath( $basePath : string ) : static
Parameters
$basePath : string
Return values
static

Search results