api.md

Table of contents

• \UserFrosting\UniformResourceLocator\ResourceLocation
• \UserFrosting\UniformResourceLocator\ResourceLocationInterface (interface)
• \UserFrosting\UniformResourceLocator\ResourceStream
• \UserFrosting\UniformResourceLocator\ResourceLocatorInterface (interface)
• \UserFrosting\UniformResourceLocator\ResourceInterface (interface)
• \UserFrosting\UniformResourceLocator\Resource
• \UserFrosting\UniformResourceLocator\ResourceLocator
• \UserFrosting\UniformResourceLocator\ResourceStreamInterface (interface)
• \UserFrosting\UniformResourceLocator\Exception\StreamNotFoundException
• \UserFrosting\UniformResourceLocator\Exception\LocationNotFoundException

---

Class: \UserFrosting\UniformResourceLocator\ResourceLocation

ResourceLocation Class The representation of a location

Visibility	Function
public	__construct(string $name</strong>, <em>string/null</em> <strong>$path=null) : void Constructor
public	getName() : string
public	getPath() : string
public	setName(string $name) : \UserFrosting\UniformResourceLocator\static
public	setPath(string $path=null) : \UserFrosting\UniformResourceLocator\static

This class implements \UserFrosting\UniformResourceLocator\ResourceLocationInterface

---

Interface: \UserFrosting\UniformResourceLocator\ResourceLocationInterface

ResourceLocationInterface Interface

Visibility	Function
public	getName() : string
public	getPath() : string
public	setName(string $name) : \UserFrosting\UniformResourceLocator\static
public	setPath(string $path=null) : \UserFrosting\UniformResourceLocator\static

---

Class: \UserFrosting\UniformResourceLocator\ResourceStream

ResourceStream Class The representation of a stream

Visibility	Function
public	__construct(string $scheme</strong>, <em>string</em> <strong>$prefix='', string $path=null</strong>, <em>bool</em> <strong>$shared=false) : void Constructor
public	getPath() : string
public	getPrefix() : string
public	getScheme() : string
public	isShared() : bool
public	setPath(string $path) : \UserFrosting\UniformResourceLocator\static
public	setPrefix(string $prefix) : \UserFrosting\UniformResourceLocator\static
public	setScheme(string $scheme) : \UserFrosting\UniformResourceLocator\static
public	setShared(bool $shared) : \UserFrosting\UniformResourceLocator\static

This class implements \UserFrosting\UniformResourceLocator\ResourceStreamInterface

---

Interface: \UserFrosting\UniformResourceLocator\ResourceLocatorInterface

ResourceLocatorInterface Class

Visibility	Function
public	addLocation(\UserFrosting\UniformResourceLocator\ResourceLocationInterface $location) : void Add an existing RessourceLocation instance to the location list
public	addStream(\UserFrosting\UniformResourceLocator\ResourceStreamInterface $stream) : void Add an exisitng ResourceStream to the stream list
public	getBasePath() : string
public	getLocation(string $name) : \UserFrosting\UniformResourceLocator\ResourceLocationInterface Get a location instance based on it's name
public	getLocations() : array Get a a list of all registered locations
public	getResource(string $uri</strong>, <em>bool</em> <strong>$first=false) : \UserFrosting\UniformResourceLocator\resource Return a resource instance
public	getResources(string $uri</strong>, <em>bool</em> <strong>$all=false) : array Array of Resource Return a list of resources instances
public	getStream(string $scheme) : \UserFrosting\UniformResourceLocator\ResourceStreamInterface
public	getStreams() : array
public	listLocations() : array An array of registered name => location Return a list of all the locations registered by name
public	listResources(string $uri</strong>, <em>bool</em> <strong>$all=false) : array The ressources list List all ressources found at a given uri.
public	listStreams() : array An array of registered scheme => location Return a list of all the stream scheme registered
public	locationExist(string $name) : bool Returns true if a location has been defined
public	registerLocation(string $name</strong>, <em>string</em> <strong>$path=null) : \UserFrosting\UniformResourceLocator\static Register a new location
public	registerStream(string $scheme</strong>, <em>string</em> <strong>$prefix='', string/array/null $paths=null</strong>, <em>bool</em> <strong>$shared=false) : void Register a new stream
public	removeLocation(string $name) : \UserFrosting\UniformResourceLocator\static Unregister the specified location
public	removeStream(string $scheme) : \UserFrosting\UniformResourceLocator\static Unregister the specified stream
public	schemeExists(string $scheme) : bool Returns true if a stream has been defined

This class implements \RocketTheme\Toolbox\ResourceLocator\ResourceLocatorInterface

---

