ExtExtractPhp

Introduction

Note: extExtract.php is a PHP script (in contrast to the rest of the suite). While special care has been taken to make the integration of extExtract.php as smooth as possible, the use of PHP has a few usability implications. Please see the Known Problems section at the end of this article for further details.

The general-purpose functions (like --extract-config) are only implemented for compatibility reasons and should be considered second-class citizens in the PHP implementation. The other scripts should generally be preferred for tasks that are not specific to extExtract.php

While extExtract.php is primarily designed to extract TYPO3 extension files (.t3x), it can also retrieve specific versions of an extension file from the TYPO3 extension repository.
This makes it especially helpful when trying to compare released TYPO3 extension file versions.

Arguments

$ ./extExtract.php --help
  Usage: ./extExtract.php [OPTIONS] [--extension=]EXTKEY

  Core:
  --help              Display this help and exit.
  --verbose           Display more detailed messages.
  --quiet             Do not display anything.
  --force             Perform actions that would otherwise abort the script.
  --update            Tries to update the script to the latest version.
  --update-check      Checks if a newer version of the script is available.
  --export-config     Prints the default configuration of this script.
  --extract-config    Extracts configuration parameters from TYPO3.
  --base=PATH         The name of the base path where TYPO3 is
                      installed. If no base is supplied, "typo3" is used.

  Options:
  --extension=EXTKEY      The extension key of the extension that should be
                          operated on.
  --force-version=VERSION Forces download of specific extension version.
  --dump                  Prints out a dump of the data structure of the
                          extension file.
  --string-limit=LENGTH   The LENGTH at which string data should be summarized
                          as String[N]. Default: 60 No Limit: 0
  --extract               Forces the extraction process even if other commands
                          were invoked.
  --output-dir=DIRECTORY  The DIRECTORY to where the extension should be
                          extracted.
  --output-file[=NAME]    Write the downloaded extension file to disk with and
                          optional NAME.

Overview

For general information regarding the configuration of scripts in the typo3scripts suite, please see the article about Configuration.

Command Line Parameters

• --help

  Prints the output seen above, giving an overview of available command line parameters.

• --verbose

  Enable verbose (more detailed) output.

• --quiet

  Reduced verbosity (less detailed) output.

• --force

  Perform actions that would otherwise stop execution.

• --update

  Invokes the self-updating mechanism in this script. This will download the latest release version from the official source code repository and replace your current script.

  Note: To perform a quick check if a new version is available, run extExtract.php with the --update-check parameter. If a new version is found online, the following message will be printed to the standard output:

  NOTE: New version available!
  

  In previous versions, this check would be performed every time you run the script.

• --export-config

  Print the default configuration of the script to the standard output.

  This allows for easy generation of a default config file, like so:

    $ ./extExtract.php --export-config > typo3scripts.conf
  

• --extract-config

  Tries to read the database-related parameters out of the TYPO3 configuration file.

  This allows for easy generation of a base config file for other typo3scripts after you have completed your TYPO3 installation.

    $ ./extExtract.php --extract-config > typo3scripts.conf
  

  In case you're using a non-default TYPO3 installation directory, make sure to supply the --base parameter before the --extract-config parameter.

    $ ./extExtract.php --base=myt3site --extract-config > typo3scripts.conf
  

  Note: This functionality is currently not compatible with TYPO3 6.0 configuration file format.

• --base / BASE

  By default, it is assumed that the TYPO3 installation is located in a sub-folder relative to the current working directory, named typo3. Use --base if the installation is placed in a differently named sub-folder.

    $ ./extExtract.php --version=4.6.0 --base=myt3site
  

• --extension / EXTENSION

  Tells extExtract.php what TYPO3 extension should be extracted.
  If the given string is a filename, the file will be extracted.
  If the given string is an extension key, the given extension will be downloaded from the TYPO3 extension repository. See --force-version regarding what version will be downloaded.

    $ ./extExtract.php --extension=news
  

