typo3-documentation / typo3cms-reference-coreapi Goto Github PK

https://docs.typo3.org/typo3cms/extensions/core/latest/Changelog/7.6/Breaking-69916-RegisteredAJAXHandlersReplacedByRoutes.html

From @tmotyl on November 4, 2017 0:4

TYPO3 Core team has decided to follow Airbnb CGL rules for JS files.
https://decisions.typo3.org/t/results-define-coding-guidelines-for-javascript/301

In this document we should at last:

• refer to airbnb rule set
• highlight few most important like:
  -- 2 spaces indentation (no TABS)
  -- single quotes should be used
  -- jQuery variable should start with $
  -- space between function keyword and opening bracket like function () {

Copied from original issue: TYPO3-Documentation/TYPO3CMS-Reference-CodingGuidelines#15

This info Feature: #82441 - Inject logger when creating objects should be referenced in the Logging API chapter.

I would like to see more diagrams (or one really good one) which give a general overview of the components, e.g. as in a layer / component diagram or something similar.

I know, more diagrams exist but somehow they haven't found their way into the documentation, e.g.

• Video 2017 from TYPO3 camp "Mitteldeutschland", Oliver Hader, 17:09: https://www.youtube.com/watch?v=Y6wlsAsLc08&feature=youtu.be&t=1028
• There is a diagram in "Inside TYPO3", but the component "CORE" could be broken down further: https://docs.typo3.org/m/typo3/reference-coreapi/master/en-us/Introduction/Index.html#system-overview

FILETYPE_* constants are defined here for TYPO3 8.7:

https://github.com/TYPO3/TYPO3.CMS/blob/TYPO3_8-7/typo3/sysext/core/Classes/Resource/AbstractFile.php#L66

and here for current master (9.2 at the time of writing?):
https://github.com/TYPO3/TYPO3.CMS/blob/master/typo3/sysext/core/Classes/Resource/AbstractFile.php#L66

Currently there seems to be not explanation / table of available FILETYPE_* constants and their usage anywhere in the documentation. I would like to suggest to implement some kind of reference, simply for the sake to have a "lookup table" of "which file type is which constant", preferably in the DAM / FAL Documentation as a separate menu "FILETYPE constants" and may even in the constants table:
https://docs.typo3.org/typo3cms/CoreApiReference/ApiOverview/GlobalValues/Constants/Index.html

Any feedback most welcome!
Thanks to Sybille Peters for help and support!

The table "Elements nesting other elements (“Array” elements)" has horizontal scrollbars at
https://docs.typo3.org/typo3cms/CoreApiReference/DataFormats/T3datastructure/Elements/Index.html

which you don't see until you scroll down to the end of the table.

There is no reason for it to have scrollbars.

Migrated from https://forge.typo3.org/issues/52079
Was: New parameter for ExtensionManagementUtility::addModule

4 years old.

In #49643 Benni introduced a new parameter to 
ExtensionManagementUtility::addModule to be 
able to override (or completely replace) the conf.php 
file for BE modules.

The method is documented in 
Documentation/ApiOverview/MainClasses/UsefulFunctions/Index.rst 
and so this new parameter should be mentioned there.

Additionally a new option "inheritNavigationComponentFromMainModule" 
is available if one want to put a BE module in Web> without a pagetree.

This also makes the "conf.php" file and the included $MCONF and 
$MLANG variables obsolete. There are some mentions to $MCONF
in the same documentation, those could adapted too._

_Any news in here? How should the 5th parameter ($moduleConfiguration) 
look like? It would be a great improvement to get rid of the old "conf.php"...

https://docs.typo3.org/typo3cms/CoreApiReference/ExtensionArchitecture/Documentation/Index.html

Some information is outdated:

• as alternative to ext:sphinx, link to information about rendering with docker (will be added to https://docs.typo3.org/typo3cms/HowToDocument/Index.html)
• "In TYPO3 6.2, the system extension "documentation" is using such a simple manual." : outdated: sysext:documentation has been removed

Additionally,

• add links to reSt reference : https://docs.typo3.org/typo3cms/HowToDocument/WritingReST/Index.html

file https://github.com/TYPO3-Documentation/TYPO3CMS-Reference-CoreApi/blob/5ba7d08dfa028f48b6b5ce7934ee6bb24b8db680/Documentation/ApiOverview/BackendUserObject/Index.rst
contains reference to the condensedMode setting which is long gone.
see https://forge.typo3.org/issues/24585

The documentation of "Plugging a RTE" seems to be deprecated since TYPO3 CMS 7.4.
Link

RTE registration isn't made via $GLOBALS['TYPO3_CONF_VARS']['BE']['RTE_reg'] anymore.
Instead the NodeFactory api is used.

in page File Storages

the sentence

This flag will generally not be set voluntarily

does not appear to be correct.
does someone force you to set the flag if it is not set voluntarily?

This has been transferred from TYPO3-Documentation/TYPO3CMS-Guide-Security#12 - that repository has been inlined into 'core api'

All files and folders can and should be write protected for the webserver/php user. However, fileadmin/ and typo3temp/ and uploads/ cannot be write protected be definition. These folders should be excluded in the webserver configuration from executing PHP files.

Unconfirmed suggestion:

"In a standard setup, TYPO3 CMS does not require to write into any directories other than fileadmin, typo3temp, typo3conf and upload. These directories can and should be write protected for the webserver/PHP user. Depending on the individual setup it is also recommended to prevent executing PHP files in the fileadmin and upload directory."

Note: originally posted by Helmut Hummel as https://forge.typo3.org/issues/73031

Problem:

The change itself is documented in the core: https://docs.typo3.org/typo3cms/extensions/core/Index.html

Some changes however do need other docs (probably mostly this one) to be changed. How do we make sure every change gets properly reflected in the core API?

Or: do we worry about that when the core API is edited for a major release? (Disadvantage: takes longer for change to be documented, some changes may get missed)

Example

See issue #239

the action "paste" is used in some places in the core like:

$commandMap[$tableName][$uid]['move'] = [
                'action' => 'paste',
                'target' => $pageId,
                'update' => $recordData,
            ];
//or
$CMD[$table][$uid][$mode] = [
                        'action' => 'paste',
                        'target' => $pUid,
                        'update' => $update,
                    ];

but it's not documented here:
https://docs.typo3.org/typo3cms/CoreApiReference/ApiOverview/Typo3CoreEngine/Database/Index.html

In https://docs.typo3.org/typo3cms/CoreApiReference/ApiOverview/Namespaces/Index.html#creating-instances the text still speaks of escaping the backslashes, but since the 6.2 documentation the example shows the new syntax introduced with PHP 5.5 without quotes and without escaping and with added ::class. This is rather confusing. ;)
And imo in the new syntax shown in the example you do not omit the leading backslash, because it uses the Fully qualified name of the namespace.

As this manual is more and more becoming a technical guide of TYPO3, I think it would be great to create a new introductory chapter "TYPO3 Architecture". This would try to focus more on the big picture and try to give an overview of the various components and how they interact with each other. It also might point out in which way TYPO3 is different as other CMS / Web frameworks.

You don't need to write the entire chapter from scratch. Some texts already exist and could be moved here, for example:

• For example, this part https://docs.typo3.org/typo3cms/CoreApiReference/ApiOverview/FormEngine/Introduction/Index.html gives an overview of FormEngine, DataHandler and Frontend rendering
• Some parts of "Inside TYPO3" could be moved to the "TYPO3 architecture" section, e.g. https://docs.typo3.org/typo3cms/InsideTypo3Reference/Introduction/Index.html

e.g. which parameters are supported.

Migrated from Forge: https://forge.typo3.org/issues/59369

Description

While implementing CSRF protection for backend modules,
it was forgotten to implement a solution for navigation components
that also could be modules.

Add this possibility now by introducing yet another
configuration option for modules.

'navigationFrameModule' name of the module that is loaded in the navigation frame
'navigationFrameModuleParameters' additional parameters (if needed and specified)

Related to https://forge.typo3.org/issues/58138

As stated in the subject, this doc

https://docs.typo3.org/typo3cms/CoreApiReference/ApiOverview/Examples/EditLinks/Index.html?highlight=alt_doc

page still references alt_doc.php as the file to use for generating links in the backend for editing and creating new records, even though editOnClick() correctly creates an url with index.php and route param

This has been transferred from TYPO3-Documentation/TYPO3CMS-Guide-Security#14 - that repository has been inlined into 'core api'

In security chapter Guidelines for Integrators, section "TypoScript" [1], we explain the risk of SQL injection via TypoScript. Nothing is wrong with that, but I wonder if we should expand the code example, so that is also covers strings in GET/POST requests and also describe to parse/inject the argument properly and securely.

I am thinking about a code fragment, Jigal van Hemert posted in the English mailing list [2] in December 2014:

lib.products = CONTENT
lib.products{
    table = TABLE
    select {
        selectFields = name
        pidInList = 26506
        orderBy = name
        where = sid like ###GPSID###
        markers {
            GPSID.data = GP:SID
        }
    }
    renderObj = COA
    renderObj {
        10  = COA
        10  {
            10 = TEXT
            10.dataWrap ={field:name}[\n]
        }
    }
}

If someone is interested and has the time to re-work the code snippet and add the "argument as string" example, knock yourself out :-)
The main point of the code above is that by using markers, values get escaped and quoted automatically if required.

[1] http://docs.typo3.org/typo3cms/SecurityGuide/GuidelinesIntegrators/Typoscript/Index.html
[2] http://lists.typo3.org/pipermail/typo3-english/2014-December/092321.html

• Add information about deprecation log
• remove wiki page: https://wiki.typo3.org/Deprecation_Log

See also #600 as general issue for Wiki migration

From @Chrissitopher on December 7, 2015 21:48

What I personally am still missing is the rules after which TSconfig overwrites other TSconfig:

• TSconfig of different groups and their order
• TSconfig of groups and of a user

The same can also be explained for TS Templates.

Copied from original issue: TYPO3-Documentation/TYPO3CMS-Reference-TyposcriptSyntax#3

A new Locking API was introduced with TYPO3 CMS 7.3 but there is no further information about it in the documentation.

Details: https://wiki.typo3.org/TYPO3.CMS/Releases/7.2/Feature#Feature:_.2347712_-_New_Locking_API

It may be helpful to describe:

• who (core developers, extension developers?) should use the Locking API
• why someone should use the Locking API
• which problems can be tackled by using the Locking API
• which problems can not be tackled by using the Locking API
• how the Locking API can/should be used
• possible problems and limitations when working with the Locking API

The TOC nesting on the "Extension Architecture" page is wrong:

Not everything should be childs of "Introduction".

https://docs.typo3.org/typo3cms/CoreApiReference/latest/ExtensionArchitecture/Index.html

Section about ajax in BE is outdated:
https://docs.typo3.org/typo3cms/CoreApiReference/JavaScript/Ajax/Backend/Index.html

In version 8, the AjaxRequestHandler and registerAjaxHandler were deprecated:
https://github.com/TYPO3/TYPO3.CMS/blob/master/typo3/sysext/core/Documentation/Changelog/8.0/Deprecation-73352-DeprecateOld-schoolAJAXRequests.rst
https://github.com/TYPO3/TYPO3.CMS/blob/master/typo3/sysext/core/Documentation/Changelog/8.1/Deprecation-75340-MethodsRelatedToGeneratingTraditionalBackendAJAXURLs.rst
https://docs.typo3.org/typo3cms/extensions/core/Changelog/7.5/Feature-65493-BackendRouting.html

The code block on following page, which shows a example of the integration has a mistake.

https://docs.typo3.org/typo3cms/CoreApiReference/8.7/ApiOverview/Examples/ContentElementWizard/Index.html

The array identifier "icon" was dropped and doesn't work anymore. You have now to use the the array identifier "iconIdentifier" and the Icon-API.

In few places in the documentation we still reference tce_db.php endpoint, which is long gone.
It was deprecated in 7.1
https://docs.typo3.org/typo3cms/extensions/core/7.6/Changelog/7.1/Deprecation-64922-DeprecatedEntryPoints.html
https://docs.typo3.org/typo3cms/extensions/core/Changelog/7.5/Breaking-68812-DeprecatedBackendEntrypointsMoved.html

for example here, there is a whole chapter about tce_db: https://docs.typo3.org/typo3cms/CoreApiReference/ApiOverview/Typo3CoreEngine/TceDb/Index.html

tce_db currently exists in the core as a route name to /record/commit path. See
typo3/sysext/backend/Configuration/Backend/Routes.php

    'tce_db' => [
        'path' => '/record/commit',
        'target' => Controller\SimpleDataHandlerController::class . '::mainAction'
    ],

We could also mention typo3/sysext/backend/Resources/Private/TypeScript/AjaxDataHandler.ts javascript class.

See also change in the core removing last mentions of tce_db.php https://review.typo3.org/#/c/57636

JavaScript in TYPO3 and Developing with Ajax in the TYPO3 Backend could use more content:

• Developing with AJAX in the TYPO3 Backend is empty: https://docs.typo3.org/typo3cms/CoreApiReference/latest/ApiOverview/JavaScript/Ajax/Backend/Index.html
• The entire section could use an example

Most of the stuff todo is probably self-explaining (inherit from AbstractUpdate, add functions checkForUpdate, performUpdate etc.

It might be useful to provide

• some general guidelines.
• Naming conventions? (some are named *Update, some *UpdateWizard ...)
• can one assume that the DB compare has already been run, why does ExtensionManagerTables do the schema migration (in getUpdateStatements).

There is a chapter about Hooks: http://docs.typo3.org/typo3cms/CoreApiReference/ApiOverview/Hooks/Index.html

There should also be a chapter about Signal/Slot.

It would be helpful to show when to use Hooks and when Signals should be used - in TYPO3 CMS extensions and TYPO3 CMS core.

Looks like this link doesn´t exist anymore
https://docs.typo3.org/typo3cms/CodingGuidelinesReference/latest/PhpArchitecture/WorkingWithExceptions/Index.html

The left navigation menu for the TCE section isn't nice.

I don't know why there is a "Files" section, or why everything is below "Introduction".

1.) Why do you call the usage of "$GLOBALS['TYPO3_CONF_VARS']['SYS']['Objects'] " still XCLASS? It should be called "using System Objects" or similar. Since TYPO3 6.2 the name XCLASS should disappear from the manuals.

2.) What must be done if the array $GLOBALS['TYPO3_CONF_VARS']['SYS']['Objects']['TYPO3\CMS\Backend\Controller\NewRecordController'] already exists? Shall it be overwritten without any notice? Or is there any recommendation for an entry into an error log file?