Interface: \UserFrosting\UniformResourceLocator\ResourceInterface

Resource Interface

Visibility	Function
public	getAbsolutePath() : string
public	getBasePath() : string Get the resource base path, aka the path that comes after the ://.
public	getBasename() : string Extract the trailing name component (test.txt -> test.txt)
public	getExtension() : string Extract the resource extension (test.txt -> txt)
public	getFilename() : string Extract the resource filename (test.txt -> test)
public	getLocation() : \UserFrosting\UniformResourceLocator\ResourceLocationInterface
public	getLocatorBasePath() : string
public	getPath() : string
public	getSeparator() : string
public	getStream() : \UserFrosting\UniformResourceLocator\ResourceStream
public	getUri() : string Get Resource URI
public	setLocatorBasePath(string $locatorBasePath) : \UserFrosting\UniformResourceLocator\static
public	setSeparator(string $separator) : \UserFrosting\UniformResourceLocator\static

---

Class: \UserFrosting\UniformResourceLocator\Resource

Resource Class Resources are used to represent a file with info regarding the stream and Location used to find it. When a resource is created, we save the stream used to find it, the location where it was found, and the absolute and relative paths of the file. Using this information, we can later rebuilt the URI used to find this file. Since the full path will contains the relative location of the stream and location inside the filesystem, this information will be removed to recrete the relative 'basepath' of the file, allowing the recreatation of the uri (scheme://basePath).

Visibility	Function
public	__construct(\UserFrosting\UniformResourceLocator\ResourceStreamInterface stream</strong>, <em>[\UserFrosting\UniformResourceLocator\ResourceLocationInterface](#interface-userfrostinguniformresourcelocatorresourcelocationinterface)/null/[\UserFrosting\UniformResourceLocator\ResourceLocationInterface](#interface-userfrostinguniformresourcelocatorresourcelocationinterface)</em> <strong>location=null, string $path</strong>, <em>string</em> <strong>$locatorBasePath='') : void Constructor
public	__toString() : string The resource absolute path Magic function to convert the class into the resource absolute path
public	getAbsolutePath() : string
public	getBasePath() : string Get the resource base path, aka the path that comes after the ://. To to this, we use the relative path and remove the stream and location base path. For example, a stream with a base path of data/foo/, will return a relative path for every resource it find as data/foo/filename.txt. So we want to remove the data/foo/ part to keep only the filename.txt part, aka the part after the :// in the URI. Same goes for the location part, which comes before the stream: locations/locationA/data/foo
public	getBasename() : string Extract the trailing name component (test.txt -> test.txt)
public	getExtension() : string Extract the resource extension (test.txt -> txt)
public	getFilename() : string Extract the resource filename (test.txt -> test)
public	getLocation() : \UserFrosting\UniformResourceLocator\ResourceLocationInterface
public	getLocatorBasePath() : string
public	getPath() : string
public	getSeparator() : string
public	getStream() : \UserFrosting\UniformResourceLocator\ResourceStreamInterface
public	getUri() : string Get Resource URI Also adds the prefix stream prefix if it existprefix.
public	setLocatorBasePath(string $locatorBasePath) : \UserFrosting\UniformResourceLocator\static
public	setSeparator(string $separator) : \UserFrosting\UniformResourceLocator\static

This class implements \UserFrosting\UniformResourceLocator\ResourceInterface

---

Class: \UserFrosting\UniformResourceLocator\ResourceLocator

ResourceLocator Class The locator is used to find resources.

Visibility	Function
public	__construct(string/string/null $basePath='') : void Constructor
public	__invoke(string $uri) : string/bool
public	addLocation(\UserFrosting\UniformResourceLocator\ResourceLocationInterface $location) : void Add an existing RessourceLocation instance to the location list
public	addPath(string $scheme</strong>, <em>string</em> <strong>$prefix, string/array $paths</strong>, <em>bool/bool/string</em> <strong>$override=false, bool $force=false) : void AddPath function. Used to preserve compatibility with RocketTheme/Toolbox
public	addStream(\UserFrosting\UniformResourceLocator\ResourceStreamInterface $stream) : \UserFrosting\UniformResourceLocator\static Add an exisitng ResourceStream to the stream list
public	findResource(string $uri</strong>, <em>bool</em> <strong>$absolute=true, bool $first=false) : string The ressource path 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	findResources(string $uri</strong>, <em>bool</em> <strong>$absolute=true, bool $all=false) : array[string] An array of all the ressources path 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	getBasePath() : string
public	getLocation(string $name) : \UserFrosting\UniformResourceLocator\ResourceLocationInterface Get a location instance based on it's name
public	getLocations() : \UserFrosting\UniformResourceLocator\array[ResourceLocationInterface] Get a a list of all registered locations
public	getResource(string $uri</strong>, <em>bool</em> <strong>$first=false) : \UserFrosting\UniformResourceLocator\ResourceInterface Return a resource instance
public	getResources(string $uri</strong>, <em>bool</em> <strong>$all=false) : array[ResourceInterface] Array of Resource Return a list of resources instances
public	getStream(string $scheme) : \UserFrosting\UniformResourceLocator\ResourceStreamInterface
public	getStreamBuilder() : \RocketTheme\Toolbox\StreamWrapper\StreamBuilder
public	getStreams() : \UserFrosting\UniformResourceLocator\array[ResourceStreamInterface]
public	isStream(string $uri) : bool True if is resolvable Returns true if uri is resolvable by using locator.
public	listLocations() : array[string] An array of registered name => location Return a list of all the locations registered by name
public	listResources(string $uri</strong>, <em>bool</em> <strong>$all=false, bool $sort=true) : array[ResourceInterface] The ressources list List all ressources found at a given uri. Same as listing all file in a directory, except here all topmost ressources will be returned when considering all locations
public	listStreams() : array[string] An array of registered scheme => location Return a list of all the stream scheme registered
public	locationExist(string $name) : bool Returns true if a location has been defined
public	normalize(string $uri</strong>, <em>bool</em> <strong>$throwException=false, bool $splitStream=false</strong>)</strong> : <em>string/array/bool</em><br /><em>Returns the canonicalized URI on success. 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.
public	registerLocation(string $name</strong>, <em>string</em> <strong>$path=null) : \UserFrosting\UniformResourceLocator\static Register a new location
public	registerStream(string $scheme</strong>, <em>string</em> <strong>$prefix='', string/array/null $paths=null</strong>, <em>bool</em> <strong>$shared=false) : \UserFrosting\UniformResourceLocator\static Register a new stream
public	removeLocation(string $name) : \UserFrosting\UniformResourceLocator\static Unregister the specified location
public	removeStream(string $scheme) : \UserFrosting\UniformResourceLocator\static Unregister the specified stream
public	reset() : \UserFrosting\UniformResourceLocator\static Reset locator by removing all the registered streams and locations.
public	schemeExists(string $scheme) : bool Returns true if a stream has been defined
public	setBasePath(string/null $basePath) : \UserFrosting\UniformResourceLocator\static
protected	find(string $scheme</strong>, <em>string</em> <strong>$file, bool $array</strong>, <em>bool</em> <strong>$all) : \UserFrosting\UniformResourceLocator\ResourceInterface/\UserFrosting\UniformResourceLocator\array[ResourceInterface] Returns path of a file (or directory) based on a search uri
protected	findCached(string $uri</strong>, <em>bool</em> <strong>$array, bool $all) : \UserFrosting\UniformResourceLocator\array[ResourceInterface]/ResourceInterface The ressource path or an array of all the ressources path Find a resource from the cached properties
protected	searchPaths(\UserFrosting\UniformResourceLocator\ResourceStreamInterface $stream) : array[ResourceLocationInterface] The search paths based on this stream and all available locations Build the search path out of the defined strean and locations. If the scheme is shared, we don't need to involve locations and can return it's path directly
protected	setupStreamWrapper(string $scheme) : void Register the scheme as a php stream wrapper
protected	unsetStreamWrapper(string $scheme) : void Unset a php stream wrapper

This class implements \UserFrosting\UniformResourceLocator\ResourceLocatorInterface, \RocketTheme\Toolbox\ResourceLocator\ResourceLocatorInterface

---

Interface: \UserFrosting\UniformResourceLocator\ResourceStreamInterface

ResourceStreamInterface Interface

Visibility	Function
public	getPath() : string
public	getPrefix() : string
public	getScheme() : string
public	isShared() : bool
public	setPath(string $path) : \UserFrosting\UniformResourceLocator\static
public	setPrefix(string $prefix) : \UserFrosting\UniformResourceLocator\static
public	setScheme(string $scheme) : \UserFrosting\UniformResourceLocator\static
public	setShared(bool $shared) : \UserFrosting\UniformResourceLocator\static

---

Class: \UserFrosting\UniformResourceLocator\Exception\StreamNotFoundException

StreamNotFoundException Used when a path is not registered.

Visibility	Function

This class extends \Exception

This class implements \Throwable

---

Class: \UserFrosting\UniformResourceLocator\Exception\LocationNotFoundException

LocationNotFoundException Used when a Location is not registered.

Visibility	Function

This class extends \Exception

This class implements \Throwable