PHP Class lithium\net\http\Media

_assetOptions() protected static method

Initialize options for Media::asset().

protected static _assetOptions ( string $path, string $type, array $options ) : array
$path	string	The path to the asset.
$type	string	The asset type.
$options	array	Contains setting for finding and handling the path.
return	array	The initialized options.

_assets() protected static method

Helper method to list all asset paths, or the path for a single type.

protected static _assets ( string $type = null ) : mixed
$type	string	The type you wish to get paths for.
return	mixed	An array of all paths, or a single array of paths for the given type.

_handle() protected static method

Called by Media::render() to render response content. Given a content handler and data, calls the content handler and passes in the data, receiving back a rendered content string.

protected static _handle ( array $handler, array $data, object &$response ) : string
$handler	array
$data	array
$response	object	A reference to the `Response` object for this dispatch cycle.
return	string

_initScopes() protected static method

Initialize static::$_scopes with a lithium\core\Configuration instance.

protected static _initScopes ( )

_types() protected static method

Helper method for listing registered media types. Returns all types, or a single content type if a specific type is specified.

protected static _types ( string $type = null ) : mixed
$type	string	Type to return.
return	mixed	Array of types, or single type requested.

asset() public static method

Calculates the web-accessible path to a static asset, usually a JavaScript, CSS or image file.

public static asset ( string $path, string $type, array $options = [] ) : string
$path	string	The path to the asset, relative to the given `$type`s path and without a suffix. If the path contains a URI Scheme (eg. `http://`), no path munging will occur.
$type	string	The asset type. See `Media::$_assets` or `Media::assets()`.
$options	array	Contains setting for finding and handling the path, where the keys are the following: - `'base'`: The base URL of your application. Defaults to `null` for no base path. This is usually set with the return value of a call to `env('base')` on an instance of `lithium\action\Request`. - `'check'`: Check for the existence of the file before returning. Defaults to `false`. - `'filter'`: An array of key/value pairs representing simple string replacements to be done on a path once it is generated. - `'paths'`: An array of paths to search for the asset in. The paths should use `String::insert()` formatting. See `Media::$_assets` for more. - `suffix`: The suffix to attach to the path, generally a file extension. - `'timestamp'`: Appends the last modified time of the file to the path if `true`. Defaults to `false`. - `'library'`: The name of the library from which to load the asset. Defaults to `true`, for the default library.
return	string	Returns the publicly-accessible absolute path to the static asset. If checking for the asset's existence (`$options['check']`), returns `false` if it does not exist in your `/webroot` directory, or the `/webroot` directories of one of your included plugins.

assets() public static method

Gets or sets options for various asset types.

public static assets ( string $type = null, array $options = [] ) : array
$type	string	The name of the asset type, i.e. `'js'` or `'css'`.
$options	array	If registering a new asset type or modifying an existing asset type, contains settings for the asset type, where the available keys are as follows: - `'suffix'`: The standard suffix for this content type, with leading dot ('.') if applicable. - `'filter'`: An array of key/value pairs representing simple string replacements to be done on a path once it is generated. - `'paths'`: An array of key/value pairs where the keys are `String::insert()` compatible paths, and the values are array lists of keys to be inserted into the path string.
return	array	If `$type` is empty, an associative array of all registered types and all associated options is returned. If `$type` is a string and `$options` is empty, returns an associative array with the options for `$type`. If `$type` and `$options` are both non-empty, returns `null`.

attach() public static method

Example: Media::attach('app', array( 'path' => '/var/www/website/app/webroot/extradir', 'prefix' => 'extradir' )); Media::attach('cdn', array( 'absolute' => true, 'path' => null, 'host' => 'http://my.cdn.com', 'prefix' => 'project1/assets' )); Media::attach('cdn', array( 'absolute' => true, 'path' => null, 'host' => array('my.cdn.com', 'secure.cdn.com'), 'scheme' => array('http://', 'https://'), 'prefix' => 'project1/assets', )); Media::attach('cdn', array( 'absolute' => true, 'path' => null, 'host' => array('my1.cdn.com', 'my2.cdn.com'), 'scheme' => 'http://', 'prefix' => 'project1/assets', ));

