Friday, December 21, 2012

TYPO3 Extbase - mapping existing fields from fe_users

Extbase comes with an own domain model and repository to access the frontend users (fe_users) and frontend groups (fe_groups) tables. If you install sr_feuser_register, several extra fields are added to the fe_users table. Those extra fields are not included in extbase default domain model for fe_users, so you have to extend the domain model with the fields you want to access. This article show howto extend the existing domain model and some things to keep in mind.

Preperation

The first thing to do is to create a new domain model, which extends the existing one. Create a new class for this in your extensions Domain\Model folder.

class Tx_Testext1_Domain_Model_FrontendUser extends Tx_Extbase_Domain_Model_FrontendUser {

}

Next you need to create a repository for the new domain model. Create this in the Domain\Repository folder of your extension.

class Tx_Testext1_Domain_Repository_FrontendUserRepository extends Tx_Extbase_Domain_Repository_FrontendUserRepository {

}

The next thing to do is to setup the mapping for the new table, so Extbase knows from which table it has to get the fields. Add the following to your sites typoscript setup.

config.tx_extbase.persistence.classes {
    Tx_Testext1_Domain_Model_FrontendUser {
        mapping {
            tableName = fe_users
        }
    }
}

You also need to configure, in which storage pid the frontend users are stored. You can set this in the typoscript constants of your extension.

plugin.tx_testext1 { 
  persistence.storagePid = 100
}

Extending the existing domain model
Now you're ready to extend the domain model Tx_Extbase_Domain_Model_FrontendUser to access the fields, which are not included in the default domain model. Actually you can also extend the domain model with new fields, but this is not part of this article.

Lets assume, you want to access the field "comments", which was created by sr_feuser_register. The only thing to do is to add a getter and a setter for this field in the newly created domain model.

class Tx_Testext1_Domain_Model_FrontendUser extends Tx_Extbase_Domain_Model_FrontendUser {

 /**
  * Comment
  *
  * @var string
  */
 protected $comment;

 /**
  * Setter for comment
  *
  * @param string $comment
  * @return void
  */
 public function setComment ($comment) {
  $this->comment = $comment;
 }

 /**
  * Getter for comment
  *
  * @return string
  */
 public function getComment () {
  return $this->comment;
 }
}

Now you can inject the newly created repository to get a record from the database.

/**
 * @var Tx_Testext1_Domain_Repository_FrontendUserRepository
 */
protected $userRepository;

/**
 * Inject the user repository
 *
 * @param Tx_Testext1_Domain_Repository_FrontendUserRepository $userRepository
 * @return void
 */
public function injectFrontendUserRepository (Tx_Testext1_Domain_Repository_FrontendUserRepository $userRepository) {
 $this->userRepository = $userRepository;
}

/**
 * Test action
 *
 * @return void
 */
public function testAction () {
 $user = $this->userRepository->findByUid(1);
 t3lib_utility_Debug::debug($user);
}

When you call the action showed above, you should see the debug output of the user object from the user with the uid 1. In the debug output, you should see the additional field "comment", which is included in the newly created domain model.

Fields with underscore and mixed case
The extension sr_feuser_register adds some additional field to fe_users, which include underscores. The same does "felogin", which actually adds fields with underscores and mixed case (e.g. "felogin_forgotHash").

If you want to include fields with underscore in your domain model (e.g. "date_of_birth"), make sure to remove the underscore and to set a Uppercase of the next letter instead.

/**
 * Date of birth
 *
 * @var int
 */
protected $dateOfBirth;

/**
 * Setter for date_of_birth
 *
 * @param int $dateOfBirth
 * @return void
 */
public function setDateOfBirth ($dateOfBirth) {
 $this->dateOfBirth = $dateOfBirth;
}

/**
 * Getter for date_of_birth
 *
 * @return int
 */
public function getDateOfBirth () {
 return $this->dateOfBirth;
}

If you have fields with underscore and mixed case, just remove the underscore. Extbase seems to ignore the case.

Here is an example of the field "felogin_forgotHash"

