File.php

Summary
File.php
FileTable Definition for file
FileA superclass containing the database representation of a file attatchment and the related interfaces.
schemaDefReturns an array representing the database schema this class is interfacing with.
isProtectedReturns true/false whether the URL is considered “protected”.
saveNewSave a new file record.
saveFileThis slightly-misleadingly named function saves the File record to the database, for actually creating a new file properly, see saveNew.
processNew
respectsQuotaTests whether a new upload respects the various quotas set in the instance configuration.
getFilenameReturns the filename for the file represented by this File object.
getSizeReturns the filesize as reported by the system for the file.
filenameConstruct the filename for a new File object.
guessMimeExtensionAttempt to determine the mime extension for the file represented by this File object.
validFilenameReturns true/false whether the filename is a valid Linux filename.
tryFilename
pathConstructs the path for a given $filename based on site configuration.
urlConstructs the URL for a file entry.
getEnclosureReturn the mime enclosure for a file.
hasThumbnailReturns true/false whether this attachment has a thumbnail on record.
getThumbnailGet the attachment’s thumbnail record, if any.
getPathReturns the local filesystem path to a file we have stored locally.
getAttachmentUrl
getUrl
getByUrlRetrieve a File object by looking up its URL.
getByHashRetrieve a File object by looking up its hash.
updateUrl
blowCacheBlow the cache of notices that link to this URL
streamStream of notices linking to this URL or attachment
noticeCountReturns how many notices use this attachment.
isLocalReturns whether we have a local copy of this file in the filesystem.
deleteRemove an attachment entry from the DB and the associated file if stored locally.
getTitleRetrieves the title of an attachment entry, or if none is set, the filename.
setTitleSet the title of the attachment object.
hashurlHash a URL provided using our given hash algorithm.
beforeSchemaUpdateThis procedure contains the various integrity checks we need to perform for the attachment system specifically.

File

Table Definition for file

postActiv

the micro-blogging software

Copyright

Copyright © 2016-2017, Maiyannah Bishop

Derived from code copyright various sources

  • GNU Social © 2013-2016, Free Software Foundation, Inc
  • StatusNet © 2008-2012, StatusNet, Inc

License

This program is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Affero General Public License for more details.

You should have received a copy of the GNU Affero General Public License along with this program.  If not, see http://www.gnu.org/licenses/.

https://www.gnu.org/licenses/agpl.html

About

A superclass containing the database representation of a file attatchment and the related interfaces.

Basically, this is things attached to a post.  One thing to note here is that it might not represent an actual attachment like an image or movie, it can also represent the metadata for a hyperlink to another website.

PHP version

Tested with PHP 7

File Authors

Web

File

A superclass containing the database representation of a file attatchment and the related interfaces.

Property

  • __table - ‘file’; // table name
  • id - int(4) primary_key not_null
  • urlhash - varchar(64) unique_key
  • url - text
  • filehash - varchar(64) indexed
  • mimetype - varchar(50)
  • size - int(4)
  • title - text()
  • date - int(4)
  • protected - int(4)
  • filename - text()
  • width - int(4)
  • height - int(4)
  • modified - timestamp() not_null default_CURRENT_TIMESTAMP
Summary
schemaDefReturns an array representing the database schema this class is interfacing with.
isProtectedReturns true/false whether the URL is considered “protected”.
saveNewSave a new file record.
saveFileThis slightly-misleadingly named function saves the File record to the database, for actually creating a new file properly, see saveNew.
processNew
respectsQuotaTests whether a new upload respects the various quotas set in the instance configuration.
getFilenameReturns the filename for the file represented by this File object.
getSizeReturns the filesize as reported by the system for the file.
filenameConstruct the filename for a new File object.
guessMimeExtensionAttempt to determine the mime extension for the file represented by this File object.
validFilenameReturns true/false whether the filename is a valid Linux filename.
tryFilename
pathConstructs the path for a given $filename based on site configuration.
urlConstructs the URL for a file entry.
getEnclosureReturn the mime enclosure for a file.
hasThumbnailReturns true/false whether this attachment has a thumbnail on record.
getThumbnailGet the attachment’s thumbnail record, if any.
getPathReturns the local filesystem path to a file we have stored locally.
getAttachmentUrl
getUrl
getByUrlRetrieve a File object by looking up its URL.
getByHashRetrieve a File object by looking up its hash.
updateUrl
blowCacheBlow the cache of notices that link to this URL
streamStream of notices linking to this URL or attachment
noticeCountReturns how many notices use this attachment.
isLocalReturns whether we have a local copy of this file in the filesystem.
deleteRemove an attachment entry from the DB and the associated file if stored locally.
getTitleRetrieves the title of an attachment entry, or if none is set, the filename.
setTitleSet the title of the attachment object.
hashurlHash a URL provided using our given hash algorithm.
beforeSchemaUpdateThis procedure contains the various integrity checks we need to perform for the attachment system specifically.