public static attach ( string $name, array $config = null ) : void
$name	string	The name of the media you wish to attach.
$config	array	Asset configuration options for the given scope. - `'path'` _string_: Path of the media. - `'prefix'` _string_: Contains the uri prefix. Such as `css`. - `'absolute'` _boolean_: Defaults to `false`. If you want to generate absolute URL's. - `'host'` _mixed_: String host, or array of hosts, of the media, if absolute is `true`. - `'scheme'` _mixed_: String scheme, or array of sc, of the media, if absolute is `true`.
return	void

attached() public static method

Returns an attached mount point configuration.

public static attached ( $name = null )

decode() public static method

For media types registered in $_handlers which include an 'decode' setting, decodes data according to the specified media type.

public static decode ( string $type, mixed $data, array $options = [] ) : mixed
$type	string	Specifies the media type into which `$data` will be encoded. This media type must have an `'encode'` setting specified in `Media::$_handlers`.
$data	mixed	Arbitrary data you wish to encode. Note that some encoders can only handle arrays or objects.
$options	array	Handler-specific options.
return	mixed

encode() public static method

For media types registered in $_handlers which include an 'encode' setting, encodes data according to the specified media type.

public static encode ( mixed $handler, mixed $data, object &$response = null ) : mixed
$handler	mixed	Specifies the media type into which `$data` will be encoded. This media type must have an `'encode'` setting specified in `Media::$_handlers`. Alternatively, `$type` can be an array, in which case it is used as the type handler configuration. See the `type()` method for information on adding type handlers, and the available configuration keys.
$data	mixed	Arbitrary data you wish to encode. Note that some encoders can only handle arrays or objects.
$response	object	A reference to the `Response` object for this dispatch cycle.
return	mixed	Returns the result of `$data`, encoded with the encoding configuration specified by `$type`, the result of which is usually a string.

filterAssetPath() public static method

Performs checks and applies transformations to asset paths, including verifying that the virtual path exists on the filesystem, appending a timestamp, prepending an asset host, or applying a user-defined filter.

public static filterAssetPath ( string $asset, mixed $path, array $config, array $options = [] ) : mixed
$asset	string	A full asset path, relative to the public web path of the application.
$path	mixed	Path information for the asset type.
$config	array	The configuration array of the library from which the asset is being loaded.
$options	array	The array of options passed to `asset()` (see the `$options` parameter of `Media::asset()`).
return	mixed	Returns a modified path to a web asset, or `false`, if the path fails a check.

formats() public static method

Alias for types(); included for interface compatibility with lithium\util\Collection::to(), which allows a collection object to be exported to any format supported by a Media handler. See the documentation for Collection::to() for more information.

public static formats ( ) : array
return	array	Returns the value of `Media::types()`.

handlers() public static method

Helper method for listing registered type handlers. Returns all handlers, or the handler for a specific media type, if requested.

public static handlers ( string $type = null ) : mixed
$type	string	The type of handler to return.
return	mixed	Array of all handlers, or the handler for a specific type.

match() public static method

Assists Media::negotiate() in processing the negotiation conditions of a content type, by iterating through the conditions and checking each one against the Request object.

public static match ( Request $request, array $config ) : boolean
$request	lithium\action\Request	The request to be checked against a set of conditions (if applicable).
$config	array	Represents a content type configuration, which is an array containing 3 keys: - `'name'` _string_: The type name, i.e. `'html'` or `'json'`. - `'content'` _mixed_: One or more content types that the configuration represents, i.e. `'text/html'`, `'application/xhtml+xml'` or `'application/json'`, or an array containing multiple content types. - `'options'` _array_: An array containing rendering information, and an optional `'conditions'` key, which contains an array of matching parameters. For more details on these matching parameters, see `Media::type()`.
return	boolean	Returns `true` if the information in `$request` matches the type configuration in `$config`, otherwise false.

negotiate() public static method

Performs content-type negotiation on a Request object, by iterating over the accepted types in sequence, from most preferred to least, and attempting to match each one against a content type defined by Media::type(), until a match is found. If more than one defined type matches for a given content type, they will be checked in the order they were added (usually, this corresponds to the order they were defined in the application bootstrapping process).

