JAR Utilities 

Version

3.0

Language

en

Authors

Julian Lichte, Maurice Möllmer

Email

info@invokable.gmbh

License

This extension documentation is published under the Creative Commons BY 4.0 license

Utility classes that simplify TYPO3 development. We have been developing TYPO3 projects for over 10 years using the same little helpers repeatedly. Now we outsourced these helpers in an own extension to offer all TYPO3 developers a faster and easier way to develop their extensions as well.

TYPO3

The content of this document is related to TYPO3 CMS, a GNU/GPL CMS/Framework available from typo3.org .

Extension Manual

This documentation is for the TYPO3 extension jar_utilities.

Author 

This extension has been created by JAR Media, a brand of invokable.

Introduction 

Installation 

composer req jar/jar_utilities

Data Processors 

GetRow Processor 

Loads one row from a database table

tt_content.tx_myextension_jobdetailctype {
   dataProcessing {
      100 = Jar\Utilities\DataProcessing\GetRowProcessor
      100 {
         table = tx_myextension_jobs
         uid = TEXT
         uid.data = GP:jobid
         as = item
      }
   }
}

Link Processor 

Creates a link on a (mainly) dataprocessed element

tt_content.tx_myextension_joblistctype {
   dataProcessing {
      10 = TYPO3\CMS\Frontend\DataProcessing\DatabaseQueryProcessor
      10 {
         table = tx_myextension_jobs
         pidInList = 266
         as = jobs
         dataProcessing {
            10 = Jar\Utilities\DataProcessing\LinkProcessor
            10 {
               page = 187
               title = TEXT
               title.data = field:title
               as = detail_link
               params {
                  jobid = TEXT
                  jobid.data = field:uid
               }
            }
         }
      }
   }
}

Localization Processor 

Add translations directly to the template - this gives frontenders faster handling of the translation variables

tt_content.tx_myextension_joblistctype {
   dataProcessing {         
      20 = Jar\Utilities\DataProcessing\LocalizationProcessor
      20 {
         extensionsToLoad = myextension
         as = translations
         flat = 1
      }
   }
}

Reflection Processor 

TypoScript wrapper for Reflection Service. Maps data to a simple array structure, based on the TCA configuration of the table. Also resolves all TCA-relations to other tables. The strength lies in the fast loading of already existing structures, especially when using Ajax requests or headless systems.

[
   'data' => [
      'uid' => 123,
      'pid' => 345,
      'categories' => 4,
      'header' => 'my slider',
      'tx_myextension_duration' => 8000,
      'tx_myextension_slides' = 3
      // ... many other system related columns
   ],
   'current' => null
]

tt_content.slider.dataProcessing {
   10 = Jar\Utilities\DataProcessing\ReflectionProcessor
   10 {
      # FYI: this is superfluous, because "tt_content" is the default value
      table = tt_content
      
      tableColumnWhitelist {
         # just reflect the slide related fields and the header in tt_content
         tt_content = tx_myextension_*, header
      }
      
      tableColumnBlacklist {
         # don't reflect the "categories" column in tx_myextension_slides
         tx_myextension_slides = categories
      }

      tableColumnRemapping {
         tt_content {
            # rename the column "header" to "title" in the result
            header = title 
         }
      }

      tableColumnRemoveablePrefixes {
         # remove the prefix "tx_myextension_" from our columns
         tt_content = tx_myextension_
      }

      buildingConfiguration {
         file {
            # we don't want deeper informations about files (f.e. filename, extension, size, etc ..)
            showDetailedInformations = 0

            # set image rendering instructions for the different cropping variants
            processingConfigurationForCrop {
               desktop.maxWidth = 3000
               medium.maxWidth = 1920
               tablet.maxWidth = 1024
               mobile.maxWidth = 920
            }
         }
      }
   }
}

[
   // original data:

   'data' => [
      'uid' => 123,
      'pid' => 345,
      'categories' => 4,
      'header' => 'my slider',
      'tx_myextension_duration' => 8000,
      'tx_myextension_slides' = 3
      // ... many other system related columns
   ],
   'current' => null

   
   // results of reflection:

   'uid' => '123',
   'title' => 'my slider',
   'duration' => 8000,
   'slides' => [
      0 => [            
         'image' => [
            0 => [
               'uid' => 1
               'url' => 'fileadmin/user_upload/my-image-original.jpg',
               'alt' => 'some text',
               'title' => 'some text',
               'description' => 'some text',
               'link' => NULL,
               'cropped' => [
                  'desktop' => 'fileadmin/_processed_/1/my-image-original-max-width-3000.jpg',
                  'medium' => 'fileadmin/_processed_/1/my-image-original-max-width-1920.jpg',
                  'tablet' => 'fileadmin/_processed_/1/my-image-original-max-width-1024.jpg',
                  'mobile' => 'fileadmin/_processed_/1/my-image-original-max-width-920.jpg'
               ]
            ]
         ],
         'headline' => 'some text',
         'descrition' => '<p>some RTE content</p>',
         'link' => [
            'url' => 'https://example.com/a-page?bla=1',
            'base' => 'https://example.com/a-page',
            'params' => '?bla=1',
            'target' => '_blank',
            'text' => 'Click me',
            'class' => 'warning',
            'raw' => 't3://page?uid=196 _blank warning "Click me" ?bla=1'
         ]
      ],
      1 => [
         // same structure as above
      ],
      2 => [
         // same structure as above
      ]
   ]
]

Services 

Reflection Service 

Service class for converting complex objects to a simple array structure based of TCA configuration. Handy for faster integration development, headless systems and ajax calls.

class ReflectionService

Fully qualified name

\Jar\Utilities\Services\ReflectionService

Configuration

Tip

For column definitions, you can use wildcards like "?" and "*". So instead of define table_class, table_caption, table_delimiter, table_enclosure, ... specificly, you can use table_*.

setPropertiesByConfigurationArray ( $configuration)

Sets multiple properties in one call.

param array $configuration

Configuration settings.