/**
 * Password forgot hash
 *
 * @var string
 */
protected $feloginForgothash;



Saturday, December 15, 2012

TYPO3 Flow / Fluid - translating select fields

In a TYPO3 Flow project, I had to create a select box with countries, from which the user could select one. This task is really easy with TYPO3 Flow. Just create a domain and repository for the countries, add the necessary templates and create the country-records. Now you are ready to create a relation from a existing domain (e.g. a domain with some address-fields) to the country domain. No problems here. But what, if you want to translate the country-names in different languages?

The Fluid viewhelper "f:form.select" seems to have an argument called "translate" which can handle translation of select fields labels. I could'nt find a tutorial how to use this argument and finally found out, that everything was described directly in the viewhelpers class.

Here is a short summary on how to use the f:form.select viewhelper together with the "translate" argument.

Assume you have an domain called "country". It only has one property called "alpha2", which is a string representing the country's ISO-3166 alpha2-code. You create some records in the new domain like "DE" for Germany, "DK" for Denmark and so on. You also have an domain called "address", where you have a relation to the country domain.

The first thing to do is to create the translation files. In this example I create one for english and one for german.

<?xml version="1.0" encoding="UTF-8"?>
<xliff version="1.2" xmlns="urn:oasis:names:tc:xliff:document:1.2">
    <file original="" source-language="en"  datatype="plaintext">
        <body>
            <trans-unit id="DE">
                <source>Germany</source>
            </trans-unit>
            <trans-unit id="DK">
                <source>Denmark</source>
            </trans-unit>
        </body>
    </file>
</xliff>


<?xml version="1.0" encoding="UTF-8"?>
<xliff version="1.2" xmlns="urn:oasis:names:tc:xliff:document:1.2">
    <file original="" source-language="en" target-language="de"  datatype="plaintext">
        <body>
            <trans-unit id="DE">
                <source>Germany</source>
                <target>Deutschland</target>
            </trans-unit>
            <trans-unit id="DK">
                <source>Denmark</source>
                <target>Dänemark</target>
            </trans-unit>
        </body>
    </file>
</xliff>

Next you should configure your f:form.select viewhelper, so it uses the translations.

<f:form.select property="country" id="country" options="{countries}" optionLabelField="alpha2" translate="{using: 'label'}"/>

The viewhelper is configured to use "alpha2" as a label field and to use the label field for translation. There are several other options for the translate argument (e.g. the "source" attribute which enables you to select a different localization file), which are described directly in the class.

Now you just have to assign the object "countries" (containing all countries from the country-repository) through the controller to the corresponding view and you're done.

Thursday, December 6, 2012

TYPO3 CMS - Run Extbase unit tests in PHPStorm

Update 27.06.2014

With TYPO3 6.2 unit- and functional test execution is possible directly through phpunit on command line. So keep in mind, that the steps described below are obsolete, if you use TYPO3 6.2.

Original Article

TYPO3 CMS is great and since Extbase it is easy to create unit tests for your code. Just create your extension with the extension_builder (or manually), install the extension phpunit from TER, add some tests to your extension and now you´re fine to run your unit tests in the phpunit TYPO3 backend module.

If you want to run your tests directly in an IDE (in this article it´s PhpStorm), there are some things to keep care of, before the IDE is ready to run the tests. This article describes how to configure PhpStorm to run Extbase unit tests directly in the IDE and also shows some common error messages including a possible solution.

Prerequisites:
  • A working TYPO3 installation with at least one page and a TS template
  • An Extbase extension with at least one test
  • TYPO3 extension "phpunit" installed 
  • The Extbase unit tests must run in TYPO3´s backend module "phpunit"
