FileResource Abstract Class
An abstract class for resources embedded in a web page (images, scripts,
whatever), (*1)
This package is intended to provide a standard means by which web applications
can treat resources embedded in the web page as objects., (*2)
The advantage of treating resources as objects is it allows them to have both
properties and methods that can do stuff with those properties and/or
parameters fed to those methods., (*3)
This package also includes an abstract class for using PHP to serve the
resource described by a FileResource object., (*4)
Install Package
You can install this class with composer require awonderphp/fileresource:^1.0, (*5)
Class Properties
The following properties are defined by the abstract class:, (*6)
-
protected $mime = null;
The MIME type the file should be served with when a client requests it., (*7)
-
protected $checksum = null;
The algorithm used to calculate a checksum digest, followed by a colon,
followed by either a hex or base64 representation of the checksum digest. It
is recommended to use one of the SHA-2 algorithms that browsers are required
to support for use with the integrity attribute., (*8)
-
protected $validIntegrityAlgo = array('sha256', 'sha384', 'sha512');
Algorithms that are supported by all web browsers that support the
integrity attribute., (*9)
-
protected $filepath = null;
The full path on the local server to the file. Please note this property
should remain null when the file described by the object is not present
on the local filesystem., (*10)
-
protected $crossorigin = null;
The contents of the crossorigin attribute that should be used when creating
an (X)HTML node that references the resource., (*11)
-
$validCrossOrigin = array('anonymous', 'use-credentials');
The valid options that can be used with a crossorigin attribute., (*12)
-
protected $lastmod = null;
The last time the file was modified, using ISO 8601 in Y-m-d\TH:i:sO, which
can be achieve in PHP as date('c'). This does not need to match the file
timestamp on the local filesystem, which often is not accurate., (*13)
-
protected $urlscheme = null;
Should be one of null, http, or https. The scheme to use when creating
a src or href attribute to embed the resource in a web page. This should
be null when the resource will be served from the same server that is
serving the web page., (*14)
-
protected $urlhost = null;
Should be null or the hostname to use when creating a src or href
attribute to embed the resource in a web page. This should be null when the
resource will be served from the same server as that is serving the web page., (*15)
-
protected $urlpath = null;
The path to the resource on the server that is serving the resource when
creating a src or href attribute to embed the resource in a web page., (*16)
-
protected $urlquery = null;
In the event a URL query is needed (the part after the ? in a URL), the
query that should be appended at the end of the URL when construction a src
or href attribute to embed the resource in a web page., (*17)
Notes About the Class Properties
For many files, additional properties are needed to adequately embed the
resource within a web page (such as alt tag and possibly caption for an
image), (*18)
This abstract class is intended to define most properties commonly needed for
embedding a resource in a web page and everything that is needed for a PHP
wrapper to correctly serve the file., (*19)
The four url* properties correspond with the the PHP function
parse_url with the
following ommissions:, (*20)
-
port
Only applicable if the resource is remote, in which case HTTPS should be
preferred and only the default port 443 should be used for HTTPS., (*21)
-
user
Not an appropriate component of a URL for embedding resources in a web page., (*22)
-
pass
Not an appropriate component of a URL for embedding resources in a web page., (*23)
-
fragment
Not an appropriate component of a URL for embedding resources in a web page., (*24)
Class Methods
The following methods are defined by the abstract class:, (*25)
-
public function getMimeType()
Returns the $mime property., (*26)
-
public function getChecksum()
Returns the $checksum property., (*27)
-
public function getCrossOrigin()
Returns the $crossorigin property., (*28)
-
public function getFilePath()
Returns the $filepath property., (*29)
-
public function validateFile()
If the $checksum property is set and the $filepath property is set
and the file exists, returns true if the file matches the checksum and
false if it does not., (*30)
-
public function getSrcAttribute($prefix = null)
Builds the contents of the src or href attribute needed to embed the
resource in a web page. Note that this will return null if the $urlscheme
property is http and the file does not have a $checksum property that
uses an algorithm in the $validIntegrityAlgo property. The optional
parameter $prefix is a filesystem path to put in front of the $urlpath
property, useful for web applications using a wrapper to serve the file., (*31)
-
public function getIntegrityAttribute()
Builds the contents of an integrity attribute, if the $checksum property
uses a suitable algorithm., (*32)
-
public function getTimestamp()
If the $lastmode property is not null, returns a UNIX timestamp (seconds
from UNIX epoch)., (*33)
FileWrapper Class
This is a class that extends my \AWonderPHP\FileWrapper\FileWrapper class.
The class it extends was written to be a download wrapper including support
for client cache validation and partial content requests., (*34)
However that class uses the timestamp of the file on the filesystem for the
Last-Modified header and uses the inode of the file on the filesystem in
its generation of the ETag header., (*35)
The extended class allows the modification timestamp and the ETag to be set
independent of the file on the filesystem., (*36)
ResourceServer Class
This is an abstract class that provides a public method for serving a file
based from a FileResource object., (*37)
The idea is to extend the class adding a method construct the necessary
FileResource object and then serve it., (*38)
GenericFileResource Class
This is a very generic class that extends the FileResource abstract class. It
exists to provide for easy unit testing of the public methods in the abstract
class but it can be used in web applications., (*39)
The __construct function takes a single argument, an array of key => value
pairs where the key corresponds to the FileResource property you wish to set., (*40)
Unit Testing
Unit Testing is performed using PHPUnit version 7. The
results can be viewed in the file UnitTestResults.txt, (*41)
EOF, (*42)
Wallogit.com