public static negotiate ( Request $request ) : string | null
$request	lithium\action\Request	The request which contains the details of the request to be content-negotiated.
return	string | null	Returns the first matching type name, i.e. `'html'` or `'json'`. When no matching type is found returns `null`.

path() public static method

Returns the physical path to an asset in the /webroot directory of an application or plugin.

public static path ( $path, string $type, array $options = [] ) : string
$type	string	A valid asset type, i.e. `'js'`, `'cs'`, `'image'`, or another type registered with `Media::assets()`, or `'generic'`.
$options	array	The options used to calculate the path to the file.
return	string	Returns the physical filesystem path to an asset in the `/webroot` directory.

render() public static method

Renders data (usually the result of a controller action) and generates a string representation of it, based on the type of expected output.

public static render ( object $response, mixed $data = null, array $options = [] ) : object
$response	object	A Response object into which the operation will be rendered. The content of the render operation will be assigned to the `$body` property of the object, the `'Content-Type'` header will be set accordingly, and it will be returned.
$data	mixed	The data (usually an associative array) to be rendered in the response.
$options	array	Any options specific to the response being rendered, such as type information, keys (i.e. controller and action) used to generate template paths, etc.
return	object	Returns a modified `Response` object with headers and body defined.

reset() public static method

Resets the Media class to its default state. Mainly used for ensuring a consistent state during testing.

public static reset ( )

scope() public static method

Special use case: If $closure is not null executing the closure inside the specified scope.

public static scope ( string $name = null, Closur\Closure $closure = null ) : mixed
$name	string	Name of the scope to use.
$closure	Closur\Closure	A closure to execute inside the scope.
return	mixed	Returns the previous scope if if `$name` is not null and `$closure` is null, returns the default used scope if `$name` is null, otherwise returns `null`.

to() public static method

Alias for encode(); included for interface compatibility with lithium\util\Collection::to(), which allows a collection object to be exported to any format supported by a Media handler. See the documentation for Collection::to() for more information.

public static to ( mixed $format, mixed $data, array $options = [] ) : mixed
$format	mixed	Format into which data will be converted, i.e. `'json'`.
$data	mixed	Either an array or object (usually an instance of `Collection`) which will be converted into the specified format.
$options	array	Additional handler-specific options to pass to the content handler.
return	mixed

type() public static method

Examples: embed:lithium\tests\cases\net\http\MediaTest::testMediaTypes(1-2) embed:lithium\tests\cases\net\http\MediaTest::testMediaTypes(19-23) embed:lithium\tests\cases\net\http\MediaTest::testMediaTypes(43-44) Alternatively, can be used to detect the type name of a registered content type: Media::type('application/json'); // returns 'json' Media::type('application/javascript'); // returns 'javascript' Media::type('text/javascript'); // also returns 'javascript' Media::type('text/html'); // returns 'html' Media::type('application/xhtml+xml'); // also returns 'html' #### Content negotiation When creating custom media types, specifying which content-type(s) to match isn't always enough. For example, if you wish to serve a different set of templates to mobile web browsers, you'd still want those templates served as HTML. You might add something like this: Media::type('mobile', array('application/xhtml+xml', 'text/html')); However, this would cause _all_ requests for HTML content to be interpreted as 'mobile'-type requests. Instead, we can use _content negotiation_ to granularly specify how to match a particular type. Content negotiation is the process of examining the HTTP headers provided in the request (including the content-types listed in the Accept header, and optionally other things as well, like the Accept-Language or User-Agent headers), in order to produce the best representation of the requested resource for the client; in other words, the resource that most closely matches what the client is asking for. Content negotiation with media types is made possible through the 'conditions' key of the $options parameter, which contains an array of assertions made against the Request object. Each assertion (array key) can be one of three different things: - 'type' _boolean_: In the default routing, some routes have {:type} keys, which are designed to match file extensions in URLs. These values act as overrides for the HTTP Accept header, allowing different formats to be served with the same content type. For example, if you're serving JSONP, you'll want to serve it with the same content-type as JavaScript (since it is JavaScript), but you probably won't want to use the same template(s) or other settings. Therefore, when serving JSONP content, you can specify that the extension defined in the type must be present in the URL: Media::type('jsonp', array('application/json'), array( template settings... 'conditions' => array('type' => true) )); Then, JSONP content will only ever be served when the request URL ends in .jsonp. - ':' _string_: This type of assertion can be used to match against arbitrary information in the request, including headers (i.e. 'http:user_agent'), environment variables (i.e. 'env:home'), GET and POST data (i.e. 'query:foo' or 'data:foo', respectively), and the HTTP method ('http:method') of the request. For more information on possible keys, see lithium\action\Request::get(). - '' _boolean_: Uses detector checks added to the Request object to make boolean assertions against the request. For example, if a detector called 'iPhone' is attached, you can add 'iPhone' => true to the 'conditions' array in order to filter for iPhone requests only. See lithium\action\Request::detect() for more information on adding detectors.