schemaDef

public static function schemaDef()

Returns an array representing the database schema this class is interfacing with.

isProtected

public static function isProtected($url)

Returns true/false whether the URL is considered “protected”.

FIXME: un-hardcode this, or at the very least, make it configurable.

saveNew

public static function saveNew(array $redir_data,
 $given_url)

Save a new file record.

Parameters

  • array $redir_data lookup data eg from File_redirection::where()
  • string $given_url

Returns

  • File class representing the saved file

FIXME: we should probably give at least some debug-level feedback if we receive a link to a file that is our own allegedly, but we do not have the file available locally.

saveFile

public function saveFile()

This slightly-misleadingly named function saves the File record to the database, for actually creating a new file properly, see saveNew.

processNew

public static function processNew( $given_url,  
Notice $notice = null,
 $followRedirects = true)

Go look at a URL and possibly save data about it if it’s new

  • follow redirect chains and store them in file_redirection
  • if a thumbnail is available, save it in file_thumbnail
  • save file record with basic info
  • optionally save a file_to_post record
  • return the File object with the full reference

Parameters

  • string $given_url the URL we’re looking at
  • Notice $notice (optional)
  • bool $followRedirects defaults to true

Returns

  • mixed File on success, -1 on some errors

@throws ServerException on failure

respectsQuota

public static function respectsQuota(Profile $scoped,
 $fileSize)

Tests whether a new upload respects the various quotas set in the instance configuration.

Parameters

  • Profile scoped
  • fileSize

getFilename

public function getFilename()

Returns the filename for the file represented by this File object.

getSize

public function getSize()

Returns the filesize as reported by the system for the file.

filename

static function filename(Profile $profile,
 $origname,
 $mimetype)

Construct the filename for a new File object.  Returns the constructed filename.

guessMimeExtension

static function guessMimeExtension($mimetype,  
$filename = null)

Attempt to determine the mime extension for the file represented by this File object.  Returns the match on success.

Parameters

  • $mimetype - The mimetype we’ve discovered for this file.
  • $filename - An optional filename which we can use on failure.

validFilename

static function validFilename($filename)

Returns true/false whether the filename is a valid Linux filename.

tryFilename

static function tryFilename($filename)
Sees if a given $filename is a valid filenameraises InvalidFilenameException on failure, true on success.

FIXME: since this is being called elsewhere, shouldn’t this return false on failure?

path

static function path($filename)

Constructs the path for a given $filename based on site configuration.

Error States

  • ClientException on invalid filename

url

static function url($filename)

Constructs the URL for a file entry.

getEnclosure

function getEnclosure()

Return the mime enclosure for a file.

hasThumbnail

public function hasThumbnail()

Returns true/false whether this attachment has a thumbnail on record.

getThumbnail

public function getThumbnail($width = null,
$height = null,
$crop = false,
$force_still = true,
$upscale = null)

Get the attachment’s thumbnail record, if any.  Make sure you supply proper ‘int’ typed variables (or null).

Parameters

  • integer width - Max width of thumbnail in pixels.  (if null, use common_config values)
  • integer height - Max height of thumbnail in pixels.  (if null, square-crop to $width)
  • boolean crop - Crop to the max-values’ aspect ratio
  • boolean $force_still - Don’t allow fallback to showing original (such as animated GIF)
  • mixed $upscale - Whether or not to scale smaller images up to larger thumbnail sizes.  (null = site default)

Returns

  • File_thumbnail object representing the thumbnail

Error States

  • UseFileAsThumbnailException - if the file is considered an image itself and should be itself as thumbnail
  • UnsupportedMediaException - if, despite trying, we can’t understand how to make a thumbnail for this format
  • ServerException - on various other errors

getPath

public function getPath()

Returns the local filesystem path to a file we have stored locally.

getAttachmentUrl

public function getAttachmentUrl()
Returns the local URL of an attachmentobviously, this needs to be a locally-stored one but this won’t be checked here.

getUrl

public function getUrl($use_local = null)
Returns the URL of the File objectthe filename if it’s local, otherwise just the stored URL.