Setup:

  1. Configure the PHP interpreter and set the PHP home path to:

    /path-to-typo3-site/typo3conf/ext/phpunit/Ressources/Private/Scripts


  2. Edit your PhpStorm project to use the new PHP interpreter

  3. Adjust the PHP interpreter script.

    The script which comes with the TYPO3 extension "phpunit" seems to contain an error in the CLI path. Adjust this path, so it uses php_ide_testrunner instead of php_ide as the cliKey

    CLI_PATH="${TYPO3_SITE_PATH}/typo3/cli_dispatch.phpsh phpunit_ide_testrunner"
    
  4. Configure an environment variable in your PhpStorm project

    Edit the test configuration for the folder "Tests" of your Extbase extension and set the environment variable ENV_TYPO3_SITE_PATH to the path of your website root

  5. Create a new TYPO3 Backend user named _cli_phpunit
  6. Configure include paths

    Add the TYPO3 source and the TYPO3 extension phpunit to your PhpStorm projects include paths



    This step is optional, but I think it is always nice to have code completion working when coding TYPO3 extensions.
  7. Now you should be ready to run your Extbase unit tests directly in PhpStorm




TYPO3 6.0 issues

TYPO3 6.0 comes with a new base test class, which actually is´nt recognised by the TYPO3 Extension "phpunit" in TER (version 3.6.11). The problem has already been fixed, but it is not published yet, so you have to get the changes manually and pull a new version of the extension from the GIT repository at git://git.typo3.org/TYPO3v4/Extensions/phpunit.git


Error messages and possible solutions

While working with TYPO3, Extbase, phpunit and PhpStorm, I stumbled across some situations, where the tests were not running because of some misconfigured settings. Below are 2 possible situations with an error message an a description how I fixed them.

Situation 1

If you face the error message "Unable to attach test reporter to test framework or test framework quit unexpectedly", this may indicate, that something is wrong with your local permissions.

Solution 1 - Wrong permissions

I am developing on an Ubuntu 12.04 desktop and apache2 and TYPO3 is installed locally. I have my own user to start the desktop, so my user does not have necessary permissions to access the files owned by the webserver.

First, you should add your local user to the group "www-data" (or the group running your local webserver). Next, you should check the TYPO3 install tool for the following:

[fileCreateMask] = 664
[FolderCreateMask] = 775

This is needed, so you local user can read/write to typo3temp. Finally delete the typo3temp/ folder, so the folder is recreated with the new file- and folder permissions.

Solution 2 - Trailing slash in ENV_TYPO3_SITE_PATH

This error message can also orrur, if the ENV_TYPO3_SITE_PATH contains a trailing slash. So check if the path is correct.

Situation 2

Once I also came across this error message "PHP Fatal error:  Cannot redeclare phpunit_autoload() (previously declared in /some/path/script.php)".

The solution for this problem was, that the cliKey in the php interpreter script was set to "phpunit" instead of "phpunit_ide_testrunner"


Monday, October 29, 2012

Integrating TYPO3 Flow commands to the PhpStorm command line tool

Last week I read about the possibility to integrate composer to the PhpStorm command line tool. Inspired by this article, I created a configuration file for TYPO3 Flow commands.

TYPO3 Flow command line integration in PhpStorm
I published the configuration file on github, so it can easily be shared, extended, forked or whatever.

Sadly I did'nt get the Quick Definition View to work as it was described in the original article from Jetbrains.

Configuration:
  1. Navigate to Settings | Command Line Tool Support and add custom configuration
  2. Add the Framework Name (e.g. "TYPO3 Flow"), the Tool path (e.g. "./flow") and the Alias (e.g. "flow")
  3. Import the XML configuration file available here: https://github.com/derhansen/typo3-flow-phpstorm-cl-xml
Be sure to check, that the Tool path doesn't contain an absolute path to the flow executable.

How to use it?
  1. Open a TYPO3 Flow project in PhpStorm and press CTRL + SHIFT + X
  2. Check, that the current directory contains the TYPO3 Flow executable (in Linux systems you can use pwd to check the current directory). If not, navigate to that directory.
  3. Enter a TYPO3 Flow command by using the alias defined in the configuration (in this example "flow")

FlashMessages in TYPO3 Flow überschreiben

In TYPO3 Flow kann man Domain-Models sehr einfach per Annotations validieren. So definiert man in seinem Domain Model lediglich die Eigenschaften und die dazugehörigen Validierungsregeln. Will man nun über ein Formular Daten speichern, gibt TYPO3 Flow wie erwartet Fehlermeldungen passend zu den definierten Validierungsregeln aus.

