.. include:: ../Includes.txt

.. _Fal:

============
Fal
============

\\nn\\t3::Fal()
---------------

Methods to create sysFile and sysFileReference entries.

Checklist:

.. code-block:: php

	\TYPO3\CMS\Extbase\Persistence\Generic\ObjectStorage
	 |
	 └─ \TYPO3\CMS\Extbase\Domain\Model\FileReference
	        ... getOriginalResource()
	                |
	                └─ \TYPO3\CMS\Core\Resource\FileReference
	                    ... getOriginalFile()
	                            |
	                            └─ \TYPO3\CMS\Core\Resource\File

Overview of Methods
~~~~~~~~~~~~~~~~

\\nn\\t3::Fal()->attach(``$model, $field, $filePath = NULL``);
""""""""""""""""

Convert a file to a FileReference object, and attach it
Attach it to the Property or ObjectStorage of a model.
See also: ``\nn\t3::Fal()->setInModel( $member, 'falslideshow', $imagesToSet );`` with the
array of multiple images can be attached to an ObjectStorage.

.. code-block:: php

	\nn\t3::Fal()->attach( $model, $fieldName, $filePath );
	\nn\t3::Fal()->attach( $model, 'image', 'fileadmin/user_uploads/image.jpg' );

| ``@return \TYPO3\CMS\Extbase\Domain\Model\FileReference``
.

\\nn\\t3::Fal()->detach(``$model, $field, $obj = NULL``);
""""""""""""""""

Deletes an ObjectStorage in a model or removes an
single Object from the Model or an ObjectStorage.
In the example, ``image`` can be an ObjectStorage or a single ``FileReference``:

.. code-block:: php

	\nn\t3::Fal()->detach( $model, 'image' );
	\nn\t3::Fal()->detach( $model, 'image', $singleObjToRemove );

| ``@return void``

\\nn\\t3::Fal()->fromFile(``$params = []``);
""""""""""""""""

Creates a FileRefence object (table: ``sys_file_reference``) and associates it with a record.
Example: Uploaded JPG should be attached as FAL to tt_news record

parameter:
| ``src`` => path to source file (can also be http link to YouTube video).
| ``dest`` => path to destination folder (optional if file is to be moved/copied).
| ``table`` => target table to which FileReference should be assigned (e.g. ``tx_myext_domain_model_entry``).
| ``title`` => title.
| ``description`` => description.
| ``link`` => link
| ``crop`` => crop.
| ``table`` => Target table to which the FileReference is to be mapped (e.g. ``tx_myext_domain_model_entry``).
| ``sorting`` => (int) sorting.
| ``field`` => Column name of the target table to which the FileReference should be assigned (e.g., ``image``).
| ``uid`` => (int) uid of the record in the target table (``tx_myext_domain_model_entry.uid``).
| ``pid`` => (int) pid of the record in the target table.
| ``cruser_id`` => cruser_id of the record in the destination table.
| ``copy`` => do not move src file but copy it (default: ``true``)
| ``forceNew`` => Force new file in destination folder (otherwise check if file already exists) default: ``false``
| ``single`` => Ensure that same FileReference is linked only 1x per record (default: ``true``)

Example:

.. code-block:: php

	$fal = \nn\t3::Fal()->fromFile([
	    'src' => 'fileadmin/test/image.jpg',
	    'dest' => 'fileadmin/test/fal/',
	    'pid' => 132,
	    'uid' => 5052,
	    'table' => 'tx_myext_domain_model_entry',
	    'field' => 'fallistimage'
	]);

| ``@return \TYPO3\CMS\Extbase\Domain\Model\FileReference``
.

\\nn\\t3::Fal()->createFalFile(``$storageConfig, $srcFile, $keepSrcFile = false, $forceCreateNew = false``);
""""""""""""""""

Creates a \File (FAL) Object (sys_file)

nn\t3::createFalFile( $storageConfig, $srcFile, $keepSrcFile, $forceCreateNew );