• --force-version / FORCE_VERSION

  Tells extExtract.php that the extension that should be retrieved, should be retrieved in a specific version. This obviously only makes sense when you're not trying to extract a local .t3x file. If no version is given with --force-version, the version of the installed extension is used. If the extension is not installed, extExtract.php will fail.

    $ ./extExtract.php --extension=news --force-version=1.2.3
  

• --dump / DUMP

  Renders the data structure contained in the extension file. When using --dump, the extension is not extracted to the disk unless --extract is also specified.

    $ ./extExtract.php --extension=news --dump
  

• --string-limit / STRING_LIMIT

  String values in the extensions data structure will be summarized as String[length] if they are longer than this limit. The default is 60 characters. A limit of 0 means, no limit will be applied.
  A string value will always be summarized if it contains non-printable characters.

    $ ./extExtract.php --extension=news --dump --string-limit=100
  

• --extract / EXTRACT

  When using --dump to print the data structure of an extension, --extract will ensure that the file contents are also extracted to disk.

    $ ./extExtract.php --extension=news --dump --extract
  

• --output-dir / OUTPUT_DIR

  The location where the extension should be extracted to. By default the extension file name with -extracted added at the end is used as the name for the folder where the extension is extracted to.

    $ ./extExtract.php --extension=news --output-dir=/tmp
  

Examples

Installation

/var/www$ cd t3site/
/var/www/t3site$ wget https://raw.github.com/oliversalzburg/typo3scripts/master/extExtract.php
/var/www/t3site$ chmod 700 extExtract.php

Determine local changes in extension

Sometime it is desirable to compare the local version of an extension against the one that is publicly available in the TYPO3 extension repository.
This can easily be achieved with extExtract.php:

/var/www/t3site$ ./extExtract.php --extension=news
Sourcing script configuration from typo3scripts.conf...Done.
Update checking isn't yet implemented for 'extExtract.php'.
Retrieving original extension file for 'news' 1.3.1...Done.
Extracting file 'news_1.3.1.t3x.temp'...Done.
/var/www/t3site$ diff --recursive news_1.3.1.t3x.temp-extracted typo3/typo3conf/ext/news/
Only in typo3/typo3conf/ext/news: ext_emconf.php

In this case, the file ext_emconf.php was manipulated. Further use of diff could identify the changes on a file level.

Retrieve specific version of extension

If you need the .t3x file for a given extension of a given version, you can easily do that with extExtract.php like so:

/var/www/t3site$ ./extExtract.php --extension=yag --force-version=1.0.0
Sourcing script configuration from typo3scripts.conf...Done.
Update checking isn't yet implemented for 'extExtract.php'.
Retrieving original extension file for 'yag' 1.0.0...Done.
Extracting file 'yag_1.0.0.t3x.temp'...Done.

Known Issues

Bad interpreter

By default, extExtract.php will assume that the PHP command line interpreter (version 5.0+) is located at /usr/bin/php. If it is located somewhere else, you might get the following error message:

-bash: ./extExtract.php: /usr/bin/php: bad interpreter: No such file or directory

In this case, find php like this:

$ which php
/usr/local/bin/php

Now replace the interpreter on line 1 of extExtract.php with the value that which printed.

Call to undefined function

By default, extExtract.php will assume that the PHP command line interpreter (version 5.0+) is located at /usr/bin/php. If the version located there is too low, some methods won't be available for use. This will result in error like:

<br />
<b>Fatal error</b>:  Call to undefined function:  file_put_contents() in <b>/users/hamburgler/websites/extExtract.php</b> on line <b>149</b><br />

If multiple versions of PHP are installed on your host, change the interpreter to match the location of your latest (5.0+) PHP installation.

X-Powered-By headers in the shell

If you local PHP installation is running in CGI mode, you will see output like:

X-Powered-By: PHP/5.2.13
Content-type: text/html

To avoid this, adjust the interpreter to include the -q parameter, like so:

#!/usr/local/bin/php5 -q