3.) I cannot get System Objects class extending working with an abstract class.
"abstract class AbstractConditionMatcher extends \TYPO3\CMS\Core\Configuration\TypoScript\ConditionMatching\AbstractConditionMatcher {"
Are abstract classes not supported for extending them?

Is there a reason that the chapter about FormEngine is missing in 7.6?

TYPO3CMS-Reference-CoreApi/Documentation/ApiOverview/Index.rst

There is a 404 Error: http://typo3.org/documentation/api/
It should be: http://api.typo3.org/

Please correct me if I am wrong!

Should contain:

• Information about displayCond should be added as well.

See also

• Wiki can be used? https://wiki.typo3.org/Extension_Development,_using_Flexforms
• https://docs.typo3.org/m/typo3/reference-tca/master/en-us/ColumnsConfig/Type/Flex.html

SkillsDisplay:

https://my.skilldisplay.eu/skill/279/37

The doc only give one example for rte using
'defaultExtras' => 'richtext[]'

Missing is that it's possible to add it like this to get a full options rte:
'defaultExtras' => 'richtext[*]'
some details what is possible to insert here would be useful as well.

One problem i found was about file links in rte, it only rendered "file:1234" in FE. I was able to fix it this way:
'defaultExtras' => 'richtext[]:rte_transform[mode=ts_links]'