Beispiel:

/**
 * The firstname
 *
 * @var string
 * @Flow\Validate(type="String")
 * @Flow\Validate(type="NotEmpty")
 */
 protected $firstname;

Die Eigenschaft "firstname" muss ein String und darf nicht leer sein. Erstellt man dafür nun ein Formular, würde das so aussehen.

<f:form action="create" controller="Register">
  <label for="firstname">Firstname:</label>
  <f:form.textfield=" id="firstname" name="data[firstname]" property="firstname" />
  <f:form.submit value="Submit" />
</f:form>

Um die Validierungsergebnisse auszugeben, muss das Formular wie folgt ergänzt werden.

<f:flashMessages />
<f:form.validationResults for="data">
    <f:if condition="{validationResults.flattenedErrors}">
        <div class="error">
            <f:for each="{validationResults.flattenedErrors}" key="propertyPath" as="errors">{propertyPath}: <f:for each="{errors}" as="error">{error}</f:for></f:for>
        </div>
    </f:if>
</f:form.validationResults>

Wenn man die das Formular nun absendet, erhält man in den validationResults die Meldungen bzgl. des Domain-Models. Aber im flashMessage Container erscheint noch eine nicht sehr schöne Fehlermeldung von TYPO3 Flow.
An error occurred while trying to call Your\Package\Controller\RegisterController->createAction()

Diese Meldung kann man überschreiben, indem man im Controller die Methode getErrorFlashMessage() überschreibt.

/**
 * @return \TYPO3\Flow\Error\Message
 */
protected function getErrorFlashMessage() {
 switch ($this->actionMethodName) {
  case 'createAction' :
   return new \TYPO3\Flow\Error\Message('Could not save form, because some fields are not filled out correctly');
  default:
   return parent::getErrorFlashMessage();
 }
}

Abhängig von der aufgerufenen Action, kann man die ausgegebene Fehlermeldung überschreiben.

Thursday, October 18, 2012

TYPO3 Flow 1.2 - Kickstarter Package über Composer installieren

Heute wollte ich mal die aktuelle Developer Version von TYPO3 Flow 1.2 installieren nachdem ich ein Tweet von Robert Lemke über TYPO3 flow und Composer gelesen hatte. Da mir Composer nicht nicht sehr geläufig ist, habe ich etwas länger gebraucht um das alles zum laufen zu bekommen.

Die Installation von TYPO3 Flow über Composer ist wirklich sehr einfach und mit einem simplen Befehl erhält man (fast) alle benötigten Dateien und Abhängigkeiten

composer create-project typo3/flow-base-distribution

Wer nun erwartet, dass man wie in Flow 1.1 einfach mit dem Kickstarter loslegen und Packages erstellen kann, der wird  feststellen, dass der TYPO3 Kickstarter gar nicht in der flow-base-distribution enthalten ist.

Nachdem ich dann etwas in der composer.json Datei reingeschaut hatte, fiel mir die Zeile "require-dev" auf. Dort stand unter anderem etwas vom TYPO3 Kickstarter. Die dort erwähnten Pakete installiert man mit folgendem Befehl:

composer install --dev

Nun kann man mit dem TYPO3 Kickstarter neue Packages erstellen.

Wednesday, October 3, 2012

Mapping anderer Tabellen in Extbase

Neulich stand ich vor der eigentlich recht simplen Aufgabe aus einer Extbase Extension heraus auf die erzeugten Daten einer anderen Extbase Extension zuzugreifen. Im Web gibt es auch einige Tutorials, welche beschreiben wie man dieses macht, aber fast alle zeigen, wie man auf die Tabellen fe_users und fe_groups zugreift, welche beide schon als Domain-Model bei Extbase mitgeliefert werden. Ein funktionierendes Praxisbeispiel für den Zugriff auf eigene Datenstrukturen konnte ich leider nicht finden.