Example:

                                                                                       
setPropertiesByConfigurationArray([
   'tableColumnBlacklist' => [        
      // don't reflect the "categories" column in tx_myextension_slides          
      'tx_myextension_slides' => 'categories',                  
      // don't reflect the "doktype" column and all columns
      // starting with "cache_" in pages
      'pages' => 'cache_*, doktype'
   ],
   'tableColumnWhitelist' => [
      // just reflect the slide related fields and the header in tt_content
      'tt_content' => 'tx_myextension_*, header'
   ],
   'tableColumnRemoveablePrefixes' => [
      // remove the prefix "tx_myextension_" from our columns
      'tt_content' => 'tx_myextension_'
   ],
   'tableColumnRemapping' => [
      'tt_content' => [
         // rename the column "header" to "title" in the result
         'header' => 'title'
      ]
   ],
   'buildingConfiguration' => [
      // ... same settings like "setBuildingConfiguration" (example below)
   ],
   // deactivate debug output of reflection
   'debug' => false,
]);

Copied!

Attention

In comparison to the direct using of setter-methods, some table-handle-definitions are commaseparated. This affects the setting for tableColumnBlacklist, tableColumnWhitelist and tableColumnRemoveablePrefixes.

Returns

self

setColumnBlacklist ( $columnBlacklist)

Set list of columns that are generally not processed. This blacklist will be applied to every table.

param array $columnBlacklist

List of columns that are generally not processed.

Example:

                                                                                       
setColumnBlacklist([
   't3ver_*',
   'l18n_*',
   'l10n_*',
   'crdate',
   'cruser_id',
   'editlock',
   /* ... */
]);   

Copied!

Returns

self

setTableColumnBlacklist ( $columnBlacklist)

Set list of table specific columns which aren't processed.

param array $tableColumnBlacklist

List of table specific columns which aren't processed.

Example:

                                                                                       
setTableColumnBlacklist([        
   // don't reflect the "categories" column in tx_myextension_slides          
   'tx_myextension_slides' => ['categories'],                  
   // don't reflect the "doktype" column and all columns
   // starting with "cache_" in pages
   'pages' => ['cache_*', 'doktype']
]);

Copied!

Returns

self

addToTableColumnBlacklist ( $tableColumnBlacklist)

Add to list of table specific columns which aren't processed. Same as setTableColumnBlacklist without replacing the whole tableColumnBlacklist-Settings

param array $tableColumnBlacklist

List of table specific columns which aren't processed.

Returns

self

setTableColumnWhitelist ( $tableColumnWhitelist)

Set List of tables columns which should be processed exclusively.

param array $tableColumnWhitelist

List of tables columns which should be processed exclusively.

Example:

                                                                                       
setTableColumnWhitelist([        
   // just reflect the slide related fields and the header in tt_content
   'tt_content' => ['tx_myextension_*', 'header']
]);

Copied!

Returns

self

setTableColumnRemoveablePrefixes ( $tableColumnRemoveablePrefixes)

Set wildcard based replacement for column names. F.e. 'tt_content' => ['table_'] converts 'tt_content->table_caption' to 'tt_content->caption'

param array $tableColumnRemoveablePrefixes

Wildcard based replacement for column names.

Example:

                                                                                       
setTableColumnRemoveablePrefixes([        
   // remove the prefix "tx_myextension_" from our columns
   'tt_content' => ['tx_myextension_']
]);

Copied!

Returns

self

setTableColumnRemapping ( $tableColumnRemapping)

Set remap column-names in reflected result. F.e. 'tt_content' => ['table_caption' => 'heading'] converts 'tt_content->table_caption' to 'tt_content->heading'. Important: takes action AFTER replacement of ColumnNames! Keep that in mind.

param array $tableColumnRemapping

Remapping definition list.

returns

self

Example:

                                                                                       
setTableColumnRemapping([        
   'tt_content' => [
      // rename the column "header" to "title" in the result
      'header' => 'title'
   ]
]);

Copied!

setBuildingConfiguration ( $arrayBuildingConfiguration)

Contains e.g. instructions for the preparation of files and images.

param array $arrayBuildingConfiguration

Instructions for the preparation of files and images.

Example:

                                                                                       
setBuildingConfiguration([
   'file' => [
      // we don't want deeper informations about files (f.e. filename,
      // extension, size, etc ..)
      'showDetailedInformations' => false,
      // set image rendering instructions for the different cropping variants             
      'processingConfigurationForCrop' => [                  
         'desktop' => [
            'maxWidth' => 3000
         ],
         'medium' => [
            'maxWidth' => 1920
         ],
         'tablet' => [
            'maxWidth' => 1024
         ],
         'mobile' => [
            'maxWidth' => 920
         ]
      ]
   ]
]);

Copied!

Returns

self

|

Reflection output

buildArrayByRows ( $rows, $table, $maxDepth)

Reflects a list of record rows.

param array $rows

The record list.

param string $table

The tablename.

param int $maxDepth

The maximum depth at which related elements are loaded (default is 8).

Returns

Reflected result.

buildArrayByRow ( $rows, $table, $maxDepth)

Reflects a single record row.

param array $row

The record row.

param string $table

The tablename.

param int $maxDepth

The maximum depth at which related elements are loaded (default is 8).

Returns

Reflected result.

Tip

For examples output, take a look into Reflection Processor example or services-reflection-input-output-examples

|

Getter

getTcaFieldDefinition ( )

Get array for used TCA field definitions, helpful for Post-handling that prepared data.

Returns

All used TCA table and column definitions which was used on the last reflection.

Note

For each configration-Setter above there is also a getter available (f.e. setColumnBlacklist / getColumnBlacklist). For the sake of clarity, these are not listed here.

|

                                                                                                
[
   'url' => 'https://example.com/a-page?bla=1',
   'base' => 'https://example.com/a-page',
   'params' => '?bla=1',
   'target' => '_blank',
   'text' => 'Click me',
   'class' => 'warning',
   'raw' => 't3://page?uid=196 _blank warning "Click me" ?bla=1'
]

                                                                                                
[
   'timeForSorting' => 62880,
   'formatedTime' => '17:28'
]

                                                                                                
[
   'unix' => 1629898260,
   'day' => '25',
   'dayNonZero' => '25',
   'weekDayText' => 'Mittwoch',
   'weekDayTextShort' => 'Mi',
   'month' => '08',
   'monthText' => 'August',
   'monthTextShort' => 'Aug',
   'year' => '2021',
   'hour' => '13',
   'minute' => '31',
   'second' => '00',
   'dateForSorting' => '2021-08-25',
   'formatedDate' => '25.08.2021',
   'formatedDateShort' => '25.08.21',
   'formatedDateShorter' => '25.08.',
   'dayOfWeek' => '3',
   'weekOfYear' => '34',
   'formatedTime' => '13:31',
]

