File Abstraction Layer

h1. Migration

(needs to be updated.)

* Migration wizard for integrating contents of an uploads/.../ folder to the asset database

** This has to be done on a per table/field base. Successful migration should be saved in some config var so the system will know where to use old or new relation handling

** Copy files to a defined/selectable location, create asset records, merge duplicates, change relations from file names to a relation 

** Remove the uploads folder completely? Thus _all_ files are in fileadmin and not spread around and uploaded maybe multiple times. An option would be to move files into fileadmin/migrated_files/ - that's most likely all we can do.

* soft migration path: Only migrate extensions that are ready, administrators have full control. No automatic migration (except core tables maybe)

** offer an easy API for accessing media data that can also handle the old way of relations. This will leave the decision to the admin, not the developer -> easier adoption

* Handling of _group_ fields in TCEforms/TCEmain has to be adjusted: for internal_type = _file_ or _file_reference_, there has to be additional code for handling new relations (this will only come into action for migrated fields, where the old code will not work anymore)

* Ingo: I'd go for a completely new system where we do not have to care about BC, will make a lot of things a lot easier. After all it's a new feature. The migration wizard needs to take care of the transition though.

h1. Upgrading Prodedure for FAL

Upgrading from a pre-FAL to a FAL version of TYPO3 involves certain steps and depending on which steps have been done, the system is in a different state.

h2. Step 1: Upgrade the source (normal TYPO3 update)

* Updating the TYPO3 Source (i.e. by pointing your typo3_src symlink from the pre-FAL to the FAL version of TYPO3 or by executing a git pull on your typo3_src directory if you got it straight from the git repositories)

* Updating the database structure (using the COMPARE and IMPORT steps of the Instal Tool->Database Analyser)

Your installation is now in the  "after source upgrade" state.

Warning: 

    This is a dangerous state to be in, because when editors in your TYPO3 backend now edit tt_content records and click save, data could be lost (more precisely: image or media fields might get emptied, because the path/filename string that was saved in the group/internal_type=file fields would then be overridden with a 0 for the new IRRE file fields).

h2. Step 2: FAL Upgrade Wizards

Use the the Install Tool -> Upgrade Wizards to executed the following two upgrade wizards:

    create symlinks from fileadmin/pics pointing to uploads/pics/ and from fileadmin/media/ pointing to uploads/media/. 

    ttContentUpgradeWizard (which actually upgrades fields in both tt_content and the pages table, even though the name only suggests that tt_content would be updated)

    ttContentUploadsUpgradeWizard (which updates fields related to the "File Links" aka uploads content element).

Your installation is now in the "content migrated" state. At this point, not all content table (pages, tt_content)  file fields are completely migrated to FAL. File fields of extensions and some file fields of the core (e.g. resources attached to sys_template records) are still missing, but everything is consistent again (that means the settings in the TCA now correspond to your data in the database tables again).

Note that it is no problem if some fields are still of the "old style" file fields with type=group/internal_type=file, as that type is handled exactly like before. The field type still stores files in a folder underneath uploads/ as configured for the specific field and leaves a comma separated list of filenames as value of the field in the database. The only difference is that after installation of FAL the user can select files from any (remote or local) storage as configured in FAL. But once the user clicks "save" in the TCEForm, the file is copied to the local uploads/ folder as before.

h2. Changes in the output of content elements:

The uploads/ content element has gotten a change

TODO:

    Rename ttContentUpgradeWizard to something more meaningful as it actually updates both the pages (with media field) and the tt_content table (with image field)

    make the ttContentUpgradeWizard actually copy files instead of only correcting the references.

    Possibly provide a workaround for the dangerous