Trait UploadedFileTrait

Provides a set of methods to honor the Psr-7 Uploaded File Interface.

Traits provide extended method support to classes without requiring a direct, linear chain of inheritance. This allows functions to inherit subsets of related methods without declaring a parent class.

In Oroboros core, ALL methods are granted to classes via traits, and the classes themselves are just containers that correlate their methods to an interface they are expected to honor. This approach maximizes interoperability, by entirely removing class inheritance as a requirement for extension of any class in this system.

3rd parties using this package are not expected to follow this approach,

but ALL of our internal class and logic structure does.

oroboros\core\traits\libraries\file\UploadedFileTrait uses oroboros\core\traits\libraries\file\FileTrait

Direct Known Users

oroboros\core\abstracts\libraries\file\AbstractFileUpload

Indirect Known Users

oroboros\core\libraries\file\FileUpload

Namespace: oroboros\core\traits\libraries\file
Package: oroboros\core\psr7
Category: traits
License: The MIT License (MIT)
Author: Brian Dayhoff mopsyd@me.com
Version: 0.2.4
Since: 0.2.4-alpha
Used by: oroboros\core\interfaces\api\psr\Psr7Api::UPLOADEDFILE_ABSTRACT_CLASS
Used by: oroboros\core\interfaces\api\psr\Psr7Api::SERVERREQUEST_ABSTRACT_CLASS
Link: bitbucket.org/oroborosframework/oroboros-core/wiki/development/api/traits.md
Satisfies: \oroboros\core\interfaces\contract\libraries\file\UploadedFileContract
Satisfies: \Psr\Http\Message\UploadedFileInterface
Located at core/traits/libraries/file/UploadedFileTrait.php

Methods summary