Hello
World

                                                                                                
Hello<br />World

<h1>Lorem Ipsum</h1><p><a href="t3://page?uid=123">Click me</a></p>

                                                                                                
<h1>Lorem Ipsum</h1><p><a href="/a-page">Click me</a></p>

                                                                                                
[
   [
      'uid' => 1
      'url' => 'fileadmin/user_upload/my-image-original.jpg',
      'alt' => 'some text',
      'title' => 'some text',
      'description' => 'some text',
      'link' => NULL,
      // 'cropped' is just available for image-files
      'cropped' => [
         'desktop' => 'fileadmin/_processed_/1/my-image-original-max-width-3000.jpg',
         'medium' => 'fileadmin/_processed_/1/my-image-original-max-width-1920.jpg',
         'tablet' => 'fileadmin/_processed_/1/my-image-original-max-width-1024.jpg',
         'mobile' => 'fileadmin/_processed_/1/my-image-original-max-width-920.jpg'
      ]
   ],
   /* maybe more images ... */
]

Registry Service 

Simple Memory cache class, handy for use before TYPO3 native caches are available (they can not be injected/instantiated during ext_localconf.php).

class RegistryService

Fully qualified name

\Jar\Utilities\Services\RegistryService

set ( $storeName, $key, $value)

Put a item in a store.

param string $storeName

Name of the store.

param string $key

Key of the item.

param mixed $value

Value of the item.

Returns

self

get ( $storeName, $key)

Returns a value out of a store.

param string $storeName

Name of the store.

param string $key

Key of the item.

Returns

Value of the item or false.

getWholeStore ( $storeName)

Returns the whole content of a store.

param string $storeName

Name of the store.

Returns

Value of the store or null.

Example:

                                                                                       
$cache = GeneralUtility::makeInstance(RegistryService::class);

$hash = 'my-elements';

if (($elements = $cache->get('my-little-store', $hash)) === false) {
   $elements = [1, 2, 3, 4, 5];
   $cache->set('my-little-store', $hash, $elements);
}

var_dump($cache->getWholeStore('my-little-store'));
// Result of var_dump:
[
   'my-elements' => [1, 2, 3, 4, 5]
]

Utilities 

Backend Utility 

Collection of helpers for backend developing.

class BackendUtility

Fully qualified name

\Jar\Utilities\Utilities\BackendUtility

createFrontendLink ( $pageUid, $params)

Creates a frontend link, also in backend context.

param int $pageUid

The page uid.

param array $params

Typolink parameters.

Example:

BackendUtility::createFrontendLink(123, ['lightbox' => 1]);

Copied!

returns

/a-page?lightbox=1&cHash=ffe...

Copied!

Returns

Link url.

currentPageUid ( )

Returns the current page uid (in backend and frontend context).

Example:

BackendUtility::currentPageUid();

Copied!

returns

123

Copied!

Returns

Current page uid.

getHostname ( )

Get the fully-qualified domain name of the host.

Example:

// current Domain is https://example.com/bla
BackendUtility::getHostname();

Copied!

returns

example.com

Copied!

Returns

The fully-qualified host name.

getEditLink ( $table, $uid)

Get route link for editing records in backend.

param string $table

The record table.

param int $uid

The record uid.

Example:

BackendUtility::getEditLink('tt_content', 123);

Copied!

returns

/typo3/index.php?route=%2Frecord%2Fedit&token=75...&returnUrl=%2Ftypo3%2Findex.php%3Froute%3D%252Fmodule%252Fweb%252Flayout%26token%3D74...%26id%3D270%23element-tt_content-123&edit%5Btt_content%5D%5B123%5D=edit

Copied!

Returns

The resulting link.

getWrappedEditLink ( $table, $uid, $content)

Get route link for editing records in backend. Wrapped in a <a>-Tag

param string $table

The record table.

param int $uid

The record uid.

param string $content

Inner HTML of the <a>-tag.

Example:

BackendUtility::getWrappedEditLink('tt_content', 123, 'Click to edit');

Copied!

returns

<a href="/typo3/index.php?route=%2Frecord%2Fedit&token=...">Click to edit</a>

Copied!

Returns

The resulting <a>-tag.

getWizardInformations ( $ctype)

Returns informations from the "New Content Wizard".

param string $ctype

The CType.

Example:

BackendUtility::getWizardInformations('html');

Copied!

returns

[
   'iconIdentifier' => 'content-special-html',
   'title' => 'Plain HTML',
   'description' => 'With this element you can insert raw HTML code on the page.'
]

Copied!

Returns

Informations about that wizard.

getCurrentPageTS ( )

Returns the current page TSconfig as array.

Example:

BackendUtility::getCurrentPageTS();

Copied!

returns

[      
   mod => array(/* 6 items */),
   TCEMAIN => array(/* 4 items */),
   TCEFORM => array(/* 3 items */),
   RTE => array(/* 1 item */),
   options => array(/* 1 item */),
   TCAdefaults => array(/* 2 items */),
   tt_content => array(/* 1 item */),
]

Copied!

Returns

Current page TSconfig.

Content Utility 

Load and render content elements.

class ContentUtility

Fully qualified name

\Jar\Utilities\Utilities\ContentUtility

renderElement ( $uid)

Render the frontend output of a content element.

param int $uid

The content element uid.

Example:

ContentUtility::renderElement(123);

Copied!

returns

<div id="c123" class="component mediabox--outer">
   <div class="mediabox bg-deepgrey">
         <div class="container content">
            <!-- ... -->
      </div>
   </div>
</div>

Copied!

Returns

The rendered markup.

Data Utility 

Doing database related stuff.

class DataUtility

Fully qualified name

\Jar\Utilities\Utilities\DataUtility

getRow ( $table, $uid)

Load one record from a table.

param string $table

The table name.

param int $uid

The record uid.

Example:

DataUtility::getRow('tt_content', 123);

Copied!

returns