| ``@param string $storageConfig`` Path/folder where FAL file should be stored (e.g. 'fileadmin/projectdata/').
| ``@param string $srcFile`` Source file to be converted to FAL (e.g. 'uploads/tx_nnfesubmit/example.jpg').
Can also be URL to YouTube/Vimeo video (e.g. https://www.youtube.com/watch?v=7Bb5jXhwnRY)
| ``@param boolean $keepSrcFile`` Copy source file only, not move it?
| ``@param boolean $forceCreateNew`` Should new file always be created? If not, it returns existing File object if necessary

| ``@return \Nng\Nnhelpers\Domain\Model\File|\TYPO3\CMS\Core\Resource\File|boolean``

\\nn\\t3::Fal()->getFalFile(``$srcFile``);
""""""""""""""""

Gets a \File (FAL) Object (sys_file)

| ``@param string $srcFile``
| ``@return FileReference|boolean``

\\nn\\t3::Fal()->getImage(``$src = NULL``);
""""""""""""""""

.
Gets/converts to a \TYPO3\CMS\Core\Resource\FileReference Object (sys_file_reference).
"Smart" variant to ``\TYPO3\CMS\Extbase\Service\ImageService->getImage()``

.. code-block:: php

	\nn\t3::Fal()->getImage( 1 );
	\nn\t3::Fal()->getImage( 'path/to/image.jpg' );
	\nn\t3::Fal()->getImage( $fileReference );

| ``@param string|\TYPO3\CMS\Extbase\Domain\Model\FileReference $src``
| ``@return \TYPO3\CMS\Core\Resource\FileReference|boolean``

\\nn\\t3::Fal()->getFileObjectFromCombinedIdentifier(``$file = ''``);
""""""""""""""""

Gets a SysFile from the CombinedIdentifier notation ('1:/uploads/example.txt').
If file does not exist FALSE will be returned.

.. code-block:: php

	\nn\t3::getFileObjectFromCombinedIdentifier( '1:/uploads/example.txt' );

| ``@param string $file`` Combined Identifier ('1:/uploads/example.txt')
| ``@return file|boolean``

\\nn\\t3::Fal()->fileReferenceExists(``$sysFile = NULL, $params = []``);
""""""""""""""""

Checks if a SysFileReference to the same SysFile already exists for a record

.. code-block:: php

	\nn\t3::Fal()->fileReferenceExists( $sysFile, ['uid_foreign'=>123, 'tablenames'=>'tt_content', 'field'=>'media'] );

| ``@param $sysFile``
| ``@param array $params`` => uid_foreign, tablenames, fieldname.
| ``@return FileReference|false``
.

\\nn\\t3::Fal()->getFileReferenceByUid(``$uid = NULL``);
""""""""""""""""

Gets a SysFileReference based on the uid.
Alias to ``\nn\t3::Convert( $uid )->toFileReference()``;

| ``@param $uid``
| ``@return \TYPO3\CMS\Extbase\Domain\Model\FileReference``
.

\\nn\\t3::Fal()->deleteSysFileReference(``$uidOrFileReference = NULL``);
""""""""""""""""

Lödeletes a SysFileReference.
See also ``\nn\t3::Fal()->detach( $model, $field );`` to delete from a model.

.. code-block:: php

	\nn\t3::Fal()->deleteSysFileReference( 112 );
	\nn\t3::Fal()->deleteSysFileReference( \TYPO3\CMS\Extbase\Domain\Model\FileReference );

| ``@param $uidOrFileReference``

| ``@return mixed``

\\nn\\t3::Fal()->deleteSysFile(``$uidOrObject = NULL``);
""""""""""""""""

Deletes a SysFile (record from table ``sys_file``) and all associated SysFileReferences.
A radical way to take an image completely out of Typo3's indexing.

The physical file is not deleted from the server!
See ``\nn\t3::File()->unlink()`` to delete the physical file.
See ``\nn\t3::Fal()->detach( $model, $field );`` for löling from a model.

.. code-block:: php

	\nn\t3::Fal()->deleteSysFile( 1201 );
	\nn\t3::Fal()->deleteSysFile( 'fileadmin/path/to/image.jpg' );
	\nn\t3::Fal()->deleteSysFile( \TYPO3\CMS\Core\Resource\File );
	\nn\t3::Fal()->deleteSysFile( \TYPO3\CMS\Core\Resource\FileReference );

| ``@param $uidOrObject``

| ``@return integer``

\\nn\\t3::Fal()->unlink(``$uidOrObject = NULL``);
""""""""""""""""

Deletes a SysFile and all associated SysFileReferences.
Alias to ``\nn\t3::Fal()->deleteSysFile()``

| ``@return integer``
.

\\nn\\t3::Fal()->createSysFile(``$file, $autoCreateStorage = true``);
""""""""""""""""

Creates new entry in ``sys_file``
Searches all ``sys_file_storage`` entries to see if the path to the $file already exists as a storage.
If not, a new storage is created.

.. code-block:: php

	\nn\t3::Fal()->createSysFile( 'fileadmin/image.jpg' );

| ``@return File|\TYPO3\CMS\Core\Resource\File``

\\nn\\t3::Fal()->clearCache(``$filenameOrSysFile = ''``);
""""""""""""""""

Deletes the cache for the image sizes of a FAL including the converted images.
If e.g. the f:image-ViewHelper is used, all calculated image sizes will be
are stored in the table sys_file_processedfile. Ächanges the original image,
an image from the cache may still be accessed.

| ``@param $filenameOrSysFile`` FAL or path (string) to the file.
| ``@return void``

\\nn\\t3::Fal()->updateMetaData(``$filenameOrSysFile = '', $data = []``);
""""""""""""""""

Update the details in sys_file_metadata and sys_file

| ``@param $filenameOrSysFile`` FAL or path (string) to the file.
| ``@param $data`` Array of data to be updated.
If empty, image data will be read automatically

| ``@return void``

\\nn\\t3::Fal()->setInModel(``$model, $fieldName = '', $imagesToAdd = []``);
""""""""""""""""

Replaces a ``FileReference`` or ``ObjectStorage`` in a model with images.
Typical use case: A FAL image should be changed via an upload form in the frontend.
in the frontend.

For each image, it is checked if a ``FileReference`` already exists in the model.
Existing FileReferences are not overwritten, otherwise captions or cropping annotations might be used.
Captions or cropping instructions would be lost!

Attention! The model will be persisted automatically!

.. code-block:: php

	$newModel = new \My\Extension\Domain\Model\Example();
	\nn\t3::Fal()->setInModel( $newModel, 'falslideshow', 'path/to/file.jpg' );
	echo $newModel->getUid(); // Model has been persisted!

Example with a simple FileReference in the Model:

.. code-block:: php

	$imageToSet = 'fileadmin/images/portrait.jpg';
	\nn\t3::Fal()->setInModel( $member, 'falprofileimage', $imageToSet );
	
	\nn\t3::Fal()->setInModel( $member, 'falprofileimage', ['publicUrl'=>'01.jpg', 'title'=>'title', 'description'=>'...'] );

Example with an ObjectStorage in the model:

.. code-block:: php

	$imagesToSet = ['fileadmin/images/01.jpg', 'fileadmin/images/02.jpg', ...];
	\nn\t3::Fal()->setInModel( $member, 'falslideshow', $imagesToSet );
	
	\nn\t3::Fal()->setInModel( $member, 'falslideshow', [['publicUrl'=>'01.jpg'], ['publicUrl'=>'02.jpg']] );
	\nn\t3::Fal()->setInModel( $member, 'falvideos', [['publicUrl'=>'https://youtube.com/?watch=zagd61231'], ...] );

Example with videos:

.. code-block:: php

	$videosToSet = ['https://www.youtube.com/watch?v=GwlU_wsT20Q', ...];
	\nn\t3::Fal()->setInModel( $member, 'videos', $videosToSet );

| ``@param mixed $model`` The model to be changed.
| ``@param string $fieldName`` Property (field name) of the ObjectStorage or FileReference.
| ``@param mixed $imagesToAdd`` String / array of images

| ``@return mixed``

\\nn\\t3::Fal()->getFilePath(``$falReference``);
""""""""""""""""

Get the URL to a FileReference

.. code-block:: php

	\nn\t3::Fal()->getFilePath( $fileReference ); // yields e.g. 'fileadmin/pictures/01.jpg'

| ``@param \TYPO3\CMS\Extbase\Domain\Model\FileReference $falReference``
| ``@return string``

\\nn\\t3::Fal()->process(``$fileObj = '', $processing = []``);
""""""""""""""""

Calculates an image üover ``maxWidth``, ``maxHeight``, ``cropVariant`` etc.
Returns URI to image as string. Helpful when calculating thumbnails in the backend.
Alias to ``\nn\t3::File()->process()``

.. code-block:: php

	\nn\t3::File()->process( 'fileadmin/images/portrait.jpg', ['maxWidth'=>200] );
	\nn\t3::File()->process( '1:/images/portrait.jpg', ['maxWidth'=>200] );
	\nn\t3::File()->process( $sysFile, ['maxWidth'=>200] );
	\nn\t3::File()->process( $sysFileReference, ['maxWidth'=>200, 'cropVariant'=>'square'] );

| ``@return string``

\\nn\\t3::Fal()->toArray(``$fileReference = NULL``);
""""""""""""""""

Convert a FileReference to an array.
Contains publicUrl, title, alternative, crop etc of the FileReference.
Alias to ``\nn\t3::Obj()->toArray( $fileReference );``

.. code-block:: php

	\nn\t3::Fal()->toArray( $fileReference ); // yields ['publicUrl'=>'fileadmin/...', 'title'=>'...']

| ``@param \TYPO3\CMS\Extbase\Domain\Model\FileReference $falReference``
| ``@return array``