Resources API 

TYPO3 projects and extensions can reference two types of resource files:

Public resources that should be accessible with a browser, such as CSS and JavaScript files, images and downloads.

Private resources that are used by server-side code, such as templates, configuration files and localization files.

Table of contents

Location for resources in Composer-mode installations 

By default, public resources must be put into the folder Resources/Public of an extension or somewhere within the web root folder in Composer-based installations. Private resources should reside in folder Resources/Private or Configuration of an extension or the folders config/sites or config/system.

Images and downloads may reside in folder public/fileadmin or custom file storage.

Resources in classic mode installations 

In TYPO3 classic mode, all files in extensions are already located within the document root. Restricting resources to default locations in classic mode therefore mainly follows coding guidelines and keeps compatibility with Composer mode.

Classic mode installations should use server side access restriction, for example by using .htaccess or Nginx configurations. .htaccess can be automatically tested and adjusted: Verify webserver configuration (.htaccess).

Referencing private resources on the server side 

The actual directory location where a file can be found varies from installation to installation. It depends on the mode (Composer / Classic) and on certain configuration, for example of the vendor folder. You should therefore avoid using absolute or large relative paths like ../../../../public/_assets/12345.

The EXT: syntax: referencing resources in extensions 

Most API functions in PHP and TypoScript expect files to reside in extensions and accept a syntax such as EXT:my_extension/Resources/Private/Page/Default.html.

They resolve the path internally. my_extension is the extension key as defined in extra.typo3/cms.extension-key in the extension's composer.json, the rest is the relative path from that extension's root folder.

Using API functionality to determine the path to a resource 

In some rare cases you may need the absolute or relative path to a resource from within your code.

GeneralUtility offers utility method GeneralUtility::getFileAbsFileName() to resolve file paths:

packages/my_extension/Classes/Something/MyClass.php 
<?php

declare(strict_types=1);

namespace MyVendor\MyExtension\Something;

use TYPO3\CMS\Core\Utility\GeneralUtility;

class MyClass
{
    public function myFunction(): void
    {
        $absoluteFilePath = GeneralUtility::getFileAbsFileName(
            'EXT:my_extension/Resources/Private/SomeFile.xml',
        );
    }
}
Copied!

The Environment PHP API can be used to resolve paths to other locations within the project such as the path to the config folder.

Referencing public resources 

Public resources such as JavaScript and CSS files are usually referenced using the Asset collector or f.assets.* ViewHelpers.

Public resources should not be referenced by their path in the _assets folder as these paths contain a hash that might change during updates.

Fluid ViewHelper f:uri.resource 

In Fluid you can use the Uri.resource ViewHelper <f:uri.resource> to reference resources. You can then provide the resource path in a data attribute:

packages/my_extension/Resources/Private/Content/Map.html 
<div id="myMap"
     data-icon="{f:uri.resource(extensionName: 'my_extension', path: 'Icons/Map/marker.svg')}"
     data-addresses="{f:uri.resource(extensionName: 'my_extension', path: 'XML/addresses.xml')}"
></div>
Copied!

The file paths can then be used within JavaScript:

packages/my_extension/Resources/Public/JavaScript/Content/Map.js 
const myMapElement= document.getElementById('myMap');

const addresses = myMapElement.dataset.addresses;
const iconPath = myMapElement.dataset.icon;
Copied!

If the assets lie within the same extension you can also use relative paths in the JavaScript and CSS files.

PHP: PathUtility::getAbsoluteWebPath() 

You can use the class \TYPO3\CMS\Core\Utility\PathUtility to get an absolute web path for a public resource via PathUtility::getAbsoluteWebPath():

packages/my_extension/Classes/Controller/MyMapController.php 
<?php

declare(strict_types=1);

namespace MyVendor\MyExtension\Something;

use TYPO3\CMS\Core\Utility\GeneralUtility;
use TYPO3\CMS\Core\Utility\PathUtility;

class MyMapController
{
    public function getWebPath(string $path = 'EXT:my_extension/Resources/Public/myfile.xml'): string
    {
        // This only works in frontend context, not in CLI
        $absolutePath = GeneralUtility::getFileAbsFileName($path);
        return PathUtility::getAbsoluteWebPath($absolutePath);
    }
}
Copied!