[
   'uid' => 1455,
   'pid' => 267,
   't3ver_oid' => 0,
   't3ver_wsid' => 0,
   't3ver_state' => 0,
   't3ver_stage' => 0,
   't3ver_count' => 0,
   't3ver_tstamp' => 0,
   't3ver_move_id' => 0,
   't3_origuid' => 0,
   'tstamp' => 1637579249,
   'crdate' => 1637579249,
   'cruser_id' => 9,
   'editlock' => 0,
   'hidden' => 0,
   'sorting' => 128,
   'CType' => 'html',
   'header' => '',
   'header_position' => '',
   'rowDescription' => NULL,
   'bodytext' => '...',
   // ...
]

Copied!

Returns

The resulting row.

Extension Utility 

Load informations from TYPO3 extensions.

class ExtensionUtility

Fully qualified name

\Jar\Utilities\Utilities\ExtensionUtility

getExtensionConfiguration ( $extkey)

Loads the configuration from a extension.

param string $extkey

The extension key.

Example:

ExtensionUtility::getExtensionConfiguration('backend');

Copied!

returns

[        
   'backendFavicon' => '',
   'backendLogo' => '',
   'loginBackgroundImage' => '',
   'loginFootnote' => '',
   'loginHighlightColor' => '',
   'loginLogo' => ''
]

Copied!

Returns

The extension configuration.

getAbsExtPath ( $extkey, $path)

Get the absolute path to a extension.

param string $extkey

The extension key.

param string $path

Optional path in extension directory.

Example:

ExtensionUtility::getAbsExtPath('backend', 'Resources/Public');

Copied!

returns

/var/www/.../typo3/sysext/backend/Resources/Public

Copied!

Returns

The absolute path.

getExtensionVersion ( $extkey)

Same as ExtensionManagementUtility::getExtensionVersion but removes the trailing "v". Handy when using version_compare.

param string $extkey

The extension key.

Example:

debug( ExtensionManagementUtility::getExtensionVersion('core') );
// returns 'v11.5.9'

debug( ExtensionUtility::getExtensionVersion('core') );
// returns '11.5.9'

Copied!

Returns

The extension version as a string in the format "x.y.z".

File Utility 

Handle files and their references.

class FileUtility

Fully qualified name

\Jar\Utilities\Utilities\FileUtility

getFileReferenceByUid ( $uid)

Loads \TYPO3\CMS\Core\Resource\FileReference object from sys_file_reference table via UID.

param int $uid

UID of the sys_file_reference record.

Example:

FileUtility::getFileReferenceByUid(123);

Copied!

returns

// TYPO3\CMS\Core\Resource\FileReference
{
   'propertiesOfFileReference' => /* ... */,
   'name' => /* ... */,
   'originalFile' => /* ... */,
   'mergedProperties' => /* ... */
}

Copied!

Returns

TYPO3\CMS\Core\Resource\FileReference or null if resource doesn't exist or file is missing.

buildFileArrayBySysFileReferenceUid ( $uid, $configuration)

Shorthand for FileUtility::buildFileArrayBySysFileReference(FileUtility::getFileReferenceByUid($uid)), accepts the UID of an FileReference instead of using the FileReference object directly.

param int $uid

UID of the sys_file_reference record.

param array $configuration

(optional) See buildFileArrayBySysFileReference for further details.

Example:

FileUtility::buildFileArrayBySysFileReferenceUid(123);

Copied!

returns

[
   'uid' => 123
   'url' => 'fileadmin/user_upload/my-image-original.jpg',
   'alt' => 'some text',
   'title' => 'some text',
   'description' => 'some text',
   'link' => NULL,
]

Copied!

Returns

File-information array or null if resource doesn't exist or file is missing.

buildFileArrayBySysFileReference ( $fileReference, $configuration)

Preparation of files and images in a simple array structure. Very helpful in image preparation and cropping.

param \TYPO3\CMS\Core\Resource\FileReference

$fileReference

param array $configuration

(optional). The configuration is based on three settings:

1. showDetailedInformations (bool): For all kind of files. If active, list more informations about the file (name, extension, type, mimetype, size, basename).

Warning

This has an noticeable impact on performance when a huge amount of files is processed.

2. tcaCropVariants (array): Just for images. List of -, which are applied to the images.

Tip

Instead of putting this together yourself, it's easier to use the Reflection Service or Reflection Processor. These automatically read the tcaCropVariants from the corresponding TCA configurations of the images.

3. processingConfigurationForCrop (array): Just for images. Configuration how the image should be proceed in the different tcaCropVariants. Configurations like maxWidth, minWidth, width (applies also for heigth) are possible.

Example:

FileUtility::buildFileArrayBySysFileReference(
   $aFileReference,
   [			
      // show informations about file
      'showDetailedInformations' => true,

      // set cropping variants
      'tcaCropVariants' => [
         'desktop' => [
            /* .. */
            'cropArea' => [
               'x' => 0.0,
               'y' => 0.0,
               'width' => 1.0,
               'height' => 1.0,
            ]
         ], 
         'mobile' => [
            /* .. */
            'cropArea' => [
               'x' => 0.0,
               'y' => 0.0,
               'width' => 1.0,
               'height' => 1.0,
            ]
         ]
      ],

      // set image rendering instructions for the different cropping variants             
      'processingConfigurationForCrop' => [
         'desktop' => [
            'maxWidth' => 3000
         ],
         // will be ignored, because we have no tcaCropVariants['medium'] informations
         'medium' => [
            'maxWidth' => 1920
         ],
         // will be ignored, because we have no tcaCropVariants['tablet'] informations
         'tablet' => [
            'maxWidth' => 1024
         ],
         'mobile' => [
            'maxWidth' => 920
         ]
      ]
   ]
);

Copied!

returns

                                                                                             
[      
   // base informations
   'uid' => 1
   'url' => 'fileadmin/user_upload/my-image-original.jpg',
   'alt' => 'some text',
   'title' => 'some text',
   'description' => 'some text',
   'link' => NULL,

   // detailed informations
   'name' => 'my-image-original.jpg',
   'extension' => 'jpg',
   'type' => 2,
   'mimetype' => 'image/jpeg',
   'size' => 2313,
   'basename' => 'my-image-original',

   // 'cropped' is just available for image-files
   'cropped' => [
      'desktop' => 'fileadmin/_processed_/1/my-image-original-max-width-3000.jpg',           
      'mobile' => 'fileadmin/_processed_/1/my-image-original-max-width-920.jpg'
   ]

   // if the extension "focuspoint" is installed, you also get the following properties
   'has_focuspoint' => true,
   'focuspoint' => [
      'x' => 0.1,
      'y' => 0.2,
      'w' => 0.3,
      'h' => 0.4
   ]
]