In diesem Beitrag zeige ich deshalb, wie man aus einer Extbase Extension heraus auf die Daten einer anderen Extbase Extensions zugreifen kann.

Ausgangssituation:

In einer TYPO3 Installation wurden 2 Extbase Extensions (testext1 und testext2) eingerichtet, welche jeweils eigene Repositories und Storagefolder haben. Die Typoscript Constants der Extensions sind wie folgt eingerichtet:

plugin.tx_testext1 {
  persistence {
    storagePid = 5
  }
}

plugin.tx_testext2 {
  persistence {
    storagePid = 6
  }
}

Die Datensätze von testext1 werden also im Sysordner mit der Pid 5 abgelegt und die Datensätze von testext2 im Sysordner mit der Pid 6. In testext1 gibt es ein Domainmodel mit dem Namen Testext1Table und in testext2 gibt es ein Domainmodel mit dem Namen Testext2Table.

Ziel ist es nun, aus einem Controller in testext2 auf die angelegten Daten von testext1 zuzugreifen.

Vorgehensweise:

Als erstes muss in testext2 ein Domainmodel angelegt werden, welches das Domainmodel von textext1 extended. Also wird in textext2\Classes\Domain\Model\ die Datei Testext1Table.php angelegt.

class Tx_Testext2_Domain_Model_Testext1Table extends Tx_Testext1_Domain_Model_Testext1Table {

}

Somit wurde der testext2 schon mal das Domainmodel aus testext1 bekannt gemacht. Damit wir auf die Daten aus testext1 zugreifen können, wird noch ein entsprechendes Repository benötigt. Dieses wird in  textext2\Classes\Domain\Repository\Testext1TableRepository.php definiert.

class Tx_Testext2_Domain_Repository_Testext1TableRepository extends Tx_Extbase_Persistence_Repository {

}

Nun kennt die Extension testext2 das Domainmodel und hat auch ein entsprechendes Repository. Das neue Repository wird in einem Controller von testext2 per Dependency Injection implementiert.

/**
 * testext1TableRepository
 *
 * @var Tx_Testext2_Domain_Repository_Testext1TableRepository
 */
protected $testext1TableRepository;

/**
 * injectTestext1TableRepository
 *
 * @param Tx_Testext2_Domain_Repository_Testext1TableRepository $testext1TableRepository
 * @return void
 */
public function injectTestext1TableRepositoryRepository(Tx_Testext2_Domain_Repository_Testext1TableRepository $testext1TableRepository) {
 $this->testext1TableRepository = $testext1TableRepository;
}

Wer an dieser Stelle jetzt schon erste Ergebnisse aus dem implementierten Repository erwartet, wird enttäuscht und bekommt beim Versuch Daten aus dem Repository abzufragen/anzuzeigen eine Exception vom Typ Tx_Extbase_Persistence_Storage_Exception_SqlError, welche besagt, dass eine Tabelle nicht existiert.

Die Extension testext2 weiß also anscheinend noch gar nicht, aus welcher Tabelle die Daten des neuen Repositories abgefragt werden sollen. Um dieses einzurichten, muss man im Typoscript Setup von testext2 ein Mapping einrichten.

config.tx_extbase {
 persistence {
    classes { 
        Tx_Testext2_Domain_Model_Testext1Table {
            mapping.tableName = tx_testext1_domain_model_testext1table
        }
    }
 }
}

An dieser Stelle ist es wichtig, dass das Mapping direkt auf den Tabellennamen in der Datenbank stattfindet.

Auch jetzt erhalten wir über das neue Repository in testext2 noch keine Daten, da die testext2 noch nicht weiß, in welcher StoragePid die Datensätze von testext1 liegen. Hierzu ergänzt man lediglich die Typoscript Constants von testext2 wie folgt.

plugin.tx_testext2 {
  persistence {
    storagePid = 6,5
  }
}

Die StoragePid von testext1 wurde hinter der StoragePid von testext2 angehängt. Nun kann das neue Repository in testext2 angesprochen und die erwarteten Daten erfolgreich zurückgeliefert werden.