Affected TYPO3 Version: 9.5.x since https://review.typo3.org/57600

Since the path to l10n folder is not hardcoded anymore, the documentation about this could be centralized mentioned in an upcoming Environment section of https://docs.typo3.org/typo3cms/CoreApiReference/ApiOverview/Index.html.

Then we can use http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#substitutions (http://docutils.sourceforge.net/docs/ref/rst/directives.html#replacement-text) to add abbreviations whenever typo3temp/l10n must be mentioned in an core documentation

In CoreApiReference is written:

This is the second step of the processing chain: The rendering part gets the data array prepared by FormDataCompiler and creates a result array containing HTML, CSS and JavaScript. This is then post-processed by a controller to feed it to the PageRenderer or to create an ajax response.

Passing Resources like CSS and JavaScript to form-elements is not clear and I get the impression I've to pass them by myself to pageRenderer.
Actually I'm creating a UserElement (userdefined, not related to users) and I don't see any option to pass there anything but HTML to the upper node.

Migrated issue https://forge.typo3.org/issues/47965 from Forge

It has been discussed in Core List when and how the Core should use the "use" 
statement for PHP namespaces.

The correct place for "use" statements inside a file is directly below the "namespace" line 
itself and in front of the copyright notice. That is already documented.

What is still missing are guidelines, when to use "use" statements and how/in which way.