Copied!

Returns

File-information array or null if resource doesn't exist or file is missing.

buildFileArrayByFile ( $file, $configuration)

Same as buildFileArrayBySysFileReference based on a file object

param \TYPO3\CMS\Core\Resource\File $file

The file object

param array $configuration

(optional) See buildFileArrayBySysFileReference for further details.

Returns

File-information array or null if resource doesn't exist or file is missing.

buildFileArrayByPath ( $path, $configuration)

Same as buildFileArrayBySysFileReference based on a file path.

param string $path

The file path

param array $configuration

(optional) See buildFileArrayBySysFileReference for further details.

Returns

File-information array or null if resource doesn't exist or file is missing.

getFileByPath ( $path)

Returns the File object to a given path.

param $path $path

UID of the sys_file_reference record.

Returns

File object or null if resource doesn't exist or file is missing.

humanFilesize ( $bytes, $decimals = 2)

Converts filesizes in a human readable format.

param int $bytes

Size of file in bytes.

param int $decimals

(optional) Length of decimals.

Example:

FileUtility::humanFilesize(123456);    // 120.56 kB
FileUtility::humanFilesize(123456, 0); // 121 kB

Copied!

Returns

Filesize in human readable format.

Format Utility 

Utility Class which mainly converts TYPO3 Backend strings to handy arrays.

class FormatUtility

Fully qualified name

\Jar\Utilities\Utilities\FormatUtility

buildLinkArray ( $params)

Converts t3link parameters to a list of ready-to-use link informations.

param string $params

T3link parameters.

Example:

FormatUtility::buildLinkArray('t3://page?uid=196 _blank warning "Click me" ?bla=1');

Copied!

returns

[
   'url' => 'https://example.com/a-page?bla=1',
   'base' => 'https://example.com/a-page',
   'params' => '?bla=1',
   'target' => '_blank',
   'text' => 'Click me',
   'class' => 'warning',
   'raw' => 't3://page?uid=196 _blank warning "Click me" ?bla=1'
]

Copied!

Returns

Link informations or null when failed.

buildTimeArray ( $time)

Build time information for a stored time.

param int $time

Time in seconds.

Example:

FormatUtility::buildTimeArray(62880);

Copied!

returns

[
   'timeForSorting' => 62880,
   'formatedTime' => '17:28'
]

Copied!

Returns

Time informations or null when failed.

buildDateTimeArrayFromString ( $date)

Build date informations from a date string.

param string $date

Date string.

Example:

FormatUtility::buildDateTimeArrayFromString('2021-08-25 13:31:00');

Copied!

returns

[
   'unix' => 1629898260,
   'day' => '25',
   'dayNonZero' => '25',
   'weekDayText' => 'Mittwoch',
   'weekDayTextShort' => 'Mi',
   'month' => '08',
   'monthText' => 'August',
   'monthTextShort' => 'Aug',
   'year' => '2021',
   'hour' => '13',
   'minute' => '31',
   'second' => '00',
   'dateForSorting' => '2021-08-25',
   'formatedDate' => '25.08.2021',
   'formatedDateShort' => '25.08.21',
   'formatedDateShorter' => '25.08.',
   'dayOfWeek' => '3',
   'weekOfYear' => '34',
   'formatedTime' => '13:31',
]

Copied!

Returns

Date informations or null when failed.

buildDateTimeArray ( $date)

Build date informations from a DateTime object.

param \DateTime $date

DateTime object.

Example:

Same as buildDateTimeArrayFromString, but with a \DateTime object as parameter.

Returns

Date informations or null when failed.

renderRteContent ( $value)

Compiles rich-text to the final markup.

param string $value

The rich-text.

Example:

FormatUtility::renderRteContent('<h1>Lorem Ipsum</h1><p><a href="t3://page?uid=123">Click me</a></p>');

Copied!

returns

<h1>Lorem Ipsum</h1><p><a href="/a-page">Click me</a></p>

Copied!

Returns

string The final markup.

Frontend Utility 

Get Informations about the current Frontend.

class FrontendUtility

Fully qualified name

\Jar\Utilities\Utilities\FrontendUtility

getCurrentPageUid ( )

Returns the current Page UID.

Returns

int The current Page UID

getCurrentLanguageId ( )

Returns the current active language ID.

Returns

int The current active language ID.

Iterator Utility 

Helpers for iterate and handle throught lists.

class IteratorUtility

Fully qualified name

\Jar\Utilities\Utilities\IteratorUtility

sortArrayByColumn ( &$arr, $col, $dir = SORT_ASC)

Sort array by column/key value.

param array $arr

Reference of array.

param string $col

The column/key name.

param int $dir

The direction SORT_ASC or SORT_DESC

Example:

$persons = [
   [
      'name' => 'peter',
      'age' => 34
   ],
   [
      'name' => 'klaus',
      'age' => 21
   ],
   [
      'name' => 'michael',
      'age' => 17
   ],
];

IteratorUtility::sortArrayByColumn($persons, 'age');

Copied!

returns

[
   [
      'name' =>  'michael' 
      'age' =>  17
   ],
   [
      'name' =>  'klaus' 
      'age' =>  21
   ],
   [
      'name' =>  'peter' 
      'age' =>  34
   ]
]

Copied!

extractValuesViaGetMethod ( $listOfObjects, $methodName)

Extracts properties from objects via their get method.

param array $listOfObjects

List of objects.

param string $methodName

The name of the method, without the beginning 'get'.

Example:

class Person
{
   private string $name;

   function __construct($name)
   {
      $this->name = $name;
   }

   public function getName(): string
   {
      return $this->name;
   }
};

/* ... */


$persons = [ new Person('klaus'), new Person('peter')];
$names = IteratorUtility::extractValuesViaGetMethod($persons, 'name');

var_dump($names);

Copied!

returns

['klaus', 'peter']

Copied!

Returns

Extracted values.

extractValuesViaGetMethodFlattened ( $listOfObjects, $methodName, $keepKeys = false)

