Author: Raymond Bosman Date: 2006-01-19 17:00:22 +0100 (Thu, 19 Jan 2006) New Revision: 1984
Log: - Added an ezcArchive tutorial. Added: packages/Archive/trunk/docs/tutorial.txt packages/Archive/trunk/docs/tutorial_autoload.php packages/Archive/trunk/docs/tutorial_extract.php packages/Archive/trunk/docs/tutorial_iterator.php packages/Archive/trunk/docs/tutorial_replacing.php Added: packages/Archive/trunk/docs/tutorial.txt =================================================================== --- packages/Archive/trunk/docs/tutorial.txt 2006-01-19 15:59:17 UTC (rev 1983) +++ packages/Archive/trunk/docs/tutorial.txt 2006-01-19 16:00:22 UTC (rev 1984) @@ -0,0 +1,123 @@ +eZ components - Archive +~~~~~~~~~~~~~~~~~~~~~~~ + +.. contents:: Table of Contents + +Introduction +============ + +The Archive component provides a generic API to create or extract an archive. +Currently, the archive supports the Tar and Zip format. +Compression algorithms, such as GZip or BZip2, are indirectly supported by this +component. The stream wrappers from PHP should be used to handle compressed archives. + + +Class overview +============== + +The following list sums up the most important classes in order to use the +archive: + +ezcArchive + This class provides the main API for accessing or creating a non-existing + tar or zip archive. The Archive designed that it provides methods for + extracting entries (files, directories, symbolic links, etc), appending + entries, or removing entries from the opened archive. + +ezcArchiveEntry + The ezcArchive returns an ezcArchiveEntry when an entry is requested from the + archive. The ezcArchiveEntry provides file information about the file path, + it's access rights and whether the file is an directory, symbolic link, + hardlink, block-file, etc. The owner name, the group name, the last access + time are also available. + +For more information about these classes, see the class documentation. + + +Installation +============ + +This tutorial assumes that you have set-up an eZ components enviroment. For +information on how to do this, please refer to the ComponentsIntroduction_. + +.. _ComponentsIntroduction: http://ez.no/community/articles/an_introduction_to_ez_components + + +Flexible and dynamic use cases with an optimization to its synergy +================================================================== + +The following examples demonstrate the Archive component. + + +Extracting a TAR-archive +------------------------ + +The TAR format has more than one standard. The most common formats are: + +- Unix V7 +- Ustar +- Posix +- Gnu + +Each format can be extracted from the archive. Appending entries to the archive +is only available for Unix V7 and Ustar format. + +Extracting an Archive comes in two flavours: + +- ezcArchive->extract(), extracts all entries from the archive. +- ezcArchive->extractCurrent(), extracts only the current entry. + +The Archive can be treated like an iterator. +After opening the archive, it points to the first entry. The iterator can be +moved using the ezcArchive->next() and ezcArchive->rewind() to move to the next +entry or go back to the first entry. + +The next example demonstrates how to extract an entire archive file-by-file: + +.. include:: tutorial_extract.php + :literal: + +First the tutorial_autoload.php is included. The included file loads the +correct php files for the archive package. Hereafter the timezone is set to +"UTC". The archive uses some date functions and without a timezone PHP may +show some warnings. + +The gzipped TAR archive is opened using the zlib stream. The while() method +iterates over each entry, shows the name, and extracts the entry itself. + +The Archive extends from the PHP Iterator class, the example above can be +rewritten as: + +.. include:: tutorial_iterator.php + :literal: + + + +Appending files to an archive +----------------------------- + +Unfortunately, it is not yet possible to directly append files to a gzipped or +bzipped Tar archive. The zlib and bzip2 library do not support opening a file +for reading and writing. + +ezcArchive has two methods for appending files: + +- ezcArchive->append(), appends to the end of the archive. +- ezcArchive->appendCurrent(), appends after the current entry and removes the + rest of the files from the archive. + +To replace also the first file, the ezcArchive->truncate() should be used. The +next example replaces all entries from an existing Zip archive with the files +file1.txt and file2.txt: + +.. include:: tutorial_replacing.php + :literal: + + + +.. + Local Variables: + mode: rst + fill-column: 79 + End: + vim: et syn=rst tw=79 Property changes on: packages/Archive/trunk/docs/tutorial.txt ___________________________________________________________________ Name: svn:eol-style + native Added: packages/Archive/trunk/docs/tutorial_autoload.php =================================================================== --- packages/Archive/trunk/docs/tutorial_autoload.php 2006-01-19 15:59:17 UTC (rev 1983) +++ packages/Archive/trunk/docs/tutorial_autoload.php 2006-01-19 16:00:22 UTC (rev 1984) @@ -0,0 +1,23 @@ +<?php + +require_once 'Base/trunk/src/base.php'; + +/** + * Autoload ezc classes + * + * @param string $class_name + */ +function __autoload( $class_name ) +{ + if ( ezcBase::autoload( $class_name ) ) + { + return; + } + if ( strpos( $class_name, '_' ) !== false ) + { + $file = str_replace( '_', '/', $class_name ) . '.php'; + require_once( $file ); + } +} + +?> Property changes on: packages/Archive/trunk/docs/tutorial_autoload.php ___________________________________________________________________ Name: svn:eol-style + native Added: packages/Archive/trunk/docs/tutorial_extract.php =================================================================== --- packages/Archive/trunk/docs/tutorial_extract.php 2006-01-19 15:59:17 UTC (rev 1983) +++ packages/Archive/trunk/docs/tutorial_extract.php 2006-01-19 16:00:22 UTC (rev 1984) @@ -0,0 +1,23 @@ +<?php + +include( "tutorial_autoload.php" ); +date_default_timezone_set( "UTC" ); + +// Open the gzipped TAR archive. +$archive = ezcArchive::getInstance( "compress.zlib:///tmp/my_archive.tar.gz" ); + +while( $archive->valid() ) +{ + // Returns the current entry (ezcArchiveEntry). + $entry = $archive->current(); + + // ezcArchiveEntry has an __toString() method. + echo $entry, "\n"; + + // Extract the current archive entry to /tmp/target_location/ + $archive->extractCurrent( "/tmp/target_location/" ); + + $archive->next(); +} + +?> Property changes on: packages/Archive/trunk/docs/tutorial_extract.php ___________________________________________________________________ Name: svn:eol-style + native Added: packages/Archive/trunk/docs/tutorial_iterator.php =================================================================== --- packages/Archive/trunk/docs/tutorial_iterator.php 2006-01-19 15:59:17 UTC (rev 1983) +++ packages/Archive/trunk/docs/tutorial_iterator.php 2006-01-19 16:00:22 UTC (rev 1984) @@ -0,0 +1,16 @@ +<?php + +include( "tutorial_autoload.php" ); +date_default_timezone_set( "UTC" ); + +$archive = ezcArchive::getInstance( "compress.zlib:///tmp/my_archive.tar.gz" ); + +// The foreach method calls internally the iterator methods. +foreach( $archive as $entry ) +{ + echo $entry, "\n"; + + $archive->extractCurrent( "/tmp/target_location/" ); +} + +?> Property changes on: packages/Archive/trunk/docs/tutorial_iterator.php ___________________________________________________________________ Name: svn:eol-style + native Added: packages/Archive/trunk/docs/tutorial_replacing.php =================================================================== --- packages/Archive/trunk/docs/tutorial_replacing.php 2006-01-19 15:59:17 UTC (rev 1983) +++ packages/Archive/trunk/docs/tutorial_replacing.php 2006-01-19 16:00:22 UTC (rev 1984) @@ -0,0 +1,16 @@ +<?php + +include( "tutorial_autoload.php" ); +date_default_timezone_set( "UTC" ); + +$archive = ezcArchive::getInstance( "/tmp/my_archive.zip" ); +$archive->truncate(); + +$filesToAppend[] = "/tmp/file1.txt"; +$filesToAppend[] = "/tmp/file2.txt"; + +// The second parameter specifies prefix. The prefix is normally not included +// in the archive. +$archive->appendToCurrent( $filesToAppend, "/tmp/" ); + +?> Property changes on: packages/Archive/trunk/docs/tutorial_replacing.php ___________________________________________________________________ Name: svn:eol-style + native -- svn-components mailing list [email protected] http://lists.ez.no/mailman/listinfo/svn-components