Parameters

  • mixed $use_local - true means require local, null means prefer local, false means use whatever is stored

getByUrl

static public function getByUrl($url)

Retrieve a File object by looking up its URL.

Parameters

  • string url

getByHash

static public function getByHash($hashstr)

Retrieve a File object by looking up its hash.

Parameters

  • string $hashstr - String of (preferrably lower case) hexadecimal characters, same as result of ‘hash_file(...)’

updateUrl

public function updateUrl($url)
Update an attachmentnote, this will throw an exception if it hasn’t changed, which may not be expected behaviour in all control paths.

blowCache

function blowCache($last = false)

Blow the cache of notices that link to this URL

Parameters

  • boolean $last Whether to blow the “last” cache too

Returns

  • void

stream

function stream($offset = 0,
$limit = NOTICES_PER_PAGE,
$since_id = 0,
$max_id = 0)

Stream of notices linking to this URL or attachment

  • integer $offset Offset to show; default is 0
  • integer $limit Limit of notices to show
  • integer $since_id Since this notice
  • integer $max_id Before this notice

Returns

  • array ids of notices that link to this file

FIXME: Try to get the Profile::current() here in some other way to avoid mixing the current session user with possibly background/queue processing.

noticeCount

function noticeCount()

Returns how many notices use this attachment.  Good for finding orphaned files.

isLocal

public function isLocal()

Returns whether we have a local copy of this file in the filesystem.

delete

public function delete($useWhere = false)

Remove an attachment entry from the DB and the associated file if stored locally.  Also cleans out thumbnails in the case of visual media.

getTitle

public function getTitle()

Retrieves the title of an attachment entry, or if none is set, the filename.

setTitle

public function setTitle($title)

Set the title of the attachment object.

hashurl

static public function hashurl($url)

Hash a URL provided using our given hash algorithm.

beforeSchemaUpdate

static public function beforeSchemaUpdate()

This procedure contains the various integrity checks we need to perform for the attachment system specifically.

public static function schemaDef()
Returns an array representing the database schema this class is interfacing with.
public static function isProtected($url)
Returns true/false whether the URL is considered “protected”.
public static function saveNew(array $redir_data,
 $given_url)
Save a new file record.
public function saveFile()
This slightly-misleadingly named function saves the File record to the database, for actually creating a new file properly, see saveNew.
public static function processNew( $given_url,  
Notice $notice = null,
 $followRedirects = true)
public static function respectsQuota(Profile $scoped,
 $fileSize)
Tests whether a new upload respects the various quotas set in the instance configuration.
public function getFilename()
Returns the filename for the file represented by this File object.
public function getSize()
Returns the filesize as reported by the system for the file.
static function filename(Profile $profile,
 $origname,
 $mimetype)
Construct the filename for a new File object.
static function guessMimeExtension($mimetype,  
$filename = null)
Attempt to determine the mime extension for the file represented by this File object.
static function validFilename($filename)
Returns true/false whether the filename is a valid Linux filename.
static function tryFilename($filename)
static function path($filename)
Constructs the path for a given $filename based on site configuration.
static function url($filename)
Constructs the URL for a file entry.
function getEnclosure()
Return the mime enclosure for a file.
public function hasThumbnail()
Returns true/false whether this attachment has a thumbnail on record.
public function getThumbnail($width = null,
$height = null,
$crop = false,
$force_still = true,
$upscale = null)
Get the attachment’s thumbnail record, if any.
public function getPath()
Returns the local filesystem path to a file we have stored locally.
public function getAttachmentUrl()
public function getUrl($use_local = null)
static public function getByUrl($url)
Retrieve a File object by looking up its URL.
static public function getByHash($hashstr)
Retrieve a File object by looking up its hash.
public function updateUrl($url)
function blowCache($last = false)
Blow the cache of notices that link to this URL
function stream($offset = 0,
$limit = NOTICES_PER_PAGE,
$since_id = 0,
$max_id = 0)
Stream of notices linking to this URL or attachment
function noticeCount()
Returns how many notices use this attachment.
public function isLocal()
Returns whether we have a local copy of this file in the filesystem.
public function delete($useWhere = false)
Remove an attachment entry from the DB and the associated file if stored locally.
public function getTitle()
Retrieves the title of an attachment entry, or if none is set, the filename.
public function setTitle($title)
Set the title of the attachment object.
static public function hashurl($url)
Hash a URL provided using our given hash algorithm.
static public function beforeSchemaUpdate()
This procedure contains the various integrity checks we need to perform for the attachment system specifically.