Extracts properties from objects via their get method and flattens the result.

param array $listOfObjects

List of objects.

param string $methodName

The name of the method, without the beginning 'get'.

param bool $keepKeys

Keep keys in result. Will overwrite existing values for this key.

Example:

class Element
{
   private array $items;

   function __construct($items)
   {
      $this->items = $items;
   }

   public function getItems(): array
   {
      return $this->items;
   }
};

/* ... */


$elements = [
   new Element(
      [
         'a' => 1,
         'b' => 2,
         'c' => 3,
         'd' => 4
      ]
   ),
   new Element([
      'e' => 5,
      'f' => 6,
      'g' => 7,
      'a' => 8
   ])
];

// without "keepKeys"

$allItems = IteratorUtility::extractValuesViaGetMethodFlattened($elements, 'items');      
var_dump($allItems);
/*
   Result:
      0 =>  1
      1 =>  2
      2 =>  3
      3 =>  4
      4 =>  5
      5 =>  6
      6 =>  7
      7 =>  8
*/

// with "keepKeys"

$allItems = IteratorUtility::extractValuesViaGetMethodFlattened($elements, 'items', true);
var_dump($allItems);
/*
   Result:
      'a' =>  8
      'b' =>  2
      'c' =>  3
      'd' =>  4
      'e' =>  5
      'f' =>  6
      'g' =>  7
*/

Copied!

Returns

Extracted flattened values.

callMethod ( $listOfObjects, $method)

Calls a method in each object and returns the results.

param array $listOfObjects

List of objects.

param string $method

name of the method.

Example:

class Element
{
   private int $number;

   function __construct($number)
   {
      $this->number = $number;
   }

   public function add(): int
   {
      return $this->number + 1;
   }
};

/* ... */

$numbers = [ new Element(5), new Element(2) ];

$addedNumbers = IteratorUtility::callMethod($numbers, 'add');

var_dump($addedNumbers);

Copied!

returns

[6, 3]

Copied!

Returns

List of method results.

compact ( $arr)

Returns a copy of the list with all falsy values (null, 0, '') removed.

param array $arr

List with values.

Example:

IteratorUtility::compact(['hello', null, '', 0, 'world'])

Copied!

returns

['hello', 'world']

Copied!

Returns

List without falsy values

flatten ( $arr)

Flattens a nested array.

param array $arr

The nested array.

Example:

IteratorUtility::flatten([
   [1, 2, 3],
   [4, 5],
   [6]
]);

Copied!

returns

[1, 2, 3, 4, 5, 6]

Copied!

Returns

The flat array.

filter ( $arr, $func)

Filters a list with a closure condition

param array $arr

The array.

param callable $func

The filter closure.

Example:

IteratorUtility::filter(
   [1, 2, 3, 4, 5, 6],
   function($value) {            
      return (bool) ($value % 2);
   }
);

Copied!

returns

[1, 3, 5]

Copied!

Returns

The filtered result.

map ( $arr, $func)

Iterates each item and maps the new value throught a function.

param array $arr

The array.

param callable $func The transformation function (receives three parametes

1. value, 2. key, 3. current transformated list).

Example:

IteratorUtility::map(
   [1, 2, 3, 4, 5, 6],
   function($value) {            
      return $value * 2;
   }
);

Copied!

returns

[2, 4, 6, 8, 10, 12]

Copied!

Returns

The mapped array.

first ( $arr)

Returns the first element from a list.

param array $arr

The array.

Example:

IteratorUtility::first(['hello', 'world'])

Copied!

returns

'hello'

Copied!

Returns

First element.

pluck ( $arr, $key)

Extracts a the value of a certain key.

param array $arr

The array.

param string $key

The key.

Example:

$persons = [
   [
      'name' => 'peter',
      'age' => 34
   ],
   [
      'name' => 'klaus',
      'age' => 21
   ],
   [
      'name' => 'michael',
      'age' => 17
   ],
];

IteratorUtility::pluck($persons, 'name');

Copied!

returns

['peter' , 'klaus' , 'michael']

Copied!

Returns

The extracted values.

contains ( $arr, $needle)

Checks if a value exist in an array.

param array $arr

The array.

param string $needle

The value to check.

Example:

// true
IteratorUtility::contains([1, 2, 3, 4, 5, 6], 2);

// false
IteratorUtility::contains([1, 2, 3, 4, 5, 6], 7);

Copied!

Returns

Check result.

whitelist ( $array, $whitelist)

Returns only array entries listed in a whitelist.

param array $array

Original array to operate on.

param array $whitelist

Keys you want to keep.

Example:

IteratorUtility::whitelist([
   'a' => 1,
   'b' => 2,
   'c' => 3,
   'd' => 4
], ['a', 'c']);

Copied!

returns

[
   'a' =>  1,
   'c' =>  3
]

Copied!

Returns

The whitelisted entries.

whitelistList ( $array, $whitelist)

Returns only nested array entries listed in a whitelist.

param array $array

List of nested array items

param array $whitelist

Keys you want to keep.

Example:

IteratorUtility::whitelistList([
   [
      'a' => 1,
      'b' => 2,
      'c' => 3,
      'd' => 4
   ],
   [
      'a' => 5,
      'b' => 6,
      'c' => 7,
      'd' => 8
   ]
], ['a', 'c'])

Copied!

returns

[
   [
      'a' =>  1,
      'c' =>  3
   ],
   [
      'a' =>  5,
      'c' =>  7
   ]
] 

Copied!

Returns

The whitelisted entries.

indexBy ( $arr, $key)

Create a indexed list based on key values.

param array $array

The array.

param string $key

The index key name.

Example:

$persons = [
   [
      'id' => 5,
      'name' => 'peter',
   ],
   [
      'id' => 2,
      'name' => 'klaus',
   ],
   [
      'id' => 3,
      'name' => 'michael',
   ],
];      

var_dump($persons);
/*
   Result: 
   [
      0 => [
         'id' =>  5
         'name' =>  'peter'
      ],
      1 => [
         'id' =>  2
         'name' =>  'klaus'
      ],
      2 => [
         'id' =>  3
         'name' =>  'michael'
      ]
   ]
*/

$indexedPersons = IteratorUtility::indexBy($persons, 'id');