`public static oroboros\core\libraries\container\Collection`	# `getUploadedFileCollection( array $files )` Returns a collection of UploadedFile objects from the full set of files passed in $_FILES Returns a collection of UploadedFile objects from the full set of files passed in $_FILES Parameters `$files` Returns `oroboros\core\libraries\container\Collection`
`public`	# `__construct( array $uploaded_file )` This constructor should receive as it's only parameter the value of a file upload within $_FILES This constructor should receive as it's only parameter the value of a file upload within $_FILES Parameters `$uploaded_file` Throws `oroboros\core\utilities\exception\RuntimeException` If instantiation cannot complete with the provided parameters.
`public StreamInterface`	# `getStream( )` Retrieve a stream representing the uploaded file. Retrieve a stream representing the uploaded file. This method MUST return a StreamInterface instance, representing the uploaded file. The purpose of this method is to allow utilizing native PHP stream functionality to manipulate the file upload, such as stream_copy_to_stream() (though the result will need to be decorated in a native PHP stream wrapper to work with such functions). If the moveTo() method has been called previously, this method MUST raise an exception. Returns StreamInterface Stream representation of the uploaded file. Throws `RuntimeException` in cases when no stream is available. `RuntimeException` in cases when no stream can be created.
`public`	# `moveTo( string $targetPath )` Move the uploaded file to a new location. Move the uploaded file to a new location. Use this method as an alternative to move_uploaded_file(). This method is guaranteed to work in both SAPI and non-SAPI environments. Implementations must determine which environment they are in, and use the appropriate method (move_uploaded_file(), rename(), or a stream operation) to perform the operation. $targetPath may be an absolute path, or a relative path. If it is a relative path, resolution should be the same as used by PHP's rename() function. The original file or stream MUST be removed on completion. If this method is called more than once, any subsequent calls MUST raise an exception. When used in an SAPI environment where $_FILES is populated, when writing files via moveTo(), is_uploaded_file() and move_uploaded_file() SHOULD be used to ensure permissions and upload status are verified correctly. If you wish to move to a stream, use getStream(), as SAPI operations cannot guarantee writing to stream destinations. Parameters `$targetPath` Path to which to move the uploaded file. Throws `InvalidArgumentException` if the $targetPath specified is invalid. `RuntimeException` on any error during the move operation. `RuntimeException` on the second or subsequent call to the method. See http://php.net/is_uploaded_file http://php.net/move_uploaded_file
`public integer\|null`	# `getSize( )` Retrieve the file size. Retrieve the file size. Implementations SHOULD return the value stored in the "size" key of the file in the $_FILES array if available, as PHP calculates this based on the actual size transmitted. Returns integer\|null The file size in bytes or null if unknown.
`public integer`	# `getError( )` Retrieve the error associated with the uploaded file. Retrieve the error associated with the uploaded file. The return value MUST be one of PHP's UPLOAD_ERR_XXX constants. If the file was uploaded successfully, this method MUST return UPLOAD_ERR_OK. Implementations SHOULD return the value stored in the "error" key of the file in the $_FILES array. Returns integer One of PHP's UPLOAD_ERR_XXX constants. See http://php.net/manual/en/features.file-upload.errors.php
`public string\|null`	# `getClientFilename( )` Retrieve the filename sent by the client. Retrieve the filename sent by the client. Do not trust the value returned by this method. A client could send a malicious filename with the intention to corrupt or hack your application. Implementations SHOULD return the value stored in the "name" key of the file in the $_FILES array. Returns string\|null The filename sent by the client or null if none was provided.
`public string\|null`	# `getClientMediaType( )` Retrieve the media type sent by the client. Retrieve the media type sent by the client. Do not trust the value returned by this method. A client could send a malicious media type with the intention to corrupt or hack your application. Implementations SHOULD return the value stored in the "type" key of the file in the $_FILES array. Returns string\|null The media type sent by the client or null if none was provided.
`protected`	# `_initializeUploadedFileObject( array $uploaded_file )` Parameters `$uploaded_file`
`private`	# `_moveUploadedFile( type $filePath )` Handles the safe move operation, regardless of whether it is an http or cli environment. Handles the safe move operation, regardless of whether it is an http or cli environment. Parameters `$filePath` The new location for the file Throws `oroboros\core\utilities\exception\RuntimeException` on any error during the move operation
`private`	# `_moveUploadedHttpFile( type $old, type $new )` Moves the file in a http-safe way. Moves the file in a http-safe way. Parameters `$old` the file upload `$new` the new location for the file Throws `oroboros\core\utilities\exception\RuntimeException` if the supplied file is not an uploaded file.
`private`	# `_moveUploadedCliFile( string $old, string $new )` Moves the file in a cli-safe way. Moves the file in a cli-safe way. Parameters `$old` The location of the existing file `$new` The new location
`private static type`	# `_parseUploadedFilesStatic( array $files )` Corrects known edge-cases in the $_FILES superglobal structure that can be corrected through rekeying the array. Corrects known edge-cases in the $_FILES superglobal structure that can be corrected through rekeying the array. Parameters `$files` the raw $_FILES array Returns type \oroboros\core\libraries\container\Collection Throws `oroboros\core\utilities\exception\InvalidArgumentException` if an invalid $_FILES array is passed.
`private static boolean`	# `_validateUploadedFileArray( array $files )` Returns a boolean determination as to whether a provided array can be directly used to create a valid UploadedFile instance. Returns a boolean determination as to whether a provided array can be directly used to create a valid UploadedFile instance. Parameters `$files` Returns boolean
`private static boolean`	# `_isMultileafUploadedFileArray( array $files )` Returns a boolean determination as to whether the provided array is a multi-leaf file array that needs additional consideration. Returns a boolean determination as to whether the provided array is a multi-leaf file array that needs additional consideration. Parameters `$files` Returns boolean
`private static Psr\Http\Message\UploadedFileInterface`	# `_createUploadedFileInstance( type $files )` Creates an instance of the called class implementing this trait. This class must also implement \Psr\Http\Message\UploadedFileInterface, and it must either use the provided constructor or have one that is compatible with the one provided by this trait. Creates an instance of the called class implementing this trait. This class must also implement \Psr\Http\Message\UploadedFileInterface, and it must either use the provided constructor or have one that is compatible with the one provided by this trait. Parameters `$files` Returns Psr\Http\Message\UploadedFileInterface (this will be an instance of the called class that directly or indirectly implements this trait, on the assumption that the constructor exists as provided in this trait, or is compatible with it). Throws `oroboros\core\utilities\exception\LogicException` The implementing class must be an instance of \Psr\Http\Message\UploadedFileInterface
`private static string`	# `_getUploadedFileMultileafPathString( array $subject, string $path = null )` Contencates the multidimensional array structure into a collection compatible dot separated notation string. This allows this class to easily fix miskeyed $_FILES keys for multipart uploads without a ton of redundant recursion. Contencates the multidimensional array structure into a collection compatible dot separated notation string. This allows this class to easily fix miskeyed $_FILES keys for multipart uploads without a ton of redundant recursion. Parameters `$subject` The nested files array, typically a multi-part expression of $_FILES `$path` (optional) This is used for recursion and should not be provided. If it is provided, it will act as a prefix to the filepath. Returns string
`private static array`	# `_extractUploadedFileLeafKeys( array $subject )` Returns the numeric leaf keys of a multidimensional array, ignoring the rest of the nested keys. Returns the numeric leaf keys of a multidimensional array, ignoring the rest of the nested keys. Parameters `$subject` Returns array
`private static boolean`	# `_checkUploadedFileLeafKeysAlreadyHandled( array $subject )` Checks if nested leaf keys are already instances of \Psr\Http\Message\FileUploadInterface Checks if nested leaf keys are already instances of \Psr\Http\Message\FileUploadInterface Parameters `$subject` Returns boolean
`private static boolean`	# `_checkUploadedFileLeafKeys( mixed $subject )` Checks all valid cases for nesting of ambiguous multi-leaf file arrays. Checks all valid cases for nesting of ambiguous multi-leaf file arrays. Parameters `$subject` Returns boolean
`private static array`	# `_reorderUploadedFileMultileafArray( array $subject )` Corrects the issue of the leaf keys of a multi-leaf file array being numeric instead of the expected keys from $_FILES Corrects the issue of the leaf keys of a multi-leaf file array being numeric instead of the expected keys from $_FILES Parameters `$subject` Takes an array of arrays, where the keys are expected keys from $_FILES and the subkeys are integers Returns array