public static type ( string $type, mixed $content = null, array $options = [] ) : mixed
$type	string	A file-extension-style type name, i.e. `'txt'`, `'js'`, or `'atom'`. Alternatively, a mapped content type, i.e. `'text/html'`, `'application/atom+xml'`, etc.; in which case, the matching type name (i.e. '`html'` or `'atom'`) will be returned.
$content	mixed	Optional. A string or array containing the content-type(s) that `$type` should map to. If `$type` is an array of content-types, the first one listed should be the "primary" type, and will be used as the `Content-type` header of any `Response` objects served through this type.
$options	array	Optional. The handling options for this media type. Possible keys are: - `'view'` _string_: Specifies the view class to use when rendering this content. Note that no `'view'` class is specified by default. If you want to render templates using Lithium's default view class, use `'lithium\template\View'` - `'decode'` _mixed_: A (string) function name or (object) closure that handles decoding or unserializing content from this format. - `'encode'` _mixed_: A (string) function name or (object) closure that handles encoding or serializing content into this format. - `'cast'` _boolean_: Used with `'encode'`. If `true`, all data passed into the specified encode function is first cast to array structures. - `'paths'` _array_: Optional key/value pairs mapping paths for `'template'`, `'layout'`, and `'element'` template files. Any keys ommitted will use the default path. The values should be `String::insert()`-style paths or an array of `String::insert()`-style paths. If it is an array, each path will be tried in the order specified until a template is found. This is useful for allowing custom templates while falling back on default templates if no custom template was found. If you want to render templates without a layout, use a `false` value for `'layout'`. - `'conditions'` _array_: Optional key/value pairs used as assertions in content negotiation. See the above section on **Content Negotiation**.
return	mixed	If `$content` and `$options` are empty, returns an array with `'content'` and `'options'` keys, where `'content'` is the content-type(s) that correspond to `$type` (can be a string or array, if multiple content-types are available), and `'options'` is the array of options which define how this content-type should be handled. If `$content` or `$options` are non-empty, returns `null`.

types() public static method

Returns the list of registered media types. New types can be set with the type() method.

public static types ( ) : array
return	array	Returns an array of media type extensions or short-names, which comprise the list of types handled.

view() public static method

Configures a template object instance, based on a media handler configuration.

public static view ( mixed $handler, mixed $data, object &$response = null, array $options = [] ) : object
$handler	mixed	Either a string specifying the name of a media type for which a handler is defined, or an array representing a handler configuration. For more on types and type handlers, see the `type()` method.
$data	mixed	The data to be rendered. Usually an array.
$response	object	The `Response` object associated with this dispatch cycle. Usually an instance of `lithium\action\Response`.
$options	array	Any options that will be passed to the `render()` method of the templating object.
return	object	Returns an instance of a templating object, usually `lithium\template\View`.

webroot() public static method

Gets the physical path to the web assets (i.e. /webroot) directory of a library.

public static webroot ( string | boolean $library = true, string | boolean $scope = null ) : string
$library	string | boolean	The name of the library for which to find the path, or `true` for the default library.
$scope	string | boolean	The name of the to use to find the path.
return	string	Returns the physical path to the web assets directory.