var_dump($indexedPersons);
/*
   Result: 
   [
      5 => [
         'id' =>  5
         'name' =>  'peter'
      ],
      2 => [
         'id' =>  2
         'name' =>  'klaus'
      ],
      3 => [
         'id' =>  3
         'name' =>  'michael'
      ]
   ]
*/

Copied!

Returns

The indexed List.

Localization Utility 

Shorthands for receiving and output translations.

class LocalizationUtility

Fully qualified name

\Jar\Utilities\Utilities\LocalizationUtility

loadTyposcriptTranslations ( $extension)

Loads the translations, set by _LOCAL_LANG from a extension.

param string $extension

Extension Key without the beginnining tx_

Example:

plugin.tx_myextension._LOCAL_LANG {
   default {
      hello = Hello
      world = World
   }
   de {
      hello = Hallo
   }
}

Copied!

LocalizationUtility::loadTyposcriptTranslations('myextension');

Copied!

returns

// in EN
[
   'hello' =>  'Hello',
   'world' =>  'World',
]

// in DE
[
   'hello' =>  'Hallo',
   'world' =>  'World',
]

Copied!

Returns

The translations.

getLanguageService ( )

Get the current Language Service.

Returns

The Language Service.

localize ( $input)

Localize a translation key to the translation value.

param string $input

The translation key.

Returns

The translation value or the translation key, when no translation is found.

Number Utility 

Utility Class for working with numbers.

class NumberUtility

Fully qualified name

\Jar\Utilities\Utilities\NumberUtility

isWholeInt ( $val)

Checks if the value represents a whole number (integer).

param mixed $val

The value to check.

Example:

NumberUtility::isWholeInt(1234);
// returns true      

NumberUtility::isWholeInt(12.34);
// returns false      

NumberUtility::isWholeInt("01234");
// returns true      

NumberUtility::isWholeInt("1234");
// returns true      

NumberUtility::isWholeInt("hello");
// returns false      

NumberUtility::isWholeInt("");
// returns false      

NumberUtility::isWholeInt(null);
// returns false

Copied!

Returns

"True" if is a whole number else return "false".

Page Utility 

Doing Page (and Pagetree) related stuff.

class PageUtility

Fully qualified name

\Jar\Utilities\Utilities\PageUtility

getPidsRecursive ( $pids, $level = 3)

Returns all Sub-Pids of certain PIDs.

param string $pids

The starting PID.

param int $level

Depth of the traversing levels.

Example:

|

var_dump(PageUtility::getPidsRecursive(1));
// ['1','2', '3', '7', '8', '4', '5', '9', '10', '6']

var_dump(PageUtility::getPidsRecursive(1, 1));
// ['1','2', '3', '4', '5', '6']

Copied!

Returns

List of matching PIDs.

getPageFieldSlided ( $fieldname)

Slides up a the Pagetree (starting from the current page) and return the nearest filled value of the field.

param string $fieldname

Name of the field/column.

Returns

Value of the field when found, otherwise "null".

String Utility 

Collection of string helpers.

class StringUtility

Fully qualified name

\Jar\Utilities\Utilities\StringUtility

crop ( $value, int $maxCharacters = 150)

Crops a string.

param string $value

The string to crop.

param int $maxCharacters

Length of cropping.

Example:

var_dump(StringUtility::crop('Lorem ipsum dolor sit amet.', 20));
// 'Lorem ipsum dolor...'

// Respects also crops in Tags
var_dump(StringUtility::crop('<h1>Lorem ipsum dolor sit.</h1>', 20));
// '<h1>Lorem ipsum dolor...</h1>'

Copied!

Returns

The cropped string.

ripTags ( $string)

Same as "strip_tags" but leaves spaces at the position of removed tags.

param string $string

The string to strip.

Example:

var_dump(strip_tags('<span>Hello</span><span>World</span>'));
// 'HelloWorld'

var_dump(StringUtility::ripTags('<span>Hello</span><span>World</span>'));
// 'Hello World'

Copied!

Returns

The stripped string.

fastSanitize ( $string, $toLowerCase = true)

Simple sanitizing of strings, no complex handling of umlauts like "äöü".

param string $string

The string to sanitize.

param bool $toLowerCase

Should the string converted to lower case?

Example:

var_dump(StringUtility::fastSanitize('Über wie viele Brücken musst du gehen?', true));
// 'ber_wie_viele_br_cken_musst_du_gehen'

var_dump(StringUtility::fastSanitize('Über wie viele Brücken musst du gehen?', false));
// 'ber_wie_viele_Br_cken_musst_du_gehen'

Copied!

Returns

The sanitized string.

sanitize ( $string, $toLowerCase = true)

More complex sanitizing of strings, also handles of umlauts like "äöü".

param string $string

The string to sanitize.

param bool $toLowerCase

Should the string converted to lower case?

Example:

var_dump(StringUtility::sanitize('Über wie viele Brücken musst du gehen?', true));
// 'ueber_wie_viele_bruecken_musst_du_gehen'

var_dump(StringUtility::sanitize('Über wie viele Brücken musst du gehen?', false));
// 'UEber_wie_viele_Bruecken_musst_du_gehen'

Copied!

Returns

The sanitized string.

TCA Utility 

Utility Class for working faster with the TCA.

class TcaUtility

Fully qualified name

\Jar\Utilities\Utilities\TcaUtility

getColumnsByType ( $table, $type)

Returns active columns by TCA type.

param string $table

The table name.

param string $type

The type name.

Example:

|

var_dump(TcaUtility::getColumnsByType('tt_content', 'html'));
// ['CType', 'colPos', 'header', 'bodytext', 'layout', 'frame_class', ... ]      

var_dump(TcaUtility::getColumnsByType('tt_content', 'image'));
// ['CType', 'colPos', 'header', ..., 'image', 'imagewidth', 'imageheight', ...]

Copied!

Returns

List of column names.

getColumnsByRow ( $table, $row)

Returns active columns based on a table record.

param string $table

The table name.

param array $row

The table record.

Example:

// Shorthand for:
TcaUtility::getColumnsByType( TcaUtility::getTypeFromRow( $row ));

// Example output, see above under "getColumnsByType".

Copied!

Returns

List of column names.

getColumnsByTable ( $table)

Returns all default (first type) columns from a table.

param string $table

The table name.

Returns

