UUID

Version: 0.3
Language: en
Authors: Andreas Wolf
Email: dev (at) a-w.io
License: This extension documentation is published under the CC BY-NC-SA 4.0 (Creative Commons) license

{extension.description}

TYPO3

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

Community Documentation

This documentation is community documentation for the TYPO3 extension uuid.

It is maintained as part of this third party extension.

If you find an error or something is missing, please: Report a Problem

Extension Manual

This documentation is for the TYPO3 extension uuid.

For Contributors

You are welcome to help improve this guide. Just click on "Edit me on GitHub" on the top right to submit your change request.

Introduction

What does it do?

This extension provides support for Universally Unique Identifiers (UUIDs) in TYPO3.

From Wikipedia:

A universally unique identifier (UUID) is a 128-bit label used for information in computer systems.

-- https://en.wikipedia.org/wiki/Universally_unique_identifier

With the help of this extension, a UUID can be added to possibly every record in TYPO3. This allows for e.g. safely identifying records that were added by a migration (in contrast to their uid, which depends on the time of execution of the migration, which will be different in each instance like development, stage and production).

Change Log

Version 0.3.3

Allow resolving multiple UUIDs in the TypoScript function uuid, separated by commas.

Version 0.2.2

Fixed version constraint in ext_emconf.php.

Installation

To install this extension, require it via Composer:

.. console::

$ composer require andreaswolf/typo3-uuid

See the Developer chapter for information on how to enable UUIDs for your own extension and how to resolve a UUID back to a record.

Configuration

There is not much configuration to do for this extension.

One decision you have to make is enabling support for UUIDs in t3://page links. If you want to do this (it is not widely tested and thus not enabled by default currently), you can add the following code block to your AdditionalConfiguration.php:

$GLOBALS['TYPO3_CONF_VARS']['SYS']['linkHandler']['page'] =
    \AndreasWolf\Uuid\LinkHandling\UuidEnabledPageLinkHandler::class;

By default, no UUID field is added to any table. So you need to configure UUIDs for your extension‘s own tables and/or core or third-party extension tables. See the developer chapter for more information.

For Developers

API

Resolving UUIDs to records in PHP

Resolving a UUID to a record is performed by \AndreasWolf\Uuid\UuidResolver. One instance of this class is required per table that should be resolved.

To get an instance of this class, you can use \AndreasWolf\Uuid\UuidResolverFactory. This class also checks if a table has UUIDs enabled.

You can also define Dependency Injection services to get resolvers injected into your class:

Configuration/Services.yaml:

Vendor\MyExtension\MyClass:
  public: true
  arguments:
    $pageUuidResolver: '@pageUuidResolver'
    # this resolver is only available for this class
    $contentUuidResolver: !service
      factory: ['@AndreasWolf\Uuid\UuidResolverFactory', 'getResolverForTable']
      arguments:
        $table: 'tt_content'

# this resolver can be used in different classes
# use this in the 'arguments' section:
#   $myArgumentName: '@pageUuidResolver'
'pageUuidResolver':
   factory: ['@AndreasWolf\Uuid\UuidResolverFactory', 'getResolverForTable']
   class: AndreasWolf\Uuid\UuidResolver
   arguments:
     $table: 'pages'

# you can also enable autowiring: all constructor parameters $namedUuidResolver
# in any class will be filled with a UUID resolver for tt_content
AndreasWolf\Uuid\UuidResolver $namedUuidResolver:
  factory: ['@AndreasWolf\Uuid\UuidResolverFactory', 'getResolverForTable']
  class: AndreasWolf\Uuid\UuidResolver
  arguments:
    $table: 'tx_myextension_sometable'

The setup above can then be used to get the resolvers injected into a class, like this:

namespace Vendor\MyExtension;

use \AndreasWolf\Uuid\UuidResolver;

class MyClass {
    public function __construct(
        UuidResolver $pageUuidResolver, // for 'pages'
        UuidResolver $contentResolver, // for 'tt_content'
        UuidResolver $namedUuidResolver // for 'tx_myextension_sometable'
    ) {
        // UUIDs from pages, tt_content and tx_myextension_sometable can be resolved
        // with the three resolvers
    }
}

Resolving UUIDs to records in TypoScript

For TypoScript, there is a custom preprocessor function uuid() that resolves a table-UUID combination into a record UID.

Use it like this:

# e.g. in the sitepackage's constants.typoscript file
somePage := uuid(pages, 12345678-90ab-cdef-1234-567890123456)

Enabling UUIDs for your own tables

Adding UUIDs to your extension’s tables is easy: Just add uuid = true to the ctrl section in your table’s TCA file:

Configuration/TCA/tx_yourext_yourtable.php:

return [
    'ctrl' => [
        // other configuration options here
        'uuid' => true,
    ],
    'columns' => [
        // …
    ],
];

Enabling UUIDs for Core/third-party tables

Enabling the UUIDs for existing tables is done via a service that can be called in TCA override files.

To enable UUIDs for the pages table, place this pages.php file in your extensions‘s Configuration/TCA/Overrides/ folder:

$tableConfigurationService = \TYPO3\CMS\Core\Utility\GeneralUtility::makeInstance(
    \AndreasWolf\Uuid\Service\TableConfigurationService::class
);
$tableConfigurationService->enableUuidForTable('pages');

Known problems

Use this section for informing about any type of of problem.

This extension does not offer a way to automatically generate UUIDs for new/existing records. You currently have to do this by hand, e.g. when creating records via Doctrine Migrations for TYPO3 <https://github.com/andreaswolf/typo3-ext-migrations/>.

Find a list of open issues on Github.

Sitemap

Index

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

About This Extension

Lorem Ipsum Dolor

Feedback and contribute

If you find an error in this manual, please be so kind to hit the "Edit me on GitHub" button in the top right corner and submit a pull request via GitHub.

Alternatively you can just report an issue on GitHub.

You can find more about this in Writing Documentation:

Contribute to the TYPO3 documentation : Make a change by editing directly on GitHub and creating a pull request
Workflow #2: "Local editing and rendering with Docker" : If you are experienced with Docker and Git you can edit and render locally.

If you want to support us, please join the slack channel #example_extension on Slack (Register for Slack).

And finally, as a last resort, you can get in touch with the example extension Team by mail.

Credits

This extension was originally developed by Maria Musterfrau. It was further maintained, refreshed and expanded by Emilio Example

Linktargets

Labels for Cross-Referencing

.. ref-targets-list::