Resources API 

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.

<?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',
    );
  }
}

Resource identifiers: referencing files with EXT:, PKG:, FAL: and URLs 

Where TYPO3 resolves a system resource, for example in the TypoScript property includeCSS , in the asset collector, in Fluid or in the PHP API, it accepts these resource identifiers:

PKG:my-vendor/my-extension:Resources/Public/Css/main.css

A file in a package, identified by its Composer name. This works in classic mode as well, if the extension has a composer.json. The EXT: syntax can still be used for extensions.

PKG:typo3/app:public/typo3temp/assets/style.css

A file of the project itself, with the virtual package name typo3/app and a path relative to the project root.

FAL:1:/templates/css/main.css

A file in the file storage with the UID 1.

https://example.org/css/main.css or URI:/css/main.css

A URL, or a URL relative to the current host. An invalid URL throws an exception instead of ending up in the HTML.

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.

<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>

const myMapElement= document.getElementById('myMap');

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

<f:variable
  name="addresses"
  value="PKG:my-vendor/my-extension:Resources/Public/XML/addresses.xml"
/>
<div
  id="myMap"
  data-addresses="{addresses -> f:resource() -> f:uri.resource()}"
></div>

<?php

declare(strict_types=1);

namespace MyVendor\MyExtension\Controller;

use Psr\Http\Message\ServerRequestInterface;
use TYPO3\CMS\Core\SystemResource\Publishing\SystemResourcePublisherInterface;
use TYPO3\CMS\Core\SystemResource\Publishing\UriGenerationOptions;
use TYPO3\CMS\Core\SystemResource\SystemResourceFactory;

final readonly class MyMapController
{
  public function __construct(
    private SystemResourceFactory $systemResourceFactory,
    private SystemResourcePublisherInterface $resourcePublisher,
  ) {}

  public function getAddressesUrl(ServerRequestInterface $request): string
  {
    $resource = $this->systemResourceFactory->createPublicResource(
      'PKG:my-vendor/my-extension:Resources/Public/XML/addresses.xml',
    );
    return (string)$this->resourcePublisher->generateUri(
      $resource,
      $request,
      new UriGenerationOptions(absoluteUri: true),
    );
  }
}