List of column names.

getTypeFromRow ( $table, $row)

Returns actice TCA type based on a table record.

param string $table

The table name.

param array $row

The table record.

Returns

Name of the type will fallback to default type when no individual type is found.

getVisibleColumnsByRow ( $table, $row)

Just return the columns which are visible for the current Backend User, respects current active display conditions of fields.

param string $table

The table name.

param array $row

The table record.

Returns

List of column names.

getTypeFieldOfTable ( $table)

Returns the column name which contains the "type" value from a table.

param string $table

The table name.

Returns

The name of the "type" column.

getLabelFieldOfTable ( $table)

Returns the column name which contains the "label" value from a table.

param string $table

The table name.

Returns

The name of the "label" column.

getLabelFromRow ( $row, $table)

Returns the label from a table record.

param array $row

The table record.

param string $table

The table name.

Example:

TcaUtility::getLabelFromRow([
   'uid' => 3,
   'doktype => 254',
   'title' => 'Elemente',
   /* ... */
], 'pages');

// returns "Elemente"

Copied!

Returns

The label or "null" when empty.

mapStringListToColumns ( $list, $table = null, $extendedList = false)

Converts a comma-separated list of TCA Columns (a,b,c) to [a,b,c]. Also columns of containing pallets will be resolved (if parameter table is available).

param string $list

Comma-separated list of TCA Columns.

param string $table

The table name.

param bool $extendedList

Flag for returning extendedList.

Returns

List of column names or list of [column name | label] when $extendedList is active.

getFieldDefinition ( $table, $column, $type = null)

Returns the current TCA field definition from a table column. Also resolves column overrides when parameter "type" is set.

param string $table

The table name.

param string $column

The column name.

param null|string $type

The type to respect column overrides.

Returns

The field definition or "null" when no field definition is found.

getFieldConfig ( $table, $column, $type = null)

Returns the TCA field configuration from a table column.

param string $table

The table name.

param string $column

The column name.

param null|string $type

The type to respect column overrides.

Returns

The field configuration or "null" when no field configuration is found.

remapItemArrayToKeybasedList ( $items)

Converts a TCA item array to a key-based list.

param array $items

TCA item array.

Example:

TcaUtility::remapItemArrayToKeybasedList([['LLL:.../locallang.xlf:creation', 'uid'], ['LLL:.../locallang.xlf:backendsorting', 'sorting']]);

// returns:

[
   'uid' => [
      'label' => 'LLL:.../locallang.xlf:creation',
      'icon' => null
   ],
   'sorting' => [
      'label' => 'LLL:.../locallang.xlf:backendsorting',
      'icon' => null
   ]
]

Copied!

Returns

Key-based list.

getLabelOfSelectedItem ( $value, $column, $table, $type = null, $localize = true)

Load the backend label from a selected item.

param string $value

The selected item. F.e ['LLL:.../locallang.xlf:backendsorting', 'sorting']

param string $column

Column name which contains the selected item.

param string $table

The table name.

param null|string $type

The type to respect column overrides.

param boolean $localize

If false return the raw value, otherwise return the translated value.

Returns

The label.

getL10nConfig ( $table)

Returns the TCA language fields from a table or null, if not set.

param string $table

The table name.

Returns

TCA language fields from a table or null, if not set

getTca ( )

Returns the current TCA.

Returns

The TCA.

TypoScript Utility 

Load and progress faster with TypoScript.

class TypoScriptUtility

Fully qualified name

\Jar\Utilities\Utilities\TypoScriptUtility

get ( $path = null, $pageUid = null, $populated = false)

Loads current TypoScript like TypoScriptUtility::get('plugin.tx_jarfeditor.settings')

param string|null $path

Dot notated TypoScript path.

param int|null $pageUid

PageUid from which page the TypoScript should be loaded (optional in Frontend).

param bool $populated

should the Data be populated (f.e. "element = TEXT / element.value = Bla" => "element = Bla").

Returns

The plain TypoScript array.

convertTypoScriptArrayToPlainArray ( $typoscriptArray)

Wrapper for the Core convertTypoScriptArrayToPlainArray

param array $typoscriptArray

A TypoScript array.

Returns

The plain TypoScript array or "null" when not found.

populateTypoScriptConfiguration ( $conf, $cObj = null)

Resolves cObjects and leaves values without deeper configuration as they are

param array $conf

Plain TypoScript array.

param null|ContentObjectRenderer $cObj

ContentObject which should be used.

Example:

# converts this typoscript array from ...
   hello = world
   element = TEXT 
   element.value = Bla
   tree.value = Blupp
   
# ... to this:
   hello = world
   element = Bla
   tree.value = Blupp

Copied!

Returns

The plain populated TypoScript array.

Wildcard Utility 

Utility Class for handling wildcard opertations like "b?a_*"

class WildcardUtility

Fully qualified name

\Jar\Utilities\Utilities\WildcardUtility

matchAgainstPatternList ( $patterns, $string, $flags = 0)

Matches a string against a whole list of patterns, returns "true" on first match

param array $patterns

List of patterns like ['b?a_', 'plupp_']

param string $string

The string to match.

param int $flags

Flags ("FNM_PATHNAME" or 1, "FNM_NOESCAPE" or 2, "FNM_PERIOD" or 4, "FNM_CASEFOLD" or 16) based on https://www.php.net/manual/en/function.fnmatch.php#refsect1-function.fnmatch-parameters

Returns

Returns "true" on first match, otherwise false.

match ( $pattern, $string, $flags = 0)

Simple wildcard which matches a string against a pattern. Wildcards like * or ? are useable.

param string $pattern

The Pattern like "hello*world"

param string $string

The string to match.

param int $flags

Flags ("FNM_PATHNAME" or 1, "FNM_NOESCAPE" or 2, "FNM_PERIOD" or 4, "FNM_CASEFOLD" or 16) based on https://www.php.net/manual/en/function.fnmatch.php#refsect1-function.fnmatch-parameters

Example:

$pattern = 'hello*world';

WildcardUtility::match($pattern, 'hello beatiful world'); // true
WildcardUtility::match($pattern, 'hello happy planet');   // false

Copied!

Returns

Returns "true" on match, otherwise false.

Sitemap 

Index 

Note: This index page has just entered the scene. I will develop gradually.

Overview