Documentation

Media
in package

Helpers for resolving and loading media files.

These are asset files from modules, skin or sprout. These are files are not necessarily accessible from the web root because they're located in the src/ or vendor/ folders.

Asset files are expected to live in the media/ folder for core, sprout and modules sections. Skin files are exempt to this rule.

For public access, files are served by the MediaController with a checksum per 'section' (core/sprout/skin/module). This url is generated by the Media::url helper also used internally by the Needs helper.

Note that Sprout has two media folders. This is simply a legacy holdover - there's no true distinction between the two.

Tags
see
MediaController

Table of Contents

Properties

$name  : string
This is the asset descriptor.
$root  : string
This is the root directory for the section/asset media folder.
$section  : string
The section for the asset.
$checksums  : array<string|int, string>
Short cache of checksums.

Methods

clean()  : void
Clean out the media cache.
generateChecksum()  : string|null
Generate a checksum for a given directory.
generateUrl()  : string
Generate a URL for an asset.
getChecksum()  : null|string
Get the checksum for this asset.
getPath()  : string
The full absolute path to the original asset.
getUrl()  : string
The non-generated URL.
parse()  : Media
Parse a media asset.
tag()  : string
Get a media tag for a file.
url()  : string
Get the URL for an asset.

Properties

$name

This is the asset descriptor.

public string $name

Relative to the root web path and section.

  • WEBROOT + _media + section + name is the web URL
  • root + name is the original path

$root

This is the root directory for the section/asset media folder.

public string $root

Sections define where a collection of assets live.

  • core: COREPATH/media
  • sprout: APPPATH/media
  • skin: DOCROOT/{skin}
  • module: {path}/media

The asset name is always relative to this root.

$section

The section for the asset.

public string $section

One of:

  • core
  • sprout
  • skin/{name}
  • modules/{name}

This is a unique identifier for where each group of assets live. This forms the cache Skins and modules

$checksums

Short cache of checksums.

protected static array<string|int, string> $checksums = []

It's important the key here is independent of any absolute paths given an application may be mounted in a container or use symlinks.

[ section => checksum ]`

Methods

clean()

Clean out the media cache.

public static clean([bool|string $act = true ]) : void
Parameters
$act : bool|string = true

act|dry|silent

generateChecksum()

Generate a checksum for a given directory.

public static generateChecksum(string $path[, bool $copy_files = false ]) : string|null

Optionally copy all files within to the WEBROOT/_media/ folder.

Parameters
$path : string
$copy_files : bool = false
Return values
string|null

generateUrl()

Generate a URL for an asset.

public generateUrl() : string
Tags
throws
MediaException
Return values
string —

media URL like _media/{checksum}/{section}/{file}

getChecksum()

Get the checksum for this asset.

public getChecksum() : null|string

A checksum is common across all resources within the same section.

Return values
null|string

getPath()

The full absolute path to the original asset.

public getPath() : string
Return values
string

getUrl()

The non-generated URL.

public getUrl([bool $timestamp = true ]) : string

This URL will always redirect to the generated URL.

Parameters
$timestamp : bool = true
Return values
string

parse()

Parse a media asset.

public static parse(string $asset) : Media

Provide an asset descriptor like:

  • core/js/file.js
  • sprout/css/sheet.css
  • skin/default/images/office.png
  • modules/{name}/css/custom.css

This extracts the section, file name, and root path.

Parameters
$asset : string
Tags
throws
MediaException
Return values
Media

tag()

Get a media tag for a file.

public static tag(string $file[, array<string|int, mixed> $extra_attrs = [] ]) : string

This will return a <script> or tag for the given file based on the file extension.

Parameters
$file : string

section/path/to/file

$extra_attrs : array<string|int, mixed> = []
Return values
string

url()

Get the URL for an asset.

public static url(string $name[, bool $generate = true ]) : string
Parameters
$name : string

like section/path/to/file

$generate : bool = true
Return values
string —

a relative URL (without ROOT/)

On this page

Search results