Here is the [discussion](http://lists.typo3.org/pipermail/typo3-team-core/2013-March/053732.html),
 however, I did not find a clear result yet._


**Note**: 
* There is a section on 
  [Namespaces](https://docs.typo3.org/typo3cms/CoreApiReference/CodingGuidelines/PhpFileFormatting/FileStructure.html#namespace) 
  in the Coding Guidelines but how to use use is a litte fuzzy
* PSR-2 is pretty explicit about it : "There MUST be one blank line after the namespace 
  declaration, and there MUST be one blank line after the block of use declarations."

This could be added to the docs. 

Documentation/ApiOverview/FormProtection/Index.rst should talk about frontend CSRF.

It should also tell that you need a logged in user for it - see https://forge.typo3.org/issues/77403

The documentation clearly discourages using TYPO3_MODE check in ext_tables.phpandext_localconf.php files.
quote from documentation:

It is heavily recommended to AVOID any checks on TYPO3_MODE or TYPO3_REQUESTTYPE
constants (e.g. if(TYPO3_MODE === 'BE')) within these files as it limits the functionality to cache the
whole systems' configuration.

but every system extension contains the following check

<?php
defined('TYPO3_MODE') or die();

and the statement is also present in documentation in the same page, where its usage is discouraged.
is this an error in documentation or what ?

As TYPO3 CMS 9 LTS will be released this year, we should update the attention box at the bottom of
https://docs.typo3.org/typo3cms/CoreApiReference/ApiOverview/Database/Configuration/Index.html where we wrote:

The core team hopes this situation settles until the final release of TYPO3 v8 LTS.

The information provided by core team is:

postgres, maria, mysql works, mssql mostly works. however, mssql is currently not actively tested since the container does not work well in testing environment and it always costs a day or so to fiddle with that, last time i tried (3 month ago or so) i failed.

So we can update this box with the given information.

Migrated from Forge: https://forge.typo3.org/issues/57253

4 years ago: (The information is outdated!)

"The section about Extension Architecture should now include a mention of the composer manifest. 
How should this file look like and what is it good for?

...
Tom Maroschik says:

Currently it is not necessary [to use a composer manifest]. The composer workflow is currently
beeing established and researched by the composer team. After we figured out how all those 
gears work together we will publish guidelines for the community and the core. So currently it is 
not advised to include a composer.json in your own extension. If you do so unexpected behavior 
can occur.

The schema of this manifest is described here: https://getcomposer.org/doc/04-schema.md

The only thing required for a TYPO3 CMS extension is the type attribute with the value 
"typo3-cms-extension". The rest should be according to the default composer scheme. 
The naming convention usually is {vendor}/{product}

If a composer.json is not found but a ext_emconf.php is present the Package Management 
considers the package to be a typo3 extension with all implications. So in package management 
the composer.json takes precedence when it's available. Currently the extensionmanager does 
not consider the composer.json yet. The plan was to rebuild the EM upon composer and ship it 
via the TER once the CMS release is out.

In an attempt to converge further with Flow the ext_emconf.php will phase out once we established 
the full composer workflow which includes a composer based variant of the TER on our 
own infrastructure.

Migrated already existing old issue from Forge https://forge.typo3.org/issues/9712, added some info:

• Find way to generate list of hooks / Signals
• Figure out what is a good way to format the information (e.g. https://wiki.typo3.org/User:Layne.obserdia/Hook_List)
• Create stub page

Resources:

• First Draft: https://wiki.typo3.org/User:Layne.obserdia/Hook_List
• A list of signals already exists for FAL: https://docs.typo3.org/typo3cms/CoreApiReference/ApiOverview/Fal/Architecture/Signals.html?highlight=hook

The minimal information necessary IMO would be:

• name of the hook
• purprose
• parameters received
• expected return value
• Having code examples is of course a great idea, but would require a lot of work. Better to have the list first and enhance it later.

There is a chapter "Creating a new extension" in Core API: https://docs.typo3.org/typo3cms/CoreApiReference/ExtensionArchitecture/CreateNewExtension/Index.html#

There is a chapter with identical name in Extbase / Fluid Book: https://docs.typo3.org/typo3cms/ExtbaseFluidBook/latest/4-FirstExtension/

In one, the extension builder is used, in the other a sample extension. While the scope of the Extbase / Fluid Book is a little different it might be good to have one landing page for starting an extension and then link to all relevant information from there.

Used without additional resources the chapter in Core API is a little thin and not very helpful. At least a few links could be added. Also, using the Extension builder is not the best choice for all use cases.

So, if possible, merge the information and / or cross-link to information which is missing.

Specifcally:

• "This chapter is not a tutorial about how to create an Extension. It only aims to be a list of steps to perform and key information to remember." Ok, if it's not, then link somehwere else where the reader gets this information.
• "Although it is possible to write every single line of an extension from scratch, there is a tool which makes it easier to start. It is called "Extension builder" (key: "extension_builder") and can be installed from TER." Actually not: Last time I checked, current version for TYPO3 8 can only be installed via Github or composer

• "Please refer to the Extension Builder's manual for more information." - A link would be cool right here.

This has been transferred from TYPO3-Documentation/TYPO3CMS-Guide-Security#11 - that repository has been inlined into 'core api'

Several attempts have been made in the past to extend the TYPO3 Security Guide by a chapter for developers (Guidelines for Extension Developers). Some suggestions were for example:

• Information on SQL injections and Cross Site Scripting
• Explain process how to report a security issue in own extension to the Security Team
• Highlight that a fix for a security issue should be the only change in a release
• Explain the policy of "least disclosure" (used by the Security Team)
• List/summarize typical security vulnerabilities in PHP code (see CWE/SANS Most Dangerous Software Errors)
• Describe how to prevent these errors (maybe show code examples?)
• Explain which typical TYPO3 API functions should be used (?)
• Explain different HTML contexts and which API methods we have to sanitize values.
• Do not use second argument of getLL()
• Explain how FE session handling should be done by developers

The chapter should also include how to avoid SQLi properly, how to avoid XSS and a general recommendation to always use the TYPO3 API for validation, escaping and encoding.

It is best practice to make sure you always know which values are safe for output to the browser (htmlspecialchars, quoteJS) and which are not. A general rule we follow is to prepare variables in a raw form (putting together a title, a link or similar) and doing the actual encoding/safety later when outputting it. Another thing would be to make sure to typecast an integer-variable to (int) when you add it to HTML-output and not rely on that "some earlier part" would have made sure it's only a number.

https://forge.typo3.org/issues/50165
https://forge.typo3.org/issues/31672
https://forge.typo3.org/issues/71699
https://forge.typo3.org/issues/71701
https://forge.typo3.org/issues/79575
https://forge.typo3.org/issues/68167

In https://docs.typo3.org/typo3cms/CoreApiReference/ApiOverview/Database/QueryBuilder/Index.html#execute is a reference to https://docs.typo3.org/typo3cms/CodingGuidelinesReference/latest/PhpArchitecture/WorkingWithExceptions/Index.html which delivers a 404.
We should update the reference or remove it.

Documentation of icon API looks up to date:
https://docs.typo3.org/typo3cms/CoreApiReference/ApiOverview/Icon/Index.html

I was missing the following information:

• where do I find a list of icons provided by the core
• are the icons supported as public API (e.g. actions-open).

Here is a very useful and extensive Resource.

https://usetypo3.com/icon-api.html