Methods used from oroboros\core\traits\libraries\file\FileTrait

_copyFileTo(), _deleteFile(), _fileExists(), _fileIsInitialized(), _fileIsTemp(), _fileReadable(), _fileWriteable(), _getFileAlias(), _getFileExtension(), _getFileFullyQualifiedName(), _getFileInfoLink(), _getFileMimeType(), _getFileName(), _getFilePath(), _getFileSize(), _getFileStreamResource(), _initializeFileObject(), _loadFileCodex(), _moveFileTo(), _setFileContents(), _setFileEncodingValue(), _setFileExistsValue(), _setFileExtensionValue(), _setFileNameValue(), _setFilePathValue(), _setFileReadableValue(), _setFileSizeValue(), _setFileTempAliasValue(), _setFileType(), _setFileTypeValue(), _setFileWriteableValue(), _touchFile(), _truncateFile()

Properties summary

`private array`	`$_uploaded_file_valid_errors` Represents the subset of valid upload errors, as defined by PHP Represents the subset of valid upload errors, as defined by PHP	# `array( UPLOAD_ERR_OK, UPLOAD_ERR_INI_SIZE, UPLOAD_ERR_FORM_SIZE, UPLOAD_ERR_PARTIAL, UPLOAD_ERR_NO_FILE, UPLOAD_ERR_NO_TMP_DIR, UPLOAD_ERR_CANT_WRITE, UPLOAD_ERR_EXTENSION )`
`private integer`	`$_uploaded_file_error` Represents the upload error, if an error occurs. If this has a value of 0, then no upload error occurred. Represents the upload error, if an error occurs. If this has a value of 0, then no upload error occurred.	# `UPLOAD_ERR_OK`
`private integer`	`$_uploaded_file_size` Represents the uploaded file size. Represents the uploaded file size.	# `0`
`private boolean`	`$_uploaded_file_is_sapi` Represents whether or not the current PHP execution is sapi or non-sapi Represents whether or not the current PHP execution is sapi or non-sapi	# `false`
`private string`	`$_uploaded_file_default_stream_wrapper` Represents the default stream wrapper class. Represents the default stream wrapper class.	# `'\\oroboros\\core\\libraries\\stream\\Stream'`
`private string`	`$_uploaded_file_stream_wrapper` Represents the current stream wrapper class, which is the default, unless substituted. Represents the current stream wrapper class, which is the default, unless substituted.	# `'\\oroboros\\core\\libraries\\stream\\Stream'`

Properties used from oroboros\core\traits\libraries\file\FileTrait

$_file_encoding, $_file_exists, $_file_extension, $_file_extension_information, $_file_is_initialized, $_file_is_temp, $_file_mime, $_file_name, $_file_path, $_file_readable, $_file_size, $_file_temp_alias, $_file_type_info, $_file_writeable

Namespaces

Traits

Trait UploadedFileTrait

Provides a set of methods to honor the Psr-7 Uploaded File Interface.

but ALL of our internal class and logic structure does.

Direct Known Users

Indirect Known Users

Methods summary

Parameters

Returns

Parameters

Throws

Returns

Throws

Parameters

Throws

See

Returns

Returns

See

Returns

Returns

Parameters

Parameters

Throws

Parameters

Throws

Parameters

Parameters

Returns

Throws

Parameters

Returns

Parameters

Returns

Parameters

Returns

Throws

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Methods used from oroboros\core\traits\libraries\file\FileTrait

Properties summary

Properties used from oroboros\core\traits\libraries\file\FileTrait